ts-prorm-orm 1.1.0

package/dist/dialects/vertica/index.js

@@ -0,0 +1,317 @@
+"use strict";
+/**
+ * Vertica dialect implementation for the TypeScript ORM
+ *
+ * Vertica is an analytic, columnar, massively-parallel-processing (MPP)
+ * database. It speaks the PostgreSQL wire protocol on port 5433 and is
+ * broadly SQL-compatible with PostgreSQL, so this dialect extends
+ * `PostgresDialect` and reuses the `pg` driver, query building, escaping and
+ * transaction handling. Only the genuinely Vertica-specific differences are
+ * overridden here:
+ *
+ * - Default port is 5433 (not Postgres's 5432).
+ * - CREATE TABLE supports Vertica's columnar/MPP physical-design clauses:
+ *     * `ORDER BY col, ...`            — sort order of the column store.
+ *     * `SEGMENTED BY HASH(cols) ALL NODES` — hash-distribute rows across
+ *       all cluster nodes, or `UNSEGMENTED ALL NODES` to replicate the whole
+ *       table on every node.
+ *     * `PARTITION BY expr`            — data partitioning (partition pruning /
+ *       fast bulk drop of partitions).
+ *   These are emitted by the overridden `createTable` via the synchronous
+ *   `buildCreateTableSql` helper, driven by extra `VerticaTableOptions`.
+ * - `CREATE PROJECTION` — projections are Vertica's materialized,
+ *   pre-sorted/pre-segmented physical storage for a table (its equivalent of
+ *   an index). `buildCreateProjectionSql`/`createProjection` build that DDL.
+ * - Type mapping differs from Postgres:
+ *     * No SERIAL/BIGSERIAL — auto-increment columns use `IDENTITY`.
+ *     * Large text/blob use `LONG VARCHAR` / `LONG VARBINARY`.
+ *     * BOOLEAN is native.
+ *   `getDataTypeSql` is overridden for these; everything else delegates to the
+ *   Postgres mapping.
+ * - DML differences from Postgres:
+ *     * No `ON CONFLICT` — upserts are expressed with `MERGE INTO ... USING ...
+ *       WHEN MATCHED THEN UPDATE ... WHEN NOT MATCHED THEN INSERT ...`.
+ *       `buildUpsertQuery` and `buildInsertQuery({ upsert: true })` both emit
+ *       Vertica MERGE instead of the Postgres `INSERT ... ON CONFLICT`.
+ *     * No `RETURNING` clause on INSERT/UPDATE/DELETE. The Postgres builders
+ *       append `RETURNING` when asked; the Vertica overrides strip it (Vertica
+ *       cannot return affected rows inline — read them back with a follow-up
+ *       SELECT).
+ *     * `addColumn` uses `IDENTITY` (not SERIAL) for auto-increment columns.
+ *
+ * Constraint enforcement note: Vertica only *enforces* PRIMARY KEY / UNIQUE /
+ * FOREIGN KEY / NOT NULL / CHECK constraints during `COPY`/`ANALYZE_CONSTRAINTS`
+ * (or when `ENABLE` is set) — they are otherwise advisory metadata used by the
+ * optimizer. Constraint DDL is still emitted (same syntax as Postgres) but a
+ * duplicate/violating row is not rejected at INSERT time by default.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerticaDialect = void 0;
+exports.createVerticaDialect = createVerticaDialect;
+const index_1 = require("../postgres/index");
+/**
+ * Vertica dialect class. Extends the PostgreSQL dialect (same pg wire) and
+ * overrides only the Vertica-specific type mapping and CREATE TABLE / CREATE
+ * PROJECTION DDL.
+ */
+class VerticaDialect extends index_1.PostgresDialect {
+    constructor(config = {}) {
+        // Vertica's default SQL port is 5433 (not Postgres's 5432).
+        super({ port: 5433, ...config });
+        this.name = 'vertica';
+    }
+    /**
+     * Normalize a `string | string[]` column list into a comma-separated,
+     * quoted identifier list.
+     */
+    columnList(cols) {
+        const arr = Array.isArray(cols) ? cols : [cols];
+        return arr.map((c) => this.escapeId(c)).join(', ');
+    }
+    /**
+     * Build the Vertica physical-design tail clauses (`ORDER BY`,
+     * `SEGMENTED BY`/`UNSEGMENTED`, `PARTITION BY`) shared by tables and
+     * projections. Returns a leading-space-prefixed fragment (possibly empty).
+     */
+    buildPhysicalDesignClauses(opts) {
+        let sql = '';
+        if (opts.orderBy) {
+            sql += ` ORDER BY ${this.columnList(opts.orderBy)}`;
+        }
+        if (opts.unsegmented) {
+            sql += ' UNSEGMENTED ALL NODES';
+        }
+        else if (opts.segmentedBy) {
+            sql += ` SEGMENTED BY HASH(${this.columnList(opts.segmentedBy)}) ALL NODES`;
+        }
+        if (opts.partitionByExpression) {
+            sql += ` PARTITION BY ${opts.partitionByExpression}`;
+        }
+        return sql;
+    }
+    /**
+     * Build a single column definition for a Vertica CREATE TABLE. Handles
+     * IDENTITY auto-increment (Vertica has no SERIAL) and otherwise mirrors the
+     * common column clauses (NOT NULL, DEFAULT, PRIMARY KEY, UNIQUE, REFERENCES).
+     */
+    buildColumnSql(columnName, definition) {
+        const dt = definition.type;
+        const isAutoInt = definition.autoIncrement && (dt.key === 'INTEGER' || dt.key === 'BIGINT' || !dt.key);
+        let sql = `${this.escapeId(columnName)} ${isAutoInt ? 'IDENTITY' : this.getDataTypeSql(definition.type)}`;
+        // IDENTITY columns are implicitly NOT NULL and cannot carry a DEFAULT.
+        if (!isAutoInt) {
+            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}`;
+        }
+        return sql;
+    }
+    /**
+     * Synchronously build the Vertica `CREATE TABLE ...` statement, including the
+     * columnar/MPP `ORDER BY`, `SEGMENTED BY HASH(...) ALL NODES` /
+     * `UNSEGMENTED ALL NODES`, and `PARTITION BY` clauses. Exposed as a pure
+     * string builder so it can be unit-tested without a live connection.
+     */
+    buildCreateTableSql(tableName, columns, options) {
+        const columnDefs = Object.entries(columns).map(([name, def]) => this.buildColumnSql(name, def));
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        if (options) {
+            sql += this.buildPhysicalDesignClauses(options);
+        }
+        return sql;
+    }
+    /**
+     * Create a table on Vertica, emitting the columnar/MPP physical-design
+     * clauses. Overrides the Postgres implementation because Vertica's CREATE
+     * TABLE tail differs (ORDER BY / SEGMENTED BY / PARTITION BY) and it has no
+     * SERIAL columns.
+     */
+    async createTable(tableName, columns, options) {
+        await this.query(this.buildCreateTableSql(tableName, columns, options));
+    }
+    /**
+     * Synchronously build a Vertica `CREATE PROJECTION ...` statement. A
+     * projection is Vertica's materialized, pre-sorted/pre-segmented physical
+     * copy of a table's data (its "index" equivalent).
+     */
+    buildCreateProjectionSql(options) {
+        let sql = 'CREATE PROJECTION';
+        if (options.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(options.name)}`;
+        const cols = options.columns && options.columns.length > 0
+            ? this.columnList(options.columns)
+            : '*';
+        sql += ` (${cols})`;
+        sql += ` AS SELECT ${cols} FROM ${this.escapeId(options.table)}`;
+        sql += this.buildPhysicalDesignClauses({
+            orderBy: options.orderBy,
+            segmentedBy: options.segmentedBy,
+            unsegmented: options.unsegmented,
+        });
+        return sql;
+    }
+    /**
+     * Create a Vertica projection (materialized columnar storage for a table).
+     */
+    async createProjection(options) {
+        await this.query(this.buildCreateProjectionSql(options));
+    }
+    // ---------------------------------------------------------------------------
+    // DML overrides — Vertica has no ON CONFLICT and no RETURNING.
+    // ---------------------------------------------------------------------------
+    /**
+     * Build an INSERT for Vertica.
+     *
+     * Two differences from the Postgres base:
+     *   - `upsert: true` routes to a Vertica `MERGE` (Postgres would emit the
+     *     unsupported `INSERT ... ON CONFLICT`).
+     *   - `returning` is stripped — Vertica does not support `RETURNING`.
+     */
+    buildInsertQuery(tableName, values, options) {
+        if (options?.upsert) {
+            return this.buildUpsertQuery(tableName, values, {
+                conflictFields: options.conflictFields,
+                updateOnDuplicate: options.updateOnDuplicate,
+                schema: options.schema,
+            });
+        }
+        // Delegate to the Postgres builder but never emit RETURNING.
+        return super.buildInsertQuery(tableName, values, this.stripReturning(options));
+    }
+    /**
+     * Build an upsert for Vertica as a `MERGE INTO ... USING (SELECT ...) ...`
+     * statement. Vertica has no `INSERT ... ON CONFLICT`.
+     *
+     * The inserted row is materialized as a single-row source relation
+     * (`SELECT $1 AS col1, $2 AS col2`), joined to the target on `conflictFields`.
+     * Matching rows get `UPDATE SET` for the non-key columns (or the explicit
+     * `updateOnDuplicate` list); non-matching rows are inserted. `RETURNING` is
+     * not supported and is ignored.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const queryValues = Object.values(values);
+        if (!options?.conflictFields || options.conflictFields.length === 0) {
+            throw new Error('buildUpsertQuery: options.conflictFields is required - Vertica MERGE needs the ' +
+                'key column(s) for its ON join condition, which cannot be inferred from the ' +
+                'inserted columns.');
+        }
+        const conflictFields = options.conflictFields;
+        const target = this.quoteTable(tableName, options.schema);
+        // Single-row source relation: SELECT $1 AS "col1", $2 AS "col2"
+        const sourceSelect = columns
+            .map((c, i) => `$${i + 1} AS ${this.escapeId(c)}`)
+            .join(', ');
+        const onCondition = conflictFields
+            .map((c) => `tgt.${this.escapeId(c)} = src.${this.escapeId(c)}`)
+            .join(' AND ');
+        // Update every non-key column (or the explicit updateOnDuplicate list).
+        const candidateUpdateFields = options.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? options.updateOnDuplicate
+            : columns;
+        const updateFields = candidateUpdateFields.filter((c) => !conflictFields.includes(c));
+        let sql = `MERGE INTO ${target} AS tgt USING (SELECT ${sourceSelect}) AS src ON ${onCondition}`;
+        if (updateFields.length > 0) {
+            const setClause = updateFields
+                .map((c) => `${this.escapeId(c)} = src.${this.escapeId(c)}`)
+                .join(', ');
+            sql += ` WHEN MATCHED THEN UPDATE SET ${setClause}`;
+        }
+        const insertCols = columns.map((c) => this.escapeId(c)).join(', ');
+        const insertVals = columns.map((c) => `src.${this.escapeId(c)}`).join(', ');
+        sql += ` WHEN NOT MATCHED THEN INSERT (${insertCols}) VALUES (${insertVals})`;
+        return { sql, values: queryValues };
+    }
+    /**
+     * Build an UPDATE for Vertica. Same as Postgres but `RETURNING` is stripped.
+     */
+    buildUpdateQuery(tableName, values, where, options) {
+        return super.buildUpdateQuery(tableName, values, where, this.stripReturning(options));
+    }
+    /**
+     * Build a DELETE for Vertica. Same as Postgres but `RETURNING` is stripped.
+     */
+    buildDeleteQuery(tableName, where, options) {
+        return super.buildDeleteQuery(tableName, where, this.stripReturning(options));
+    }
+    /**
+     * Return a shallow copy of the given DML options with any `returning`
+     * request removed. Vertica does not support the `RETURNING` clause, so the
+     * inherited Postgres builders must not emit it.
+     */
+    stripReturning(options) {
+        if (!options || options.returning === undefined) {
+            return options;
+        }
+        const { returning, ...rest } = options;
+        return rest;
+    }
+    /**
+     * Add a column on Vertica. Overrides the Postgres implementation so that
+     * auto-increment columns use `IDENTITY` (Vertica has no SERIAL) and the
+     * Vertica column-definition builder is used.
+     */
+    async addColumn(tableName, columnName, definition) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${this.buildColumnSql(columnName, definition)}`;
+        await this.query(sql);
+    }
+    /**
+     * Vertica type mapping. Differs from Postgres in three ways:
+     *   - auto-increment integers use `IDENTITY` (no SERIAL/BIGSERIAL);
+     *   - large text/blob map to `LONG VARCHAR` / `LONG VARBINARY`;
+     *   - BOOLEAN is native.
+     * Everything else delegates to the Postgres mapping.
+     */
+    getDataTypeSql(dataType) {
+        if (dataType && typeof dataType === 'object') {
+            const dt = dataType;
+            switch (dt.key) {
+                case 'INTEGER':
+                case 'BIGINT':
+                    if (dt.autoIncrement) {
+                        return 'IDENTITY';
+                    }
+                    break;
+                case 'TEXT':
+                    // Vertica's large variable-length text type.
+                    return 'LONG VARCHAR';
+                case 'BLOB':
+                    // Vertica's large variable-length binary type.
+                    return 'LONG VARBINARY';
+                case 'BOOLEAN':
+                    return 'BOOLEAN';
+            }
+        }
+        return super.getDataTypeSql(dataType);
+    }
+}
+exports.VerticaDialect = VerticaDialect;
+/**
+ * Create a new Vertica dialect instance
+ */
+function createVerticaDialect(options) {
+    return new VerticaDialect(options || {});
+}
+exports.default = VerticaDialect;