ts-prorm-orm 1.1.0 → 1.2.1

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

@@ -0,0 +1,729 @@
+/**
+ * IBM Db2 (Db2 for LUW - Linux/Unix/Windows) dialect implementation for the TypeScript ORM
+ * Uses the `ibm_db` driver (ODBC-based CLI driver) for database connectivity.
+ *
+ * Notable Db2 LUW SQL characteristics implemented here:
+ *  - Double-quoted identifiers (like Oracle/ANSI SQL)
+ *  - `OFFSET n ROWS FETCH FIRST m ROWS ONLY` for pagination
+ *  - `MERGE INTO ... WHEN MATCHED / WHEN NOT MATCHED` for upsert
+ *  - `GENERATED ALWAYS AS IDENTITY` for auto-increment columns
+ *  - `CREATE SEQUENCE` / `NEXT VALUE FOR` for sequences
+ *  - `CREATE SCHEMA` for first-class schema support
+ *  - `?` (ODBC-style) positional bind markers, matching the ibm_db driver
+ */
+import type { Pool as IbmDbPool } from 'ibm_db';
+import { Dialect, DialectOptions, ColumnDefinition, TableOptions, DropTableOptions, TableDescription, IndexOptions, IndexDefinition, InsertOptions, UpdateOptions, DeleteOptions, SelectOptions, UpsertQueryOptions, DropSchemaOptions, ViewOptions, DropViewOptions, ConstraintDefinition, DropConstraintOptions, BuildOptions, MaterializedViewOptions, RefreshOptions, DropMaterializedViewOptions, ExtensionInfo, FdwForeignServerOptions, FdwAlterForeignServerOptions, FdwUserMappingOptions, FdwForeignTableOptions, FdwImportForeignSchemaOptions } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, DataType, WhereOptions, Order, PoolOptions, RetryOptions, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, TriggerOptions, DropTriggerOptions, SequenceOptions, DropSequenceOptions, PolicyOptions, DropPolicyOptions, StreamOptions } from '../../types';
+import { Readable } from 'stream';
+/**
+ * Db2 dialect options.
+ *
+ * Either supply structured `host`/`port`/`database`/`username`/`password`
+ * fields (which are assembled into the Db2 keyword=value connection
+ * string), or provide a raw `connectionString` to bypass that entirely.
+ */
+export interface DB2DialectOptions extends DialectOptions {
+    /** Raw Db2 connection string override, e.g. "DATABASE=x;HOSTNAME=y;PORT=50000;PROTOCOL=TCPIP;UID=u;PWD=p;" */
+    connectionString?: string;
+    /** Default schema for operations (defaults to the connecting user's schema) */
+    schema?: string;
+    /** Connection pool options */
+    pool?: PoolOptions;
+    /** Connection retry options */
+    retry?: RetryOptions;
+    /** Additional raw keyword=value pairs appended to the connection string */
+    extraConnectionParams?: Record<string, string>;
+    /** Whether to use SECURITY=SSL in the connection string */
+    ssl?: boolean;
+}
+/**
+ * Db2-specific `TableOptions` extension.
+ *
+ * Db2 LUW supports row compression at CREATE TABLE / ALTER TABLE time via
+ * `COMPRESS YES ADAPTIVE` (adaptive compression, default & recommended for
+ * OLTP workloads since 10.1), `COMPRESS YES STATIC` (classic static
+ * dictionary-based row compression), or `COMPRESS NO` to disable it.
+ */
+export interface Db2TableOptions extends TableOptions {
+    /**
+     * Row compression mode: `'ADAPTIVE'` for `COMPRESS YES ADAPTIVE`,
+     * `'STATIC'` for `COMPRESS YES STATIC`, or `false` for `COMPRESS NO`.
+     * Omit to leave compression unspecified (server/tablespace default).
+     */
+    compress?: 'ADAPTIVE' | 'STATIC' | false;
+}
+/**
+ * Options describing a recursive common table expression, threaded through
+ * `buildSelectQuery` via an untyped `cte` property (see `buildSelectQuery`
+ * for why this isn't part of the shared `SelectOptions` interface).
+ *
+ * Produces standard SQL:
+ *   WITH name(columns) AS (
+ *     baseQuery
+ *     UNION ALL
+ *     recursiveQuery
+ *   )
+ */
+export interface RecursiveCteOptions {
+    /** Name of the CTE, referenced by the outer query's `tableName`/`FROM`. */
+    name: string;
+    /** Optional explicit column list for the CTE. */
+    columns?: string[];
+    /** The non-recursive "seed" branch of the CTE. */
+    baseQuery: string;
+    /** The recursive branch, which self-references `name`. */
+    recursiveQuery: string;
+    /**
+     * Whether to combine the base/recursive branches with `UNION ALL` (the
+     * default, and the only form Db2 accepts for a *recursive* CTE) or plain
+     * `UNION`. Db2 requires `UNION ALL` for recursion; `false` is only useful
+     * for a non-recursive multi-branch CTE reusing this same builder.
+     */
+    unionAll?: boolean;
+}
+/** Options describing an OLAP window/analytic function call. */
+export interface WindowFunctionOptions {
+    /** Function name, e.g. `ROW_NUMBER`, `RANK`, `SUM`, `LAG`. */
+    fn: string;
+    /** Raw argument expressions passed to the function (already escaped by the caller). */
+    args?: string[];
+    /** `PARTITION BY` column(s). */
+    partitionBy?: string | string[];
+    /** `ORDER BY` column(s), either plain names or `{ column, direction }`. */
+    orderBy?: (string | {
+        column: string;
+        direction?: 'ASC' | 'DESC';
+    })[];
+    /** Raw frame clause, e.g. `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`. */
+    frame?: string;
+}
+/** A `SELECT` attribute entry representing an aliased window-function expression. */
+export interface WindowAttribute {
+    window: WindowFunctionOptions;
+    as: string;
+}
+/**
+ * Db2 (LUW) dialect class implementing the shared Dialect interface.
+ */
+export declare class DB2Dialect implements Dialect {
+    readonly name = "db2";
+    readonly library = "ibm_db";
+    private pool;
+    private _isConnected;
+    private config;
+    private poolOptions;
+    private retryOptions;
+    private connectionString;
+    constructor(config: DB2DialectOptions);
+    /**
+     * Build the Db2 keyword=value connection string from structured options,
+     * unless a raw `connectionString` override was provided.
+     */
+    private buildConnectionString;
+    private withRetry;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Get the current connection pool
+     */
+    getConnection(): IbmDbPool | null;
+    isConnected(): boolean;
+    /**
+     * Execute `sql` against a specific, already-open connection (either a
+     * transaction's pinned connection or a freshly-opened pooled one) and
+     * normalize the result shape. This is the single execution path shared by
+     * `query()` for both transactional and non-transactional calls, so there is
+     * no divergence between how a plain `query()` call and a transactional one
+     * interpret results.
+     *
+     * Uses `queryResult`/`ODBCResult` (rather than the plain `query` helper) so
+     * affected-row counts for DML/DDL statements are available via
+     * `getAffectedRowsSync()`, matching how ibm_db surfaces this information for
+     * non-SELECT statements.
+     */
+    private executeOnConnection;
+    /**
+     * Stream query results by paging through `sql` via repeated
+     * dialect-appropriate LIMIT/OFFSET queries (see
+     * `createPaginatedQueryStream()` in `src/dialects/query-stream-helper.ts`)
+     * instead of loading the whole result set into memory at once.
+     * @param sql - The SELECT statement to stream
+     * @param options - Streaming options (batch size, backpressure watermark, model mapping)
+     */
+    queryStream(sql: string, options?: StreamOptions): Readable;
+    /**
+     * Execute a query.
+     *
+     * If `options.transaction` carries a `DB2Transaction` (as returned by
+     * `startTransaction()`), the statement is executed on that transaction's
+     * *pinned* connection instead of a fresh connection from the pool. This is
+     * required by `ibm_db`: transactions are tied to the specific connection
+     * that issued `beginTransaction()` (see DRIVER_NOTES.md section 6), so
+     * running statements on a different, autocommit-by-default pooled
+     * connection would make them commit independently of the transaction and
+     * never actually participate in it.
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    escape(value: any): string;
+    private formatDate;
+    /**
+     * Db2 uses double-quoted delimited identifiers (like Oracle/ANSI SQL).
+     * Unquoted identifiers are folded to uppercase by Db2, so identifiers
+     * created via quoteIdentifier()/escapeId() must always be quoted the
+     * same way on every reference.
+     */
+    escapeId(identifier: unknown): string;
+    quoteIdentifier(identifier: string): string;
+    quoteTable(tableName: string, schema?: string): string;
+    getDatabaseVersion(): Promise<string>;
+    createSchema(schema: string): Promise<void>;
+    /**
+     * Drop a schema. Db2 only supports `DROP SCHEMA ... RESTRICT` - the
+     * schema must already be empty, there is no CASCADE equivalent.
+     */
+    dropSchema(schema: string, options?: DropSchemaOptions): Promise<void>;
+    showAllSchemas(): Promise<string[]>;
+    listSchemas(): Promise<string[]>;
+    createDatabaseSQL(options: {
+        name: string;
+        encoding?: string;
+        tablespace?: string;
+    }): string;
+    dropDatabaseSQL(name: string): string;
+    createSavepointSQL(name?: string): string;
+    releaseSavepointSQL(name: string): string;
+    rollbackToSavepointSQL(name: string): string;
+    createExtension(): Promise<void>;
+    dropExtension(): Promise<void>;
+    getExtensions(): Promise<ExtensionInfo[]>;
+    hasExtension(): Promise<boolean>;
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: Db2TableOptions): Promise<void>;
+    private buildColumnDefinition;
+    private buildConstraintSql;
+    /**
+     * Builds the `COMPRESS ...` clause shared by `CREATE TABLE` and
+     * `ALTER TABLE` statements. Returns an empty string when `mode` is
+     * `undefined` (compression left unspecified), ` COMPRESS YES ADAPTIVE`
+     * / ` COMPRESS YES STATIC` for the respective modes, or ` COMPRESS NO`
+     * when explicitly disabled via `false`.
+     */
+    private buildCompressClause;
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * Bulk insert records into a table. Db2's `ibm_db` driver does not offer a
+     * multi-row VALUES shortcut that's meaningfully different from repeated
+     * single-row inserts sent through the ODBC layer, so each record is
+     * inserted individually within a single statement using multiple VALUES
+     * clauses (all Db2 LUW versions targeted here support multi-row INSERT).
+     */
+    bulkInsert(tableName: string, records: Record<string, any>[], options?: {
+        schema?: string;
+    }): Promise<QueryResult>;
+    createPartitionedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: Db2TableOptions & {
+        partitionBy: {
+            type: 'range' | 'list' | 'hash';
+            column: string | string[];
+        };
+        partitions?: {
+            name: string;
+            bound?: {
+                from: string | number | Date;
+                to?: string | number | Date;
+            };
+            tablespace?: string;
+        }[];
+    }): Promise<void>;
+    private formatPartitionBound;
+    createPartition(options: CreatePartitionOptions): Promise<void>;
+    attachPartition(options: AttachPartitionOptions): Promise<void>;
+    detachPartition(options: DetachPartitionOptions): Promise<void>;
+    dropPartition(partitionName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a system-period temporal table.
+     *
+     * Emits:
+     *   CREATE TABLE tableName (
+     *     ...columns...,
+     *     rowBeginColumn   TIMESTAMP(12) GENERATED ALWAYS AS ROW BEGIN NOT NULL,
+     *     rowEndColumn     TIMESTAMP(12) GENERATED ALWAYS AS ROW END NOT NULL,
+     *     [transactionIdColumn TIMESTAMP(12) GENERATED ALWAYS AS TRANSACTION START ID IMPLICITLY HIDDEN NOT NULL,]
+     *     PERIOD SYSTEM_TIME (rowBeginColumn, rowEndColumn)
+     *   );
+     *   CREATE TABLE historyTableName LIKE tableName;
+     *   ALTER TABLE tableName ADD VERSIONING USE HISTORY TABLE historyTableName;
+     *
+     * This is real Db2 LUW 10.5+ syntax - the hidden row-begin/row-end pair is
+     * declared via `GENERATED ALWAYS AS ROW BEGIN/END`, grouped into a
+     * `PERIOD SYSTEM_TIME`, and then wired to a (structurally identical)
+     * history table via `ADD VERSIONING`, after which the engine automatically
+     * moves the pre-update/pre-delete image of every row into the history
+     * table on every UPDATE/DELETE.
+     */
+    createSystemTemporalTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & {
+        historyTableName?: string;
+        rowBeginColumn?: string;
+        rowEndColumn?: string;
+        transactionIdColumn?: string;
+    }): Promise<void>;
+    /**
+     * Disable system-period versioning and drop both the base table and its
+     * history table (mirrors `createSystemTemporalTable`).
+     */
+    dropSystemTemporalTable(tableName: string, options?: {
+        historyTableName?: string;
+        ifExists?: boolean;
+        dropHistoryTable?: boolean;
+    }): Promise<void>;
+    /**
+     * Create an application-period ("business-time") temporal table.
+     *
+     * Emits:
+     *   CREATE TABLE tableName (
+     *     ...columns...,
+     *     businessStartColumn DATE NOT NULL,
+     *     businessEndColumn   DATE NOT NULL,
+     *     PERIOD BUSINESS_TIME (businessStartColumn, businessEndColumn)
+     *   );
+     *
+     * Unlike system-period tables, application-period tables are not
+     * automatically versioned by the engine - the application is responsible
+     * for setting/maintaining the business-time period on each row; Db2 only
+     * enforces `FOR PORTION OF BUSINESS_TIME` UPDATE/DELETE semantics and
+     * `WITHOUT OVERLAPS` constraints (optionally) on top of the declared
+     * period.
+     */
+    createApplicationTemporalTable(tableName: string, columns: Record<string, ColumnDefinition>, options: TableOptions & {
+        businessStartColumn: string;
+        businessEndColumn: string;
+        periodDataType?: string;
+        withoutOverlapsKey?: string[];
+    }): Promise<void>;
+    /**
+     * Format a point-in-time value for use in a `FOR SYSTEM_TIME`/
+     * `FOR BUSINESS_TIME` clause. Accepts a `Date`, or a raw SQL expression
+     * string (e.g. `'CURRENT TIMESTAMP'`, or an already-quoted literal) which
+     * is passed through unescaped so callers can supply expressions.
+     */
+    private formatTemporalTimestamp;
+    private formatTemporalDate;
+    /** Build a `FOR SYSTEM_TIME AS OF ...` clause. */
+    buildSystemTimeAsOfClause(asOf: string | Date): string;
+    /** Build a `FOR SYSTEM_TIME BETWEEN ... AND ...` clause (inclusive of both endpoints). */
+    buildSystemTimeBetweenClause(start: string | Date, end: string | Date): string;
+    /** Build a `FOR SYSTEM_TIME FROM ... TO ...` clause (end-exclusive). */
+    buildSystemTimeFromToClause(start: string | Date, end: string | Date): string;
+    /** Build a `FOR BUSINESS_TIME AS OF ...` clause. */
+    buildBusinessTimeAsOfClause(asOf: string | Date): string;
+    /** Build a `FOR BUSINESS_TIME BETWEEN ... AND ...` clause (inclusive). */
+    buildBusinessTimeBetweenClause(start: string | Date, end: string | Date): string;
+    /** Build a `FOR BUSINESS_TIME FROM ... TO ...` clause (end-exclusive). */
+    buildBusinessTimeFromToClause(start: string | Date, end: string | Date): string;
+    /**
+     * Compose whichever temporal clause(s) are present on an (extended)
+     * SelectOptions object into a single string suitable for insertion right
+     * after the table reference in a `FROM` clause. Not part of the shared
+     * `Dialect` interface's `SelectOptions` type - callers pass the temporal
+     * options as extra (untyped) properties, e.g.:
+     *
+     *   dialect.buildSelectQuery({
+     *     tableName: 'Employees',
+     *     systemTimeAsOf: new Date('2024-01-01T00:00:00Z'),
+     *   } as any)
+     */
+    private buildTemporalClause;
+    createView(viewName: string, query: string, options?: ViewOptions): Promise<void>;
+    dropView(viewName: string, options?: DropViewOptions): Promise<void>;
+    showViews(): Promise<string[]>;
+    createMaterializedView(options: MaterializedViewOptions): Promise<void>;
+    refreshMaterializedView(viewName: string, options?: RefreshOptions): Promise<void>;
+    dropMaterializedView(viewName: string, options?: DropMaterializedViewOptions): Promise<void>;
+    showMaterializedViews(): Promise<string[]>;
+    hasMaterializedView(viewName: string, schema?: string): Promise<boolean>;
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    /**
+     * Changes row compression on an existing table via
+     * `ALTER TABLE ... COMPRESS YES ADAPTIVE|STATIC|COMPRESS NO`.
+     *
+     * Per Db2 LUW, altering the COMPRESS attribute only affects rows written
+     * after the change; existing rows are only rewritten once the table is
+     * reorganized, so a `REORG TABLE` is issued afterwards to apply the new
+     * compression setting to existing data (failures are swallowed, mirroring
+     * `changeColumn`'s best-effort REORG, since REORG requires elevated
+     * privileges that may not be granted in every environment).
+     */
+    alterTableCompression(tableName: string, mode: 'ADAPTIVE' | 'STATIC' | false): Promise<void>;
+    addForeignKey(tableName: string, columnName: string, referencedTableName: string, referencedColumnName: string, options?: {
+        name?: string;
+        onDelete?: string;
+        onUpdate?: string;
+    }): Promise<void>;
+    describeTable(tableName: string): Promise<TableDescription>;
+    renameTable(oldName: string, newName: string): Promise<void>;
+    showTables(): Promise<string[]>;
+    showConstraints(tableName: string): Promise<any[]>;
+    addConstraint(tableName: string, options: {
+        type: 'UNIQUE' | 'CHECK' | 'PRIMARY KEY' | 'FOREIGN KEY';
+        fields: string[];
+        name?: string;
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        check?: string;
+    }): Promise<void>;
+    removeConstraint(tableName: string, constraintName: string): Promise<void>;
+    showIndexes(tableName: string): Promise<any[]>;
+    private buildCreateIndexSql;
+    addIndex(tableName: string, indexName: string, fields: string[], options?: IndexOptions): Promise<void>;
+    removeIndex(tableName: string, indexName: string): Promise<void>;
+    createIndex(tableName: string, indexDef: IndexDefinition): Promise<void>;
+    dropIndex(tableName: string, indexName: string, _options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    createFulltextIndex(): Promise<void>;
+    createSpatialIndex(): Promise<void>;
+    createConstraint(tableName: string, constraintDef: ConstraintDefinition): Promise<void>;
+    dropConstraint(tableName: string, constraintName: string, _options?: DropConstraintOptions): Promise<void>;
+    changeOwner(): Promise<void>;
+    /**
+     * Transfer ownership of a table (Db2's equivalent of changeOwner)
+     */
+    transferOwnership(tableName: string, newOwner: string): Promise<void>;
+    createForeignDataWrapper(fdwName: string, options?: {
+        handler?: string;
+    }): Promise<void>;
+    dropForeignDataWrapper(fdwName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    createForeignServer(serverName: string, fdwName: string, options?: {
+        options?: Record<string, string>;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    dropForeignServer(serverName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    createForeignTable(tableName: string, columns: Record<string, {
+        type: string;
+    }>, options?: {
+        serverName?: string;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    createUserMapping(userName: string, serverName: string, options?: {
+        username?: string;
+        password?: string;
+        options?: Record<string, string>;
+    }): Promise<void>;
+    dropUserMapping(userName: string, serverName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Build `CREATE SERVER` SQL.
+     *
+     * Db2 federation syntax:
+     *   CREATE SERVER server-name
+     *     [TYPE server-type] [VERSION 'server-version']
+     *     WRAPPER wrapper-name
+     *     [AUTHORIZATION auth-id PASSWORD password]
+     *     [OPTIONS (option-name 'value', ...)]
+     *
+     * `opts.options` may carry the reserved keys `TYPE`/`AUTHORIZATION`/
+     * `PASSWORD` (case-insensitive) which are extracted into their dedicated
+     * clauses rather than passed through the generic `OPTIONS(...)` list -
+     * see the section header comment above for why.
+     */
+    buildCreateServerQuery(name: string, opts: FdwForeignServerOptions): string;
+    /**
+     * Build `ALTER SERVER` SQL.
+     *
+     *   ALTER SERVER server-name
+     *     [VERSION 'server-version']
+     *     [OPTIONS ({ADD|SET|DROP} option-name ['value'], ...)]
+     */
+    buildAlterServerQuery(name: string, opts: FdwAlterForeignServerOptions): string;
+    /**
+     * Build `DROP SERVER` SQL. Db2's `DROP SERVER` has no `CASCADE`/`RESTRICT`
+     * clause - any nicknames referencing the server must be dropped first -
+     * so the `cascade` option (present only for interface compatibility with
+     * other dialects) has no SQL-level effect here.
+     */
+    buildDropServerQuery(name: string, _opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    /**
+     * Build `CREATE USER MAPPING` SQL.
+     *
+     *   CREATE USER MAPPING FOR { auth-id | USER | PUBLIC }
+     *     SERVER server-name
+     *     [OPTIONS (option-name 'value', ...)]
+     */
+    buildCreateUserMappingQuery(opts: FdwUserMappingOptions): string;
+    /**
+     * Build `ALTER USER MAPPING` SQL.
+     *
+     *   ALTER USER MAPPING FOR { auth-id | USER | PUBLIC }
+     *     SERVER server-name
+     *     OPTIONS ({ADD|SET|DROP} option-name ['value'], ...)
+     */
+    buildAlterUserMappingQuery(opts: FdwUserMappingOptions): string;
+    /**
+     * Build `DROP USER MAPPING` SQL.
+     *
+     *   DROP USER MAPPING FOR { auth-id | USER | PUBLIC } SERVER server-name
+     */
+    buildDropUserMappingQuery(serverName: string, user: string, _opts?: {
+        ifExists?: boolean;
+    }): string;
+    private formatMappingUserToken;
+    /**
+     * Build `CREATE NICKNAME` SQL - Db2's analogue of `CREATE FOREIGN TABLE`.
+     *
+     *   CREATE NICKNAME [schema.]nickname
+     *     FOR server-name.[remote-schema.]remote-table
+     *     [OPTIONS (option-name 'value', ...)]
+     *
+     * Db2 nicknames auto-discover their columns from the remote object rather
+     * than declaring them inline, so `opts.columns` isn't rendered here -
+     * `createForeignTable()` applies each supplied column as a follow-up
+     * `ALTER NICKNAME ... ALTER COLUMN ... LOCAL TYPE ...` statement instead.
+     * `opts.options` may carry the reserved keys `remoteSchema`/`remoteTable`
+     * (case-insensitive) to identify the remote object; if omitted, the local
+     * nickname name is used as the remote table name with no remote schema.
+     */
+    buildCreateForeignTableQuery(tableName: string, opts: FdwForeignTableOptions): string;
+    /**
+     * Build `DROP NICKNAME` SQL. Db2's `DROP NICKNAME` has no
+     * `CASCADE`/`RESTRICT` clause, so the `cascade` option (present only for
+     * interface compatibility) has no SQL-level effect here.
+     */
+    buildDropForeignTableQuery(tableName: string, _opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    /**
+     * Db2 has no bulk "discover and create nicknames for every table in a
+     * remote schema" statement analogous to Postgres' `IMPORT FOREIGN
+     * SCHEMA` - nicknames must be created one at a time via `CREATE NICKNAME`
+     * (see `createForeignTable`/`buildCreateForeignTableQuery`). This throws
+     * with that specific explanation rather than a blanket "federation isn't
+     * supported" message.
+     */
+    buildImportForeignSchemaQuery(_remoteSchema: string, _serverName: string, _opts?: FdwImportForeignSchemaOptions): string;
+    /**
+     * Return SQL to list all registered federation servers from the Db2
+     * catalog.
+     */
+    getServersQuery(): string;
+    createSecurityPolicy(policyName: string, tableName: string, options?: {
+        predicate?: string;
+    }): Promise<void>;
+    dropSecurityPolicy(policyName: string, _tableName: string): Promise<void>;
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(transaction: Transaction): Promise<void>;
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    getDataTypeSql(dataType: DataType): string;
+    private mapDataType;
+    buildWhereClause(where: WhereOptions, _options?: BuildOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildOrderClause(order: Order, _options?: BuildOptions): string;
+    /**
+     * Db2 LUW (9.7+) pagination uses the SQL standard
+     * `OFFSET n ROWS FETCH FIRST m ROWS ONLY` clause. OFFSET must precede
+     * FETCH FIRST when both are supplied.
+     */
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    buildInsertQuery(tableName: string, values: Record<string, any>, options?: InsertOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildUpdateQuery(tableName: string, values: Record<string, any>, where: WhereOptions, options?: UpdateOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build a `WITH name(columns) AS (base UNION ALL recursive)` prefix for a
+     * recursive common table expression. Db2 LUW has full standard recursive
+     * CTE support (self-referencing `WITH`, required `UNION ALL` between the
+     * seed and recursive branches).
+     */
+    buildRecursiveCteClause(cte: RecursiveCteOptions): string;
+    /**
+     * Build a full recursive-CTE `SELECT ... FROM cte-name` query in one call,
+     * combining `buildRecursiveCteClause` with `buildSelectQuery`.
+     */
+    buildRecursiveCteQuery(cte: RecursiveCteOptions, outer: Omit<SelectOptions, 'tableName'> & {
+        tableName?: string;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build an OLAP window/analytic function expression, e.g.:
+     *   ROW_NUMBER() OVER (PARTITION BY "dept" ORDER BY "salary" DESC)
+     *
+     * Db2 LUW has mature, standard window-function support (`ROW_NUMBER`,
+     * `RANK`, `DENSE_RANK`, `LAG`/`LEAD`, aggregate-as-window-function forms,
+     * frame clauses, etc.) since 9.x - this builds the `OVER (...)` clause
+     * generically so it works for any of them.
+     */
+    buildWindowFunction(options: WindowFunctionOptions): string;
+    buildSelectQuery(options: SelectOptions): {
+        sql: string;
+        values: any[];
+    };
+    /**
+     * Build an UPSERT query using Db2's `MERGE INTO ... WHEN MATCHED / WHEN
+     * NOT MATCHED` syntax against a single-row VALUES() source.
+     */
+    buildUpsertQuery(tableName: string, values: Record<string, any>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: any[];
+    };
+    buildIncrementQuery(tableName: string, fields: string | string[] | Record<string, number>, where: WhereOptions, options?: {
+        by?: number;
+    }): {
+        sql: string;
+        values: any[];
+    };
+    replaceReplacements(sql: string, replacements?: Record<string, unknown> | unknown[]): string;
+    buildCreateUserQuery(): string;
+    buildAlterUserQuery(): string;
+    buildDropUserQuery(): string;
+    getUsersQuery(): string;
+    buildGrantQuery(options: {
+        privileges: string[] | string;
+        on: string;
+        to: string;
+        withGrantOption?: boolean;
+    }): string;
+    buildRevokeQuery(options: {
+        privileges: string[] | string;
+        on: string;
+        from: string;
+    }): string;
+    buildShowGrantsQuery(username: string): string;
+    buildFlushPrivilegesQuery(): string;
+    buildCreateRoleQuery(roleName: string): string;
+    buildDropRoleQuery(roleName: string): string;
+    buildGrantRoleQuery(role: string, to: string): string;
+    buildRevokeRoleQuery(role: string, from: string): string;
+    getRolesQuery(): string;
+    createSequence(options: SequenceOptions): Promise<void>;
+    dropSequence(sequenceName: string, options?: DropSequenceOptions): Promise<void>;
+    nextSequenceValue(sequenceName: string): Promise<number>;
+    currSequenceValue(sequenceName: string): Promise<number>;
+    hasSequence(sequenceName: string, schema?: string): Promise<boolean>;
+    listSequences(): Promise<string[]>;
+    createStoredProcedure(options: StoredProcedureOptions): Promise<void>;
+    dropStoredProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    dropProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    createProcedure(options: StoredProcedureOptions): Promise<void>;
+    executeStoredProcedure(options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
+    hasStoredProcedure(procedureName: string, schema?: string): Promise<boolean>;
+    createTrigger(options: TriggerOptions): Promise<void>;
+    dropTrigger(triggerName: string, _tableName: string, options?: DropTriggerOptions): Promise<void>;
+    hasTrigger(triggerName: string, tableName: string, schema?: string): Promise<boolean>;
+    createPolicy(options: PolicyOptions): Promise<void>;
+    dropPolicy(policyName: string, _tableName: string, options?: DropPolicyOptions): Promise<void>;
+    enableRLS(tableName: string, schema?: string): Promise<void>;
+    disableRLS(tableName: string, schema?: string): Promise<void>;
+    hasPolicy(policyName: string, _tableName: string): Promise<boolean>;
+    commentTable(tableName: string, comment: string): Promise<void>;
+    commentColumn(tableName: string, columnName: string, comment: string): Promise<void>;
+    /**
+     * Build a JSON_TABLE expression to shred a JSON document/array into relational rows.
+     * Db2 for LUW added the SQL/JSON standard `JSON_TABLE` function in 11.5.6+ (Mod Pack 6),
+     * with syntax matching Oracle/MySQL: JSON_TABLE(expr, path COLUMNS(name type PATH path, ...)).
+     * On earlier Db2 versions this function does not exist and callers must fall back to
+     * `JSON_VAL`/`SYSTOOLS.JSON2BSON` based workarounds instead.
+     */
+    buildJsonTable(jsonExpression: string, rowPath: string, columns: Array<{
+        name: string;
+        type?: string;
+        path?: string;
+        forOrdinality?: boolean;
+    }>, alias: string): string;
+    /**
+     * Build a `JSON_VALUE(column, 'path' RETURNING type)` scalar accessor
+     * (Db2 11.5+). `path` may be a dot path (`address.city`) or an explicit
+     * SQL/JSON path (`$.address.city`); the former is normalized to the latter.
+     */
+    buildJsonValue(column: string, path: string, options?: {
+        returning?: string;
+    }): string;
+    /**
+     * Build a Db2 `LISTAGG(expr, delimiter) WITHIN GROUP (ORDER BY ...)`
+     * expression — Db2's string-aggregation idiom (distinct from MySQL's
+     * `GROUP_CONCAT` and Postgres' `STRING_AGG`).
+     */
+    listAgg(expr: string, delimiter?: string, orderBy?: string): string;
+    /**
+     * Build a Db2 `XMLAGG(XMLELEMENT(NAME tag, expr) ORDER BY ...)` expression for
+     * aggregating rows into an XML fragment (pureXML).
+     */
+    xmlAgg(expr: string, elementName?: string, orderBy?: string): string;
+    /**
+     * Build a Db2 `XMLQUERY('xquery' PASSING column)` expression to evaluate an
+     * XQuery/XPath expression against a pureXML column.
+     */
+    buildXmlQuery(column: string, xquery: string): string;
+    /**
+     * Build a Db2 `XMLEXISTS('xquery' PASSING column)` predicate to test whether
+     * an XQuery/XPath matches anything in a pureXML column — for WHERE clauses.
+     */
+    buildXmlExists(column: string, xquery: string): string;
+    /**
+     * Build a Db2 `XMLTABLE(...)` expression to shred a pureXML document into
+     * relational rows, analogous to `JSON_TABLE` for XML.
+     */
+    buildXmlTable(rowXQuery: string, passing: string, columns: Array<{
+        name: string;
+        type?: string;
+        path?: string;
+        forOrdinality?: boolean;
+    }>, alias: string): string;
+    /**
+     * Create a Db2 global (or session-scoped) variable
+     * (`CREATE VARIABLE name type [DEFAULT ...]`).
+     */
+    createVariable(name: string, type: string, options?: {
+        default?: string | number | boolean;
+        orReplace?: boolean;
+    }): Promise<void>;
+    /** Drop a Db2 global variable (`DROP VARIABLE name`). */
+    dropVariable(name: string): Promise<void>;
+    /** Assign a value to a Db2 global/session variable (`SET name = value`). */
+    setVariable(name: string, value: unknown): Promise<void>;
+    /**
+     * Build the trailing table-organization clause for a Db2 `CREATE TABLE`:
+     * `ORGANIZE BY COLUMN` (BLU Acceleration column-organized) or
+     * `ORGANIZE BY DIMENSIONS (col, ...)` (Multidimensional Clustering / MDC).
+     * Returns an empty string when neither is requested.
+     */
+    buildOrganizeByClause(options: {
+        organizeBy?: 'row' | 'column';
+        dimensions?: string[];
+    }): string;
+    /**
+     * Create a column-organized (BLU Acceleration) table by appending
+     * `ORGANIZE BY COLUMN` (or `ORGANIZE BY DIMENSIONS (...)` for MDC) to a
+     * standard `CREATE TABLE`. Convenience wrapper for analytics workloads.
+     */
+    createColumnOrganizedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: Db2TableOptions & {
+        dimensions?: string[];
+    }): Promise<void>;
+}