ts-prorm-orm 1.1.0

package/dist/dialects/greenplum/index.js

@@ -0,0 +1,457 @@
+"use strict";
+/**
+ * Greenplum dialect implementation for the TypeScript ORM.
+ *
+ * Greenplum Database is a massively-parallel-processing (MPP) analytics
+ * database built by forking PostgreSQL (historically the 8.2/8.3 line, with
+ * later releases rebased onto PostgreSQL 9.x and 12). Because it speaks the
+ * PostgreSQL wire protocol and is largely SQL-compatible with it, this dialect
+ * extends {@link PostgresDialect} and reuses the same `pg` driver (default port
+ * 5432, exactly like Postgres — the coordinator/master segment listens on the
+ * standard Postgres port).
+ *
+ * Notable Greenplum-specific differences vs. plain PostgreSQL that this dialect
+ * models on top of the inherited Postgres behavior:
+ *
+ * - Distribution policy: every Greenplum table is physically distributed across
+ *   segments. `CREATE TABLE` accepts a trailing `DISTRIBUTED BY (cols)` /
+ *   `DISTRIBUTED RANDOMLY` / `DISTRIBUTED REPLICATED` clause. This dialect emits
+ *   that clause when a distribution option is supplied (see
+ *   {@link GreenplumDialect.buildDistributionClause}). To stay safe against
+ *   plain-Postgres targets it only emits the clause when explicitly asked; when
+ *   asked but under-specified it defaults to `DISTRIBUTED RANDOMLY`.
+ * - Append-optimized / column-oriented storage: Greenplum supports
+ *   append-optimized (AO) tables and column orientation with compression via a
+ *   table `WITH (appendoptimized=true, orientation=column, compresstype=zstd)`
+ *   storage clause (see {@link GreenplumDialect.buildStorageClause}).
+ * - Legacy partitioning: in addition to Postgres 10+ declarative partitioning
+ *   (inherited from the base dialect), Greenplum has its own older
+ *   `PARTITION BY RANGE(col) (START (...) END (...) EVERY (...))` syntax
+ *   (see {@link GreenplumDialect.buildRangePartitionClause}).
+ * - External tables: `CREATE EXTERNAL TABLE ... LOCATION ('gpfdist://...')
+ *   FORMAT '...'` exposes external data (e.g. served by the `gpfdist` file
+ *   distribution daemon) as a readable/writable table
+ *   (see {@link GreenplumDialect.buildExternalTableSQL}).
+ *
+ * Greenplum does NOT support some PostgreSQL features (e.g. `SERIAL` maps to a
+ * distributed sequence, no global secondary UNIQUE guarantees unless the
+ * distribution key is a subset of the constraint, no savepoints inside some
+ * plans). Those caveats are inherited-as-is from the Postgres behavior here and
+ * are out of scope for this dialect wrapper.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GreenplumDialect = void 0;
+exports.createGreenplumDialect = createGreenplumDialect;
+const index_1 = require("../postgres/index");
+/**
+ * Greenplum dialect class. Extends {@link PostgresDialect}, overriding the
+ * `CREATE TABLE` builder to append Greenplum distribution/storage clauses and
+ * adding helpers for legacy range partitioning and external tables.
+ */
+class GreenplumDialect extends index_1.PostgresDialect {
+    constructor(config) {
+        // Greenplum's coordinator listens on the standard Postgres port 5432.
+        super({ port: 5432, ...config });
+        // Explicit `string` type (rather than the inferred `'greenplum'` literal)
+        // keeps this assignable to the base `readonly name: string` property.
+        this.name = 'greenplum';
+        this.library = 'pg';
+    }
+    // ==========================================================================
+    // Distribution policy
+    // ==========================================================================
+    /**
+     * Build the trailing `DISTRIBUTED ...` clause for a Greenplum `CREATE TABLE`.
+     *
+     * Returns an empty string when no distribution option is supplied, so callers
+     * that never set one produce plain-Postgres-compatible DDL. When a
+     * distribution intent is expressed but under-specified (e.g. an empty
+     * `distributedBy` array), it falls back to `DISTRIBUTED RANDOMLY`.
+     *
+     * @returns e.g. `DISTRIBUTED BY ("id")`, `DISTRIBUTED RANDOMLY`,
+     *   `DISTRIBUTED REPLICATED`, or `''`.
+     */
+    buildDistributionClause(options) {
+        if (!options) {
+            return '';
+        }
+        if (options.distributedReplicated) {
+            return 'DISTRIBUTED REPLICATED';
+        }
+        if (options.distributedBy && options.distributedBy.length > 0) {
+            const cols = options.distributedBy.map((c) => this.escapeId(c)).join(', ');
+            return `DISTRIBUTED BY (${cols})`;
+        }
+        // Either `distributedRandomly` was set, or a distribution intent was
+        // expressed without usable columns — default to random distribution.
+        if (options.distributedRandomly ||
+            options.distributedBy !== undefined ||
+            options.distributedReplicated !== undefined) {
+            return 'DISTRIBUTED RANDOMLY';
+        }
+        return '';
+    }
+    // ==========================================================================
+    // Append-optimized / columnar storage
+    // ==========================================================================
+    /**
+     * Build the `WITH (...)` storage clause for append-optimized / column-
+     * oriented Greenplum tables. Returns `''` unless append-optimized storage is
+     * requested (via `appendOptimized`, a non-`row` `orientation`, or any of the
+     * compression parameters).
+     *
+     * @returns e.g. `WITH (appendoptimized=true, orientation=column, compresstype=zstd)`.
+     */
+    buildStorageClause(options) {
+        if (!options) {
+            return '';
+        }
+        const wantsAO = options.appendOptimized === true ||
+            options.orientation !== undefined ||
+            options.compressType !== undefined ||
+            options.compressLevel !== undefined ||
+            options.blocksize !== undefined;
+        if (!wantsAO) {
+            return '';
+        }
+        const params = ['appendoptimized=true'];
+        if (options.orientation) {
+            params.push(`orientation=${options.orientation}`);
+        }
+        if (options.compressType) {
+            params.push(`compresstype=${options.compressType}`);
+        }
+        if (options.compressLevel !== undefined) {
+            params.push(`compresslevel=${options.compressLevel}`);
+        }
+        if (options.blocksize !== undefined) {
+            params.push(`blocksize=${options.blocksize}`);
+        }
+        return `WITH (${params.join(', ')})`;
+    }
+    // ==========================================================================
+    // CREATE TABLE
+    // ==========================================================================
+    /**
+     * Synchronously build the full Greenplum `CREATE TABLE` statement, including
+     * the append-optimized storage `WITH (...)` clause and the trailing
+     * `DISTRIBUTED ...` clause. Exposed as a sync builder so callers (and tests)
+     * can inspect the emitted SQL without a live connection.
+     */
+    buildCreateTableSQL(tableName, columns, options) {
+        const defs = Object.entries(columns).map(([name, def]) => this.buildGreenplumColumnSql(name, def));
+        // Table-level constraints are emitted inside the column list.
+        for (const c of options?.constraints ?? []) {
+            defs.push(this.buildTableConstraintSql(c));
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} (${defs.join(', ')})`;
+        // Legacy inheritance / declarative partitioning passthrough.
+        if (options?.inherit) {
+            sql += ` INHERITS (${this.escapeId(options.inherit)})`;
+        }
+        if (options?.partitionBy) {
+            sql += ` PARTITION BY ${options.partitionBy}`;
+        }
+        // Append-optimized / columnar storage parameters.
+        const storage = this.buildStorageClause(options);
+        if (storage) {
+            sql += ` ${storage}`;
+        }
+        // TABLESPACE follows storage/partitioning and precedes the DISTRIBUTED clause.
+        if (options?.tablespace) {
+            sql += ` TABLESPACE ${options.tablespace}`;
+        }
+        // Distribution policy — must be the final clause on a Greenplum CREATE TABLE.
+        const distribution = this.buildDistributionClause(options);
+        if (distribution) {
+            sql += ` ${distribution}`;
+        }
+        return sql;
+    }
+    /**
+     * Build a single table-level constraint clause for the CREATE TABLE column
+     * list, e.g. `CONSTRAINT "pk_orders" PRIMARY KEY ("id")` or
+     * `FOREIGN KEY ("customer_id") REFERENCES "customers"("id")`.
+     */
+    buildTableConstraintSql(c) {
+        const prefix = c.name ? `CONSTRAINT ${this.escapeId(c.name)} ` : '';
+        const cols = (c.fields ?? []).map((f) => this.escapeId(f)).join(', ');
+        switch (c.type) {
+            case 'PRIMARY KEY':
+                return `${prefix}PRIMARY KEY (${cols})`;
+            case 'UNIQUE':
+                return `${prefix}UNIQUE (${cols})`;
+            case 'FOREIGN KEY': {
+                const ref = c.references;
+                const refClause = ref
+                    ? ` REFERENCES ${this.escapeId(ref.table)}(${this.escapeId(ref.field)})`
+                    : '';
+                return `${prefix}FOREIGN KEY (${cols})${refClause}`;
+            }
+            case 'CHECK':
+                return `${prefix}CHECK (${c.expression ?? ''})`;
+        }
+    }
+    // ==========================================================================
+    // Upsert — Greenplum has no INSERT ... ON CONFLICT
+    // ==========================================================================
+    /**
+     * Greenplum (Postgres 8/9-derived) does not implement `INSERT ... ON
+     * CONFLICT`. Refuse an upsert INSERT with a clear error pointing callers at
+     * {@link GreenplumDialect.buildUpsertQuery}'s staging-table strategy. Plain
+     * (non-upsert) inserts delegate to the inherited PostgreSQL builder.
+     */
+    buildInsertQuery(tableName, values, options) {
+        if (options?.upsert) {
+            throw new Error('GreenplumDialect: INSERT ... ON CONFLICT upsert is not supported by Greenplum ' +
+                '(Postgres 8/9-derived). Use buildUpsertQuery(), which emits a staging-table ' +
+                'CREATE TEMP + DELETE ... USING + INSERT ... SELECT strategy instead.');
+        }
+        return super.buildInsertQuery(tableName, values, options);
+    }
+    /**
+     * Build a Greenplum-compatible upsert as a staging-table batch (no
+     * `ON CONFLICT`):
+     *
+     *   CREATE TEMP TABLE "<t>_gp_upsert_stg" (LIKE "<t>") ON COMMIT DROP;
+     *   INSERT INTO "<t>_gp_upsert_stg" (cols) VALUES (...);
+     *   DELETE FROM "<t>" USING stg WHERE "<t>".k = stg.k [AND ...];
+     *   INSERT INTO "<t>" (writeCols) SELECT writeCols FROM stg [RETURNING ...];
+     *   [DROP TABLE stg]   -- only when no RETURNING (RETURNING must be the last statement)
+     *
+     * `writeCols` is the conflict keys plus `updateOnDuplicate` when given,
+     * otherwise every provided column.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const conflictFields = options?.conflictFields ?? [];
+        if (conflictFields.length === 0) {
+            throw new Error('GreenplumDialect.buildUpsertQuery: options.conflictFields is required — the ' +
+                'staging-table strategy matches existing rows on these key columns.');
+        }
+        const cols = Object.keys(values);
+        const qTable = this.escapeId(tableName);
+        const stg = this.escapeId(`${tableName}_gp_upsert_stg`);
+        const q = (c) => this.escapeId(c);
+        // Columns written back into the target: keys + updated columns, else all.
+        const writeCols = options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? Array.from(new Set([...conflictFields, ...options.updateOnDuplicate]))
+            : cols;
+        const placeholders = cols.map((_, i) => `$${i + 1}`).join(', ');
+        const joinCond = conflictFields
+            .map((k) => `${qTable}.${q(k)} = ${stg}.${q(k)}`)
+            .join(' AND ');
+        const writeList = writeCols.map(q).join(', ');
+        const statements = [
+            `CREATE TEMP TABLE ${stg} (LIKE ${qTable}) ON COMMIT DROP`,
+            `INSERT INTO ${stg} (${cols.map(q).join(', ')}) VALUES (${placeholders})`,
+            `DELETE FROM ${qTable} USING ${stg} WHERE ${joinCond}`,
+        ];
+        let finalInsert = `INSERT INTO ${qTable} (${writeList}) SELECT ${writeList} FROM ${stg}`;
+        if (options?.returning === true) {
+            finalInsert += ' RETURNING *';
+        }
+        else if (Array.isArray(options?.returning) && options.returning.length > 0) {
+            finalInsert += ` RETURNING ${options.returning.map(q).join(', ')}`;
+        }
+        statements.push(finalInsert);
+        // RETURNING must be the last statement; otherwise eagerly drop the staging
+        // table (it is also ON COMMIT DROP as a safety net).
+        if (!options?.returning) {
+            statements.push(`DROP TABLE ${stg}`);
+        }
+        return { sql: statements.join(';\n'), values: Object.values(values) };
+    }
+    /**
+     * Create a new table, emitting Greenplum distribution and append-optimized
+     * storage clauses. Overrides {@link PostgresDialect.createTable}.
+     */
+    async createTable(tableName, columns, options) {
+        const sql = this.buildCreateTableSQL(tableName, columns, options);
+        await this.query(sql);
+        // Table comment (inherited COMMENT ON semantics).
+        if (options?.comment) {
+            await this.query(`COMMENT ON TABLE ${this.escapeId(tableName)} IS ${this.escape(options.comment)}`);
+        }
+        // Post-creation indexes, delegated to the inherited addIndex().
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.addIndex(tableName, index.name || `idx_${tableName}_${index.fields.join('_')}`, index.fields, {
+                    unique: index.unique,
+                    type: index.type,
+                    using: index.using,
+                    where: index.where,
+                    expression: index.expression,
+                    include: index.include,
+                });
+            }
+        }
+    }
+    /**
+     * Build a single column definition for a Greenplum `CREATE TABLE`. Mirrors
+     * the common subset of the Postgres column builder (which is private on the
+     * base class): type, NOT NULL, DEFAULT, PRIMARY KEY, UNIQUE, and references.
+     */
+    buildGreenplumColumnSql(columnName, definition) {
+        const dt = definition.type;
+        // Auto-increment integer columns -> SERIAL (Postgres-compatibility
+        // shorthand; Greenplum backs it with a distributed sequence).
+        if (definition.autoIncrement && (dt.key === 'INTEGER' || !dt.key)) {
+            let sql = `${this.escapeId(columnName)} SERIAL`;
+            if (definition.primaryKey)
+                sql += ' PRIMARY KEY';
+            if (definition.allowNull === false)
+                sql += ' NOT NULL';
+            if (definition.unique)
+                sql += ' UNIQUE';
+            return sql;
+        }
+        let sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type)}`;
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.escape(definition.defaultValue)}`;
+        }
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.unique) {
+            sql += ' UNIQUE';
+        }
+        if (definition.references) {
+            const refField = definition.references.field;
+            const refFieldSql = Array.isArray(refField)
+                ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                : `(${this.escapeId(refField)})`;
+            sql += ` REFERENCES ${this.escapeId(definition.references.table)}${refFieldSql}`;
+            if (definition.references.onDelete) {
+                sql += ` ON DELETE ${definition.references.onDelete}`;
+            }
+            if (definition.references.onUpdate) {
+                sql += ` ON UPDATE ${definition.references.onUpdate}`;
+            }
+        }
+        return sql;
+    }
+    // ==========================================================================
+    // Legacy Greenplum range partitioning
+    // ==========================================================================
+    /**
+     * Build Greenplum's legacy `PARTITION BY RANGE(col) (START (...) END (...)
+     * EVERY (...))` clause (distinct from Postgres 10+ declarative partitioning,
+     * which the base dialect handles via `PARTITION BY RANGE (col)`).
+     *
+     * @param column - The range-partition key column.
+     * @param spec - Start/end bounds and optional `EVERY` step.
+     * @returns e.g.
+     *   `PARTITION BY RANGE(sale_date) (START ('2020-01-01') END ('2021-01-01') EVERY (INTERVAL '1 month'))`.
+     */
+    buildRangePartitionClause(column, spec) {
+        const parts = [
+            `START (${this.formatPartitionBound(spec.start)})`,
+            `END (${this.formatPartitionBound(spec.end)})`,
+        ];
+        if (spec.every !== undefined) {
+            parts.push(`EVERY (${this.formatPartitionBound(spec.every)})`);
+        }
+        return `PARTITION BY RANGE(${this.escapeId(column)}) (${parts.join(' ')})`;
+    }
+    /**
+     * Format a range-partition bound value as a SQL literal: numbers verbatim,
+     * already-expression strings (INTERVAL / DATE / TIMESTAMP keyword or a
+     * `func(...)` call) raw, and any other string single-quoted.
+     */
+    formatPartitionBound(value) {
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        const trimmed = value.trim();
+        if (/^(INTERVAL|DATE|TIMESTAMP|TIME|NUMERIC|MAXVALUE|MINVALUE)\b/i.test(trimmed) ||
+            /^[a-zA-Z_][a-zA-Z0-9_.]*\([^)]*\)$/.test(trimmed) ||
+            /^'.*'$/.test(trimmed)) {
+            return trimmed;
+        }
+        return `'${trimmed.replace(/'/g, "''")}'`;
+    }
+    // ==========================================================================
+    // External tables (gpfdist / EXTERNAL WEB)
+    // ==========================================================================
+    /**
+     * Build a Greenplum `CREATE EXTERNAL TABLE` statement. External tables expose
+     * data served over `gpfdist://`, `http://`, `s3://`, etc. as a queryable
+     * (and optionally writable) table with no local segment storage.
+     *
+     * @param tableName - Name of the external table to create.
+     * @param columns - Column definitions (types only; no distribution/constraints).
+     * @param options - External-table options (locations, format, writable, ...).
+     * @returns e.g.
+     *   `CREATE EXTERNAL TABLE "ext_sales" (...) LOCATION ('gpfdist://host:8081/sales/*.csv') FORMAT 'CSV' (DELIMITER ',' HEADER)`.
+     */
+    buildExternalTableSQL(tableName, columns, options) {
+        if (!options.locations || options.locations.length === 0) {
+            throw new Error('Greenplum external table requires at least one LOCATION.');
+        }
+        const columnDefs = Object.entries(columns)
+            .map(([name, def]) => `${this.escapeId(name)} ${this.getDataTypeSql(def.type)}`)
+            .join(', ');
+        let sql = 'CREATE';
+        if (options.writable) {
+            sql += ' WRITABLE';
+        }
+        sql += ' EXTERNAL';
+        if (options.web) {
+            sql += ' WEB';
+        }
+        sql += ' TABLE';
+        if (options.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} (${columnDefs})`;
+        const locations = options.locations
+            .map((loc) => `'${loc.replace(/'/g, "''")}'`)
+            .join(', ');
+        sql += ` LOCATION (${locations})`;
+        const format = options.format || 'TEXT';
+        sql += ` FORMAT '${format}'`;
+        const formatOpts = [];
+        if (options.delimiter !== undefined) {
+            formatOpts.push(`DELIMITER '${options.delimiter.replace(/'/g, "''")}'`);
+        }
+        if (options.header) {
+            formatOpts.push('HEADER');
+        }
+        if (formatOpts.length > 0) {
+            sql += ` (${formatOpts.join(' ')})`;
+        }
+        if (options.encoding) {
+            sql += ` ENCODING '${options.encoding.replace(/'/g, "''")}'`;
+        }
+        if (options.logErrors) {
+            sql += ' LOG ERRORS';
+        }
+        if (options.rejectLimit !== undefined) {
+            const unit = options.rejectLimitType || 'ROWS';
+            sql += ` SEGMENT REJECT LIMIT ${options.rejectLimit} ${unit}`;
+        }
+        return sql;
+    }
+    /**
+     * Create an external table by executing the statement built by
+     * {@link GreenplumDialect.buildExternalTableSQL}.
+     */
+    async createExternalTable(tableName, columns, options) {
+        await this.query(this.buildExternalTableSQL(tableName, columns, options));
+    }
+}
+exports.GreenplumDialect = GreenplumDialect;
+/**
+ * Create a new Greenplum dialect instance.
+ */
+function createGreenplumDialect(options) {
+    return new GreenplumDialect(options || {});
+}
+exports.default = GreenplumDialect;