ts-prorm-orm 1.1.0

package/dist/dialects/db2/index.js

@@ -0,0 +1,2225 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DB2Dialect = void 0;
+const ibm_db_1 = require("ibm_db");
+const query_stream_helper_1 = require("../query-stream-helper");
+const prorm_1 = require("../../prorm");
+/**
+ * Db2-specific transaction class.
+ * Db2 transactions (via ibm_db) are tied to a specific connection - the
+ * connection used to BEGIN the transaction must be the one used to COMMIT
+ * or ROLLBACK it.
+ */
+class DB2Transaction {
+    constructor(connection, options) {
+        this.finished = false;
+        this.parent = null;
+        this.savepoints = [];
+        this.connection = null;
+        this.id = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.options = options || {};
+        this.connection = connection;
+    }
+    async commit() {
+        this.finished = true;
+    }
+    async rollback() {
+        this.finished = true;
+    }
+}
+const DEFAULT_POOL_OPTIONS = {
+    max: 10,
+    min: 0,
+};
+const DEFAULT_RETRY_OPTIONS = {
+    max: 3,
+    timeout: 1000,
+    match: [
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'ETIMEDOUT',
+        'SQL30081N',
+        'SQL30061N',
+        'SQL1224N',
+        'Connection timed out',
+    ],
+    backoff: false,
+    backoffMultiplier: 2,
+    backoffMax: 10000,
+};
+/**
+ * Db2 (LUW) dialect class implementing the shared Dialect interface.
+ */
+class DB2Dialect {
+    constructor(config) {
+        this.name = 'db2';
+        this.library = 'ibm_db';
+        this.pool = null;
+        this._isConnected = false;
+        this.poolOptions = config.pool || {};
+        this.retryOptions = config.retry || {};
+        this.config = {
+            host: 'localhost',
+            port: 50000,
+            database: 'testdb',
+            username: 'db2inst1',
+            password: '',
+            ...config,
+        };
+        this.connectionString = this.buildConnectionString(this.config);
+    }
+    /**
+     * Build the Db2 keyword=value connection string from structured options,
+     * unless a raw `connectionString` override was provided.
+     */
+    buildConnectionString(config) {
+        if (config.connectionString) {
+            return config.connectionString;
+        }
+        const parts = [
+            `DATABASE=${config.database}`,
+            `HOSTNAME=${config.host}`,
+            `PORT=${config.port}`,
+            'PROTOCOL=TCPIP',
+            `UID=${config.username}`,
+            `PWD=${config.password}`,
+        ];
+        if (config.ssl) {
+            parts.push('SECURITY=SSL');
+        }
+        if (config.extraConnectionParams) {
+            for (const [key, value] of Object.entries(config.extraConnectionParams)) {
+                parts.push(`${key}=${value}`);
+            }
+        }
+        return `${parts.join(';')};`;
+    }
+    async withRetry(fn) {
+        const retryConfig = { ...DEFAULT_RETRY_OPTIONS, ...this.retryOptions };
+        let lastError;
+        const max = retryConfig.max ?? 3;
+        const match = retryConfig.match ?? [];
+        const timeout = retryConfig.timeout ?? 1000;
+        for (let attempt = 0; attempt <= max; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                const errorMessage = lastError.message;
+                const shouldRetry = match.some((pattern) => errorMessage.toLowerCase().includes(pattern.toLowerCase()));
+                if (!shouldRetry || attempt === max) {
+                    throw lastError;
+                }
+                let delay = timeout;
+                if (retryConfig.backoff) {
+                    delay = Math.min(timeout * Math.pow(retryConfig.backoffMultiplier || 2, attempt), retryConfig.backoffMax || 10000);
+                }
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        throw lastError;
+    }
+    async connect() {
+        await this.withRetry(async () => {
+            const pool = new ibm_db_1.Pool();
+            pool.setMaxPoolSize(this.poolOptions.max || DEFAULT_POOL_OPTIONS.max);
+            // Verify connectivity by opening and immediately releasing a connection.
+            const conn = await pool.open(this.connectionString);
+            await conn.close();
+            this.pool = pool;
+            this._isConnected = true;
+        });
+    }
+    async disconnect() {
+        if (this.pool) {
+            await this.pool.close();
+            this.pool = null;
+            this._isConnected = false;
+        }
+    }
+    /**
+     * Get the current connection pool
+     */
+    getConnection() {
+        return this.pool;
+    }
+    isConnected() {
+        return this._isConnected && this.pool !== null;
+    }
+    /**
+     * 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.
+     */
+    async executeOnConnection(conn, sql, params) {
+        // Cast to bypass the driver's overloaded (sql, params, cb) / (sql, cb)
+        // signatures - at runtime, calling with (sql, params) resolves to the
+        // Promise-returning overload.
+        const [result, outParams] = await conn.queryResult(sql, params);
+        const isSelect = /^\s*(SELECT|WITH|VALUES)\b/i.test(sql.trim());
+        if (result) {
+            const rows = isSelect ? (await result.fetchAll()) : [];
+            const rowCount = isSelect ? rows.length : result.getAffectedRowsSync();
+            await result.close();
+            return { rows, rowCount, fields: [] };
+        }
+        const rows = Array.isArray(outParams) ? outParams : [];
+        return { rows: isSelect ? rows : [], rowCount: rows.length, fields: [] };
+    }
+    /**
+     * 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, options) {
+        return (0, query_stream_helper_1.createPaginatedQueryStream)(this, sql, options);
+    }
+    /**
+     * 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.
+     */
+    async query(sql, options) {
+        const bindValues = options?.replacements ?? options?.bindings ?? options?.bind ?? [];
+        const params = Array.isArray(bindValues) ? bindValues : Object.values(bindValues);
+        const tx = options?.transaction;
+        if (tx) {
+            if (tx.finished) {
+                throw new Error('Cannot execute query: the transaction has already been committed or rolled back.');
+            }
+            if (!tx.connection) {
+                throw new Error('Cannot execute query: the transaction has no associated connection.');
+            }
+            // Run on the transaction's pinned connection - do NOT close it here;
+            // it is closed by commitTransaction()/rollbackTransaction().
+            return this.executeOnConnection(tx.connection, sql, params);
+        }
+        if (!this.pool) {
+            throw new Error('Not connected to database. Call connect() first.');
+        }
+        const conn = await this.pool.open(this.connectionString);
+        try {
+            return await this.executeOnConnection(conn, sql, params);
+        }
+        finally {
+            await conn.close();
+        }
+    }
+    escape(value) {
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        if (value === null || value === undefined)
+            return 'NULL';
+        if (typeof value === 'boolean')
+            return value ? '1' : '0';
+        if (typeof value === 'number')
+            return String(value);
+        if (value instanceof Date)
+            return this.formatDate(value);
+        if (Buffer.isBuffer(value))
+            return `BLOB(X'${value.toString('hex')}')`;
+        if (Array.isArray(value) || typeof value === 'object') {
+            return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+        }
+        return `'${String(value).replace(/'/g, "''")}'`;
+    }
+    formatDate(date) {
+        const year = date.getFullYear();
+        const month = String(date.getMonth() + 1).padStart(2, '0');
+        const day = String(date.getDate()).padStart(2, '0');
+        const hours = String(date.getHours()).padStart(2, '0');
+        const minutes = String(date.getMinutes()).padStart(2, '0');
+        const seconds = String(date.getSeconds()).padStart(2, '0');
+        const microseconds = String(date.getMilliseconds()).padStart(3, '0') + '000';
+        return `TIMESTAMP '${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${microseconds}'`;
+    }
+    /**
+     * 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) {
+        const id = String(identifier ?? '');
+        return `"${id.replace(/"/g, '""')}"`;
+    }
+    quoteIdentifier(identifier) {
+        return this.escapeId(identifier);
+    }
+    quoteTable(tableName, schema) {
+        const schemaName = schema || this.config.schema;
+        if (schemaName) {
+            return `${this.escapeId(schemaName)}.${this.escapeId(tableName)}`;
+        }
+        return this.escapeId(tableName);
+    }
+    async getDatabaseVersion() {
+        const result = await this.query('SELECT SERVICE_LEVEL AS VERSION FROM SYSIBMADM.ENV_INST_INFO');
+        return result.rows[0]?.VERSION || result.rows[0]?.version || 'unknown';
+    }
+    // ==================== Schema Operations ====================
+    async createSchema(schema) {
+        await this.query(`CREATE SCHEMA ${this.escapeId(schema)}`);
+    }
+    /**
+     * Drop a schema. Db2 only supports `DROP SCHEMA ... RESTRICT` - the
+     * schema must already be empty, there is no CASCADE equivalent.
+     */
+    async dropSchema(schema, options) {
+        let sql = 'DROP SCHEMA';
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT SCHEMANAME FROM SYSCAT.SCHEMATA WHERE SCHEMANAME = '${schema}'`);
+            if (!exists.rows || exists.rows.length === 0) {
+                return;
+            }
+        }
+        sql += ` ${this.escapeId(schema)} RESTRICT`;
+        await this.query(sql);
+    }
+    async showAllSchemas() {
+        const result = await this.query('SELECT SCHEMANAME FROM SYSCAT.SCHEMATA ORDER BY SCHEMANAME');
+        return result.rows.map((row) => row.SCHEMANAME || row.schemaname);
+    }
+    async listSchemas() {
+        return this.showAllSchemas();
+    }
+    createDatabaseSQL(options) {
+        // Db2 databases are usually created via the `db2 CREATE DATABASE` CLP
+        // command rather than plain SQL, but Db2 also accepts this form via CLI.
+        let sql = `CREATE DATABASE ${options.name}`;
+        if (options.encoding) {
+            sql += ` USING CODESET ${options.encoding}`;
+        }
+        return sql;
+    }
+    dropDatabaseSQL(name) {
+        return `DROP DATABASE ${name}`;
+    }
+    createSavepointSQL(name) {
+        const savepointName = name || `sp_${Date.now()}`;
+        return `SAVEPOINT ${savepointName} ON ROLLBACK RETAIN CURSORS`;
+    }
+    releaseSavepointSQL(name) {
+        return `RELEASE SAVEPOINT ${name}`;
+    }
+    rollbackToSavepointSQL(name) {
+        return `ROLLBACK TO SAVEPOINT ${name}`;
+    }
+    // ==================== Extensions (Not Supported) ====================
+    async createExtension() {
+        throw new Error('Extensions are not supported by Db2. This is a PostgreSQL-specific feature. Use Db2 modules/features instead.');
+    }
+    async dropExtension() {
+        throw new Error('Extensions are not supported by Db2. This is a PostgreSQL-specific feature. Use Db2 modules/features instead.');
+    }
+    async getExtensions() {
+        throw new Error('Extensions are not supported by Db2. This is a PostgreSQL-specific feature. Use Db2 modules/features instead.');
+    }
+    async hasExtension() {
+        throw new Error('Extensions are not supported by Db2. This is a PostgreSQL-specific feature. Use Db2 modules/features instead.');
+    }
+    // ==================== Table Operations ====================
+    async createTable(tableName, columns, options) {
+        const columnDefs = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            columnDefs.push(this.buildColumnDefinition(columnName, definition));
+        }
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql)
+                    columnDefs.push(constraintSql);
+            }
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.quoteTable(tableName)} (${columnDefs.join(', ')})`;
+        if (options?.tablespace) {
+            sql += ` IN ${options.tablespace}`;
+        }
+        sql += this.buildCompressClause(options?.compress);
+        await this.query(sql);
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.createIndex(tableName, {
+                    name: index.name || `${tableName}_${index.fields.join('_')}_idx`,
+                    fields: index.fields,
+                    unique: index.unique,
+                    type: index.type,
+                });
+            }
+        }
+    }
+    buildColumnDefinition(columnName, definition) {
+        let sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type)}`;
+        if (definition.autoIncrement) {
+            sql += ' GENERATED ALWAYS AS IDENTITY (START WITH 1, INCREMENT BY 1)';
+        }
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.defaultValue !== undefined && !definition.autoIncrement) {
+            if (definition.defaultValue === null) {
+                sql += ' DEFAULT NULL';
+            }
+            else if (definition.defaultValue instanceof prorm_1.Literal) {
+                sql += ` DEFAULT ${definition.defaultValue.val}`;
+            }
+            else {
+                sql += ` DEFAULT ${this.escape(definition.defaultValue)}`;
+            }
+        }
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.unique) {
+            if (typeof definition.unique === 'string') {
+                sql += ` UNIQUE`;
+            }
+            else {
+                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.quoteTable(definition.references.table)}${refFieldSql}`;
+            if (definition.references.onDelete) {
+                sql += ` ON DELETE ${definition.references.onDelete.toUpperCase()}`;
+            }
+            if (definition.references.onUpdate) {
+                sql += ` ON UPDATE ${definition.references.onUpdate.toUpperCase()}`;
+            }
+        }
+        return sql;
+    }
+    buildConstraintSql(constraint) {
+        const name = constraint.name ? `CONSTRAINT ${this.escapeId(constraint.name)} ` : '';
+        const fields = constraint.fields?.map((f) => this.escapeId(f)).join(', ') || '';
+        switch (constraint.type) {
+            case 'PRIMARY KEY':
+                return `${name}PRIMARY KEY (${fields})`;
+            case 'UNIQUE':
+                return `${name}UNIQUE (${fields})`;
+            case 'CHECK':
+                return `${name}CHECK (${constraint.check})`;
+            case 'FOREIGN KEY': {
+                if (!constraint.references)
+                    return null;
+                const refField = constraint.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                    : `(${this.escapeId(refField)})`;
+                let fkSql = `${name}FOREIGN KEY (${fields}) REFERENCES ${this.quoteTable(constraint.references.table)}${refFieldSql}`;
+                if (constraint.references.onDelete) {
+                    fkSql += ` ON DELETE ${constraint.references.onDelete.toUpperCase()}`;
+                }
+                if (constraint.references.onUpdate) {
+                    fkSql += ` ON UPDATE ${constraint.references.onUpdate.toUpperCase()}`;
+                }
+                return fkSql;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * 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`.
+     */
+    buildCompressClause(mode) {
+        if (mode === undefined)
+            return '';
+        if (mode === false)
+            return ' COMPRESS NO';
+        return ` COMPRESS YES ${mode}`;
+    }
+    async dropTable(tableName, options) {
+        let sql = 'DROP TABLE';
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT TABNAME FROM SYSCAT.TABLES WHERE TABNAME = '${tableName}'`);
+            if (!exists.rows || exists.rows.length === 0) {
+                return;
+            }
+        }
+        sql += ` ${this.quoteTable(tableName)}`;
+        await this.query(sql);
+    }
+    /**
+     * 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).
+     */
+    async bulkInsert(tableName, records, options) {
+        if (records.length === 0) {
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        const columns = Object.keys(records[0]);
+        const values = [];
+        const rowPlaceholders = [];
+        for (const record of records) {
+            const placeholders = [];
+            for (const column of columns) {
+                placeholders.push('?');
+                values.push(record[column]);
+            }
+            rowPlaceholders.push(`(${placeholders.join(', ')})`);
+        }
+        const sql = `INSERT INTO ${this.quoteTable(tableName, options?.schema)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES ${rowPlaceholders.join(', ')}`;
+        return this.query(sql, { replacements: values });
+    }
+    // Db2 LUW range partitioning is expressed via `PARTITION BY RANGE(...)` on
+    // the base CREATE TABLE statement (there's no separate list/hash
+    // partitioning syntax as with PostgreSQL/Oracle).
+    async createPartitionedTable(tableName, columns, options) {
+        if (options?.partitionBy?.type !== 'range') {
+            throw new Error('Db2 only supports RANGE partitioning for CREATE TABLE ... PARTITION BY');
+        }
+        const columnDefs = Object.entries(columns).map(([columnName, definition]) => this.buildColumnDefinition(columnName, definition));
+        const partitionColumn = Array.isArray(options.partitionBy.column)
+            ? options.partitionBy.column.join(', ')
+            : options.partitionBy.column;
+        let sql = `CREATE TABLE ${this.quoteTable(tableName)} (${columnDefs.join(', ')})`;
+        if (options.tablespace) {
+            sql += ` IN ${options.tablespace}`;
+        }
+        sql += this.buildCompressClause(options.compress);
+        sql += ` PARTITION BY RANGE (${this.escapeId(partitionColumn)}) (`;
+        const partitionDefs = (options.partitions || []).map((part) => {
+            let def = `PARTITION ${this.escapeId(part.name)} STARTING FROM (${this.formatPartitionBound(part.bound?.from)})`;
+            if (part.bound?.to !== undefined) {
+                def += ` ENDING AT (${this.formatPartitionBound(part.bound.to)})`;
+            }
+            if (part.tablespace) {
+                def += ` IN ${part.tablespace}`;
+            }
+            return def;
+        });
+        sql += partitionDefs.join(', ');
+        sql += ')';
+        await this.query(sql);
+    }
+    formatPartitionBound(value) {
+        if (value === undefined)
+            return 'MINVALUE';
+        if (value instanceof Date)
+            return this.escape(value);
+        if (typeof value === 'number')
+            return String(value);
+        return this.escape(value);
+    }
+    async createPartition(options) {
+        let sql = `ALTER TABLE ${this.quoteTable(options.parentTable)} ADD PARTITION ${this.escapeId(options.name)}`;
+        if (options.bound && 'from' in options.bound) {
+            sql += ` STARTING FROM (${this.formatPartitionBound(options.bound.from)})`;
+            if (options.bound.to !== undefined) {
+                sql += ` ENDING AT (${this.formatPartitionBound(options.bound.to)})`;
+            }
+        }
+        if (options.tablespace) {
+            sql += ` IN ${options.tablespace}`;
+        }
+        await this.query(sql);
+    }
+    async attachPartition(options) {
+        // Db2 uses ALTER TABLE ... ATTACH PARTITION ... FROM TABLE ...
+        await this.query(`ALTER TABLE ${this.quoteTable(options.parentTable)} ATTACH PARTITION ${this.escapeId(options.partitionName)} FROM TABLE ${this.quoteTable(options.partitionName)}`);
+    }
+    async detachPartition(options) {
+        await this.query(`ALTER TABLE ${this.quoteTable(options.partitionName)} DETACH PARTITION ${this.escapeId(options.partitionName)}`);
+    }
+    async dropPartition(partitionName, options) {
+        let sql = `ALTER TABLE ${this.quoteTable(partitionName)} DROP PARTITION ${this.escapeId(partitionName)}`;
+        await this.query(sql);
+    }
+    // ==================== Temporal Tables ====================
+    // Db2 for LUW's bitemporal support: system-period temporal tables track
+    // *every* change to a row automatically (row-begin/row-end timestamps
+    // maintained by the engine, with prior versions moved to a linked history
+    // table), while application-period ("business-time") temporal tables let
+    // the application itself declare the period during which a row is
+    // considered valid/effective. The two can be combined on the same table
+    // for full bitemporal support, but are modeled here as separate entry
+    // points since most callers only need one or the other.
+    /**
+     * 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.
+     */
+    async createSystemTemporalTable(tableName, columns, options) {
+        const rowBeginColumn = options?.rowBeginColumn || 'SYS_START';
+        const rowEndColumn = options?.rowEndColumn || 'SYS_END';
+        const historyTableName = options?.historyTableName || `${tableName}_HISTORY`;
+        const columnDefs = Object.entries(columns).map(([columnName, definition]) => this.buildColumnDefinition(columnName, definition));
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql)
+                    columnDefs.push(constraintSql);
+            }
+        }
+        columnDefs.push(`${this.escapeId(rowBeginColumn)} TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW BEGIN`);
+        columnDefs.push(`${this.escapeId(rowEndColumn)} TIMESTAMP(12) NOT NULL GENERATED ALWAYS AS ROW END`);
+        if (options?.transactionIdColumn) {
+            columnDefs.push(`${this.escapeId(options.transactionIdColumn)} TIMESTAMP(12) GENERATED ALWAYS AS TRANSACTION START ID IMPLICITLY HIDDEN NOT NULL`);
+        }
+        columnDefs.push(`PERIOD SYSTEM_TIME (${this.escapeId(rowBeginColumn)}, ${this.escapeId(rowEndColumn)})`);
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.quoteTable(tableName)} (${columnDefs.join(', ')})`;
+        await this.query(sql);
+        await this.query(`CREATE TABLE ${this.quoteTable(historyTableName)} LIKE ${this.quoteTable(tableName)}`);
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD VERSIONING USE HISTORY TABLE ${this.quoteTable(historyTableName)}`);
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.createIndex(tableName, {
+                    name: index.name || `${tableName}_${index.fields.join('_')}_idx`,
+                    fields: index.fields,
+                    unique: index.unique,
+                    type: index.type,
+                });
+            }
+        }
+    }
+    /**
+     * Disable system-period versioning and drop both the base table and its
+     * history table (mirrors `createSystemTemporalTable`).
+     */
+    async dropSystemTemporalTable(tableName, options) {
+        const historyTableName = options?.historyTableName || `${tableName}_HISTORY`;
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT TABNAME FROM SYSCAT.TABLES WHERE TABNAME = '${tableName}'`);
+            if (!exists.rows || exists.rows.length === 0)
+                return;
+        }
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP VERSIONING`);
+        await this.query(`DROP TABLE ${this.quoteTable(tableName)}`);
+        if (options?.dropHistoryTable !== false) {
+            await this.query(`DROP TABLE ${this.quoteTable(historyTableName)}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async createApplicationTemporalTable(tableName, columns, options) {
+        const { businessStartColumn, businessEndColumn, periodDataType } = options;
+        const periodType = periodDataType || 'DATE';
+        const columnDefs = Object.entries(columns).map(([columnName, definition]) => this.buildColumnDefinition(columnName, definition));
+        if (options.constraints) {
+            for (const constraint of options.constraints) {
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql)
+                    columnDefs.push(constraintSql);
+            }
+        }
+        columnDefs.push(`${this.escapeId(businessStartColumn)} ${periodType} NOT NULL`);
+        columnDefs.push(`${this.escapeId(businessEndColumn)} ${periodType} NOT NULL`);
+        columnDefs.push(`PERIOD BUSINESS_TIME (${this.escapeId(businessStartColumn)}, ${this.escapeId(businessEndColumn)})`);
+        if (options.withoutOverlapsKey && options.withoutOverlapsKey.length > 0) {
+            const keyFields = options.withoutOverlapsKey.map((f) => this.escapeId(f)).join(', ');
+            columnDefs.push(`PRIMARY KEY (${keyFields}, BUSINESS_TIME WITHOUT OVERLAPS)`);
+        }
+        let sql = 'CREATE TABLE';
+        if (options.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.quoteTable(tableName)} (${columnDefs.join(', ')})`;
+        await this.query(sql);
+        if (options.indexes) {
+            for (const index of options.indexes) {
+                await this.createIndex(tableName, {
+                    name: index.name || `${tableName}_${index.fields.join('_')}_idx`,
+                    fields: index.fields,
+                    unique: index.unique,
+                    type: index.type,
+                });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    formatTemporalTimestamp(value) {
+        if (value instanceof Date) {
+            const iso = value.toISOString(); // e.g. 2024-01-01T00:00:00.000Z
+            const datePart = iso.slice(0, 10); // 2024-01-01
+            const timePart = iso.slice(11, 23).replace(/:/g, '.'); // 00.00.00.000
+            const db2Ts = `${datePart}-${timePart}000`; // pad ms -> microseconds
+            return `TIMESTAMP('${db2Ts}')`;
+        }
+        const trimmed = value.trim();
+        if (/^current[\s_]timestamp$/i.test(trimmed))
+            return 'CURRENT TIMESTAMP';
+        // Already a function call / expression (contains parens or is a bind
+        // placeholder) - pass through verbatim.
+        if (/[(?]/.test(trimmed))
+            return trimmed;
+        return `TIMESTAMP('${trimmed.replace(/'/g, "''")}')`;
+    }
+    formatTemporalDate(value) {
+        if (value instanceof Date) {
+            return `DATE('${value.toISOString().slice(0, 10)}')`;
+        }
+        const trimmed = value.trim();
+        if (/^current[\s_]date$/i.test(trimmed))
+            return 'CURRENT DATE';
+        if (/[(?]/.test(trimmed))
+            return trimmed;
+        return `DATE('${trimmed.replace(/'/g, "''")}')`;
+    }
+    /** Build a `FOR SYSTEM_TIME AS OF ...` clause. */
+    buildSystemTimeAsOfClause(asOf) {
+        return `FOR SYSTEM_TIME AS OF ${this.formatTemporalTimestamp(asOf)}`;
+    }
+    /** Build a `FOR SYSTEM_TIME BETWEEN ... AND ...` clause (inclusive of both endpoints). */
+    buildSystemTimeBetweenClause(start, end) {
+        return `FOR SYSTEM_TIME BETWEEN ${this.formatTemporalTimestamp(start)} AND ${this.formatTemporalTimestamp(end)}`;
+    }
+    /** Build a `FOR SYSTEM_TIME FROM ... TO ...` clause (end-exclusive). */
+    buildSystemTimeFromToClause(start, end) {
+        return `FOR SYSTEM_TIME FROM ${this.formatTemporalTimestamp(start)} TO ${this.formatTemporalTimestamp(end)}`;
+    }
+    /** Build a `FOR BUSINESS_TIME AS OF ...` clause. */
+    buildBusinessTimeAsOfClause(asOf) {
+        return `FOR BUSINESS_TIME AS OF ${this.formatTemporalDate(asOf)}`;
+    }
+    /** Build a `FOR BUSINESS_TIME BETWEEN ... AND ...` clause (inclusive). */
+    buildBusinessTimeBetweenClause(start, end) {
+        return `FOR BUSINESS_TIME BETWEEN ${this.formatTemporalDate(start)} AND ${this.formatTemporalDate(end)}`;
+    }
+    /** Build a `FOR BUSINESS_TIME FROM ... TO ...` clause (end-exclusive). */
+    buildBusinessTimeFromToClause(start, end) {
+        return `FOR BUSINESS_TIME FROM ${this.formatTemporalDate(start)} TO ${this.formatTemporalDate(end)}`;
+    }
+    /**
+     * 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)
+     */
+    buildTemporalClause(options) {
+        const clauses = [];
+        if (options.systemTimeAsOf !== undefined) {
+            clauses.push(this.buildSystemTimeAsOfClause(options.systemTimeAsOf));
+        }
+        else if (options.systemTimeBetween !== undefined) {
+            const [start, end] = options.systemTimeBetween;
+            clauses.push(this.buildSystemTimeBetweenClause(start, end));
+        }
+        else if (options.systemTimeFromTo !== undefined) {
+            const [start, end] = options.systemTimeFromTo;
+            clauses.push(this.buildSystemTimeFromToClause(start, end));
+        }
+        if (options.businessTimeAsOf !== undefined) {
+            clauses.push(this.buildBusinessTimeAsOfClause(options.businessTimeAsOf));
+        }
+        else if (options.businessTimeBetween !== undefined) {
+            const [start, end] = options.businessTimeBetween;
+            clauses.push(this.buildBusinessTimeBetweenClause(start, end));
+        }
+        else if (options.businessTimeFromTo !== undefined) {
+            const [start, end] = options.businessTimeFromTo;
+            clauses.push(this.buildSystemTimeFromToClause(start, end));
+        }
+        return clauses.length > 0 ? ` ${clauses.join(' ')}` : '';
+    }
+    // ==================== View Operations ====================
+    async createView(viewName, query, options) {
+        if (options?.replace) {
+            await this.query(`DROP VIEW ${this.escapeId(viewName)}`).catch(() => undefined);
+        }
+        const sql = `CREATE VIEW ${this.escapeId(viewName)} AS ${query}`;
+        await this.query(sql);
+    }
+    async dropView(viewName, options) {
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT VIEWNAME FROM SYSCAT.VIEWS WHERE VIEWNAME = '${viewName}'`);
+            if (!exists.rows || exists.rows.length === 0) {
+                return;
+            }
+        }
+        await this.query(`DROP VIEW ${this.escapeId(viewName)}`);
+    }
+    async showViews() {
+        const result = await this.query('SELECT VIEWNAME FROM SYSCAT.VIEWS ORDER BY VIEWNAME');
+        return result.rows.map((row) => row.VIEWNAME || row.viewname);
+    }
+    // ==================== Materialized Query Tables (MQTs) ====================
+    // Db2's equivalent of materialized views are Materialized Query Tables.
+    async createMaterializedView(options) {
+        const viewName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        if (options.replace) {
+            await this.dropMaterializedView(options.name, { ifExists: true, schema: options.schema });
+        }
+        // Db2 only supports `DATA INITIALLY DEFERRED` at creation time (there is
+        // no `DATA INITIALLY IMMEDIATE` for MQTs) - initial population is always
+        // done via an explicit `REFRESH TABLE` afterwards, controlled by
+        // `withData`. `REFRESH {DEFERRED|IMMEDIATE}` is a completely separate
+        // concept: it controls Db2's *ongoing* maintenance mode (whether the MQT
+        // is kept in sync automatically on every base-table write), controlled
+        // by `refreshMode`.
+        const refreshClause = options.refreshMode === 'IMMEDIATE' ? 'IMMEDIATE' : 'DEFERRED';
+        const sql = `CREATE TABLE ${viewName} AS (${options.query}) DATA INITIALLY DEFERRED REFRESH ${refreshClause}`;
+        await this.query(sql);
+        if (options.withData !== false) {
+            await this.query(`REFRESH TABLE ${viewName}`);
+        }
+    }
+    async refreshMaterializedView(viewName, options) {
+        const viewNameWithSchema = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(viewName)}`
+            : this.escapeId(viewName);
+        await this.query(`REFRESH TABLE ${viewNameWithSchema}`);
+    }
+    async dropMaterializedView(viewName, options) {
+        const viewNameWithSchema = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(viewName)}`
+            : this.escapeId(viewName);
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT TABNAME FROM SYSCAT.TABLES WHERE TABNAME = '${viewName}' AND TYPE = 'S'`);
+            if (!exists.rows || exists.rows.length === 0) {
+                return;
+            }
+        }
+        await this.query(`DROP TABLE ${viewNameWithSchema}`);
+    }
+    async showMaterializedViews() {
+        // Db2 MQTs (summary tables) have TYPE = 'S' in SYSCAT.TABLES
+        const result = await this.query("SELECT TABNAME FROM SYSCAT.TABLES WHERE TYPE = 'S' ORDER BY TABNAME");
+        return result.rows.map((row) => row.TABNAME || row.tabname);
+    }
+    async hasMaterializedView(viewName, schema) {
+        let sql = `SELECT TABNAME FROM SYSCAT.TABLES WHERE TABNAME = '${viewName}' AND TYPE = 'S'`;
+        if (schema) {
+            sql += ` AND TABSCHEMA = '${schema}'`;
+        }
+        const result = await this.query(sql);
+        return result.rows.length > 0;
+    }
+    // ==================== Column Operations ====================
+    async addColumn(tableName, columnName, definition) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD COLUMN ${this.buildColumnDefinition(columnName, definition)}`);
+    }
+    async removeColumn(tableName, columnName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP COLUMN ${this.escapeId(columnName)}`);
+    }
+    async changeColumn(tableName, columnName, definition) {
+        // Db2 requires separate ALTER COLUMN clauses per attribute changed.
+        const clauses = [];
+        clauses.push(`ALTER COLUMN ${this.escapeId(columnName)} SET DATA TYPE ${this.getDataTypeSql(definition.type)}`);
+        if (definition.allowNull === false) {
+            clauses.push(`ALTER COLUMN ${this.escapeId(columnName)} SET NOT NULL`);
+        }
+        else if (definition.allowNull === true) {
+            clauses.push(`ALTER COLUMN ${this.escapeId(columnName)} DROP NOT NULL`);
+        }
+        if (definition.defaultValue !== undefined) {
+            clauses.push(`ALTER COLUMN ${this.escapeId(columnName)} SET DEFAULT ${this.escape(definition.defaultValue)}`);
+        }
+        for (const clause of clauses) {
+            await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ${clause}`);
+        }
+        // Db2 requires re-organizing the table after altering column types.
+        await this.query(`CALL SYSPROC.ADMIN_CMD('REORG TABLE ${this.quoteTable(tableName)}')`).catch(() => undefined);
+    }
+    async renameColumn(tableName, oldColumnName, newColumnName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`);
+    }
+    /**
+     * 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).
+     */
+    async alterTableCompression(tableName, mode) {
+        const sql = `ALTER TABLE ${this.quoteTable(tableName)}${this.buildCompressClause(mode)}`;
+        await this.query(sql);
+        await this.query(`CALL SYSPROC.ADMIN_CMD('REORG TABLE ${this.quoteTable(tableName)}')`).catch(() => undefined);
+    }
+    async addForeignKey(tableName, columnName, referencedTableName, referencedColumnName, options) {
+        const constraintName = options?.name
+            ? this.escapeId(options.name)
+            : this.escapeId(`fk_${tableName}_${columnName}`);
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} ADD CONSTRAINT ${constraintName} FOREIGN KEY (${this.escapeId(columnName)}) REFERENCES ${this.quoteTable(referencedTableName)} (${this.escapeId(referencedColumnName)})`;
+        if (options?.onDelete) {
+            sql += ` ON DELETE ${options.onDelete.toUpperCase()}`;
+        }
+        if (options?.onUpdate) {
+            sql += ` ON UPDATE ${options.onUpdate.toUpperCase()}`;
+        }
+        await this.query(sql);
+    }
+    async describeTable(tableName) {
+        const result = await this.query(`SELECT COLNAME, TYPENAME, NULLS, "DEFAULT", KEYSEQ, IDENTITY
+       FROM SYSCAT.COLUMNS
+       WHERE TABNAME = '${tableName}'
+       ORDER BY COLNO`);
+        const description = {};
+        for (const row of result.rows) {
+            const colName = (row.COLNAME || row.colname || '').toLowerCase();
+            description[colName] = {
+                type: row.TYPENAME || row.typename,
+                allowNull: (row.NULLS ?? row.nulls) === 'Y',
+                defaultValue: row.DEFAULT ?? row.default,
+                primaryKey: (row.KEYSEQ ?? row.keyseq) != null && (row.KEYSEQ ?? row.keyseq) > 0,
+                autoIncrement: (row.IDENTITY ?? row.identity) === 'Y',
+            };
+        }
+        return description;
+    }
+    async renameTable(oldName, newName) {
+        await this.query(`RENAME TABLE ${this.quoteTable(oldName)} TO ${this.escapeId(newName)}`);
+    }
+    async showTables() {
+        const result = await this.query("SELECT TABNAME FROM SYSCAT.TABLES WHERE TYPE = 'T' ORDER BY TABNAME");
+        return result.rows.map((row) => row.TABNAME || row.tabname);
+    }
+    async showConstraints(tableName) {
+        const sql = `
+      SELECT
+        CONSTNAME AS name,
+        TABNAME AS tableName,
+        TYPE AS type
+      FROM SYSCAT.TABCONST
+      WHERE TABNAME = '${tableName}'
+      ORDER BY CONSTNAME
+    `;
+        const result = await this.query(sql);
+        return result.rows;
+    }
+    async addConstraint(tableName, options) {
+        await this.createConstraint(tableName, {
+            name: options.name || `${tableName}_${options.type.toLowerCase().replace(/\s+/g, '_')}`,
+            type: options.type,
+            fields: options.fields,
+            references: options.references
+                ? { table: options.references.table, field: options.references.fields }
+                : undefined,
+            check: options.check,
+        });
+    }
+    async removeConstraint(tableName, constraintName) {
+        await this.dropConstraint(tableName, constraintName);
+    }
+    async showIndexes(tableName) {
+        const sql = `
+      SELECT
+        INDNAME AS name,
+        TABNAME AS tableName,
+        UNIQUERULE AS uniqueRule,
+        COLNAMES AS columnNames
+      FROM SYSCAT.INDEXES
+      WHERE TABNAME = '${tableName}'
+      ORDER BY INDNAME
+    `;
+        const result = await this.query(sql);
+        return result.rows;
+    }
+    // ==================== Index Operations ====================
+    buildCreateIndexSql(tableName, indexName, fields, options) {
+        const fieldsSql = (fields || []).map((f) => this.escapeId(f)).join(', ');
+        let sql = 'CREATE';
+        if (options?.unique) {
+            sql += ' UNIQUE';
+        }
+        sql += ` INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)} (${fieldsSql})`;
+        if (options?.include && options.include.length > 0) {
+            sql += ` INCLUDE (${options.include.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        return sql;
+    }
+    async addIndex(tableName, indexName, fields, options) {
+        await this.query(this.buildCreateIndexSql(tableName, indexName, fields, options));
+    }
+    async removeIndex(tableName, indexName) {
+        await this.query(`DROP INDEX ${this.escapeId(indexName)}`);
+    }
+    async createIndex(tableName, indexDef) {
+        await this.addIndex(tableName, indexDef.name, indexDef.fields, {
+            unique: indexDef.unique,
+            type: indexDef.type,
+            using: indexDef.using,
+            where: indexDef.where,
+        });
+    }
+    async dropIndex(tableName, indexName, _options) {
+        await this.removeIndex(tableName, indexName);
+    }
+    async createFulltextIndex() {
+        throw new Error('Fulltext indexes are not supported in Db2 LUW (requires Net Search Extender)');
+    }
+    async createSpatialIndex() {
+        throw new Error('Spatial indexes are not supported in Db2 LUW (requires Db2 Spatial Extender)');
+    }
+    // ==================== Constraint Operations ====================
+    async createConstraint(tableName, constraintDef) {
+        const constraintSql = this.buildConstraintSql({
+            name: constraintDef.name,
+            type: constraintDef.type,
+            fields: constraintDef.fields,
+            references: constraintDef.references
+                ? {
+                    table: constraintDef.references.table,
+                    field: constraintDef.references.field,
+                    onDelete: constraintDef.references.onDelete,
+                    onUpdate: constraintDef.references.onUpdate,
+                }
+                : undefined,
+            check: constraintDef.check,
+        });
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD ${constraintSql}`);
+    }
+    async dropConstraint(tableName, constraintName, _options) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`);
+    }
+    async changeOwner() {
+        throw new Error('changeOwner is not supported in Db2 (use TRANSFER OWNERSHIP instead)');
+    }
+    /**
+     * Transfer ownership of a table (Db2's equivalent of changeOwner)
+     */
+    async transferOwnership(tableName, newOwner) {
+        await this.query(`TRANSFER OWNERSHIP OF TABLE ${this.quoteTable(tableName)} TO USER ${this.escapeId(newOwner)} PRESERVE PRIVILEGES`);
+    }
+    // ==================== Federation (Db2's Foreign Data Wrapper equivalent) ====================
+    // Db2 for LUW genuinely supports federated access to remote/external data
+    // sources - it is *not* correct to say Db2 has no FDW-equivalent (that was
+    // only true of the generic Postgres-shaped API surface, not the
+    // underlying capability). Db2's federation feature is built from four
+    // real DDL statements:
+    //   - `CREATE WRAPPER`       - registers a data-source driver/library
+    //                              (Db2's analogue of a Postgres FDW handler).
+    //   - `CREATE SERVER`        - registers a specific remote data source
+    //                              instance that uses a given wrapper.
+    //   - `CREATE USER MAPPING`  - maps a local authorization ID to remote
+    //                              credentials for a given server.
+    //   - `CREATE NICKNAME`      - Db2's analogue of a "foreign table": a
+    //                              local object that transparently maps onto
+    //                              a remote table/view reachable through a
+    //                              server.
+    //
+    // The generic FDW-shaped interface (designed around Postgres) is mapped
+    // onto this real Db2 DDL below. A few notes on where the mapping isn't
+    // 1:1:
+    //   - Db2's `CREATE SERVER`/`CREATE WRAPPER`/`CREATE NICKNAME` have no
+    //     `IF NOT EXISTS` clause (Db2 doesn't support it there), so
+    //     `ifNotExists`/`ifExists` options are honored by pre-checking the
+    //     relevant `SYSCAT` catalog view and short-circuiting, matching the
+    //     pattern already used elsewhere in this file (see `dropSequence`,
+    //     `dropView`, etc.) rather than by emitting nonexistent syntax.
+    //   - `opts.options` on `createForeignServer`/`buildCreateServerQuery` may
+    //     additionally carry the reserved keys `TYPE`/`type` and
+    //     `AUTHORIZATION`/`authorization` + `PASSWORD`/`password`, which are
+    //     pulled out into their own clauses (`TYPE ...`, `AUTHORIZATION ...
+    //     PASSWORD ...`) since Db2's `CREATE SERVER` models them as first-class
+    //     syntax rather than opaque options.
+    //   - `FdwForeignTableOptions.columns` (local column name -> type/options)
+    //     doesn't map onto `CREATE NICKNAME` directly, since Db2 nicknames
+    //     auto-discover their columns from the remote object. Instead, each
+    //     supplied column is applied as a real `ALTER NICKNAME ... ALTER
+    //     COLUMN ... LOCAL TYPE ...` statement after creation, which is Db2's
+    //     genuine mechanism for overriding a nickname column's local type.
+    //   - Db2 has no bulk `IMPORT FOREIGN SCHEMA` equivalent - nicknames are
+    //     always created one at a time - so `buildImportForeignSchemaQuery`
+    //     throws with a specific, accurate explanation (as opposed to a
+    //     blanket "not supported" for federation as a whole).
+    async createForeignDataWrapper(fdwName, options) {
+        let sql = `CREATE WRAPPER ${this.escapeId(fdwName)}`;
+        if (options?.handler) {
+            sql += ` LIBRARY '${options.handler.replace(/'/g, "''")}'`;
+        }
+        await this.query(sql);
+    }
+    async dropForeignDataWrapper(fdwName, options) {
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT WRAPNAME FROM SYSCAT.WRAPPERS WHERE WRAPNAME = '${fdwName}'`);
+            if (!exists.rows || exists.rows.length === 0)
+                return;
+        }
+        await this.query(`DROP WRAPPER ${this.escapeId(fdwName)}`);
+    }
+    async createForeignServer(serverName, fdwName, options) {
+        if (options?.ifNotExists) {
+            const exists = await this.query(`SELECT SERVERNAME FROM SYSCAT.SERVERS WHERE SERVERNAME = '${serverName}'`);
+            if (exists.rows && exists.rows.length > 0)
+                return;
+        }
+        const sql = this.buildCreateServerQuery(serverName, { fdw: fdwName, options: options?.options });
+        await this.query(sql);
+    }
+    async dropForeignServer(serverName, options) {
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT SERVERNAME FROM SYSCAT.SERVERS WHERE SERVERNAME = '${serverName}'`);
+            if (!exists.rows || exists.rows.length === 0)
+                return;
+        }
+        await this.query(this.buildDropServerQuery(serverName));
+    }
+    async createForeignTable(tableName, columns, options) {
+        if (options?.ifNotExists) {
+            const exists = await this.query(`SELECT TABNAME FROM SYSCAT.NICKNAMES WHERE TABNAME = '${tableName}'`);
+            if (exists.rows && exists.rows.length > 0)
+                return;
+        }
+        const serverName = options?.serverName || 'DEFAULT_SERVER';
+        const fdwColumns = {};
+        for (const [colName, colDef] of Object.entries(columns)) {
+            fdwColumns[colName] = { type: colDef.type };
+        }
+        const sql = this.buildCreateForeignTableQuery(tableName, {
+            serverName,
+            columns: fdwColumns,
+        });
+        await this.query(sql);
+        // Db2 nicknames auto-discover their remote columns; apply each supplied
+        // column's type as a real `LOCAL TYPE` override via `ALTER NICKNAME`.
+        for (const [colName, colDef] of Object.entries(columns)) {
+            await this.query(`ALTER NICKNAME ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(colName)} LOCAL TYPE ${colDef.type}`);
+        }
+    }
+    async createUserMapping(userName, serverName, options) {
+        const mappingOptions = { ...(options?.options || {}) };
+        if (options?.username)
+            mappingOptions.REMOTE_AUTHID = options.username;
+        if (options?.password)
+            mappingOptions.REMOTE_PASSWORD = options.password;
+        const sql = this.buildCreateUserMappingQuery({
+            serverName,
+            user: userName,
+            options: mappingOptions,
+        });
+        await this.query(sql);
+    }
+    async dropUserMapping(userName, serverName, options) {
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT AUTHID FROM SYSCAT.USEROPTIONS WHERE SERVERNAME = '${serverName}' AND AUTHID = '${userName}'`);
+            if (!exists.rows || exists.rows.length === 0)
+                return;
+        }
+        await this.query(this.buildDropUserMappingQuery(serverName, userName));
+    }
+    /**
+     * 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, opts) {
+        const rest = { ...(opts.options || {}) };
+        const takeReserved = (...keys) => {
+            for (const key of keys) {
+                if (rest[key] !== undefined) {
+                    const value = rest[key];
+                    delete rest[key];
+                    return value;
+                }
+            }
+            return undefined;
+        };
+        const type = takeReserved('TYPE', 'type');
+        const authorization = takeReserved('AUTHORIZATION', 'authorization');
+        const password = takeReserved('PASSWORD', 'password');
+        let sql = `CREATE SERVER ${this.escapeId(name)}`;
+        if (type)
+            sql += ` TYPE ${type}`;
+        if (opts.version)
+            sql += ` VERSION '${opts.version.replace(/'/g, "''")}'`;
+        sql += ` WRAPPER ${this.escapeId(opts.fdw)}`;
+        if (authorization) {
+            sql += ` AUTHORIZATION ${this.escapeId(authorization)}`;
+            if (password)
+                sql += ` PASSWORD ${this.escapeId(password)}`;
+        }
+        if (Object.keys(rest).length > 0) {
+            sql += ` OPTIONS (${Object.entries(rest)
+                .map(([k, v]) => `${k} '${String(v).replace(/'/g, "''")}'`)
+                .join(', ')})`;
+        }
+        return sql;
+    }
+    /**
+     * Build `ALTER SERVER` SQL.
+     *
+     *   ALTER SERVER server-name
+     *     [VERSION 'server-version']
+     *     [OPTIONS ({ADD|SET|DROP} option-name ['value'], ...)]
+     */
+    buildAlterServerQuery(name, opts) {
+        const parts = [];
+        if (opts.version) {
+            parts.push(`VERSION '${opts.version.replace(/'/g, "''")}'`);
+        }
+        const optParts = [];
+        if (opts.addOptions) {
+            for (const [k, v] of Object.entries(opts.addOptions)) {
+                optParts.push(`ADD ${k} '${v.replace(/'/g, "''")}'`);
+            }
+        }
+        if (opts.setOptions) {
+            for (const [k, v] of Object.entries(opts.setOptions)) {
+                optParts.push(`SET ${k} '${v.replace(/'/g, "''")}'`);
+            }
+        }
+        if (opts.dropOptions) {
+            for (const k of opts.dropOptions) {
+                optParts.push(`DROP ${k}`);
+            }
+        }
+        if (opts.options) {
+            for (const [k, v] of Object.entries(opts.options)) {
+                optParts.push(`SET ${k} '${v.replace(/'/g, "''")}'`);
+            }
+        }
+        if (optParts.length > 0) {
+            parts.push(`OPTIONS (${optParts.join(', ')})`);
+        }
+        if (parts.length === 0) {
+            throw new Error(`ALTER SERVER requires at least one change for server "${name}"`);
+        }
+        return `ALTER SERVER ${this.escapeId(name)} ${parts.join(' ')}`;
+    }
+    /**
+     * 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, _opts) {
+        return `DROP SERVER ${this.escapeId(name)}`;
+    }
+    /**
+     * Build `CREATE USER MAPPING` SQL.
+     *
+     *   CREATE USER MAPPING FOR { auth-id | USER | PUBLIC }
+     *     SERVER server-name
+     *     [OPTIONS (option-name 'value', ...)]
+     */
+    buildCreateUserMappingQuery(opts) {
+        const userToken = this.formatMappingUserToken(opts.user);
+        const optClause = opts.options && Object.keys(opts.options).length > 0
+            ? ` OPTIONS (${Object.entries(opts.options)
+                .map(([k, v]) => `${k} '${String(v).replace(/'/g, "''")}'`)
+                .join(', ')})`
+            : '';
+        return `CREATE USER MAPPING FOR ${userToken} SERVER ${this.escapeId(opts.serverName)}${optClause}`;
+    }
+    /**
+     * 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) {
+        const userToken = this.formatMappingUserToken(opts.user);
+        const optClause = opts.options && Object.keys(opts.options).length > 0
+            ? ` OPTIONS (${Object.entries(opts.options)
+                .map(([k, v]) => `SET ${k} '${String(v).replace(/'/g, "''")}'`)
+                .join(', ')})`
+            : '';
+        return `ALTER USER MAPPING FOR ${userToken} SERVER ${this.escapeId(opts.serverName)}${optClause}`;
+    }
+    /**
+     * Build `DROP USER MAPPING` SQL.
+     *
+     *   DROP USER MAPPING FOR { auth-id | USER | PUBLIC } SERVER server-name
+     */
+    buildDropUserMappingQuery(serverName, user, _opts) {
+        const userToken = this.formatMappingUserToken(user);
+        return `DROP USER MAPPING FOR ${userToken} SERVER ${this.escapeId(serverName)}`;
+    }
+    formatMappingUserToken(user) {
+        const upper = user.toUpperCase();
+        if (upper === 'PUBLIC')
+            return 'PUBLIC';
+        // Db2's federation grammar uses the bare keyword `USER` to mean "the
+        // current authorization ID" (Postgres' `CURRENT_USER` is accepted here
+        // too, as a convenience alias for callers porting from Postgres).
+        if (upper === 'USER' || upper === 'CURRENT_USER')
+            return 'USER';
+        return this.escapeId(user);
+    }
+    /**
+     * 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, opts) {
+        const localName = opts.schema
+            ? `${this.escapeId(opts.schema)}.${this.escapeId(tableName)}`
+            : this.escapeId(tableName);
+        const rest = { ...(opts.options || {}) };
+        const takeReserved = (...keys) => {
+            for (const key of keys) {
+                if (rest[key] !== undefined) {
+                    const value = rest[key];
+                    delete rest[key];
+                    return value;
+                }
+            }
+            return undefined;
+        };
+        const remoteSchema = takeReserved('remoteSchema', 'REMOTE_SCHEMA');
+        const remoteTable = takeReserved('remoteTable', 'REMOTE_TABLE') || tableName;
+        const remoteObject = remoteSchema
+            ? `${this.escapeId(remoteSchema)}.${this.escapeId(remoteTable)}`
+            : this.escapeId(remoteTable);
+        let sql = `CREATE NICKNAME ${localName} FOR ${this.escapeId(opts.serverName)}.${remoteObject}`;
+        if (Object.keys(rest).length > 0) {
+            sql += ` OPTIONS (${Object.entries(rest)
+                .map(([k, v]) => `${k} '${String(v).replace(/'/g, "''")}'`)
+                .join(', ')})`;
+        }
+        return sql;
+    }
+    /**
+     * 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, _opts) {
+        return `DROP NICKNAME ${this.escapeId(tableName)}`;
+    }
+    /**
+     * 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, _serverName, _opts) {
+        throw new Error('Db2 has no bulk IMPORT FOREIGN SCHEMA equivalent - create nicknames individually via createForeignTable()/buildCreateForeignTableQuery() instead.');
+    }
+    /**
+     * Return SQL to list all registered federation servers from the Db2
+     * catalog.
+     */
+    getServersQuery() {
+        return 'SELECT SERVERNAME, SERVERTYPE, SERVERVERSION, WRAPNAME FROM SYSCAT.SERVERS ORDER BY SERVERNAME';
+    }
+    // ==================== Row/Column Access Control ====================
+    // Db2's equivalent of MSSQL security policies is Row and Column Access
+    // Control (RCAC) - a table-level PERMISSION with an enable/disable step.
+    async createSecurityPolicy(policyName, tableName, options) {
+        const predicate = options?.predicate || '1=1';
+        await this.query(`CREATE PERMISSION ${this.escapeId(policyName)} ON ${this.quoteTable(tableName)} FOR ROWS WHERE (${predicate}) ENFORCED FOR ALL ACCESS ENABLE`);
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ACTIVATE ROW ACCESS CONTROL`);
+    }
+    async dropSecurityPolicy(policyName, _tableName) {
+        await this.query(`DROP PERMISSION ${this.escapeId(policyName)}`);
+    }
+    // ==================== Transaction Operations ====================
+    async startTransaction(options) {
+        if (!this.pool) {
+            throw new Error('Not connected to database. Call connect() first.');
+        }
+        const conn = await this.pool.open(this.connectionString);
+        if (options?.isolationLevel) {
+            // Accept both ANSI isolation level names and Db2's native
+            // abbreviations (UR/CS/RS/RR), which map roughly onto the ODBC
+            // SQL_TXN_* bitmask values used by `setIsolationLevel`.
+            const levelMap = {
+                'READ UNCOMMITTED': 1,
+                UR: 1,
+                'READ COMMITTED': 2,
+                CS: 2,
+                'REPEATABLE READ': 4,
+                RS: 4,
+                SERIALIZABLE: 8,
+                RR: 8,
+            };
+            const key = options.isolationLevel.toUpperCase();
+            const level = levelMap[key];
+            if (level === undefined) {
+                throw new Error(`Unsupported isolation level "${options.isolationLevel}". Expected one of: ` +
+                    "'READ UNCOMMITTED'/'UR', 'READ COMMITTED'/'CS', 'REPEATABLE READ'/'RS', 'SERIALIZABLE'/'RR'.");
+            }
+            conn.setIsolationLevel?.(level);
+        }
+        await conn.beginTransaction();
+        return new DB2Transaction(conn, options);
+    }
+    async commitTransaction(transaction) {
+        const tx = transaction;
+        if (tx.connection) {
+            await tx.connection.commitTransaction();
+            await tx.connection.close();
+            tx.finished = true;
+        }
+    }
+    async rollbackTransaction(transaction) {
+        const tx = transaction;
+        if (tx.connection) {
+            await tx.connection.rollbackTransaction();
+            await tx.connection.close();
+            tx.finished = true;
+        }
+    }
+    // ==================== Data Type Mapping ====================
+    getDataTypeSql(dataType) {
+        if (typeof dataType === 'string') {
+            return this.mapDataType(dataType, undefined);
+        }
+        const dt = dataType;
+        return this.mapDataType(String(dt.key ?? dataType), dt);
+    }
+    mapDataType(typeKey, dt) {
+        switch (typeKey.toUpperCase()) {
+            case 'STRING':
+                if (dt?.length === 'max')
+                    return 'CLOB';
+                return `VARCHAR(${String(dt?.length || 255)})`;
+            case 'CHAR':
+                return `CHAR(${String(dt?.length || 1)})`;
+            case 'TEXT':
+                return 'CLOB';
+            case 'TINYTEXT':
+                return 'VARCHAR(255)';
+            case 'MEDIUMTEXT':
+            case 'LONGTEXT':
+                return 'CLOB';
+            case 'INTEGER': {
+                if (dt?.length === 1)
+                    return 'SMALLINT';
+                if (dt?.length === 2)
+                    return 'SMALLINT';
+                if (dt?.length === 8)
+                    return 'BIGINT';
+                return 'INTEGER';
+            }
+            case 'BIGINT':
+                return 'BIGINT';
+            case 'FLOAT':
+                return 'REAL';
+            case 'DOUBLE':
+                return 'DOUBLE';
+            case 'DECIMAL':
+            case 'NUMERIC':
+                return `DECIMAL(${String(dt?.precision || 10)},${String(dt?.scale || 0)})`;
+            case 'BOOLEAN':
+                return 'BOOLEAN';
+            case 'DATE':
+            case 'DATETIME':
+            case 'TIMESTAMP':
+                return dt?.precision ? `TIMESTAMP(${String(dt.precision)})` : 'TIMESTAMP';
+            case 'DATEONLY':
+                return 'DATE';
+            case 'TIME':
+                return 'TIME';
+            case 'BLOB':
+                return 'BLOB';
+            case 'BINARY':
+                return `BINARY(${String(dt?.length || 255)})`;
+            case 'VARBINARY':
+                return `VARBINARY(${String(dt?.length || 2000)})`;
+            case 'BIT':
+                return 'VARBINARY(1)';
+            case 'JSON':
+                return 'CLOB';
+            case 'JSONB':
+                return 'BLOB';
+            case 'UUID':
+                return 'CHAR(36)';
+            case 'GEOMETRY':
+                return 'DB2GSE.ST_GEOMETRY';
+            case 'ENUM':
+                return 'VARCHAR(255)';
+            case 'VIRTUAL':
+                return '';
+            default:
+                return 'VARCHAR(255)';
+        }
+    }
+    // ==================== Query Builders ====================
+    buildWhereClause(where, _options) {
+        const values = [];
+        if (!where || Object.keys(where).length === 0) {
+            return { sql: '', values };
+        }
+        const buildCondition = (condition) => {
+            if (!condition || typeof condition !== 'object') {
+                values.push(condition);
+                return '?';
+            }
+            const cond = condition;
+            if (cond.$and || cond.$or || cond.$not) {
+                const conditions = [];
+                if (cond.$and) {
+                    conditions.push(`(${cond.$and.map((c) => buildCondition(c)).join(' AND ')})`);
+                }
+                if (cond.$or) {
+                    conditions.push(`(${cond.$or.map((c) => buildCondition(c)).join(' OR ')})`);
+                }
+                if (cond.$not) {
+                    conditions.push(`NOT (${buildCondition(cond.$not)})`);
+                }
+                return conditions.join(' AND ');
+            }
+            const fieldConditions = [];
+            for (const [key, value] of Object.entries(cond)) {
+                if (key.startsWith('$'))
+                    continue;
+                if (value && typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) {
+                    const valueObj = value;
+                    if (valueObj.$eq !== undefined) {
+                        values.push(valueObj.$eq);
+                        fieldConditions.push(`${this.escapeId(key)} = ?`);
+                    }
+                    else if (valueObj.$ne !== undefined) {
+                        values.push(valueObj.$ne);
+                        fieldConditions.push(`${this.escapeId(key)} != ?`);
+                    }
+                    else if (valueObj.$gt !== undefined) {
+                        values.push(valueObj.$gt);
+                        fieldConditions.push(`${this.escapeId(key)} > ?`);
+                    }
+                    else if (valueObj.$gte !== undefined) {
+                        values.push(valueObj.$gte);
+                        fieldConditions.push(`${this.escapeId(key)} >= ?`);
+                    }
+                    else if (valueObj.$lt !== undefined) {
+                        values.push(valueObj.$lt);
+                        fieldConditions.push(`${this.escapeId(key)} < ?`);
+                    }
+                    else if (valueObj.$lte !== undefined) {
+                        values.push(valueObj.$lte);
+                        fieldConditions.push(`${this.escapeId(key)} <= ?`);
+                    }
+                    else if (valueObj.$like !== undefined) {
+                        values.push(valueObj.$like);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE ?`);
+                    }
+                    else if (valueObj.$notLike !== undefined) {
+                        values.push(valueObj.$notLike);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE ?`);
+                    }
+                    else if (valueObj.$in) {
+                        const inValues = valueObj.$in;
+                        values.push(...inValues);
+                        fieldConditions.push(`${this.escapeId(key)} IN (${inValues.map(() => '?').join(', ')})`);
+                    }
+                    else if (valueObj.$notIn) {
+                        const notInValues = valueObj.$notIn;
+                        values.push(...notInValues);
+                        fieldConditions.push(`${this.escapeId(key)} NOT IN (${notInValues.map(() => '?').join(', ')})`);
+                    }
+                    else if (valueObj.$between) {
+                        const between = valueObj.$between;
+                        values.push(between[0], between[1]);
+                        fieldConditions.push(`${this.escapeId(key)} BETWEEN ? AND ?`);
+                    }
+                    else if (valueObj.$notBetween) {
+                        const notBetween = valueObj.$notBetween;
+                        values.push(notBetween[0], notBetween[1]);
+                        fieldConditions.push(`${this.escapeId(key)} NOT BETWEEN ? AND ?`);
+                    }
+                    else if (valueObj.$isNull !== undefined) {
+                        fieldConditions.push(valueObj.$isNull
+                            ? `${this.escapeId(key)} IS NULL`
+                            : `${this.escapeId(key)} IS NOT NULL`);
+                    }
+                    else {
+                        values.push(value);
+                        fieldConditions.push(`${this.escapeId(key)} = ?`);
+                    }
+                }
+                else if (value === null) {
+                    fieldConditions.push(`${this.escapeId(key)} IS NULL`);
+                }
+                else if (Array.isArray(value)) {
+                    values.push(...value);
+                    fieldConditions.push(`${this.escapeId(key)} IN (${value.map(() => '?').join(', ')})`);
+                }
+                else {
+                    values.push(value);
+                    fieldConditions.push(`${this.escapeId(key)} = ?`);
+                }
+            }
+            return fieldConditions.join(' AND ');
+        };
+        const sql = buildCondition(where);
+        return { sql, values };
+    }
+    buildOrderClause(order, _options) {
+        const orderArray = order;
+        if (!orderArray || !Array.isArray(orderArray) || orderArray.length === 0) {
+            return '';
+        }
+        const orderParts = [];
+        for (const item of orderArray) {
+            if (Array.isArray(item)) {
+                const field = typeof item[0] === 'string' ? this.escapeId(item[0]) : item[0];
+                const direction = item[1] ? ` ${item[1]}` : '';
+                orderParts.push(`${field}${direction}`);
+            }
+            else if (typeof item === 'string') {
+                orderParts.push(this.escapeId(item));
+            }
+        }
+        return orderParts.length > 0 ? `ORDER BY ${orderParts.join(', ')}` : '';
+    }
+    /**
+     * 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, offset) {
+        let sql = '';
+        if (offset !== undefined) {
+            sql += ` OFFSET ${Number(offset)} ROWS`;
+        }
+        if (limit !== undefined) {
+            sql += ` FETCH FIRST ${Number(limit)} ROWS ONLY`;
+        }
+        return sql;
+    }
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push('?');
+                processedValues.push(value);
+            }
+        }
+        let sql = `INSERT INTO ${this.quoteTable(tableName, options?.schema)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${placeholders.join(', ')})`;
+        if (options?.returning) {
+            const cols = options.returning === true
+                ? '*'
+                : options.returning.map((c) => this.escapeId(c)).join(', ');
+            // Db2's `SELECT ... FROM FINAL TABLE (...)` needs the INSERT wrapped.
+            sql = `SELECT ${cols} FROM FINAL TABLE (${sql})`;
+        }
+        return { sql, values: processedValues };
+    }
+    buildUpdateQuery(tableName, values, where, options) {
+        const processedValues = [];
+        const setClauses = [];
+        for (const [key, value] of Object.entries(values)) {
+            if (value instanceof prorm_1.Literal) {
+                setClauses.push(`${this.escapeId(key)} = ${value.val}`);
+            }
+            else {
+                setClauses.push(`${this.escapeId(key)} = ?`);
+                processedValues.push(value);
+            }
+        }
+        let sql = `UPDATE ${this.quoteTable(tableName)} SET ${setClauses.join(', ')}`;
+        const whereClause = this.buildWhereClause(where);
+        if (whereClause.sql) {
+            sql += ` WHERE ${whereClause.sql}`;
+            processedValues.push(...whereClause.values);
+        }
+        if (options?.returning) {
+            const cols = options.returning === true
+                ? '*'
+                : options.returning.map((c) => this.escapeId(c)).join(', ');
+            sql = `SELECT ${cols} FROM FINAL TABLE (${sql})`;
+        }
+        return { sql, values: processedValues };
+    }
+    buildDeleteQuery(tableName, where, options) {
+        if (options?.truncate) {
+            return { sql: `TRUNCATE TABLE ${this.quoteTable(tableName)} IMMEDIATE`, values: [] };
+        }
+        let sql = `DELETE FROM ${this.quoteTable(tableName)}`;
+        const processedValues = [];
+        const whereClause = this.buildWhereClause(where);
+        if (whereClause.sql) {
+            sql += ` WHERE ${whereClause.sql}`;
+            processedValues.push(...whereClause.values);
+        }
+        if (options?.returning) {
+            const cols = options.returning === true
+                ? '*'
+                : options.returning.map((c) => this.escapeId(c)).join(', ');
+            sql = `SELECT ${cols} FROM OLD TABLE (${sql})`;
+        }
+        return { sql, values: processedValues };
+    }
+    /**
+     * 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) {
+        const columnList = cte.columns && cte.columns.length > 0
+            ? `(${cte.columns.map((c) => this.escapeId(c)).join(', ')})`
+            : '';
+        const unionKeyword = cte.unionAll === false ? 'UNION' : 'UNION ALL';
+        return `WITH ${this.escapeId(cte.name)}${columnList} AS (${cte.baseQuery} ${unionKeyword} ${cte.recursiveQuery})`;
+    }
+    /**
+     * Build a full recursive-CTE `SELECT ... FROM cte-name` query in one call,
+     * combining `buildRecursiveCteClause` with `buildSelectQuery`.
+     */
+    buildRecursiveCteQuery(cte, outer) {
+        return this.buildSelectQuery({
+            ...outer,
+            tableName: outer.tableName || cte.name,
+            cte,
+        });
+    }
+    /**
+     * 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) {
+        const args = (options.args || []).join(', ');
+        const overParts = [];
+        if (options.partitionBy) {
+            const cols = Array.isArray(options.partitionBy) ? options.partitionBy : [options.partitionBy];
+            overParts.push(`PARTITION BY ${cols.map((c) => this.escapeId(c)).join(', ')}`);
+        }
+        if (options.orderBy && options.orderBy.length > 0) {
+            const orderParts = options.orderBy.map((o) => typeof o === 'string'
+                ? this.escapeId(o)
+                : `${this.escapeId(o.column)}${o.direction ? ` ${o.direction}` : ''}`);
+            overParts.push(`ORDER BY ${orderParts.join(', ')}`);
+        }
+        if (options.frame) {
+            overParts.push(options.frame);
+        }
+        return `${options.fn.toUpperCase()}(${args}) OVER (${overParts.join(' ')})`;
+    }
+    buildSelectQuery(options) {
+        const values = [];
+        // Recursive CTE prefix (`WITH name(cols) AS (base UNION ALL recursive)`)
+        // is Db2-specific and not part of the shared `SelectOptions` interface,
+        // so - like the temporal clauses above - it's read as an extra (untyped)
+        // property on the options object.
+        const cte = options.cte;
+        let sql = cte ? `${this.buildRecursiveCteClause(cte)} ` : '';
+        sql += 'SELECT ';
+        if (options.distinct) {
+            sql += 'DISTINCT ';
+        }
+        if (options.attributes) {
+            if (Array.isArray(options.attributes)) {
+                sql += options.attributes
+                    .map((a) => {
+                    if (a === '*')
+                        return a;
+                    if (typeof a === 'object' && a !== null && 'window' in a) {
+                        const windowAttr = a;
+                        return `${this.buildWindowFunction(windowAttr.window)} AS ${this.escapeId(windowAttr.as)}`;
+                    }
+                    return this.escapeId(a);
+                })
+                    .join(', ');
+            }
+            else {
+                const include = options.attributes.include
+                    ?.map((a) => this.escapeId(a))
+                    .join(', ');
+                sql += include || '*';
+            }
+        }
+        else {
+            sql += '*';
+        }
+        sql += ` FROM ${this.quoteTable(options.tableName, options.schema)}`;
+        // Temporal query clauses (`FOR SYSTEM_TIME ...` / `FOR BUSINESS_TIME
+        // ...`) are Db2-specific and not part of the shared `SelectOptions`
+        // interface, so they're read as extra (untyped) properties on the
+        // options object rather than requiring a shared-type change.
+        sql += this.buildTemporalClause(options);
+        if (options.include && options.include.length > 0) {
+            for (const include of options.include) {
+                const joinType = include.required ? 'INNER JOIN' : 'LEFT JOIN';
+                const joinModel = include.model;
+                const joinTableName = joinModel.tableName || joinModel.name || '';
+                const joinAlias = include.as || joinTableName;
+                sql += ` ${joinType} ${this.quoteTable(joinTableName)} AS ${this.escapeId(joinAlias)}`;
+                if (include.on) {
+                    const onClause = this.buildWhereClause(include.on);
+                    sql += ` ON ${onClause.sql}`;
+                    values.push(...onClause.values);
+                }
+            }
+        }
+        if (options.where && Object.keys(options.where).length > 0) {
+            const whereClause = this.buildWhereClause(options.where);
+            if (whereClause.sql) {
+                sql += ` WHERE ${whereClause.sql}`;
+                values.push(...whereClause.values);
+            }
+        }
+        if (options.group) {
+            const groupBy = Array.isArray(options.group) ? options.group : [options.group];
+            sql += ` GROUP BY ${groupBy.map((g) => this.escapeId(g)).join(', ')}`;
+            if (options.having && Object.keys(options.having).length > 0) {
+                const havingClause = this.buildWhereClause(options.having);
+                sql += ` HAVING ${havingClause.sql}`;
+                values.push(...havingClause.values);
+            }
+        }
+        if (options.order) {
+            const orderClause = this.buildOrderClause(options.order);
+            if (orderClause)
+                sql += ` ${orderClause}`;
+        }
+        if (options.limit !== undefined || options.offset !== undefined) {
+            sql += this.buildLimitOffset(options.limit, options.offset);
+        }
+        if (options.lock) {
+            sql += ' FOR UPDATE';
+            if (options.lock === 'SHARE') {
+                sql += ' WITH RS';
+            }
+        }
+        return { sql, values };
+    }
+    /**
+     * Build an UPSERT query using Db2's `MERGE INTO ... WHEN MATCHED / WHEN
+     * NOT MATCHED` syntax against a single-row VALUES() source.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const queryValues = Object.values(values);
+        const conflictFields = options?.conflictFields && options.conflictFields.length > 0
+            ? options.conflictFields
+            : [columns[0]];
+        const updateFields = options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? options.updateOnDuplicate
+            : columns.filter((c) => !conflictFields.includes(c));
+        const sourceColumns = columns.map((c) => this.escapeId(c)).join(', ');
+        const sourceValues = columns.map(() => '?').join(', ');
+        const onClauses = conflictFields
+            .map((c) => `target.${this.escapeId(c)} = source.${this.escapeId(c)}`)
+            .join(' AND ');
+        const updateSet = updateFields.length > 0
+            ? updateFields.map((c) => `${this.escapeId(c)} = source.${this.escapeId(c)}`).join(', ')
+            : columns.map((c) => `${this.escapeId(c)} = source.${this.escapeId(c)}`).join(', ');
+        let sql = `MERGE INTO ${this.quoteTable(tableName)} AS target ` +
+            `USING (VALUES (${sourceValues})) AS source (${sourceColumns}) ` +
+            `ON ${onClauses} ` +
+            `WHEN MATCHED THEN UPDATE SET ${updateSet} ` +
+            `WHEN NOT MATCHED THEN INSERT (${sourceColumns}) VALUES (${columns.map((c) => `source.${this.escapeId(c)}`).join(', ')})`;
+        if (options?.returning) {
+            // Db2 does not support RETURNING on MERGE directly; the caller should
+            // re-select the row after the upsert.
+            throw new Error('Db2 does not support a RETURNING clause on MERGE. Re-fetch the row after the upsert instead.');
+        }
+        return { sql, values: queryValues };
+    }
+    buildIncrementQuery(tableName, fields, where, options) {
+        const by = options?.by ?? 1;
+        const setClauses = [];
+        const queryValues = [];
+        if (typeof fields === 'string') {
+            setClauses.push(`${this.escapeId(fields)} = ${this.escapeId(fields)} + ?`);
+            queryValues.push(by);
+        }
+        else if (Array.isArray(fields)) {
+            for (const field of fields) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + ?`);
+                queryValues.push(by);
+            }
+        }
+        else {
+            for (const [field, value] of Object.entries(fields)) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + ?`);
+                queryValues.push(value);
+            }
+        }
+        let sql = `UPDATE ${this.quoteTable(tableName)} SET ${setClauses.join(', ')}`;
+        const whereClause = this.buildWhereClause(where);
+        if (whereClause.sql) {
+            sql += ` WHERE ${whereClause.sql}`;
+            queryValues.push(...whereClause.values);
+        }
+        return { sql, values: queryValues };
+    }
+    replaceReplacements(sql, replacements) {
+        if (!replacements) {
+            return sql;
+        }
+        if (Array.isArray(replacements)) {
+            let result = sql;
+            for (const value of replacements) {
+                result = result.replace('?', this.escape(value));
+            }
+            return result;
+        }
+        let result = sql;
+        for (const [key, value] of Object.entries(replacements)) {
+            result = result.replace(new RegExp(`:${key}\\b`, 'g'), this.escape(value));
+        }
+        return result;
+    }
+    // ==================== User Management (limited) ====================
+    // Db2 authenticates users via the OS/LDAP, not SQL CREATE USER - only
+    // privilege GRANT/REVOKE management is meaningful at the SQL level.
+    buildCreateUserQuery() {
+        throw new Error('Db2 does not manage users via SQL (users are authenticated externally via OS/LDAP)');
+    }
+    buildAlterUserQuery() {
+        throw new Error('Db2 does not manage users via SQL (users are authenticated externally via OS/LDAP)');
+    }
+    buildDropUserQuery() {
+        throw new Error('Db2 does not manage users via SQL (users are authenticated externally via OS/LDAP)');
+    }
+    getUsersQuery() {
+        return 'SELECT GRANTEE FROM SYSCAT.DBAUTH WHERE GRANTEETYPE = \'U\' GROUP BY GRANTEE';
+    }
+    buildGrantQuery(options) {
+        const privileges = Array.isArray(options.privileges)
+            ? options.privileges.join(', ')
+            : options.privileges;
+        let sql = `GRANT ${privileges} ON ${options.on} TO ${options.to}`;
+        if (options.withGrantOption) {
+            sql += ' WITH GRANT OPTION';
+        }
+        return sql;
+    }
+    buildRevokeQuery(options) {
+        const privileges = Array.isArray(options.privileges)
+            ? options.privileges.join(', ')
+            : options.privileges;
+        return `REVOKE ${privileges} ON ${options.on} FROM ${options.from}`;
+    }
+    buildShowGrantsQuery(username) {
+        return `SELECT * FROM SYSCAT.DBAUTH WHERE GRANTEE = UPPER('${username}')`;
+    }
+    buildFlushPrivilegesQuery() {
+        throw new Error('Db2 does not require FLUSH PRIVILEGES (grants take effect immediately)');
+    }
+    buildCreateRoleQuery(roleName) {
+        return `CREATE ROLE ${this.escapeId(roleName)}`;
+    }
+    buildDropRoleQuery(roleName) {
+        return `DROP ROLE ${this.escapeId(roleName)}`;
+    }
+    buildGrantRoleQuery(role, to) {
+        return `GRANT ROLE ${this.escapeId(role)} TO ${to}`;
+    }
+    buildRevokeRoleQuery(role, from) {
+        return `REVOKE ROLE ${this.escapeId(role)} FROM ${from}`;
+    }
+    getRolesQuery() {
+        return 'SELECT ROLENAME FROM SYSCAT.ROLES ORDER BY ROLENAME';
+    }
+    // ==================== Sequences ====================
+    async createSequence(options) {
+        const seqName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        if (options.ifNotExists) {
+            const exists = await this.hasSequence(options.name, options.schema);
+            if (exists)
+                return;
+        }
+        let sql = `CREATE SEQUENCE ${seqName}`;
+        if (options.startWith !== undefined)
+            sql += ` START WITH ${options.startWith}`;
+        if (options.incrementBy !== undefined)
+            sql += ` INCREMENT BY ${options.incrementBy}`;
+        if (options.minvalue !== undefined)
+            sql += ` MINVALUE ${options.minvalue}`;
+        if (options.maxvalue !== undefined)
+            sql += ` MAXVALUE ${options.maxvalue}`;
+        sql += options.cycle ? ' CYCLE' : ' NO CYCLE';
+        if (options.cache !== undefined) {
+            sql += options.cache > 0 ? ` CACHE ${options.cache}` : ' NO CACHE';
+        }
+        await this.query(sql);
+    }
+    async dropSequence(sequenceName, options) {
+        const seqName = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(sequenceName)}`
+            : this.escapeId(sequenceName);
+        if (options?.ifExists) {
+            const exists = await this.hasSequence(sequenceName, options.schema);
+            if (!exists)
+                return;
+        }
+        await this.query(`DROP SEQUENCE ${seqName}`);
+    }
+    async nextSequenceValue(sequenceName) {
+        const result = await this.query(`SELECT NEXT VALUE FOR ${this.escapeId(sequenceName)} AS NEXTVAL FROM SYSIBM.SYSDUMMY1`);
+        const row = result.rows[0];
+        return Number(row?.NEXTVAL ?? row?.nextval);
+    }
+    async currSequenceValue(sequenceName) {
+        const result = await this.query(`SELECT PREVIOUS VALUE FOR ${this.escapeId(sequenceName)} AS CURRVAL FROM SYSIBM.SYSDUMMY1`);
+        const row = result.rows[0];
+        return Number(row?.CURRVAL ?? row?.currval);
+    }
+    async hasSequence(sequenceName, schema) {
+        let sql = `SELECT SEQNAME FROM SYSCAT.SEQUENCES WHERE SEQNAME = '${sequenceName}'`;
+        if (schema) {
+            sql += ` AND SEQSCHEMA = '${schema}'`;
+        }
+        const result = await this.query(sql);
+        return result.rows.length > 0;
+    }
+    async listSequences() {
+        const result = await this.query('SELECT SEQSCHEMA, SEQNAME FROM SYSCAT.SEQUENCES ORDER BY SEQSCHEMA, SEQNAME');
+        return result.rows.map((row) => `${row.SEQSCHEMA || row.seqschema}.${row.SEQNAME || row.seqname}`);
+    }
+    // ==================== Stored Procedures ====================
+    async createStoredProcedure(options) {
+        const procName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        if (options.ifNotExists && !options.replace) {
+            const exists = await this.hasStoredProcedure(options.name, options.schema);
+            if (exists)
+                return;
+        }
+        if (options.replace) {
+            await this.query(`DROP PROCEDURE ${procName}`).catch(() => undefined);
+        }
+        const paramList = (options.params || [])
+            .map((param) => {
+            const dir = param.mode === 'OUT' ? 'OUT' : param.mode === 'INOUT' ? 'INOUT' : 'IN';
+            return `${dir} ${this.escapeId(param.name)} ${param.type}`;
+        })
+            .join(', ');
+        const sql = `CREATE PROCEDURE ${procName} (${paramList})\nLANGUAGE SQL\nBEGIN\n${options.body}\nEND`;
+        await this.query(sql);
+    }
+    async dropStoredProcedure(procedureName, options) {
+        const procName = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(procedureName)}`
+            : this.escapeId(procedureName);
+        if (options?.ifExists) {
+            const exists = await this.hasStoredProcedure(procedureName, options.schema);
+            if (!exists)
+                return;
+        }
+        await this.query(`DROP PROCEDURE ${procName}`);
+    }
+    async dropProcedure(procedureName, options) {
+        return this.dropStoredProcedure(procedureName, options);
+    }
+    async createProcedure(options) {
+        return this.createStoredProcedure(options);
+    }
+    async executeStoredProcedure(options) {
+        const procName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.procedureName)}`
+            : this.escapeId(options.procedureName);
+        const paramValues = options.params ? Object.values(options.params) : [];
+        const placeholders = paramValues.map(() => '?').join(', ');
+        const sql = `CALL ${procName}(${placeholders})`;
+        return this.query(sql, { replacements: paramValues, timeout: options.timeout });
+    }
+    async hasStoredProcedure(procedureName, schema) {
+        let sql = `SELECT PROCNAME FROM SYSCAT.PROCEDURES WHERE PROCNAME = '${procedureName}'`;
+        if (schema) {
+            sql += ` AND PROCSCHEMA = '${schema}'`;
+        }
+        const result = await this.query(sql);
+        return result.rows.length > 0;
+    }
+    // ==================== Triggers ====================
+    async createTrigger(options) {
+        const triggerName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        const tableName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.tableName)}`
+            : this.quoteTable(options.tableName);
+        if (options.replace) {
+            await this.query(`DROP TRIGGER ${triggerName}`).catch(() => undefined);
+        }
+        const timing = options.timing === 'BEFORE' ? 'NO CASCADE BEFORE' : options.timing;
+        const events = (options.events || []).join(' OR ');
+        let sql = `CREATE TRIGGER ${triggerName}\n${timing} ${events} ON ${tableName}\nREFERENCING NEW AS N OLD AS O\nFOR EACH ${options.level === 'STATEMENT' ? 'STATEMENT' : 'ROW'}\nMODE DB2SQL\nBEGIN ATOMIC\n${options.body}\nEND`;
+        await this.query(sql);
+    }
+    async dropTrigger(triggerName, _tableName, options) {
+        const name = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(triggerName)}`
+            : this.escapeId(triggerName);
+        if (options?.ifExists) {
+            const exists = await this.hasTrigger(triggerName, _tableName, options.schema);
+            if (!exists)
+                return;
+        }
+        await this.query(`DROP TRIGGER ${name}`);
+    }
+    async hasTrigger(triggerName, tableName, schema) {
+        let sql = `SELECT TRIGNAME FROM SYSCAT.TRIGGERS WHERE TRIGNAME = '${triggerName}' AND TABNAME = '${tableName}'`;
+        if (schema) {
+            sql += ` AND TRIGSCHEMA = '${schema}'`;
+        }
+        const result = await this.query(sql);
+        return result.rows.length > 0;
+    }
+    // ==================== Row/Column Access Control (RLS-like) ====================
+    async createPolicy(options) {
+        const tableName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.tableName)}`
+            : this.quoteTable(options.tableName);
+        const predicate = options.using || options.withCheck || '1=1';
+        await this.query(`CREATE PERMISSION ${this.escapeId(options.name)} ON ${tableName} FOR ROWS WHERE (${predicate}) ENFORCED FOR ALL ACCESS ENABLE`);
+    }
+    async dropPolicy(policyName, _tableName, options) {
+        if (options?.ifExists) {
+            const exists = await this.query(`SELECT PERMISSIONNAME FROM SYSCAT.CONTROLS WHERE PERMISSIONNAME = '${policyName}'`).catch(() => ({ rows: [], rowCount: 0, fields: [] }));
+            if (!exists.rows || exists.rows.length === 0)
+                return;
+        }
+        await this.query(`DROP PERMISSION ${this.escapeId(policyName)}`);
+    }
+    async enableRLS(tableName, schema) {
+        const table = schema ? `${this.escapeId(schema)}.${this.escapeId(tableName)}` : this.quoteTable(tableName);
+        await this.query(`ALTER TABLE ${table} ACTIVATE ROW ACCESS CONTROL`);
+    }
+    async disableRLS(tableName, schema) {
+        const table = schema ? `${this.escapeId(schema)}.${this.escapeId(tableName)}` : this.quoteTable(tableName);
+        await this.query(`ALTER TABLE ${table} DEACTIVATE ROW ACCESS CONTROL`);
+    }
+    async hasPolicy(policyName, _tableName) {
+        const result = await this.query(`SELECT PERMISSIONNAME FROM SYSCAT.CONTROLS WHERE PERMISSIONNAME = '${policyName}'`).catch(() => ({ rows: [], rowCount: 0, fields: [] }));
+        return result.rows.length > 0;
+    }
+    // ==================== Comments ====================
+    async commentTable(tableName, comment) {
+        await this.query(`COMMENT ON TABLE ${this.quoteTable(tableName)} IS '${comment.replace(/'/g, "''")}'`);
+    }
+    async commentColumn(tableName, columnName, comment) {
+        await this.query(`COMMENT ON COLUMN ${this.quoteTable(tableName)}.${this.escapeId(columnName)} IS '${comment.replace(/'/g, "''")}'`);
+    }
+    /**
+     * 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, rowPath, columns, alias) {
+        const columnDefs = columns
+            .map((col) => {
+            if (col.forOrdinality) {
+                return `${this.escapeId(col.name)} FOR ORDINALITY`;
+            }
+            return `${this.escapeId(col.name)} ${col.type} PATH '${col.path}'`;
+        })
+            .join(', ');
+        return `JSON_TABLE(${jsonExpression}, '${rowPath}' COLUMNS(${columnDefs})) AS ${this.escapeId(alias)}`;
+    }
+}
+exports.DB2Dialect = DB2Dialect;