ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/vertica/index.d.ts

@@ -0,0 +1,321 @@
+/**
+ * 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.
+ */
+import { PostgresDialect, PostgresDialectOptions } from '../postgres/index';
+import { ColumnDefinition, TableOptions, InsertOptions, UpdateOptions, DeleteOptions, UpsertQueryOptions } from '../dialect';
+import { DataType } from '../../types';
+/**
+ * Vertica-specific CREATE TABLE physical-design options, layered on top of the
+ * shared `TableOptions`. Not part of the shared type (every dialect uses that),
+ * so callers targeting Vertica pass these via this extended type.
+ */
+export interface VerticaTableOptions extends TableOptions {
+    /** `ORDER BY col, ...` — column-store sort order. */
+    orderBy?: string | string[];
+    /**
+     * `SEGMENTED BY HASH(cols) ALL NODES` — hash-distribute rows across all
+     * nodes. Provide the column(s) to hash on. Mutually exclusive with
+     * `unsegmented`.
+     */
+    segmentedBy?: string | string[];
+    /**
+     * `UNSEGMENTED ALL NODES` — replicate the full table on every node instead
+     * of segmenting it. When true, takes precedence over `segmentedBy`.
+     */
+    unsegmented?: boolean;
+    /**
+     * `PARTITION BY expr` — Vertica partitioning expression (e.g.
+     * `date_trunc('month', event_time)` or a bare column). Overrides the
+     * Postgres-style `partitionBy` handling.
+     */
+    partitionByExpression?: string;
+}
+/**
+ * Options for building a Vertica `CREATE PROJECTION`.
+ */
+export interface VerticaProjectionOptions {
+    /** Name of the projection to create. */
+    name: string;
+    /** Source table the projection is built from. */
+    table: string;
+    /** Explicit projection column list. Defaults to `*` (all columns) when omitted. */
+    columns?: string[];
+    /** `ORDER BY col, ...` sort order for the projection. */
+    orderBy?: string | string[];
+    /** `SEGMENTED BY HASH(cols) ALL NODES` distribution columns. */
+    segmentedBy?: string | string[];
+    /** `UNSEGMENTED ALL NODES` — replicate the projection on every node. */
+    unsegmented?: boolean;
+    /** Emit `CREATE PROJECTION IF NOT EXISTS`. */
+    ifNotExists?: boolean;
+}
+/**
+ * Options for Vertica's native bulk-load `COPY ... FROM` (distinct from the
+ * inherited Postgres `copyFrom`, which drives `COPY ... FROM STDIN` over the
+ * pg protocol). Vertica's `COPY` can read a server-side path, a client-side
+ * `LOCAL` path, or S3/HDFS URIs, and exposes rich parser/error-handling
+ * clauses that have no Postgres equivalent.
+ */
+export interface VerticaCopyOptions {
+    /** Restrict the load to these target columns, in order. */
+    columns?: string[];
+    /**
+     * Read the file from the *client* (`COPY ... FROM LOCAL '...'`) instead of a
+     * path on the Vertica node. Ignored when `source` is an S3/HDFS/other URI.
+     */
+    local?: boolean;
+    /** Field delimiter (`DELIMITER 'x'`). Defaults to Vertica's own default (`|`) when omitted. */
+    delimiter?: string;
+    /** Quote/enclosure character (`ENCLOSED BY 'x'`). */
+    enclosedBy?: string;
+    /** String that represents SQL NULL in the input (`NULL 'x'`). */
+    nullAs?: string;
+    /** Header/leading rows to skip (`SKIP n`). */
+    skip?: number;
+    /** Record terminator (`RECORD TERMINATOR 'x'`). */
+    recordTerminator?: string;
+    /** Named parser, e.g. `'fcsvparser'`, `'fjsonparser'`, `'orc'`, `'parquet'` (`PARSER name()`). */
+    parser?: string;
+    /** Abort the whole load on the first rejected row (`ABORT ON ERROR`). */
+    abortOnError?: boolean;
+    /** Tolerate up to this many rejected rows before failing (`REJECTMAX n`). */
+    rejectMax?: number;
+    /** Route rejected rows to this table (`REJECTED DATA AS TABLE "name"`). */
+    rejectedDataTable?: string;
+    /** Character-set encoding of the source data (e.g. `'UTF-8'`). */
+    encoding?: string;
+    /** Additional raw COPY clauses appended verbatim (escape hatch). */
+    extra?: string;
+}
+/**
+ * Options for dropping a Vertica projection.
+ */
+export interface VerticaDropProjectionOptions {
+    /** Emit `DROP PROJECTION IF EXISTS`. */
+    ifExists?: boolean;
+    /** Emit `... CASCADE` to drop dependent objects. */
+    cascade?: boolean;
+}
+/**
+ * Vertica dialect class. Extends the PostgreSQL dialect (same pg wire) and
+ * overrides only the Vertica-specific type mapping and CREATE TABLE / CREATE
+ * PROJECTION DDL.
+ */
+export declare class VerticaDialect extends PostgresDialect {
+    readonly name = "vertica";
+    constructor(config?: VerticaDialectOptions);
+    /**
+     * Normalize a `string | string[]` column list into a comma-separated,
+     * quoted identifier list.
+     */
+    private columnList;
+    /**
+     * 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).
+     */
+    private buildPhysicalDesignClauses;
+    /**
+     * 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).
+     */
+    private buildColumnSql;
+    /**
+     * 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: string, columns: Record<string, ColumnDefinition>, options?: VerticaTableOptions): string;
+    /**
+     * 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.
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: VerticaTableOptions): Promise<void>;
+    /**
+     * 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: VerticaProjectionOptions): string;
+    /**
+     * Create a Vertica projection (materialized columnar storage for a table).
+     */
+    createProjection(options: VerticaProjectionOptions): Promise<void>;
+    /**
+     * 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: string, values: Record<string, any>, options?: InsertOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * 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: string, values: Record<string, any>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build an UPDATE for Vertica. Same as Postgres but `RETURNING` is stripped.
+     */
+    buildUpdateQuery(tableName: string, values: Record<string, any>, where: any, options?: UpdateOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build a DELETE for Vertica. Same as Postgres but `RETURNING` is stripped.
+     */
+    buildDeleteQuery(tableName: string, where: any, options?: DeleteOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * 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.
+     */
+    private stripReturning;
+    /**
+     * 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.
+     */
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * 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: DataType): string;
+    /**
+     * Synchronously build a Vertica `DROP PROJECTION ...` statement.
+     */
+    buildDropProjectionSql(name: string, options?: VerticaDropProjectionOptions): string;
+    /**
+     * Drop a Vertica projection.
+     */
+    dropProjection(name: string, options?: VerticaDropProjectionOptions): Promise<void>;
+    /**
+     * Refresh projections. Vertica loads new/updated data into a projection's
+     * physical storage via the `REFRESH()` meta-function; with no argument it
+     * refreshes every out-of-date projection in the schema, or pass one or more
+     * table names to refresh only those tables' projections.
+     *
+     * Builds: `SELECT REFRESH('t1, t2')` (or `SELECT REFRESH()` when no tables
+     * are given).
+     */
+    refreshProjections(tables?: string | string[]): Promise<void>;
+    /**
+     * Drop all partitions of `tableName` whose partition-expression value falls
+     * in the inclusive `[minRange, maxRange]` range, via Vertica's
+     * `DROP_PARTITIONS('table', min, max)` meta-function. This is Vertica's fast
+     * bulk-delete mechanism (it drops the underlying ROS containers rather than
+     * deleting rows one by one).
+     */
+    dropPartitions(tableName: string, minRange: string | number, maxRange: string | number, options?: {
+        enforceStorageMove?: boolean;
+    }): Promise<void>;
+    /**
+     * Swap the partitions in the inclusive `[minRange, maxRange]` value range
+     * between two tables, via Vertica's `SWAP_PARTITIONS_BETWEEN_TABLES`. Useful
+     * for atomic "publish" of a freshly-loaded staging partition into a live
+     * table.
+     */
+    swapPartitions(sourceTable: string, minRange: string | number, maxRange: string | number, destTable: string, options?: {
+        forceSplit?: boolean;
+    }): Promise<void>;
+    /**
+     * Collect optimizer statistics for a table (optionally a subset of columns)
+     * via Vertica's `ANALYZE_STATISTICS('table'[, 'col1,col2'])` meta-function.
+     */
+    analyzeStatistics(tableName: string, columns?: string | string[]): Promise<void>;
+    /**
+     * Synchronously build a Vertica `COPY <table> [(cols)] FROM ['LOCAL'] '<src>'
+     * ...` statement with parser and error-handling clauses. Exposed as a pure
+     * string builder so it can be unit-tested without a live connection.
+     *
+     * `source` is a server-side path (default), a client path when
+     * `options.local` is set, or an `s3://`/`hdfs://`/`webhdfs://` URI (in which
+     * case `LOCAL` is not emitted even if requested — remote URIs are read by the
+     * server).
+     */
+    buildCopyFromSql(tableName: string, source: string, options?: VerticaCopyOptions): string;
+    /**
+     * Bulk-load data into a Vertica table from a file/path/URI using Vertica's
+     * native `COPY` command. This is the Vertica-specific counterpart to the
+     * inherited Postgres `copyFrom` (which streams `COPY ... FROM STDIN`).
+     */
+    copyFromFile(tableName: string, source: string, options?: VerticaCopyOptions): Promise<import('../../types').QueryResult>;
+}
+/**
+ * Vertica dialect options. Structurally identical to the Postgres options
+ * (same pg driver); the default port differs (5433).
+ */
+export interface VerticaDialectOptions extends PostgresDialectOptions {
+}
+/**
+ * Create a new Vertica dialect instance
+ */
+export declare function createVerticaDialect(options?: VerticaDialectOptions): VerticaDialect;
+export default VerticaDialect;

package/dist/dialects/vertica/index.js

@@ -306,6 +306,167 @@ class VerticaDialect extends index_1.PostgresDialect {
         }
         return super.getDataTypeSql(dataType);
     }
+    // ---------------------------------------------------------------------------
+    // Projection lifecycle (createProjection is above).
+    //
+    // A projection is Vertica's materialized, pre-sorted/pre-segmented physical
+    // storage for a table (its "index" equivalent). Beyond creating them, callers
+    // need to drop and refresh projections without dropping to raw SQL.
+    // ---------------------------------------------------------------------------
+    /**
+     * Synchronously build a Vertica `DROP PROJECTION ...` statement.
+     */
+    buildDropProjectionSql(name, options) {
+        let sql = 'DROP PROJECTION';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(name)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        return sql;
+    }
+    /**
+     * Drop a Vertica projection.
+     */
+    async dropProjection(name, options) {
+        await this.query(this.buildDropProjectionSql(name, options));
+    }
+    /**
+     * Refresh projections. Vertica loads new/updated data into a projection's
+     * physical storage via the `REFRESH()` meta-function; with no argument it
+     * refreshes every out-of-date projection in the schema, or pass one or more
+     * table names to refresh only those tables' projections.
+     *
+     * Builds: `SELECT REFRESH('t1, t2')` (or `SELECT REFRESH()` when no tables
+     * are given).
+     */
+    async refreshProjections(tables) {
+        const list = tables === undefined ? [] : Array.isArray(tables) ? tables : [tables];
+        const arg = list.length > 0 ? this.escape(list.join(', ')) : '';
+        await this.query(`SELECT REFRESH(${arg})`);
+    }
+    // ---------------------------------------------------------------------------
+    // Partition maintenance.
+    //
+    // Unlike Postgres/Greenplum (ALTER TABLE ... DROP PARTITION), Vertica manages
+    // partitions through meta-functions keyed on the partition-expression value
+    // range, so these are function calls rather than DDL.
+    // ---------------------------------------------------------------------------
+    /**
+     * Drop all partitions of `tableName` whose partition-expression value falls
+     * in the inclusive `[minRange, maxRange]` range, via Vertica's
+     * `DROP_PARTITIONS('table', min, max)` meta-function. This is Vertica's fast
+     * bulk-delete mechanism (it drops the underlying ROS containers rather than
+     * deleting rows one by one).
+     */
+    async dropPartitions(tableName, minRange, maxRange, options) {
+        const args = [this.escape(tableName), this.escape(minRange), this.escape(maxRange)];
+        if (options?.enforceStorageMove !== undefined) {
+            args.push(options.enforceStorageMove ? 'true' : 'false');
+        }
+        await this.query(`SELECT DROP_PARTITIONS(${args.join(', ')})`);
+    }
+    /**
+     * Swap the partitions in the inclusive `[minRange, maxRange]` value range
+     * between two tables, via Vertica's `SWAP_PARTITIONS_BETWEEN_TABLES`. Useful
+     * for atomic "publish" of a freshly-loaded staging partition into a live
+     * table.
+     */
+    async swapPartitions(sourceTable, minRange, maxRange, destTable, options) {
+        const args = [
+            this.escape(sourceTable),
+            this.escape(minRange),
+            this.escape(maxRange),
+            this.escape(destTable),
+        ];
+        if (options?.forceSplit !== undefined) {
+            args.push(options.forceSplit ? 'true' : 'false');
+        }
+        await this.query(`SELECT SWAP_PARTITIONS_BETWEEN_TABLES(${args.join(', ')})`);
+    }
+    // ---------------------------------------------------------------------------
+    // Statistics — Vertica's optimizer relies on explicitly-collected stats
+    // (no background autoanalyze like Postgres). ANALYZE_STATISTICS is a
+    // meta-function, not the Postgres `ANALYZE` statement.
+    // ---------------------------------------------------------------------------
+    /**
+     * Collect optimizer statistics for a table (optionally a subset of columns)
+     * via Vertica's `ANALYZE_STATISTICS('table'[, 'col1,col2'])` meta-function.
+     */
+    async analyzeStatistics(tableName, columns) {
+        const args = [this.escape(tableName)];
+        if (columns !== undefined) {
+            const cols = Array.isArray(columns) ? columns.join(', ') : columns;
+            args.push(this.escape(cols));
+        }
+        await this.query(`SELECT ANALYZE_STATISTICS(${args.join(', ')})`);
+    }
+    // ---------------------------------------------------------------------------
+    // Bulk load — Vertica native COPY (server path / LOCAL client path / S3/HDFS
+    // URI), distinct from the inherited Postgres `copyFrom` (COPY ... FROM STDIN).
+    // ---------------------------------------------------------------------------
+    /**
+     * Synchronously build a Vertica `COPY <table> [(cols)] FROM ['LOCAL'] '<src>'
+     * ...` statement with parser and error-handling clauses. Exposed as a pure
+     * string builder so it can be unit-tested without a live connection.
+     *
+     * `source` is a server-side path (default), a client path when
+     * `options.local` is set, or an `s3://`/`hdfs://`/`webhdfs://` URI (in which
+     * case `LOCAL` is not emitted even if requested — remote URIs are read by the
+     * server).
+     */
+    buildCopyFromSql(tableName, source, options) {
+        const colsSql = options?.columns && options.columns.length > 0
+            ? ` (${options.columns.map((c) => this.escapeId(c)).join(', ')})`
+            : '';
+        const isUri = /^[a-z0-9]+:\/\//i.test(source);
+        const localKeyword = options?.local && !isUri ? 'LOCAL ' : '';
+        let sql = `COPY ${this.quoteTable(tableName)}${colsSql} FROM ${localKeyword}${this.escape(source)}`;
+        if (options?.delimiter !== undefined) {
+            sql += ` DELIMITER ${this.escape(options.delimiter)}`;
+        }
+        if (options?.enclosedBy !== undefined) {
+            sql += ` ENCLOSED BY ${this.escape(options.enclosedBy)}`;
+        }
+        if (options?.nullAs !== undefined) {
+            sql += ` NULL ${this.escape(options.nullAs)}`;
+        }
+        if (options?.recordTerminator !== undefined) {
+            sql += ` RECORD TERMINATOR ${this.escape(options.recordTerminator)}`;
+        }
+        if (options?.skip !== undefined) {
+            sql += ` SKIP ${Number(options.skip)}`;
+        }
+        if (options?.encoding !== undefined) {
+            sql += ` ENCODING ${this.escape(options.encoding)}`;
+        }
+        if (options?.parser !== undefined) {
+            sql += ` PARSER ${options.parser}()`;
+        }
+        if (options?.rejectedDataTable !== undefined) {
+            sql += ` REJECTED DATA AS TABLE ${this.escapeId(options.rejectedDataTable)}`;
+        }
+        if (options?.rejectMax !== undefined) {
+            sql += ` REJECTMAX ${Number(options.rejectMax)}`;
+        }
+        if (options?.abortOnError) {
+            sql += ' ABORT ON ERROR';
+        }
+        if (options?.extra) {
+            sql += ` ${options.extra}`;
+        }
+        return sql;
+    }
+    /**
+     * Bulk-load data into a Vertica table from a file/path/URI using Vertica's
+     * native `COPY` command. This is the Vertica-specific counterpart to the
+     * inherited Postgres `copyFrom` (which streams `COPY ... FROM STDIN`).
+     */
+    async copyFromFile(tableName, source, options) {
+        return this.query(this.buildCopyFromSql(tableName, source, options));
+    }
 }
 exports.VerticaDialect = VerticaDialect;
 /**