ts-prorm-orm 1.1.0

package/dist/dialects/cockroachdb/index.js

@@ -0,0 +1,4677 @@
+"use strict";
+/**
+ * CockroachDB dialect implementation for the TypeScript ORM
+ *
+ * CockroachDB speaks the CockroachDB wire protocol and is largely SQL-compatible
+ * with CockroachDB, so this dialect reuses the `pg` driver (same as the Postgres
+ * dialect) and mirrors most of its query-building behavior. Notable differences
+ * from the Postgres dialect:
+ *
+ * - Default port is 26257 (not 5432).
+ * - showTables/describeTable/showIndexes/showConstraints prefer CockroachDB's
+ *   `SHOW TABLES` / `SHOW COLUMNS FROM` / `SHOW INDEXES FROM` / `SHOW CONSTRAINTS FROM`
+ *   statements instead of querying information_schema/pg_catalog directly.
+ * - `CREATE INDEX ... CONCURRENTLY` is not supported (and not needed) in CockroachDB
+ *   because index creation is online/non-blocking by default; the `concurrently`
+ *   option is ignored with a warning instead of being emitted in the SQL.
+ * - Interleaved tables (CockroachDB's now-deprecated `INTERLEAVE IN PARENT` syntax)
+ *   are intentionally NOT implemented.
+ * - SERIAL/BIGSERIAL auto-increment columns are kept for parity with the Postgres
+ *   dialect; CockroachDB accepts these as a Postgres-compatibility shorthand that
+ *   maps to an implicit sequence internally (CockroachDB's default unique ID
+ *   generation otherwise uses `unique_rowid()`).
+ * - `buildUpsertQuery`/`buildInsertQuery` default to Postgres-style `ON CONFLICT
+ *   ... DO UPDATE` for consistency with the Postgres dialect's style, but
+ *   accept a `nativeUpsert` option to opt into CockroachDB's native
+ *   `UPSERT INTO ... VALUES (...)` shorthand, which replaces the whole row
+ *   without requiring a conflict target.
+ * - Adds `isRetryableError()` to detect CockroachDB's serialization failure
+ *   SQLSTATE (40001), which requires the client to retry the transaction.
+ *   `runTransaction()` uses it to implement CockroachDB's client-side
+ *   transaction retry loop (`SAVEPOINT cockroach_restart`), and it's also
+ *   folded into the default query-retry match lists so single-statement
+ *   retries cover it too.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CockroachDBTransaction = exports.CockroachDBDialect = void 0;
+exports.createCockroachDBDialect = createCockroachDBDialect;
+const pg_1 = __importDefault(require("pg"));
+const prorm_1 = require("../../prorm");
+const { Pool: PgPool } = pg_1.default;
+/**
+ * Build a CockroachDB OPTIONS (...) clause from a plain object.
+ * Single-quotes each value and escapes existing single-quotes.
+ */
+function buildPgOptionsClause(opts) {
+    const pairs = Object.entries(opts).map(([k, v]) => `${k} '${v.replace(/'/g, "''")}'`);
+    return `OPTIONS (${pairs.join(', ')})`;
+}
+/**
+ * Default retry options for CockroachDB connection
+ */
+const DEFAULT_RETRY_OPTIONS = {
+    max: 3,
+    timeout: 1000,
+    match: [
+        'ECONNREFUSED',
+        'ENOTFOUND',
+        'ETIMEDOUT',
+        'connection timeout',
+        'connect timeout',
+        'too many connections',
+        'remaining connection slots are reserved',
+        'Lock not available',
+        // CockroachDB's SQLSTATE 40001 ("serialization_failure"), surfaced to
+        // clients as a "restart transaction" error, is a routine occurrence
+        // under SERIALIZABLE isolation when transactions conflict. It's part of
+        // CockroachDB's documented client contract that these be retried, so
+        // single-statement retries (see query()/executeWithRetry()) need to
+        // match on it too.
+        '40001',
+        'serialization_failure',
+        'restart transaction',
+    ],
+    backoff: false,
+    backoffMultiplier: 2,
+    backoffMax: 10000,
+};
+/**
+ * Default pool options for CockroachDB
+ */
+const DEFAULT_POOL_OPTIONS = {
+    max: 20,
+    min: 0,
+    acquire: 60000,
+    idle: 30000,
+    evict: 1000,
+    handleDisconnects: false,
+    onConnect: undefined,
+    onDisconnect: undefined,
+    enableEvents: false,
+    logPoolOperations: false,
+};
+/**
+ * CockroachDB dialect class that implements the Dialect interface
+ */
+class CockroachDBDialect {
+    constructor(config) {
+        this.name = 'cockroachdb';
+        this.library = 'pg';
+        this.pool = null;
+        this._isConnected = false;
+        this.transactionDepth = 0;
+        this.config = {
+            host: 'localhost',
+            // CockroachDB's default SQL port is 26257 (not Postgres's 5432).
+            port: 26257,
+            max: 20,
+            idleTimeoutMillis: 30000,
+            connectionTimeoutMillis: 2000,
+            ...config,
+        };
+    }
+    /**
+     * Determine whether an error is retryable, i.e. whether the client should
+     * retry the transaction that produced it.
+     *
+     * CockroachDB uses SQLSTATE 40001 ("serialization_failure", surfaced as the
+     * "restart transaction" error) to signal that a transaction could not be
+     * committed due to a conflict with a concurrent transaction under
+     * SERIALIZABLE isolation, and that the client should retry it from the
+     * beginning. See: https://www.cockroachlabs.com/docs/stable/transaction-retry-error-reference
+     *
+     * @param error - The error to check (expected to expose a `.code` property,
+     *   as errors from the `pg` driver do).
+     * @returns True if the error's SQLSTATE is 40001.
+     */
+    isRetryableError(error) {
+        if (!error) {
+            return false;
+        }
+        if (error.code === '40001') {
+            return true;
+        }
+        // Some call paths (e.g. this.query()'s own error handling, or drivers/
+        // wrappers that stringify the original pg error) lose the `.code`
+        // property along the way. Fall back to checking nested causes and the
+        // error message text for CockroachDB's retry signal so callers using
+        // those paths can still detect a retryable error.
+        if (error.cause && error.cause !== error && this.isRetryableError(error.cause)) {
+            return true;
+        }
+        const message = typeof error.message === 'string' ? error.message : String(error);
+        const normalized = message.toLowerCase();
+        return (message.includes('40001') ||
+            normalized.includes('serialization_failure') ||
+            normalized.includes('restart transaction'));
+    }
+    /**
+     * Connect to the CockroachDB database
+     */
+    async connect() {
+        try {
+            this.pool = new PgPool({
+                host: this.config.host,
+                port: this.config.port,
+                user: this.config.username,
+                password: this.config.password,
+                database: this.config.database,
+                max: this.config.max,
+                idleTimeoutMillis: this.config.idleTimeoutMillis,
+                connectionTimeoutMillis: this.config.connectionTimeoutMillis,
+                ssl: this.config.ssl,
+                statement_timeout: this.config.statementTimeout,
+                query_timeout: this.config.queryTimeout,
+            });
+            // Test the connection
+            const client = await this.pool.connect();
+            client.release();
+            this._isConnected = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to connect to CockroachDB database: ${error}`);
+        }
+    }
+    /**
+     * Disconnect from the CockroachDB database
+     */
+    async disconnect() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+            this._isConnected = false;
+        }
+    }
+    /**
+     * Get the current connection pool
+     */
+    getConnection() {
+        return this.pool;
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this._isConnected && this.pool !== null;
+    }
+    /**
+     * Execute a raw SQL query with retry support
+     */
+    async query(sql, options) {
+        // Default retry options for queries
+        const defaultQueryRetryOptions = {
+            max: 3,
+            timeout: 1000,
+            match: [
+                'ECONNREFUSED',
+                'ENOTFOUND',
+                'ETIMEDOUT',
+                'connection timeout',
+                'connect timeout',
+                'too many connections',
+                'remaining connection slots are reserved',
+                'Lock not available',
+                'deadlock',
+                // See DEFAULT_RETRY_OPTIONS above: CockroachDB's 40001/
+                // serialization_failure ("restart transaction") error is the
+                // standard signal that a single statement should be retried.
+                '40001',
+                'serialization_failure',
+                'restart transaction',
+            ],
+            backoff: false,
+            backoffMultiplier: 2,
+            backoffMax: 10000,
+        };
+        const retryOptions = options?.retry;
+        const effectiveRetry = retryOptions
+            ? {
+                ...defaultQueryRetryOptions,
+                ...retryOptions,
+                match: retryOptions.match || defaultQueryRetryOptions.match,
+            }
+            : null;
+        const executeQuery = async () => {
+            if (!this.pool) {
+                throw new Error('Not connected to database');
+            }
+            const isSelect = sql.trim().toUpperCase().startsWith('SELECT') ||
+                sql.trim().toUpperCase().startsWith('WITH') ||
+                sql.trim().toUpperCase().startsWith('SHOW') ||
+                sql.trim().toUpperCase().startsWith('EXPLAIN') ||
+                sql.trim().toUpperCase().startsWith('DESCRIBE');
+            try {
+                // Apply any $1/$2 or :name replacements before sending the query. `replacements`
+                // and `bindings` are both used across this file to pass values for placeholder
+                // substitution (see replaceReplacements()); without this the SQL is sent with
+                // literal, unbound placeholders and CockroachDB raises "there is no parameter $N".
+                const replacements = options?.replacements ?? options?.bindings;
+                const finalSql = replacements !== undefined ? this.replaceReplacements(sql, replacements) : sql;
+                const result = (await this.pool.query(finalSql));
+                // Transform fields
+                const fieldInfo = result.fields
+                    ? result.fields.map((field) => ({
+                        name: field.name,
+                        type: field.dataTypeID.toString(),
+                        length: field.dataTypeModifier || 0,
+                        tableID: 0,
+                        columnID: 0,
+                        nullable: true,
+                        isEnum: field.dataTypeID === 114 /* OID for enum */,
+                        isPrimaryKey: false,
+                    }))
+                    : [];
+                if (isSelect) {
+                    return {
+                        rows: result.rows,
+                        rowCount: result.rowCount || result.rows.length,
+                        fields: fieldInfo,
+                    };
+                }
+                else {
+                    // For INSERT, UPDATE, DELETE - return row count
+                    const rowCount = result.rowCount || 0;
+                    // Handle RETURNING clause
+                    if (result.rows && result.rows.length > 0) {
+                        return {
+                            rows: result.rows,
+                            rowCount: result.rows.length,
+                            fields: fieldInfo,
+                        };
+                    }
+                    return {
+                        rows: [],
+                        rowCount,
+                        fields: fieldInfo,
+                    };
+                }
+            }
+            catch (error) {
+                throw new Error(`CockroachDB Query error: ${error}`);
+            }
+        };
+        // If retry options are provided, use retry logic
+        if (effectiveRetry && effectiveRetry.max > 0) {
+            return this.executeWithRetry(executeQuery, effectiveRetry);
+        }
+        return executeQuery();
+    }
+    /**
+     * Execute a query and stream results using CockroachDB cursor
+     * Uses server-side cursors for efficient memory usage with large datasets
+     * @param sql - The SQL query string
+     * @param options - Stream options
+     * @returns Readable stream for streaming results
+     */
+    queryStream(sql, options) {
+        const { Readable } = require('stream');
+        const batchSize = options?.batchSize || 1000;
+        const highWaterMark = options?.highWaterMark || 1000;
+        // Create a custom readable stream
+        const stream = new Readable({
+            objectMode: true,
+            highWaterMark,
+            read() { },
+        });
+        // Use cursor for streaming - requires a client from the pool
+        if (!this.pool) {
+            stream.destroy(new Error('Not connected to database'));
+            return stream;
+        }
+        // Create a client for cursor operations
+        this.pool.connect((err, client, done) => {
+            if (err) {
+                stream.destroy(err);
+                return;
+            }
+            // Use a cursor for streaming
+            const cursorName = `cursor_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const cursorSql = sql.replace(/\bLIMIT\s+\d+\s*$/i, '').trim();
+            // Declare cursor with the query
+            const declareSql = `DECLARE ${cursorName} CURSOR FOR ${cursorSql}`;
+            client.query(declareSql, (declareErr) => {
+                if (declareErr) {
+                    done();
+                    stream.destroy(declareErr);
+                    return;
+                }
+                // Fetch rows in batches
+                const fetchBatch = () => {
+                    client.query(`FETCH ${batchSize} FROM ${cursorName}`, (fetchErr, result) => {
+                        if (fetchErr) {
+                            done();
+                            stream.destroy(fetchErr);
+                            return;
+                        }
+                        const rows = result?.rows || [];
+                        if (rows.length === 0) {
+                            // No more rows - close cursor and release client
+                            client.query(`CLOSE ${cursorName}`, () => {
+                                done();
+                                stream.push(null);
+                            });
+                        }
+                        else {
+                            // Push each row to the stream
+                            for (const row of rows) {
+                                if (options?.mapToModel && options?.model) {
+                                    // Map to model instance if requested
+                                    const instance = new options.model();
+                                    Object.assign(instance, row);
+                                    stream.push(instance);
+                                }
+                                else {
+                                    stream.push(row);
+                                }
+                            }
+                            // Continue fetching
+                            process.nextTick(fetchBatch);
+                        }
+                    });
+                };
+                // Start fetching
+                fetchBatch();
+            });
+        });
+        return stream;
+    }
+    /**
+     * Execute a function with retry logic for query execution
+     */
+    async executeWithRetry(fn, retryOptions) {
+        let lastError;
+        const { backoff, backoffMultiplier, backoffMax } = retryOptions;
+        for (let attempt = 0; attempt <= retryOptions.max; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                const errorMessage = lastError.message;
+                // Check if this error should be retried
+                const shouldRetry = retryOptions.match.some((pattern) => errorMessage.toLowerCase().includes(pattern.toLowerCase()));
+                if (!shouldRetry || attempt === retryOptions.max) {
+                    throw lastError;
+                }
+                // Calculate delay - use exponential backoff if enabled
+                let delay;
+                if (backoff) {
+                    delay = retryOptions.timeout * Math.pow(backoffMultiplier || 2, attempt);
+                    delay = Math.min(delay, backoffMax || 10000);
+                }
+                else {
+                    delay = retryOptions.timeout;
+                }
+                // Add some jitter to avoid thundering herd
+                const jitter = Math.random() * 100;
+                await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Escape a value for use in a query
+     */
+    escape(value) {
+        // Handle Literal (raw SQL) values - insert directly without escaping
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        if (value === null) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            return `'${this.escapeString(value)}'`;
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'TRUE' : 'FALSE';
+        }
+        if (value instanceof Date) {
+            return `'${this.formatDate(value)}'`;
+        }
+        if (Buffer.isBuffer(value)) {
+            return `E'${value.toString('hex')}'`;
+        }
+        if (Array.isArray(value)) {
+            // Use CockroachDB ARRAY[...] literal syntax, not JSON, so the value is
+            // usable directly in an array-typed column/expression.
+            return this.escapeArray(value);
+        }
+        // JSON stringify objects
+        return `'${this.escapeString(JSON.stringify(value))}'`;
+    }
+    /**
+     * Escape a string for SQL
+     */
+    escapeString(str) {
+        return str.replace(/'/g, "''").replace(/\\/g, '\\\\');
+    }
+    /**
+     * Format a date for CockroachDB
+     */
+    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 milliseconds = String(date.getMilliseconds()).padStart(3, '0');
+        return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds}`;
+    }
+    /**
+     * Escape an identifier (table name, column name, etc.)
+     * CockroachDB uses double quotes for identifiers
+     */
+    escapeId(identifier) {
+        const id = String(identifier ?? '');
+        return `"${id.replace(/"/g, '""')}"`;
+    }
+    /**
+     * Quote an identifier (column name, table name)
+     * CockroachDB uses double quotes for identifiers
+     */
+    quoteIdentifier(identifier) {
+        return this.escapeId(identifier);
+    }
+    /**
+     * Quote a table name
+     * Includes schema prefix if provided
+     */
+    quoteTable(tableName, schema) {
+        if (schema && schema !== 'public') {
+            return `${this.escapeId(schema)}.${this.escapeId(tableName)}`;
+        }
+        return this.escapeId(tableName);
+    }
+    /**
+     * Get the database version
+     */
+    async getDatabaseVersion() {
+        if (!this.pool) {
+            throw new Error('Not connected to database');
+        }
+        const result = await this.query('SELECT version() as version');
+        return result.rows[0]?.version || 'Unknown';
+    }
+    /**
+     * Create a database schema
+     * @param schema - The schema name to create
+     */
+    async createSchema(schema) {
+        await this.query(`CREATE SCHEMA ${this.escapeId(schema)}`);
+    }
+    /**
+     * Drop a database schema
+     * @param schema - The schema name to drop
+     * @param options - Drop options (e.g., cascade)
+     */
+    async dropSchema(schema, options) {
+        let sql = 'DROP SCHEMA';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(schema)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Show all schemas in the database
+     */
+    async showAllSchemas() {
+        const result = await this.query(`SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('pg_catalog', 'information_schema') ORDER BY schema_name`, { raw: true });
+        return result.rows?.map((row) => row.schema_name) || [];
+    }
+    /**
+     * List all schemas in the database
+     */
+    async listSchemas() {
+        return this.showAllSchemas();
+    }
+    /**
+     * Replace placeholders in SQL with actual values
+     * @param sql - SQL string with placeholders
+     * @param replacements - Object or array of replacement values
+     */
+    replaceReplacements(sql, replacements) {
+        if (!replacements) {
+            return sql;
+        }
+        if (Array.isArray(replacements)) {
+            // Array-based replacements: $1, $2, etc.
+            let result = sql;
+            replacements.forEach((value, index) => {
+                const placeholder = `$${index + 1}`;
+                if (value === null) {
+                    result = result.replace(new RegExp(placeholder.replace('$', '\\$'), 'g'), 'NULL');
+                }
+                else if (typeof value === 'string') {
+                    result = result.replace(new RegExp(placeholder.replace('$', '\\$'), 'g'), `'${value.replace(/'/g, "''")}'`);
+                }
+                else if (value instanceof Date) {
+                    result = result.replace(new RegExp(placeholder.replace('$', '\\$'), 'g'), `'${value.toISOString()}'`);
+                }
+                else {
+                    result = result.replace(new RegExp(placeholder.replace('$', '\\$'), 'g'), String(value));
+                }
+            });
+            return result;
+        }
+        else {
+            // Object-based replacements: :name, :value, etc.
+            let result = sql;
+            for (const [key, value] of Object.entries(replacements)) {
+                const placeholder = `:${key}`;
+                const regex = new RegExp(placeholder.replace(/:/g, '\\:'), 'g');
+                if (value === null) {
+                    result = result.replace(regex, 'NULL');
+                }
+                else if (typeof value === 'string') {
+                    result = result.replace(regex, `'${value.replace(/'/g, "''")}'`);
+                }
+                else if (value instanceof Date) {
+                    result = result.replace(regex, `'${value.toISOString()}'`);
+                }
+                else {
+                    result = result.replace(regex, String(value));
+                }
+            }
+            return result;
+        }
+    }
+    /**
+     * Create a new table
+     */
+    async createTable(tableName, columns, options) {
+        const columnDefs = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            columnDefs.push(this.getColumnDefinitionSql(columnName, definition));
+        }
+        // Add constraints from options
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql) {
+                    columnDefs.push(constraintSql);
+                }
+            }
+        }
+        // Column families (CockroachDB storage-layout hint): `FAMILY name (col1, col2)`.
+        // CockroachDB groups columns into families to control how they're
+        // co-located in the underlying key-value store; explicit families let
+        // callers separate hot/cold columns for wide tables.
+        // See: https://www.cockroachlabs.com/docs/stable/column-families
+        if (options?.families && options.families.length > 0) {
+            for (const family of options.families) {
+                if (!family.columns || family.columns.length === 0) {
+                    throw new Error('CockroachDB column family must specify at least one column.');
+                }
+                const namePart = family.name ? `${this.escapeId(family.name)} ` : '';
+                const cols = family.columns.map((c) => this.escapeId(c)).join(', ');
+                columnDefs.push(`FAMILY ${namePart}(${cols})`);
+            }
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        // Handle CockroachDB-specific options
+        // Tablespace (CockroachDB-specific)
+        if (options?.tablespace) {
+            sql += ` TABLESPACE ${options.tablespace}`;
+        }
+        // rowFormat is not supported in CockroachDB
+        if (options?.rowFormat) {
+            console.warn(`CockroachDB: rowFormat option '${options.rowFormat}' is not supported and will be ignored`);
+        }
+        // engine and charset are not supported in CockroachDB
+        if (options?.engine) {
+            console.warn(`CockroachDB: engine option '${options.engine}' is not supported and will be ignored`);
+        }
+        if (options?.charset) {
+            console.warn(`CockroachDB: charset option '${options.charset}' is not supported and will be ignored`);
+        }
+        // Inherit from parent table (CockroachDB-specific)
+        if (options?.inherit) {
+            sql += ` INHERITS (${this.escapeId(options.inherit)})`;
+        }
+        // Partition by clause (CockroachDB)
+        if (options?.partitionBy) {
+            sql += ` PARTITION BY ${options.partitionBy}`;
+        }
+        // Multi-region table locality (CockroachDB): `LOCALITY GLOBAL` /
+        // `LOCALITY REGIONAL BY TABLE [IN region]` / `LOCALITY REGIONAL BY ROW [AS column]`.
+        // Only valid against a multi-region database (one with a primary region set).
+        // See: https://www.cockroachlabs.com/docs/stable/table-localities
+        if (options?.locality) {
+            sql += ` ${this.buildLocalityClause(options.locality)}`;
+        }
+        // Handle charset and collate (limited support in CockroachDB - affects default for new columns)
+        if (options?.collate) {
+            sql += ` COLLATE ${options.collate}`;
+        }
+        await this.query(sql);
+        // Handle uniqueKeys (CockroachDB supports unique constraints)
+        // Support both old format (Record<string, string[]>) and new format (UniqueKeyOptions[])
+        if (options?.uniqueKeys) {
+            // Check if it's the new array format
+            if (Array.isArray(options.uniqueKeys)) {
+                for (const uk of options.uniqueKeys) {
+                    const constraintName = uk.name || `${tableName}_${uk.fields.join('_')}_key`;
+                    const constraintSql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} UNIQUE (${uk.fields.map((f) => this.escapeId(f)).join(', ')})`;
+                    await this.query(constraintSql);
+                }
+            }
+            else {
+                // Legacy object format
+                for (const [keyName, fields] of Object.entries(options.uniqueKeys)) {
+                    const constraintName = keyName || `${tableName}_${fields.join('_')}_key`;
+                    const constraintSql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} UNIQUE (${fields.map((f) => this.escapeId(f)).join(', ')})`;
+                    await this.query(constraintSql);
+                }
+            }
+        }
+        // Add table comment (CockroachDB)
+        if (options?.comment) {
+            await this.query(`COMMENT ON TABLE ${this.escapeId(tableName)} IS '${this.escapeString(options.comment)}'`);
+        }
+        // Handle initialAutoIncrement for CockroachDB - set sequence start value
+        if (options?.initialAutoIncrement) {
+            // Find auto-increment column and set its sequence
+            for (const [columnName, definition] of Object.entries(columns)) {
+                if (definition.autoIncrement) {
+                    const sequenceName = `${tableName}_${columnName}_seq`;
+                    await this.query(`ALTER SEQUENCE ${this.escapeId(sequenceName)} START WITH ${options.initialAutoIncrement}`);
+                }
+            }
+        }
+        // Create indexes after table creation
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.addIndex(tableName, index.name || `idx_${tableName}_${index.fields.join('_')}`, index.fields, {
+                    unique: index.unique,
+                    type: index.type,
+                    using: index.using,
+                    where: index.where,
+                    expression: index.expression,
+                    include: index.include,
+                });
+            }
+        }
+    }
+    /**
+     * Build constraint SQL for table creation
+     */
+    buildConstraintSql(constraint) {
+        const name = constraint.name ? `"${constraint.name}"` : '';
+        const fields = constraint.fields?.map((f) => this.escapeId(f)).join(', ') || '';
+        switch (constraint.type) {
+            case 'PRIMARY KEY':
+                return `${name ? name + ' ' : ''}PRIMARY KEY (${fields})`;
+            case 'UNIQUE':
+                return `${name ? name + ' ' : ''}UNIQUE (${fields})`;
+            case 'FOREIGN KEY':
+                if (!constraint.references)
+                    return null;
+                // Handle composite foreign keys (string | string[])
+                const refField = constraint.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                    : `(${this.escapeId(refField)})`;
+                let fkSql = `${name ? name + ' ' : ''}FOREIGN KEY (${fields}) `;
+                fkSql += `REFERENCES ${this.escapeId(constraint.references.table)}${refFieldSql}`;
+                if (constraint.references.onDelete) {
+                    fkSql += ` ON DELETE ${constraint.references.onDelete}`;
+                }
+                if (constraint.references.onUpdate) {
+                    fkSql += ` ON UPDATE ${constraint.references.onUpdate}`;
+                }
+                return fkSql;
+            case 'CHECK':
+                if (!constraint.check)
+                    return null;
+                return `${name ? name + ' ' : ''}CHECK (${constraint.check})`;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Generate column definition SQL for CockroachDB
+     */
+    getColumnDefinitionSql(columnName, definition) {
+        // Check if this is an auto-increment column and use SERIAL/BIGSERIAL
+        const dt = definition.type;
+        if (definition.autoIncrement && (dt.key === 'INTEGER' || !dt.key)) {
+            // For auto-increment INTEGER columns, use SERIAL
+            let sql = `${this.escapeId(columnName)} SERIAL`;
+            if (definition.primaryKey) {
+                sql += ' PRIMARY KEY';
+            }
+            if (definition.allowNull === false) {
+                sql += ' NOT NULL';
+            }
+            if (definition.unique) {
+                sql += ' UNIQUE';
+            }
+            if (definition.references) {
+                // Handle composite foreign keys (string | string[])
+                const refField3 = definition.references.field;
+                const refFieldSql3 = Array.isArray(refField3)
+                    ? `(${refField3.map((f) => this.escapeId(f)).join(', ')})`
+                    : this.escapeId(refField3);
+                sql += ` REFERENCES ${this.escapeId(definition.references.table)}(${refFieldSql3})`;
+                if (definition.references.onDelete) {
+                    sql += ` ON DELETE ${definition.references.onDelete}`;
+                }
+                if (definition.references.onUpdate) {
+                    sql += ` ON UPDATE ${definition.references.onUpdate}`;
+                }
+            }
+            return sql;
+        }
+        let sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type)}`;
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.getDefaultValue(definition.defaultValue)}`;
+        }
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.unique) {
+            if (typeof definition.unique === 'string') {
+                sql += ` UNIQUE (${this.escapeId(definition.unique)})`;
+            }
+            else {
+                sql += ' UNIQUE';
+            }
+        }
+        if (definition.references) {
+            // Handle composite foreign keys (string | string[])
+            const refField2 = definition.references.field;
+            const refFieldSql2 = Array.isArray(refField2)
+                ? `(${refField2.map((f) => this.escapeId(f)).join(', ')})`
+                : this.escapeId(refField2);
+            sql += ` REFERENCES ${this.escapeId(definition.references.table)}(${refFieldSql2})`;
+            if (definition.references.onDelete) {
+                sql += ` ON DELETE ${definition.references.onDelete}`;
+            }
+            if (definition.references.onUpdate) {
+                sql += ` ON UPDATE ${definition.references.onUpdate}`;
+            }
+        }
+        if (definition.comment) {
+            sql += ` COMMENT '${this.escapeString(definition.comment)}'`;
+        }
+        return sql;
+    }
+    /**
+     * Get default value SQL
+     */
+    getDefaultValue(value) {
+        if (value === null) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            // Check for CockroachDB functions
+            if (value.toUpperCase().includes('CURRENT_') || value.toUpperCase() === 'NULL') {
+                return value;
+            }
+            return `'${this.escapeString(value)}'`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        if (value instanceof Date) {
+            return `'${this.formatDate(value)}'`;
+        }
+        // Handle DataType instances with toDefaultValue method (e.g., DataTypes.NOW)
+        if (typeof value === 'object' &&
+            value !== null &&
+            typeof value.toDefaultValue === 'function') {
+            return value.toDefaultValue();
+        }
+        return `'${this.escapeString(String(value))}'`;
+    }
+    /**
+     * Drop a table
+     */
+    async dropTable(tableName, options) {
+        let sql = 'DROP TABLE';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Create a partitioned table (CockroachDB)
+     *
+     * @param tableName - Name of the table to create
+     * @param columns - Column definitions
+     * @param options - Table options including partition configuration
+     */
+    async createPartitionedTable(tableName, columns, options) {
+        const columnDefs = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            columnDefs.push(this.getColumnDefinitionSql(columnName, definition));
+        }
+        // Add constraints from options
+        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.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        // Partition by clause (CockroachDB)
+        if (options?.partitionBy) {
+            const columns = Array.isArray(options.partitionBy.column)
+                ? options.partitionBy.column.join(', ')
+                : options.partitionBy.column;
+            sql += ` PARTITION BY ${options.partitionBy.type.toUpperCase()} (${columns})`;
+        }
+        await this.query(sql);
+        // Create initial partitions if specified
+        if (options?.partitions && options.partitions.length > 0) {
+            for (const partition of options.partitions) {
+                await this.createPartition({
+                    parentTable: tableName,
+                    name: partition.name,
+                    bound: partition.bound,
+                    tablespace: partition.tablespace,
+                    storageParameters: partition.storageParameters,
+                });
+            }
+        }
+    }
+    /**
+     * Create a partition for an existing partitioned table (CockroachDB)
+     *
+     * @param options - Partition creation options
+     */
+    async createPartition(options) {
+        let sql = `CREATE TABLE ${this.escapeId(options.name)} PARTITION OF ${this.escapeId(options.parentTable)}`;
+        if (options.bound) {
+            const bound = options.bound;
+            // Check for list partition
+            if ('values' in bound && bound.values && Array.isArray(bound.values)) {
+                const values = bound.values.map((v) => (typeof v === 'string' ? `'${v}'` : v)).join(', ');
+                sql += ` FOR VALUES IN (${values})`;
+            }
+            // Check for hash partition
+            else if ('modulus' in bound && bound.modulus !== undefined) {
+                const hashBound = bound;
+                sql += ` FOR VALUES WITH (MODULUS ${hashBound.modulus}, REMAINDER ${hashBound.remainder})`;
+            }
+            // Default to range partition
+            else {
+                const rangeBound = bound;
+                const from = rangeBound.from;
+                const to = rangeBound.to || 'MAXVALUE';
+                const fromStr = from instanceof Date ? from.toISOString().split('T')[0] : from;
+                const toStr = to instanceof Date ? to.toISOString().split('T')[0] : to;
+                sql += ` FOR VALUES FROM (${fromStr}) TO (${toStr})`;
+            }
+        }
+        if (options.tablespace) {
+            sql += ` TABLESPACE ${options.tablespace}`;
+        }
+        if (options.storageParameters) {
+            const params = Object.entries(options.storageParameters)
+                .map(([key, value]) => `${key} = ${value}`)
+                .join(', ');
+            sql += ` WITH (${params})`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Attach a partition to a partitioned table (CockroachDB)
+     *
+     * @param options - Partition attachment options
+     */
+    async attachPartition(options) {
+        const sql = `ALTER TABLE ${this.escapeId(options.parentTable)} ATTACH PARTITION ${this.escapeId(options.partitionName)}`;
+        await this.query(sql);
+    }
+    /**
+     * Detach a partition from a partitioned table (CockroachDB)
+     *
+     * @param options - Partition detachment options
+     */
+    async detachPartition(options) {
+        let sql = `ALTER TABLE ${this.escapeId(options.partitionName)} DETACH PARTITION`;
+        if (options.validate === false) {
+            sql += ' NOT VALIDATE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Drop a partition (CockroachDB)
+     *
+     * @param partitionName - Name of the partition to drop
+     * @param options - Drop options
+     */
+    async dropPartition(partitionName, options) {
+        let sql = 'DROP TABLE';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(partitionName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Add a partition to an existing partitioned table (CockroachDB)
+     * @param tableName - Name of the partitioned table
+     * @param partitionName - Name for the new partition
+     * @param partitionSpec - Partition specification
+     */
+    async addPartition(tableName, partitionName, partitionSpec) {
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} ATTACH PARTITION ${this.escapeId(partitionName)}`;
+        if (partitionSpec.values) {
+            sql += ` FOR VALUES ${partitionSpec.values}`;
+        }
+        else if (partitionSpec.forValues) {
+            sql += ` FOR VALUES ${partitionSpec.forValues}`;
+        }
+        await this.query(sql);
+    }
+    // ==================== Multi-region (LOCALITY) ====================
+    /**
+     * Build the `LOCALITY ...` clause fragment (without a leading space, but
+     * including the `LOCALITY` keyword itself) for a given locality setting.
+     * Shared by `createTable` and `setTableLocality`.
+     */
+    buildLocalityClause(locality) {
+        switch (locality.type) {
+            case 'global':
+                return 'LOCALITY GLOBAL';
+            case 'regional-by-table':
+                return locality.region
+                    ? `LOCALITY REGIONAL BY TABLE IN ${this.escapeId(locality.region)}`
+                    : 'LOCALITY REGIONAL BY TABLE';
+            case 'regional-by-row':
+                return locality.column
+                    ? `LOCALITY REGIONAL BY ROW AS ${this.escapeId(locality.column)}`
+                    : 'LOCALITY REGIONAL BY ROW';
+            default:
+                throw new Error(`Unknown CockroachDB locality type: ${locality.type}`);
+        }
+    }
+    /**
+     * Change the multi-region locality of an existing table
+     * (`ALTER TABLE ... SET LOCALITY ...`).
+     *
+     * Requires the database to already be multi-region (see
+     * `setPrimaryRegion`/`addRegion`).
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/table-localities
+     */
+    async setTableLocality(tableName, locality) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} SET ${this.buildLocalityClause(locality)}`;
+        await this.query(sql);
+    }
+    /**
+     * Add a region to a multi-region database (`ALTER DATABASE ... ADD REGION ...`).
+     *
+     * @param region - Region name (e.g. `'us-east1'`)
+     * @param options - `database` to target a database other than the current one
+     */
+    async addRegion(region, options) {
+        const dbPart = options?.database ? `${this.escapeId(options.database)} ` : '';
+        const ifNotExists = options?.ifNotExists ? 'IF NOT EXISTS ' : '';
+        const sql = `ALTER DATABASE ${dbPart}ADD REGION ${ifNotExists}${this.escapeId(region)}`;
+        await this.query(sql);
+    }
+    /**
+     * Remove a region from a multi-region database (`ALTER DATABASE ... DROP REGION ...`).
+     */
+    async dropRegion(region, options) {
+        const dbPart = options?.database ? `${this.escapeId(options.database)} ` : '';
+        const sql = `ALTER DATABASE ${dbPart}DROP REGION ${this.escapeId(region)}`;
+        await this.query(sql);
+    }
+    /**
+     * Set (or change) the primary region of a database
+     * (`ALTER DATABASE ... {SET|PRIMARY REGION} ...`). Setting a primary
+     * region for the first time promotes the database to a multi-region
+     * database; CockroachDB automatically adds the region as a side effect if
+     * it hasn't been added yet.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/multiregion-overview
+     */
+    async setPrimaryRegion(region, options) {
+        const dbPart = options?.database ? `${this.escapeId(options.database)} ` : '';
+        const sql = `ALTER DATABASE ${dbPart}SET PRIMARY REGION ${this.escapeId(region)}`;
+        await this.query(sql);
+    }
+    /**
+     * Set the survival goal of a multi-region database
+     * (`ALTER DATABASE ... SURVIVE {ZONE|REGION} FAILURE`).
+     */
+    async setSurvivalGoal(goal, options) {
+        const dbPart = options?.database ? `${this.escapeId(options.database)} ` : '';
+        const failureClause = goal === 'zone' ? 'ZONE FAILURE' : 'REGION FAILURE';
+        const sql = `ALTER DATABASE ${dbPart}SURVIVE ${failureClause}`;
+        await this.query(sql);
+    }
+    // ==================== Zone configuration ====================
+    /**
+     * Resolve a `CockroachZoneTarget` to the SQL fragment that follows
+     * `ALTER ...` in `CONFIGURE ZONE`/`SPLIT AT`/`UNSPLIT AT` statements,
+     * e.g. `TABLE "orders"`, `INDEX "orders"@"idx_name"`, or
+     * `PARTITION "p1" OF TABLE "orders"`.
+     */
+    resolveZoneTarget(target) {
+        switch (target.kind) {
+            case 'table':
+                return `TABLE ${this.escapeId(target.name)}`;
+            case 'index':
+                return `INDEX ${this.escapeId(target.table)}@${this.escapeId(target.index)}`;
+            case 'partition': {
+                const ofClause = target.index
+                    ? `INDEX ${this.escapeId(target.table)}@${this.escapeId(target.index)}`
+                    : `TABLE ${this.escapeId(target.table)}`;
+                return `PARTITION ${this.escapeId(target.name)} OF ${ofClause}`;
+            }
+            case 'database':
+                return `DATABASE ${this.escapeId(target.name)}`;
+            default:
+                throw new Error(`Unknown CockroachDB zone target kind: ${target.kind}`);
+        }
+    }
+    /**
+     * Configure replication/placement settings for a table, index, partition,
+     * or database (`ALTER ... CONFIGURE ZONE USING ...`).
+     *
+     * Exposes the subset of zone-configuration variables that are reasonable
+     * for an ORM to surface: replica count, placement constraints, lease
+     * preferences, GC TTL, and range size bounds. For anything more advanced,
+     * callers can fall back to raw `query()`.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/configure-zone
+     */
+    async configureZone(target, options) {
+        const assignments = [];
+        if (options.numReplicas !== undefined) {
+            assignments.push(`num_replicas = ${options.numReplicas}`);
+        }
+        if (options.numVoters !== undefined) {
+            assignments.push(`num_voters = ${options.numVoters}`);
+        }
+        if (options.constraints !== undefined) {
+            assignments.push(`constraints = '${this.escapeString(options.constraints)}'`);
+        }
+        if (options.leasePreferences !== undefined) {
+            const prefs = `[${options.leasePreferences.map((p) => `'${this.escapeString(p)}'`).join(', ')}]`;
+            assignments.push(`lease_preferences = ${prefs}`);
+        }
+        if (options.gcTtlSeconds !== undefined) {
+            assignments.push(`gc.ttlseconds = ${options.gcTtlSeconds}`);
+        }
+        if (options.rangeMinBytes !== undefined) {
+            assignments.push(`range_min_bytes = ${options.rangeMinBytes}`);
+        }
+        if (options.rangeMaxBytes !== undefined) {
+            assignments.push(`range_max_bytes = ${options.rangeMaxBytes}`);
+        }
+        if (assignments.length === 0) {
+            throw new Error('configureZone() requires at least one zone-configuration option.');
+        }
+        const sql = `ALTER ${this.resolveZoneTarget(target)} CONFIGURE ZONE USING ${assignments.join(', ')}`;
+        await this.query(sql);
+    }
+    /**
+     * Reset a zone configuration back to its inherited default
+     * (`ALTER ... CONFIGURE ZONE DISCARD`).
+     */
+    async resetZoneConfig(target) {
+        const sql = `ALTER ${this.resolveZoneTarget(target)} CONFIGURE ZONE DISCARD`;
+        await this.query(sql);
+    }
+    // ==================== Manual range splitting ====================
+    /**
+     * Format a single split/unsplit key value for use inside a `VALUES (...)`
+     * tuple: quote strings, pass numbers/booleans through, and stringify
+     * `Date`s as ISO timestamps.
+     */
+    formatSplitValue(value) {
+        if (value === null || value === undefined) {
+            return 'NULL';
+        }
+        if (value instanceof Date) {
+            return `'${value.toISOString()}'`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        return `'${this.escapeString(String(value))}'`;
+    }
+    /**
+     * Manually split a range at the given key value(s)
+     * (`ALTER TABLE/INDEX ... SPLIT AT VALUES (...)`), to pre-emptively
+     * distribute a hot/monotonically-growing key range across nodes before
+     * CockroachDB's automatic range-size-based splitting would kick in.
+     *
+     * `values` is an array of row tuples matching the index prefix; pass
+     * multiple tuples to create multiple split points in one call.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/alter-table#split-at
+     */
+    async splitAt(target, values, options) {
+        if (!values || values.length === 0) {
+            throw new Error('splitAt() requires at least one value tuple.');
+        }
+        const tuples = values
+            .map((tuple) => `(${tuple.map((v) => this.formatSplitValue(v)).join(', ')})`)
+            .join(', ');
+        let sql = `ALTER ${this.resolveZoneTarget(target)} SPLIT AT VALUES ${tuples}`;
+        if (options?.expiration) {
+            sql += ` WITH EXPIRATION ${this.formatSplitValue(options.expiration)}`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Undo a manual (or expired) range split
+     * (`ALTER TABLE/INDEX ... UNSPLIT AT VALUES (...)`), or unsplit every
+     * manually-created split point on the target when `values` is omitted
+     * (`UNSPLIT ALL`).
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/alter-table#unsplit-at
+     */
+    async unsplitAt(target, values) {
+        if (!values || values.length === 0) {
+            const sql = `ALTER ${this.resolveZoneTarget(target)} UNSPLIT ALL`;
+            await this.query(sql);
+            return;
+        }
+        const tuples = values
+            .map((tuple) => `(${tuple.map((v) => this.formatSplitValue(v)).join(', ')})`)
+            .join(', ');
+        const sql = `ALTER ${this.resolveZoneTarget(target)} UNSPLIT AT VALUES ${tuples}`;
+        await this.query(sql);
+    }
+    /**
+     * Create a database view
+     */
+    async createView(viewName, query, options) {
+        const viewNameWithSchema = options?.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(viewName)}`
+            : this.escapeId(viewName);
+        let sql = 'CREATE VIEW';
+        if (options?.replace) {
+            sql = 'CREATE OR REPLACE VIEW';
+        }
+        sql += ` ${viewNameWithSchema} AS ${query}`;
+        await this.query(sql);
+        if (options?.comment) {
+            const commentSql = `COMMENT ON VIEW ${viewNameWithSchema} IS ${this.escape(options.comment)}`;
+            await this.query(commentSql);
+        }
+    }
+    /**
+     * Drop a database view
+     */
+    async dropView(viewName, options) {
+        let sql = 'DROP VIEW';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(viewName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Show all views in the database
+     */
+    async showViews() {
+        const result = await this.query(`SELECT table_name FROM information_schema.views WHERE table_schema = 'public' ORDER BY table_name`, { raw: true });
+        return result.rows?.map((row) => row.table_name) || [];
+    }
+    /**
+     * Create a materialized view
+     * @param options - Materialized view options
+     */
+    async createMaterializedView(options) {
+        const viewNameWithSchema = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        let sql = 'CREATE MATERIALIZED VIEW';
+        if (options.replace) {
+            sql = 'CREATE OR REPLACE MATERIALIZED VIEW';
+        }
+        else if (options.ifNotExists) {
+            sql = 'CREATE MATERIALIZED VIEW IF NOT EXISTS';
+        }
+        sql += ` ${viewNameWithSchema} AS ${options.query}`;
+        if (!options.withData) {
+            sql += ' WITH NO DATA';
+        }
+        await this.query(sql);
+        // Create unique index if provided (required for CONCURRENTLY refresh)
+        if (options.uniqueIndex) {
+            const indexSql = `CREATE UNIQUE INDEX ${this.escapeId(options.uniqueIndex)} ON ${viewNameWithSchema} (${options.uniqueIndex})`;
+            await this.query(indexSql);
+        }
+        if (options.comment) {
+            const commentSql = `COMMENT ON MATERIALIZED VIEW ${viewNameWithSchema} IS ${this.escape(options.comment)}`;
+            await this.query(commentSql);
+        }
+    }
+    /**
+     * Refresh a materialized view
+     * @param viewName - Name of the materialized view to refresh
+     * @param options - Refresh options
+     */
+    async refreshMaterializedView(viewName, options) {
+        let sql = 'REFRESH MATERIALIZED VIEW';
+        if (options?.concurrently) {
+            sql += ' CONCURRENTLY';
+        }
+        sql += ` ${this.escapeId(viewName)}`;
+        if (options?.withNoData) {
+            sql += ' WITH NO DATA';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Drop a materialized view
+     * @param viewName - Name of the materialized view to drop
+     * @param options - Drop options
+     */
+    async dropMaterializedView(viewName, options) {
+        let sql = 'DROP MATERIALIZED VIEW';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(viewName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Check if a materialized view exists
+     *
+     * Queries `pg_class`/`pg_namespace` directly (filtering on
+     * `relkind = 'm'`) rather than the derived `pg_matviews` view. CockroachDB's
+     * `pg_catalog` compatibility layer is partial, and `pg_matviews` — itself
+     * normally just a view defined on top of `pg_class` in real Postgres — is
+     * not guaranteed to exist/be populated the same way on CockroachDB.
+     * `pg_class` is the more fundamental catalog and a safer bet for accurate
+     * results (an absent/empty `pg_matviews` would otherwise silently report a
+     * false "materialized view doesn't exist").
+     * @param viewName - Name of the materialized view
+     * @returns True if the materialized view exists
+     */
+    async hasMaterializedView(viewName) {
+        const result = await this.query(`SELECT 1 FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid ` +
+            `WHERE c.relkind = 'm' AND c.relname = ${this.escape(viewName)} AND n.nspname = 'public'`, { raw: true });
+        return result.rows?.length > 0;
+    }
+    /**
+     * Show all materialized views in the database
+     *
+     * See `hasMaterializedView` for why this queries `pg_class`/`pg_namespace`
+     * (`relkind = 'm'`) instead of the `pg_matviews` compatibility view.
+     */
+    async showMaterializedViews() {
+        const result = await this.query(`SELECT c.relname AS matviewname FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid ` +
+            `WHERE c.relkind = 'm' AND n.nspname = 'public' ORDER BY c.relname`, { raw: true });
+        return result.rows?.map((row) => row.matviewname) || [];
+    }
+    // ==================== Stored Procedures ====================
+    /**
+     * Create a stored procedure (CockroachDB)
+     */
+    async createStoredProcedure(options) {
+        const schema = options.schema || 'public';
+        const procName = `${this.escapeId(schema)}.${this.escapeId(options.name)}`;
+        let sql = 'CREATE PROCEDURE';
+        if (options.replace) {
+            sql = 'CREATE OR REPLACE PROCEDURE';
+        }
+        else if (options.ifNotExists) {
+            sql = 'CREATE PROCEDURE IF NOT EXISTS';
+        }
+        // Add parameters
+        if (options.params && options.params.length > 0) {
+            const params = options.params
+                .map((p) => {
+                const mode = p.mode ? `${p.mode} ` : '';
+                const defaultPart = p.defaultValue !== undefined ? ` DEFAULT ${this.escape(p.defaultValue)}` : '';
+                return `${mode}${this.escapeId(p.name)} ${p.type}${defaultPart}`;
+            })
+                .join(', ');
+            sql += ` ${procName} (${params})`;
+        }
+        else {
+            sql += ` ${procName}`;
+        }
+        sql += ` LANGUAGE plpgsql\n${options.body}`;
+        await this.query(sql);
+    }
+    /**
+     * Create a foreign data wrapper — not supported in CockroachDB.
+     * @param _fdwName - Foreign data wrapper name (unused; kept for interface parity)
+     * @param _options - Options (unused; kept for interface parity)
+     */
+    async createForeignDataWrapper(_fdwName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    async dropForeignDataWrapper(_fdwName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    async createForeignServer(_serverName, _fdwName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    async dropForeignServer(_serverName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    async createForeignTable(_tableName, _columns, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    async changeOwner(newOwner, tableName) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} OWNER TO ${this.escapeId(newOwner)}`;
+        await this.query(sql);
+    }
+    async addConstraint(tableName, options) {
+        const constraintName = options.name || `${tableName}_${options.fields.join('_')}_${options.type.toLowerCase()}`;
+        const fieldsSql = options.fields.map((f) => this.escapeId(f)).join(', ');
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} `;
+        switch (options.type) {
+            case 'UNIQUE':
+                sql += `UNIQUE (${fieldsSql})`;
+                break;
+            case 'PRIMARY KEY':
+                sql += `PRIMARY KEY (${fieldsSql})`;
+                break;
+            case 'FOREIGN KEY':
+                sql += `FOREIGN KEY (${fieldsSql}) REFERENCES ${this.escapeId(options.references.table)} (${options.references.fields.map((f) => this.escapeId(f)).join(', ')})`;
+                break;
+            case 'CHECK':
+                sql += `CHECK (${options.check})`;
+                break;
+        }
+        await this.query(sql);
+    }
+    async removeConstraint(tableName, constraintName) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`;
+        await this.query(sql);
+    }
+    async createSecurityPolicy(_policyName, _tableName, _options) {
+        throw new Error('Security policies are not supported in CockroachDB');
+    }
+    async dropSecurityPolicy(_policyName, _tableName) {
+        throw new Error('Security policies are not supported in CockroachDB');
+    }
+    /**
+     * Drop a stored procedure
+     */
+    async dropStoredProcedure(procedureName, options) {
+        const schema = options?.schema || 'public';
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const sql = `DROP PROCEDURE ${ifExists}${this.escapeId(schema)}.${this.escapeId(procedureName)}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * Drop a stored procedure (alias for dropStoredProcedure)
+     */
+    async dropProcedure(procedureName, options) {
+        return this.dropStoredProcedure(procedureName, options);
+    }
+    /**
+     * Create a stored procedure (alias for createStoredProcedure)
+     */
+    async createProcedure(options) {
+        return this.createStoredProcedure(options);
+    }
+    /**
+     * Execute a stored procedure
+     */
+    async executeStoredProcedure(options) {
+        const schema = options.schema || 'public';
+        const procName = `${this.escapeId(schema)}.${this.escapeId(options.procedureName)}`;
+        let sql = `CALL ${procName}`;
+        if (options.params && Object.keys(options.params).length > 0) {
+            const params = Object.entries(options.params)
+                .map(([name, value]) => `${this.escapeId(name)} => ${this.escape(value)}`)
+                .join(', ');
+            sql += `(${params})`;
+        }
+        return this.query(sql, { timeout: options.timeout });
+    }
+    /**
+     * Check if a stored procedure exists
+     */
+    async hasStoredProcedure(procedureName, schema) {
+        const db = schema || 'public';
+        const sql = `SELECT proname FROM pg_proc p JOIN pg_namespace n ON p.pronamespace = n.oid WHERE n.nspname = '${db}' AND proname = '${procedureName}' AND prokind = 'p'`;
+        const result = await this.query(sql, { plain: true });
+        return !!result;
+    }
+    // ==================== User-Defined Functions (UDFs) ====================
+    /**
+     * Create a user-defined function (CockroachDB)
+     *
+     * CockroachDB has supported `CREATE FUNCTION` for SQL and PL/pgSQL
+     * functions since v22.2/23.1, and unlike `CREATE PROCEDURE` (see
+     * `createStoredProcedure`), functions can be used directly in SELECT
+     * lists, computed column expressions, and CHECK constraints. A function
+     * must declare a `RETURNS` type, and may optionally declare a volatility
+     * category:
+     *  - `VOLATILE` (the default when omitted): may modify the database
+     *    and/or return different results on successive calls with the same
+     *    arguments.
+     *  - `STABLE`: cannot modify the database and returns the same result
+     *    for the same arguments within a single statement; lets the
+     *    optimizer avoid re-evaluating it per-row when safe.
+     *  - `IMMUTABLE`: cannot modify the database and always returns the same
+     *    result for the same arguments. Required for a function to be used
+     *    in a computed column expression.
+     * @see https://www.cockroachlabs.com/docs/stable/create-function
+     */
+    async createFunction(options) {
+        const schema = options.schema || 'public';
+        const funcName = `${this.escapeId(schema)}.${this.escapeId(options.name)}`;
+        let sql = 'CREATE FUNCTION';
+        if (options.replace) {
+            sql = 'CREATE OR REPLACE FUNCTION';
+        }
+        else if (options.ifNotExists) {
+            sql = 'CREATE FUNCTION IF NOT EXISTS';
+        }
+        // Add parameters
+        if (options.params && options.params.length > 0) {
+            const params = options.params
+                .map((p) => {
+                const mode = p.mode && p.mode !== 'IN' ? `${p.mode} ` : '';
+                const defaultPart = p.defaultValue !== undefined ? ` DEFAULT ${this.escape(p.defaultValue)}` : '';
+                return `${mode}${this.escapeId(p.name)} ${p.type}${defaultPart}`;
+            })
+                .join(', ');
+            sql += ` ${funcName} (${params})`;
+        }
+        else {
+            sql += ` ${funcName} ()`;
+        }
+        sql += ` RETURNS ${options.returnType}`;
+        if (options.volatility) {
+            sql += ` ${options.volatility}`;
+        }
+        const language = options.language || 'SQL';
+        sql += ` LANGUAGE ${language} AS $$\n${options.body}\n$$`;
+        await this.query(sql);
+    }
+    /**
+     * Drop a user-defined function
+     */
+    async dropFunction(functionName, options) {
+        const schema = options?.schema || 'public';
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const paramTypes = options?.paramTypes && options.paramTypes.length > 0
+            ? `(${options.paramTypes.join(', ')})`
+            : '';
+        const sql = `DROP FUNCTION ${ifExists}${this.escapeId(schema)}.${this.escapeId(functionName)}${paramTypes}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * Check if a user-defined function exists
+     */
+    async hasFunction(functionName, schema) {
+        const db = schema || 'public';
+        const sql = `SELECT proname FROM pg_proc p JOIN pg_namespace n ON p.pronamespace = n.oid WHERE n.nspname = '${db}' AND proname = '${functionName}' AND prokind = 'f'`;
+        const result = await this.query(sql, { plain: true });
+        return !!result;
+    }
+    // ==================== Triggers ====================
+    /**
+     * Create a trigger
+     *
+     * CockroachDB's trigger support (added as a preview feature and
+     * subsequently stabilized) is deliberately narrower than Postgres':
+     *  - Only row-level triggers are supported (`FOR EACH ROW`); there is no
+     *    `FOR EACH STATEMENT` execution.
+     *  - `INSTEAD OF` triggers are not supported (CockroachDB views are not
+     *    updatable in the way Postgres views can be).
+     *  - The `REFERENCING` clause (transition tables, e.g.
+     *    `REFERENCING NEW TABLE AS ...`) is not supported.
+     *  - Constraint triggers (`CREATE CONSTRAINT TRIGGER`) are not supported.
+     * Rather than silently emitting Postgres-only DDL that will fail (or
+     * behave unexpectedly) against CockroachDB, these unsupported options
+     * throw a clear error.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/triggers
+     */
+    async createTrigger(options) {
+        const level = options.level || 'ROW';
+        if (level !== 'ROW') {
+            throw new Error('CockroachDB only supports row-level triggers (FOR EACH ROW); ' +
+                'FOR EACH STATEMENT triggers are not supported.');
+        }
+        if (options.timing === 'INSTEAD OF') {
+            throw new Error('CockroachDB does not support INSTEAD OF triggers.');
+        }
+        if (options.referencing) {
+            throw new Error('CockroachDB does not support the REFERENCING clause (transition tables) for triggers.');
+        }
+        if (options.constraint) {
+            throw new Error('CockroachDB does not support constraint triggers.');
+        }
+        const timing = options.timing;
+        const events = (options.events || []).join(' OR ');
+        const tableName = options.schema
+            ? `${this.escapeId(options.schema)}.${this.escapeId(options.tableName)}`
+            : this.quoteTable(options.tableName);
+        let sql = `CREATE TRIGGER ${this.escapeId(options.name)} ${timing} ${events} ON ${tableName} FOR EACH ROW`;
+        sql += `\nEXECUTE FUNCTION ${options.body}`;
+        if (options.replace) {
+            sql = sql.replace('CREATE TRIGGER', 'CREATE OR REPLACE TRIGGER');
+        }
+        await this.query(sql);
+    }
+    /**
+     * Drop a trigger
+     */
+    async dropTrigger(triggerName, tableName, options) {
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const schemaPart = options?.schema ? `${this.escapeId(options.schema)}.` : '';
+        const sql = `DROP TRIGGER ${ifExists}${this.escapeId(triggerName)} ON ${schemaPart}${this.escapeId(tableName)}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * List triggers defined on a table.
+     *
+     * Uses CockroachDB's own `SHOW TRIGGERS FROM <table>` introspection
+     * statement (in the same family as `SHOW INDEXES FROM`/`SHOW CONSTRAINTS
+     * FROM` used elsewhere in this dialect) rather than querying the
+     * `pg_trigger` catalog directly. CockroachDB's `pg_catalog` compatibility
+     * layer is partial, and there is no guarantee `pg_trigger` is populated
+     * for CockroachDB-native triggers the same way it is in real Postgres, so
+     * relying on it risks silently reporting "no trigger" when one exists.
+     */
+    async showTriggers(tableName) {
+        const sql = `SHOW TRIGGERS FROM ${this.escapeId(tableName)}`;
+        const result = await this.query(sql);
+        return result.rows;
+    }
+    /**
+     * Check if a trigger exists
+     */
+    async hasTrigger(triggerName, tableName) {
+        const triggers = await this.showTriggers(tableName);
+        return triggers.some((row) => row.trigger_name === triggerName || row.name === triggerName);
+    }
+    // ==================== Sequences ====================
+    /**
+     * Create a sequence
+     */
+    async createSequence(options) {
+        const schema = options.schema || 'public';
+        const seqName = `${this.escapeId(schema)}.${this.escapeId(options.name)}`;
+        let sql = 'CREATE SEQUENCE';
+        if (options.replace) {
+            sql = 'CREATE OR REPLACE SEQUENCE';
+        }
+        else if (options.ifNotExists) {
+            sql = 'CREATE SEQUENCE IF NOT EXISTS';
+        }
+        if (options.temporary) {
+            sql = sql.replace('CREATE', 'CREATE TEMPORARY SEQUENCE');
+        }
+        sql += ` ${seqName}`;
+        if (options.startWith)
+            sql += ` START WITH ${options.startWith}`;
+        if (options.incrementBy)
+            sql += ` INCREMENT BY ${options.incrementBy}`;
+        if (options.minvalue)
+            sql += ` MINVALUE ${options.minvalue}`;
+        if (options.maxvalue)
+            sql += ` MAXVALUE ${options.maxvalue}`;
+        if (options.cycle)
+            sql += ` CYCLE`;
+        if (options.cache)
+            sql += ` CACHE ${options.cache}`;
+        if (options.ownedBy)
+            sql += ` OWNED BY ${options.ownedBy}`;
+        await this.query(sql);
+    }
+    /**
+     * Drop a sequence
+     */
+    async dropSequence(sequenceName, options) {
+        const schema = options?.schema || 'public';
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const sql = `DROP SEQUENCE ${ifExists}${this.escapeId(schema)}.${this.escapeId(sequenceName)}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * Get next value from a sequence
+     */
+    async nextSequenceValue(sequenceName) {
+        const sql = `SELECT nextval(${this.escape(sequenceName)}) as value`;
+        const result = await this.query(sql, { raw: true });
+        return result.rows?.[0]?.value;
+    }
+    /**
+     * Check if a sequence exists
+     */
+    async hasSequence(sequenceName) {
+        const sql = `SELECT sequence_name FROM information_schema.sequences WHERE sequence_name = '${sequenceName}'`;
+        const result = await this.query(sql, { plain: true });
+        return !!result;
+    }
+    /**
+     * List all sequences in the database (CockroachDB)
+     * @returns Array of sequence names
+     */
+    async listSequences() {
+        const sql = `SELECT sequence_name FROM information_schema.sequences ORDER BY sequence_name`;
+        const result = await this.query(sql);
+        return result.rows.map((row) => row.sequence_name);
+    }
+    // ==================== Row-Level Security (RLS) ====================
+    /**
+     * Create a policy (CockroachDB RLS)
+     */
+    async createPolicy(options) {
+        const schema = options.schema || 'public';
+        const tableName = `${this.escapeId(schema)}.${this.escapeId(options.tableName)}`;
+        const policyName = this.escapeId(options.name);
+        let sql = `CREATE POLICY ${policyName} ON ${tableName}`;
+        if (options.permissive) {
+            sql += ' FOR SELECT USING (true)';
+        }
+        if (options.roles && options.roles.length > 0) {
+            sql += ` TO ${options.roles.join(', ')}`;
+        }
+        if (options.using) {
+            sql += ` USING (${options.using})`;
+        }
+        if (options.withCheck) {
+            sql += ` WITH CHECK (${options.withCheck})`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Drop a policy (CockroachDB RLS)
+     */
+    async dropPolicy(policyName, tableName, options) {
+        const schema = options?.schema || 'public';
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const sql = `DROP POLICY ${ifExists}${this.escapeId(policyName)} ON ${this.escapeId(schema)}.${this.escapeId(tableName)}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * Enable row-level security on a table (CockroachDB)
+     */
+    async enableRLS(tableName, schema) {
+        const schemaName = schema || 'public';
+        const sql = `ALTER TABLE ${this.escapeId(schemaName)}.${this.escapeId(tableName)} ENABLE ROW LEVEL SECURITY`;
+        await this.query(sql);
+    }
+    /**
+     * Enable row-level security on a table (alias for enableRLS)
+     */
+    async enableRowLevelSecurity(tableName, schema) {
+        return this.enableRLS(tableName, schema);
+    }
+    /**
+     * Disable row-level security on a table (CockroachDB)
+     */
+    async disableRLS(tableName, schema) {
+        const schemaName = schema || 'public';
+        const sql = `ALTER TABLE ${this.escapeId(schemaName)}.${this.escapeId(tableName)} DISABLE ROW LEVEL SECURITY`;
+        await this.query(sql);
+    }
+    /**
+     * Check if a policy exists (CockroachDB RLS)
+     */
+    async hasPolicy(policyName, tableName) {
+        const sql = `SELECT policyname FROM pg_policies WHERE policyname = '${policyName}' AND tablename = '${tableName}'`;
+        const result = await this.query(sql, { plain: true });
+        return !!result;
+    }
+    // ==================== Comments ====================
+    /**
+     * Add comment to a table
+     */
+    async commentTable(tableName, comment) {
+        const sql = `COMMENT ON TABLE ${this.quoteTable(tableName)} IS ${this.escape(comment)}`;
+        await this.query(sql);
+    }
+    /**
+     * Add comment to a column
+     */
+    async commentColumn(tableName, columnName, comment) {
+        const sql = `COMMENT ON COLUMN ${this.quoteTable(tableName)}.${this.quoteIdentifier(columnName)} IS ${this.escape(comment)}`;
+        await this.query(sql);
+    }
+    // ==================== Advanced Indexes ====================
+    /**
+     * Create a partial index (index with WHERE clause)
+     */
+    async createPartialIndex(tableName, indexName, fields, where, options) {
+        const fieldsSql = fields.map((f) => this.escapeId(f)).join(', ');
+        let sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)} (${fieldsSql}) WHERE ${where}`;
+        if (options?.unique)
+            sql = sql.replace('CREATE INDEX', 'CREATE UNIQUE INDEX');
+        if (options?.ifNotExists)
+            sql = sql.replace('CREATE INDEX', 'CREATE INDEX IF NOT EXISTS');
+        await this.query(sql);
+    }
+    /**
+     * Create an expression index
+     */
+    async createExpressionIndex(tableName, indexName, expression, options) {
+        let sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)} ((${expression}))`;
+        if (options?.unique)
+            sql = sql.replace('CREATE INDEX', 'CREATE UNIQUE INDEX');
+        if (options?.ifNotExists)
+            sql = sql.replace('CREATE INDEX', 'CREATE INDEX IF NOT EXISTS');
+        await this.query(sql);
+    }
+    /**
+     * Create a fulltext index (CockroachDB)
+     * Uses GIN index for fulltext search
+     * @param tableName - Table name
+     * @param indexName - Index name
+     * @param fields - Fields to index
+     * @param options - Fulltext index options
+     */
+    async createFulltextIndex(tableName, indexName, fields, options) {
+        const usingClause = options?.parser ? ` USING gin(to_tsvector(${options.parser}, ` : ' USING gin(to_tsvector(';
+        const sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)}${usingClause}${fields.map((f) => `${this.escapeId(f)}`).join(' || ')}))`;
+        await this.query(sql);
+    }
+    /**
+     * Create a spatial index (CockroachDB)
+     * Uses GIST index for spatial data
+     * @param tableName - Table name
+     * @param indexName - Index name
+     * @param fields - Fields to index
+     * @param options - Spatial index options
+     */
+    async createSpatialIndex(tableName, indexName, fields, options) {
+        const sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.quoteTable(tableName)} USING gist(${fields.map((f) => this.escapeId(f)).join(', ')})`;
+        await this.query(sql);
+    }
+    /**
+     * Bulk insert records into a table
+     */
+    async bulkInsert(tableName, records, _options) {
+        if (records.length === 0) {
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        const values = [];
+        const placeholders = [];
+        const columns = Object.keys(records[0]);
+        for (const record of records) {
+            const rowPlaceholders = [];
+            for (let i = 0; i < columns.length; i++) {
+                rowPlaceholders.push(`$${values.length + i + 1}`);
+                values.push(record[columns[i]]);
+            }
+            placeholders.push(`(${rowPlaceholders.join(', ')})`);
+        }
+        const sql = `INSERT INTO ${this.quoteTable(tableName)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES ${placeholders.join(', ')}`;
+        return this.query(sql, { replacements: values });
+    }
+    /**
+     * Add a foreign key to a table
+     */
+    async addForeignKey(tableName, columnName, referencedTableName, referencedColumnName, options) {
+        const constraintName = options?.name || `${tableName}_${columnName}_fkey`;
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} FOREIGN KEY (${this.escapeId(columnName)}) REFERENCES ${this.quoteTable(referencedTableName)}(${this.escapeId(referencedColumnName)})`;
+        const clauses = [];
+        if (options?.onDelete) {
+            clauses.push(`ON DELETE ${options.onDelete}`);
+        }
+        if (options?.onUpdate) {
+            clauses.push(`ON UPDATE ${options.onUpdate}`);
+        }
+        if (clauses.length > 0) {
+            sql += ' ' + clauses.join(' ');
+        }
+        await this.query(sql);
+    }
+    /**
+     * Rename a column
+     */
+    async renameColumn(tableName, oldColumnName, newColumnName) {
+        const sql = `ALTER TABLE ${this.quoteTable(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`;
+        await this.query(sql);
+    }
+    // ==================== Identity & Computed Columns ====================
+    /**
+     * Create an identity column
+     */
+    async createIdentityColumn(tableName, columnName, options) {
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} ALTER COLUMN ${this.escapeId(columnName)} ADD GENERATED ALWAYS AS IDENTITY`;
+        if (options?.startWith || options?.incrementBy) {
+            const startWith = options.startWith || 1;
+            const incrementBy = options.incrementBy || 1;
+            sql = `ALTER TABLE ${this.quoteTable(tableName)} ALTER COLUMN ${this.escapeId(columnName)} ADD GENERATED ALWAYS AS IDENTITY (START WITH ${startWith} INCREMENT BY ${incrementBy})`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Create a computed column (generated column)
+     */
+    async createComputedColumn(tableName, columnName, expression, options) {
+        const persisted = options?.persisted ? 'STORED' : 'VIRTUAL';
+        const type = options?.type || 'ANY';
+        const sql = `ALTER TABLE ${this.quoteTable(tableName)} ADD COLUMN ${this.escapeId(columnName)} ${type} GENERATED ALWAYS AS (${expression}) ${persisted}`;
+        await this.query(sql);
+    }
+    assertExtensionShimSupported(extensionName) {
+        const normalized = extensionName.toLowerCase();
+        if (!CockroachDBDialect.SUPPORTED_EXTENSION_SHIMS.has(normalized)) {
+            throw new Error(`Extension '${extensionName}' is not supported by CockroachDB. CockroachDB only has partial ` +
+                'PostgreSQL extension compatibility: CREATE/DROP EXTENSION is accepted as a no-op compatibility ' +
+                `shim for a small allowlist of extension names (${Array.from(CockroachDBDialect.SUPPORTED_EXTENSION_SHIMS).join(', ')}), and no actual third-party extension code can be loaded.`);
+        }
+    }
+    /**
+     * Create a CockroachDB extension (no-op compatibility shim; see
+     * SUPPORTED_EXTENSION_SHIMS above for CockroachDB's partial extension compatibility)
+     * @param extensionName - Name of the extension to create
+     * @param options - Extension options
+     */
+    async createExtension(extensionName, options) {
+        this.assertExtensionShimSupported(extensionName);
+        const ifNotExists = options?.ifNotExists ? 'IF NOT EXISTS ' : '';
+        const schema = options?.schema ? ` SCHEMA ${this.escapeId(options.schema)}` : '';
+        const version = options?.version ? ` VERSION ${options.version}` : '';
+        const sql = `CREATE EXTENSION ${ifNotExists}${this.escapeId(extensionName)}${schema}${version}`;
+        await this.query(sql);
+    }
+    /**
+     * Drop a CockroachDB extension (no-op compatibility shim; see
+     * SUPPORTED_EXTENSION_SHIMS above for CockroachDB's partial extension compatibility)
+     * @param extensionName - Name of the extension to drop
+     * @param options - Drop options
+     */
+    async dropExtension(extensionName, options) {
+        this.assertExtensionShimSupported(extensionName);
+        const ifExists = options?.ifExists ? 'IF EXISTS ' : '';
+        const cascade = options?.cascade ? ' CASCADE' : '';
+        const sql = `DROP EXTENSION ${ifExists}${this.escapeId(extensionName)}${cascade}`;
+        await this.query(sql);
+    }
+    /**
+     * Get all installed CockroachDB extensions
+     * @returns Array of extension information
+     */
+    async getExtensions() {
+        const sql = `
+      SELECT
+        e.extname as name,
+        e.extversion as installed_version,
+        obj_description(e.oid, 'pg_extension') as comment
+      FROM pg_extension e
+      WHERE e.extname NOT IN ('plpgsql')
+      ORDER BY e.extname
+    `;
+        const result = await this.query(sql, { raw: true });
+        return (result.rows?.map((row) => ({
+            name: row.name,
+            defaultVersion: null,
+            installedVersion: row.installed_version,
+            comment: row.comment,
+        })) || []);
+    }
+    /**
+     * Check if a CockroachDB extension is installed. Extensions outside
+     * CockroachDB's small no-op compatibility allowlist (see
+     * SUPPORTED_EXTENSION_SHIMS above) can never be "installed" on CockroachDB,
+     * so this returns false for them without a round-trip to the server.
+     * @param extensionName - Name of the extension
+     * @returns True if the extension is installed
+     */
+    async hasExtension(extensionName) {
+        if (!CockroachDBDialect.SUPPORTED_EXTENSION_SHIMS.has(extensionName.toLowerCase())) {
+            return false;
+        }
+        const sql = `
+      SELECT 1 FROM pg_extension WHERE extname = $1
+    `;
+        const result = await this.query(sql, { replacements: [extensionName] });
+        return (result.rows?.length ?? 0) > 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Foreign Data Wrapper SQL builders
+    //
+    // CockroachDB implements none of the Postgres FDW machinery (no
+    // `CREATE FOREIGN SERVER`/`CREATE USER MAPPING`/`CREATE FOREIGN TABLE`/
+    // `IMPORT FOREIGN SCHEMA`, and no `pg_foreign_server`/
+    // `pg_foreign_data_wrapper` catalogs). These builders are part of the
+    // shared `Dialect` interface (implemented for real by the Postgres
+    // dialect); rather than returning Postgres-only DDL/catalog queries that
+    // would fail against a real CockroachDB cluster, they throw a clear
+    // "not supported" error instead.
+    // ---------------------------------------------------------------------------
+    buildCreateServerQuery(_name, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildAlterServerQuery(_name, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildDropServerQuery(_name, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    /**
+     * Return the SQL to list all foreign servers from the catalog — not
+     * supported in CockroachDB (no `pg_foreign_server`/`pg_foreign_data_wrapper`).
+     */
+    getServersQuery() {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildCreateUserMappingQuery(_opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildAlterUserMappingQuery(_opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildDropUserMappingQuery(_serverName, _user, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    /**
+     * Create a user mapping for a foreign server — not supported in CockroachDB.
+     */
+    async createUserMapping(_userName, _serverName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    /**
+     * Drop a user mapping for a foreign server — not supported in CockroachDB.
+     */
+    async dropUserMapping(_userName, _serverName, _options) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildCreateForeignTableQuery(_tableName, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildDropForeignTableQuery(_tableName, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    buildImportForeignSchemaQuery(_remoteSchema, _serverName, _opts) {
+        throw new Error(CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE);
+    }
+    /**
+     * Add a column to a table
+     */
+    async addColumn(tableName, columnName, definition) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${this.getColumnDefinitionSql(columnName, definition)}`;
+        await this.query(sql);
+    }
+    /**
+     * Remove a column from a table
+     */
+    async removeColumn(tableName, columnName) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} DROP COLUMN ${this.escapeId(columnName)}`;
+        await this.query(sql);
+    }
+    /**
+     * Change a column definition
+     */
+    async changeColumn(tableName, columnName, definition) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} TYPE ${this.getDataTypeSql(definition.type)}`;
+        await this.query(sql);
+        if (definition.allowNull === false) {
+            await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} SET NOT NULL`);
+        }
+        else if (definition.allowNull === true) {
+            await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} DROP NOT NULL`);
+        }
+        if (definition.defaultValue !== undefined) {
+            await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} SET DEFAULT ${this.getDefaultValue(definition.defaultValue)}`);
+        }
+    }
+    /**
+     * Show all tables in the database
+     *
+     * Uses CockroachDB's `SHOW TABLES` statement (rather than querying
+     * information_schema directly, as the Postgres dialect does) so this
+     * dialect exercises CockroachDB-specific introspection syntax. `SHOW
+     * TABLES` returns rows shaped like
+     * `{ schema_name, table_name, type, owner, estimated_row_count, locality }`
+     * for the current database's `public` schema by default.
+     */
+    async showTables() {
+        const sql = 'SHOW TABLES';
+        const result = await this.query(sql);
+        return result.rows
+            .filter((row) => !row.type || row.type === 'table')
+            .map((row) => row.table_name);
+    }
+    /**
+     * Get table status (CockroachDB implementation)
+     */
+    async getTableStatus(tableName) {
+        const sql = tableName
+            ? `SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'public' AND table_name = $1`
+            : `SELECT table_name, table_type FROM information_schema.tables WHERE table_schema = 'public'`;
+        const result = tableName
+            ? await this.query(sql, { bindings: [tableName] })
+            : await this.query(sql);
+        return result.rows;
+    }
+    /**
+     * Get table create statement (CockroachDB implementation)
+     */
+    async getCreateTable(tableName) {
+        const sql = `SELECT pg_get_constraintdef(oid) as definition FROM pg_class WHERE relname = $1`;
+        // For full CREATE TABLE statement, use pg_dump or similar
+        const tableSql = `SELECT pg_get_table_def(oid) as create_sql FROM pg_class WHERE relname = $1`;
+        const result = await this.query(tableSql, { bindings: [tableName] });
+        return result.rows[0]?.create_sql || '';
+    }
+    /**
+     * Check if a table has partitions (CockroachDB implementation)
+     */
+    async hasPartition(tableName) {
+        const sql = `
+      SELECT 1 FROM pg_tables
+      WHERE tablename = $1 AND schemaname = 'public'
+    `;
+        const result = await this.query(sql, { bindings: [tableName] });
+        // Check if it's a partitioned table
+        const partSql = `
+      SELECT 1 FROM pg_partitions
+      WHERE tablename = $1 AND schemaname = 'public'
+    `;
+        const partResult = await this.query(partSql, { bindings: [tableName] });
+        return partResult.rows.length > 0;
+    }
+    /**
+     * Show constraints for a table
+     *
+     * Uses CockroachDB's `SHOW CONSTRAINTS FROM <table>` statement, which
+     * returns rows shaped like
+     * `{ table_name, constraint_name, constraint_type, details, validated }`.
+     */
+    async showConstraints(tableName) {
+        const sql = `SHOW CONSTRAINTS FROM ${this.escapeId(tableName)}`;
+        const result = await this.query(sql);
+        return result.rows;
+    }
+    /**
+     * Show indexes for a table
+     *
+     * Uses CockroachDB's `SHOW INDEXES FROM <table>` statement, which returns
+     * rows shaped like
+     * `{ table_name, index_name, non_unique, seq_in_index, column_name,
+     *    direction, storing, implicit }`.
+     */
+    async showIndexes(tableName) {
+        const sql = `SHOW INDEXES FROM ${this.escapeId(tableName)}`;
+        const result = await this.query(sql);
+        return result.rows;
+    }
+    /**
+     * Describe a table (get column information)
+     *
+     * Uses CockroachDB's `SHOW COLUMNS FROM <table>` statement, which returns
+     * rows shaped like
+     * `{ column_name, data_type, is_nullable, column_default,
+     *    generation_expression, indices, is_hidden }`, plus
+     * `SHOW CONSTRAINTS FROM <table>` to determine which column(s) form the
+     * primary key.
+     */
+    async describeTable(tableName) {
+        const sql = `SHOW COLUMNS FROM ${this.escapeId(tableName)}`;
+        const result = await this.query(sql);
+        const description = {};
+        for (const row of result.rows) {
+            const rowData = row;
+            const columnName = rowData.column_name;
+            if (!columnName)
+                continue;
+            // Check if it's an auto-increment column (SERIAL/BIGSERIAL columns
+            // default to `unique_rowid()` or `nextval(...)` in CockroachDB).
+            const isSerial = typeof rowData.column_default === 'string' &&
+                (rowData.column_default.includes('nextval') ||
+                    rowData.column_default.includes('unique_rowid'));
+            description[columnName] = {
+                type: rowData.data_type,
+                allowNull: rowData.is_nullable === true || rowData.is_nullable === 'true',
+                defaultValue: rowData.column_default,
+                primaryKey: false, // Determined below via SHOW CONSTRAINTS
+                autoIncrement: !!isSerial,
+            };
+        }
+        // Check for primary key via SHOW CONSTRAINTS FROM <table>
+        const constraints = await this.showConstraints(tableName);
+        for (const constraint of constraints) {
+            const c = constraint;
+            if (c.constraint_type !== 'PRIMARY KEY')
+                continue;
+            // `details` is typically formatted like `PRIMARY KEY (id ASC)`; extract
+            // the column name(s) between the parentheses.
+            const match = typeof c.details === 'string' ? c.details.match(/\(([^)]+)\)/) : null;
+            if (match) {
+                for (const part of match[1].split(',')) {
+                    const colName = part.trim().split(/\s+/)[0];
+                    if (description[colName]) {
+                        description[colName].primaryKey = true;
+                    }
+                }
+            }
+        }
+        return description;
+    }
+    /**
+     * Rename a table
+     */
+    async renameTable(oldName, newName) {
+        const sql = `ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)}`;
+        await this.query(sql);
+    }
+    /**
+     * Resolve and validate the requested hash-sharded index bucket count
+     * (`bucketCount`/`shard`) from an options object. Returns `undefined` if
+     * neither is set.
+     */
+    resolveHashBucketCount(options) {
+        const bucketCount = options?.bucketCount ?? options?.shard;
+        if (bucketCount === undefined) {
+            return undefined;
+        }
+        if (!Number.isInteger(bucketCount) || bucketCount < 2) {
+            throw new Error(`Invalid hash-sharded index bucket count: ${bucketCount}. Must be an integer >= 2.`);
+        }
+        return bucketCount;
+    }
+    /**
+     * Add an index to a table
+     *
+     * Note: unlike Postgres, CockroachDB does not support (or need)
+     * `CREATE INDEX CONCURRENTLY` — index backfills are already online and
+     * non-blocking by default. If a caller requests `concurrently`, it is
+     * ignored (with a warning) rather than emitted in the SQL.
+     */
+    async addIndex(tableName, indexName, fields = [], options) {
+        if (options?.concurrently) {
+            console.warn('CockroachDB: CREATE INDEX CONCURRENTLY is not supported (or needed) — ' +
+                'CockroachDB index creation is online by default. The `concurrently` option will be ignored.');
+        }
+        let sql = 'CREATE';
+        if (options?.unique) {
+            sql += ' UNIQUE';
+        }
+        if (options?.type) {
+            sql += ` INDEX ${options.type}`;
+        }
+        else {
+            sql += ' INDEX';
+        }
+        sql += ` ${this.escapeId(indexName)} ON ${this.escapeId(tableName)}`;
+        // Handle expression index
+        if (options?.expression) {
+            sql += ` ((${options.expression}))`;
+        }
+        else {
+            sql += ` (${fields.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        // Hash-sharded index (CockroachDB-specific hotspot-avoidance mechanism
+        // for sequential/monotonic keys): `USING HASH WITH (bucket_count = N)`.
+        // See: https://www.cockroachlabs.com/docs/stable/hash-sharded-indexes
+        const bucketCount = this.resolveHashBucketCount(options);
+        if (bucketCount !== undefined) {
+            sql += ` USING HASH WITH (bucket_count = ${bucketCount})`;
+        }
+        else if (options?.using) {
+            sql += ` USING ${options.using}`;
+        }
+        // Add INCLUDE columns for covering (storing) indexes
+        if (options?.include && options.include.length > 0) {
+            sql += ` INCLUDE (${options.include.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        if (options?.where) {
+            const whereClause = this.buildWhereClause(options.where);
+            sql += ` WHERE ${whereClause.sql}`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Remove an index from a table
+     */
+    async removeIndex(tableName, indexName) {
+        const sql = `DROP INDEX ${this.escapeId(indexName)}`;
+        await this.query(sql);
+    }
+    /**
+     * Create an index on a table with full options support
+     *
+     * Note: CockroachDB does not support `CREATE INDEX CONCURRENTLY` — index
+     * creation is already online/non-blocking, so a `concurrently` flag (if
+     * present on `indexDef`) is ignored with a warning instead of being
+     * emitted in the SQL.
+     */
+    async createIndex(tableName, indexDef) {
+        if (indexDef.concurrently) {
+            console.warn('CockroachDB: CREATE INDEX CONCURRENTLY is not supported (or needed) — ' +
+                'CockroachDB index creation is online by default. The `concurrently` option will be ignored.');
+        }
+        const fields = indexDef.fields || [];
+        let sql = 'CREATE';
+        if (indexDef.unique) {
+            sql += ' UNIQUE';
+        }
+        if (indexDef.type) {
+            sql += ` INDEX ${indexDef.type}`;
+        }
+        else {
+            sql += ' INDEX';
+        }
+        sql += ` ${this.escapeId(indexDef.name)} ON ${this.escapeId(tableName)}`;
+        // Handle expression index
+        if (indexDef.expression) {
+            sql += ` ((${indexDef.expression}))`;
+        }
+        else {
+            sql += ` (${fields.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        // Hash-sharded index (CockroachDB-specific hotspot-avoidance mechanism
+        // for sequential/monotonic keys): `USING HASH WITH (bucket_count = N)`.
+        const bucketCount = this.resolveHashBucketCount(indexDef);
+        if (bucketCount !== undefined) {
+            sql += ` USING HASH WITH (bucket_count = ${bucketCount})`;
+        }
+        else if (indexDef.using) {
+            sql += ` USING ${indexDef.using}`;
+        }
+        // Add INCLUDE columns for covering index (CockroachDB)
+        if (indexDef.include && indexDef.include.length > 0) {
+            sql += ` INCLUDE (${indexDef.include.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        if (indexDef.where && Object.keys(indexDef.where).length > 0) {
+            const whereClause = this.buildWhereClause(indexDef.where);
+            sql += ` WHERE ${whereClause.sql}`;
+        }
+        await this.query(sql);
+    }
+    /**
+     * Create a GIN index for full-text search
+     * CockroachDB-specific GIN (Generalized Inverted Index) for tsvector
+     */
+    async createGINIndex(tableName, indexName, column, options) {
+        const config = options?.config || 'english';
+        const sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.escapeId(tableName)} USING GIN(to_tsvector('${config}', ${this.escapeId(column)}))${options?.storageParameters
+            ? ' WITH (' +
+                Object.entries(options.storageParameters)
+                    .map(([k, v]) => `${k} = ${v}`)
+                    .join(', ') +
+                ')'
+            : ''}`;
+        await this.query(sql);
+    }
+    /**
+     * Build a to_tsvector expression
+     * SQL: to_tsvector([config,] document)
+     */
+    buildTsVector(column, config) {
+        const cfg = config || 'english';
+        const cols = Array.isArray(column) ? column : [column];
+        const columnList = cols.map((c) => this.escapeId(c)).join(" || ' ' || ");
+        return `to_tsvector('${cfg}', ${columnList})`;
+    }
+    /**
+     * Build a to_tsquery expression
+     * SQL: to_tsquery([config,] query)
+     */
+    buildTsQuery(query, config) {
+        const cfg = config || 'english';
+        return `to_tsquery('${cfg}', ${this.escape(query)})`;
+    }
+    /**
+     * Build a plainto_tsquery expression (for phrase searching)
+     * SQL: plainto_tsquery([config,] query)
+     * Converts a phrase into a tsquery that matches documents containing all the words
+     */
+    buildPlainTsQuery(query, config) {
+        const cfg = config || 'english';
+        return `plainto_tsquery('${cfg}', ${this.escape(query)})`;
+    }
+    /**
+     * Build a phraseto_tsquery expression (for exact phrase matching)
+     * SQL: phraseto_tsquery([config,] query)
+     * Converts a phrase into a tsquery that matches documents containing the exact phrase
+     */
+    buildPhraseTsQuery(query, config) {
+        const cfg = config || 'english';
+        return `phraseto_tsquery('${cfg}', ${this.escape(query)})`;
+    }
+    /**
+     * Build a websearch_to_tsquery expression (for web search style queries)
+     * SQL: websearch_to_tsquery([config,] query)
+     * Supports web search operators like +, -, "quotes", etc.
+     */
+    buildWebsearchTsQuery(query, config) {
+        const cfg = config || 'english';
+        return `websearch_to_tsquery('${cfg}', ${this.escape(query)})`;
+    }
+    /**
+     * Build a ts_rank expression for ranking full-text search results
+     * SQL: ts_rank([weights,] vector, query [, normalization])
+     */
+    buildTsRank(vector, query, options) {
+        let sql = 'ts_rank(';
+        if (options?.weights) {
+            sql += `'{${options.weights.join(',')}}', `;
+        }
+        sql += `${vector}, to_tsquery('english', ${this.escape(query)})`;
+        if (options?.normalization !== undefined) {
+            sql += `, ${options.normalization}`;
+        }
+        sql += ')';
+        return sql;
+    }
+    // ============================================
+    // PostGIS spatial functions
+    // ============================================
+    /**
+     * Create a GIST index for spatial data
+     * CockroachDB GIST (Generalized Search Tree) index for geometry/geography columns
+     */
+    async createGISTIndex(tableName, indexName, column, options) {
+        let sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.escapeId(tableName)} USING GIST (${this.escapeId(column)})`;
+        // Add constraints if specified
+        if (options?.geometryType || options?.srid) {
+            const constraints = [];
+            if (options.geometryType) {
+                constraints.push(`geometry_type = '${options.geometryType}'`);
+            }
+            if (options.srid) {
+                constraints.push(`srid = ${options.srid}`);
+            }
+            if (constraints.length > 0) {
+                sql += ` WHERE ${constraints.join(' AND ')}`;
+            }
+        }
+        await this.query(sql);
+    }
+    /**
+     * Create a GIN index for spatial data (PostGIS 2.1+)
+     * GIN indexes are slower to build but faster for very large datasets with many overlapping geometries
+     */
+    async createGINSpatialIndex(tableName, indexName, column) {
+        const sql = `CREATE INDEX ${this.escapeId(indexName)} ON ${this.escapeId(tableName)} USING GIN (${this.escapeId(column)})`;
+        await this.query(sql);
+    }
+    /**
+     * ST_Distance - calculate distance between two geometries
+     * For geography, returns distance in meters
+     */
+    stDistance(geom1, geom2, useGeography) {
+        if (useGeography) {
+            return `ST_Distance(${geom1}::geography, ${geom2}::geography)`;
+        }
+        return `ST_Distance(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_DWithin - check if geometries are within a given distance
+     * For geography, distance is in meters
+     */
+    stDWithin(geom1, geom2, distance, useGeography) {
+        if (useGeography) {
+            return `ST_DWithin(${geom1}::geography, ${geom2}::geography, ${distance})`;
+        }
+        return `ST_DWithin(${geom1}, ${geom2}, ${distance})`;
+    }
+    /**
+     * ST_Within - check if geometry A is within geometry B
+     */
+    stWithin(geom1, geom2) {
+        return `ST_Within(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Contains - check if geometry A contains geometry B
+     */
+    stContains(geom1, geom2) {
+        return `ST_Contains(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Intersects - check if two geometries intersect
+     */
+    stIntersects(geom1, geom2) {
+        return `ST_Intersects(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Crosses - check if two geometries cross
+     */
+    stCrosses(geom1, geom2) {
+        return `ST_Crosses(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Overlaps - check if two geometries overlap
+     */
+    stOverlaps(geom1, geom2) {
+        return `ST_Overlaps(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Touches - check if two geometries touch
+     */
+    stTouches(geom1, geom2) {
+        return `ST_Touches(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Equals - check if two geometries are equal
+     */
+    stEquals(geom1, geom2) {
+        return `ST_Equals(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_IsValid - check if a geometry is valid
+     */
+    stIsValid(geom) {
+        return `ST_IsValid(${geom})`;
+    }
+    /**
+     * ST_GeomFromText - create geometry from WKT text
+     */
+    stGeomFromText(wkt, srid) {
+        if (srid) {
+            return `ST_GeomFromText('${wkt}', ${srid})`;
+        }
+        return `ST_GeomFromText('${wkt}')`;
+    }
+    /**
+     * ST_GeomFromGeoJSON - create geometry from GeoJSON
+     */
+    stGeomFromGeoJSON(geojson, srid) {
+        if (srid) {
+            return `ST_GeomFromGeoJSON('${geojson}'${srid})`;
+        }
+        return `ST_GeomFromGeoJSON('${geojson}')`;
+    }
+    /**
+     * ST_AsGeoJSON - convert geometry to GeoJSON
+     */
+    stAsGeoJSON(geom, options) {
+        let sql = `ST_AsGeoJSON(${geom}`;
+        if (options?.precision !== undefined) {
+            sql += `, ${options.precision}`;
+        }
+        if (options?.longCRS) {
+            sql += ', 0, 1';
+        }
+        sql += ')';
+        return sql;
+    }
+    /**
+     * ST_AsText - convert geometry to WKT
+     */
+    stAsText(geom) {
+        return `ST_AsText(${geom})`;
+    }
+    /**
+     * ST_Centroid - get the centroid of a geometry
+     */
+    stCentroid(geom) {
+        return `ST_Centroid(${geom})`;
+    }
+    /**
+     * ST_Area - calculate the area of a polygon
+     * For geography, returns area in square meters
+     */
+    stArea(geom, useGeography) {
+        if (useGeography) {
+            return `ST_Area(${geom}::geography)`;
+        }
+        return `ST_Area(${geom})`;
+    }
+    /**
+     * ST_Length - calculate the length of a line
+     * For geography, returns length in meters
+     */
+    stLength(geom, useGeography) {
+        if (useGeography) {
+            return `ST_Length(${geom}::geography)`;
+        }
+        return `ST_Length(${geom})`;
+    }
+    /**
+     * ST_Point - create a point from coordinates
+     */
+    stPoint(long, lat) {
+        return `ST_Point(${long}, ${lat})`;
+    }
+    /**
+     * ST_SetSRID - set the SRID of a geometry
+     */
+    stSetSRID(geom, srid) {
+        return `ST_SetSRID(${geom}, ${srid})`;
+    }
+    /**
+     * ST_SRID - get the SRID of a geometry
+     */
+    stSRID(geom) {
+        return `ST_SRID(${geom})`;
+    }
+    /**
+     * ST_X - get the X coordinate of a point
+     */
+    stX(geom) {
+        return `ST_X(${geom})`;
+    }
+    /**
+     * ST_Y - get the Y coordinate of a point
+     */
+    stY(geom) {
+        return `ST_Y(${geom})`;
+    }
+    /**
+     * ST_Distance_Sphere - calculate distance using sphere (less accurate but faster)
+     * Returns distance in meters
+     */
+    stDistanceSphere(geom1, geom2) {
+        return `ST_Distance_Sphere(${geom1}, ${geom2})`;
+    }
+    /**
+     * ST_Distance_Spheroid - calculate distance using spheroid (accurate)
+     * Returns distance in meters
+     */
+    stDistanceSpheroid(geom1, geom2) {
+        return `ST_Distance_Spheroid(${geom1}, ${geom2}, 'SPHEROID["WGS 84",6378137,298.257223563]')`;
+    }
+    /**
+     * Drop an index from a table
+     */
+    async dropIndex(tableName, indexName, options) {
+        let sql = 'DROP INDEX';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(indexName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Create a constraint on a table
+     */
+    async createConstraint(tableName, constraintDef) {
+        const fields = constraintDef.fields?.map((f) => this.escapeId(f)).join(', ');
+        switch (constraintDef.type) {
+            case 'PRIMARY KEY':
+                if (!fields) {
+                    throw new Error('Primary key constraint requires fields');
+                }
+                await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintDef.name)} PRIMARY KEY (${fields})`);
+                return;
+            case 'UNIQUE':
+                if (!fields) {
+                    throw new Error('Unique constraint requires fields');
+                }
+                await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintDef.name)} UNIQUE (${fields})`);
+                return;
+            case 'FOREIGN KEY': {
+                if (!fields || !constraintDef.references) {
+                    throw new Error('Foreign key constraint requires fields and references');
+                }
+                // Handle composite foreign keys (string | string[])
+                const refField = constraintDef.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                    : `(${this.escapeId(refField)})`;
+                let sql = `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintDef.name)} `;
+                sql += `FOREIGN KEY (${fields}) REFERENCES ${this.escapeId(constraintDef.references.table)}${refFieldSql}`;
+                if (constraintDef.references.onDelete) {
+                    sql += ` ON DELETE ${constraintDef.references.onDelete}`;
+                }
+                if (constraintDef.references.onUpdate) {
+                    sql += ` ON UPDATE ${constraintDef.references.onUpdate}`;
+                }
+                if (constraintDef.deferrable) {
+                    sql += ` DEFERRABLE ${constraintDef.deferrable}`;
+                }
+                await this.query(sql);
+                return;
+            }
+            case 'CHECK':
+                if (!constraintDef.check) {
+                    throw new Error('Check constraint requires a check expression');
+                }
+                await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintDef.name)} CHECK (${constraintDef.check})`);
+                return;
+            default:
+                throw new Error(`Unknown constraint type: ${constraintDef.type}`);
+        }
+    }
+    /**
+     * Drop a constraint from a table
+     */
+    async dropConstraint(tableName, constraintName, options) {
+        let sql = 'ALTER TABLE';
+        if (options?.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`;
+        if (options?.cascade) {
+            sql += ' CASCADE';
+        }
+        await this.query(sql);
+    }
+    /**
+     * Begin a new transaction
+     */
+    async startTransaction(options) {
+        if (!this.pool) {
+            throw new Error('Not connected to database');
+        }
+        const client = await this.pool.connect();
+        if (options?.isolationLevel) {
+            const isolationLevelSql = this.getIsolationLevelSql(options.isolationLevel);
+            if (isolationLevelSql) {
+                await client.query(`BEGIN ${isolationLevelSql}`);
+            }
+            else {
+                await client.query('BEGIN');
+            }
+        }
+        else {
+            await client.query('BEGIN');
+        }
+        const transaction = new CockroachDBTransaction(client, this.transactionDepth++, options);
+        return transaction;
+    }
+    /**
+     * Run a function inside a CockroachDB transaction, automatically retrying
+     * the *entire transaction body* when it fails with a serialization failure
+     * (SQLSTATE `40001`, surfaced as a "restart transaction" error).
+     *
+     * Under SERIALIZABLE isolation (CockroachDB's default and only isolation
+     * level), conflicting concurrent transactions routinely abort with
+     * `40001`; CockroachDB's documented client contract is to retry the whole
+     * transaction from the beginning rather than treating it as a fatal error.
+     * This implements that contract using the standard
+     * `SAVEPOINT cockroach_restart` pattern: a savepoint is created right after
+     * `BEGIN`, and on a retryable error the transaction is rolled back to that
+     * savepoint (instead of being aborted outright) so `fn` can be re-run.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/transaction-retry-error-reference
+     * @see https://www.cockroachlabs.com/docs/stable/transactions#client-side-intervention
+     *
+     * @param fn - Callback that receives the transaction and performs the work
+     *   to (re)try. It may be invoked more than once, so it should be
+     *   idempotent / avoid externally-visible side effects other than through
+     *   the database.
+     * @param options - Transaction options, plus an optional `maxRetries`
+     *   (defaults to 5) capping how many times `fn` will be retried after a
+     *   `40001` before the error is rethrown.
+     */
+    async runTransaction(fn, options) {
+        const maxRetries = options?.maxRetries ?? 5;
+        const transaction = (await this.startTransaction(options));
+        const client = transaction.client;
+        if (!client) {
+            throw new Error('Not connected to database');
+        }
+        const restartSavepoint = 'cockroach_restart';
+        try {
+            await transaction.createSavepoint(restartSavepoint);
+            for (let attempt = 0;; attempt++) {
+                try {
+                    const result = await fn(transaction);
+                    await transaction.releaseSavepoint(restartSavepoint);
+                    await client.query('COMMIT');
+                    transaction.finished = true;
+                    return result;
+                }
+                catch (error) {
+                    if (this.isRetryableError(error) && attempt < maxRetries) {
+                        await transaction.rollbackToSavepoint(restartSavepoint);
+                        continue;
+                    }
+                    try {
+                        await client.query('ROLLBACK');
+                    }
+                    catch {
+                        // The connection/transaction may already be unusable; ignore the
+                        // rollback failure and propagate the original error instead.
+                    }
+                    transaction.finished = true;
+                    throw error;
+                }
+            }
+        }
+        finally {
+            transaction.finished = true;
+            client.release();
+        }
+    }
+    /**
+     * Commit a transaction
+     */
+    async commitTransaction(transaction) {
+        const postgresTx = transaction;
+        if (postgresTx.client) {
+            await postgresTx.client.query('COMMIT');
+            postgresTx.client.release();
+            postgresTx.finished = true;
+        }
+    }
+    /**
+     * Rollback a transaction
+     */
+    async rollbackTransaction(transaction) {
+        const postgresTx = transaction;
+        if (postgresTx.client) {
+            await postgresTx.client.query('ROLLBACK');
+            postgresTx.client.release();
+            postgresTx.finished = true;
+        }
+    }
+    /**
+     * Get the SQL for a data type
+     */
+    getDataTypeSql(dataType) {
+        if (typeof dataType === 'string') {
+            return dataType;
+        }
+        if (!dataType || typeof dataType !== 'object') {
+            return 'VARCHAR(255)';
+        }
+        const dt = dataType;
+        switch (dt.key) {
+            case 'STRING':
+                return `VARCHAR(${dt.length || 255})`;
+            case 'CHAR':
+                return `CHAR(${dt.length || 1})`;
+            case 'TEXT':
+                if (dt.length) {
+                    if (dt.length === 256)
+                        return 'TEXT';
+                    if (dt.length === 65535)
+                        return 'TEXT';
+                    return `VARCHAR(${dt.length})`;
+                }
+                return 'TEXT';
+            case 'INTEGER':
+                // Handle SERIAL for auto-increment
+                if (dt.autoIncrement) {
+                    return 'SERIAL';
+                }
+                return 'INTEGER';
+            case 'BIGINT':
+                if (dt.autoIncrement) {
+                    return 'BIGSERIAL';
+                }
+                return 'BIGINT';
+            case 'FLOAT':
+                return 'REAL';
+            case 'DOUBLE':
+                return 'DOUBLE PRECISION';
+            case 'DECIMAL':
+                return `DECIMAL(${dt.precision || 10},${dt.scale || 0})`;
+            case 'BOOLEAN':
+                return 'BOOLEAN';
+            case 'DATE':
+                return dt.precision ? `TIMESTAMP(${dt.precision})` : 'TIMESTAMP';
+            case 'DATEONLY':
+                return 'DATE';
+            case 'TIME':
+                return dt.precision ? `TIME(${dt.precision})` : 'TIME';
+            case 'BLOB':
+                return 'BYTEA';
+            case 'ENUM':
+                const values = dt.values || [];
+                return `ENUM(${values.map((v) => `'${v}'`).join(',')})`;
+            case 'JSON':
+                return 'JSON';
+            case 'JSONB':
+                return 'JSONB';
+            case 'UUID':
+                return 'UUID';
+            case 'HSTORE':
+                return 'HSTORE';
+            case 'RANGE':
+                const rangeSubtype = dt.subtype || 'int4range';
+                return rangeSubtype;
+            case 'INET':
+                return 'INET';
+            case 'CIDR':
+                return 'CIDR';
+            case 'MACADDR':
+                return 'MACADDR';
+            case 'GEOMETRY':
+                const geoType = dt.type || 'GEOMETRY';
+                const srid = dt.srid;
+                if (srid) {
+                    return `${geoType}(${srid})`;
+                }
+                return geoType;
+            case 'GEOGRAPHY':
+                const geoogType = dt.type || 'GEOGRAPHY';
+                const geoSrid = dt.srid || 4326;
+                return `${geoogType}(POINT, ${geoSrid})`;
+            case 'ARRAY':
+                // Support both 'type' (for DataTypes.ARRAY(DataTypes.INTEGER)) and 'subtype' (for { type: 'ARRAY', subtype: 'INTEGER' })
+                const arrayType = dt.type || dt.subtype;
+                if (arrayType) {
+                    const baseType = this.getDataTypeSql(arrayType);
+                    return `${baseType}[]`;
+                }
+                return 'ARRAY';
+            case 'GEOGRAPHY':
+                const geogType = dt.type || 'GEOGRAPHY';
+                const geogSrid = dt.srid || 4326;
+                return `${geogType}(${geogSrid})`;
+            case 'VIRTUAL':
+                // Virtual fields don't create a database column - return empty string
+                return '';
+            default:
+                return 'VARCHAR(255)';
+        }
+    }
+    /**
+     * Get the SQL for an ARRAY type
+     */
+    getArrayTypeSql(elementType) {
+        return `${this.getDataTypeSql(elementType)}[]`;
+    }
+    /**
+     * Get the isolation level SQL
+     */
+    getIsolationLevelSql(isolationLevel) {
+        if (!isolationLevel) {
+            return '';
+        }
+        const levels = {
+            'READ UNCOMMITTED': 'READ UNCOMMITTED',
+            'READ COMMITTED': 'READ COMMITTED',
+            'REPEATABLE READ': 'REPEATABLE READ',
+            SERIALIZABLE: 'SERIALIZABLE',
+        };
+        const level = levels[isolationLevel];
+        return level ? `ISOLATION LEVEL ${level}` : '';
+    }
+    /**
+     * Build a WHERE clause from a WhereOptions object
+     */
+    buildWhereClause(where, options) {
+        const values = [];
+        if (!where || Object.keys(where).length === 0) {
+            return { sql: '', values };
+        }
+        const buildCondition = (condition) => {
+            if (!condition) {
+                return { sql: '', values: [] };
+            }
+            if (typeof condition !== 'object') {
+                values.push(condition);
+                return { sql: '$' + values.length, values: [condition] };
+            }
+            const cond = condition;
+            // Handle logical operators
+            if (cond.$and || cond.$or || cond.$not) {
+                const conditions = [];
+                if (cond.$and) {
+                    const andConditions = cond.$and.map((c) => {
+                        const result = buildCondition(c);
+                        return result.sql;
+                    });
+                    conditions.push(`(${andConditions.join(' AND ')})`);
+                }
+                if (cond.$or) {
+                    const orConditions = cond.$or.map((c) => {
+                        const result = buildCondition(c);
+                        return result.sql;
+                    });
+                    conditions.push(`(${orConditions.join(' OR ')})`);
+                }
+                if (cond.$not) {
+                    const result = buildCondition(cond.$not);
+                    conditions.push(`NOT (${result.sql})`);
+                }
+                return { sql: conditions.join(' AND '), values };
+            }
+            // Handle field conditions
+            const fieldConditions = [];
+            for (const [key, value] of Object.entries(cond)) {
+                if (key.startsWith('$'))
+                    continue;
+                if (value && typeof value === 'object') {
+                    const valueObj = value;
+                    if (valueObj.$eq !== undefined) {
+                        values.push(valueObj.$eq);
+                        fieldConditions.push(`${this.escapeId(key)} = $${values.length}`);
+                    }
+                    else if (valueObj.$ne !== undefined) {
+                        values.push(valueObj.$ne);
+                        fieldConditions.push(`${this.escapeId(key)} != $${values.length}`);
+                    }
+                    else if (valueObj.$gt !== undefined) {
+                        values.push(valueObj.$gt);
+                        fieldConditions.push(`${this.escapeId(key)} > $${values.length}`);
+                    }
+                    else if (valueObj.$gte !== undefined) {
+                        values.push(valueObj.$gte);
+                        fieldConditions.push(`${this.escapeId(key)} >= $${values.length}`);
+                    }
+                    else if (valueObj.$lt !== undefined) {
+                        values.push(valueObj.$lt);
+                        fieldConditions.push(`${this.escapeId(key)} < $${values.length}`);
+                    }
+                    else if (valueObj.$lte !== undefined) {
+                        values.push(valueObj.$lte);
+                        fieldConditions.push(`${this.escapeId(key)} <= $${values.length}`);
+                    }
+                    else if (valueObj.$like !== undefined) {
+                        values.push(valueObj.$like);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE $${values.length}`);
+                    }
+                    else if (valueObj.$notLike !== undefined) {
+                        values.push(valueObj.$notLike);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE $${values.length}`);
+                    }
+                    else if (valueObj.$iLike !== undefined) {
+                        values.push(valueObj.$iLike);
+                        fieldConditions.push(`${this.escapeId(key)} ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$notILike !== undefined) {
+                        values.push(valueObj.$notILike);
+                        fieldConditions.push(`${this.escapeId(key)} NOT ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$startsWith !== undefined) {
+                        values.push(valueObj.$startsWith + '%');
+                        fieldConditions.push(`${this.escapeId(key)} ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$notStartsWith !== undefined) {
+                        values.push(valueObj.$notStartsWith + '%');
+                        fieldConditions.push(`${this.escapeId(key)} NOT ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$endsWith !== undefined) {
+                        values.push('%' + valueObj.$endsWith);
+                        fieldConditions.push(`${this.escapeId(key)} ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$notEndsWith !== undefined) {
+                        values.push('%' + valueObj.$notEndsWith);
+                        fieldConditions.push(`${this.escapeId(key)} NOT ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$substring !== undefined) {
+                        values.push('%' + valueObj.$substring + '%');
+                        fieldConditions.push(`${this.escapeId(key)} ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$notSubstring !== undefined) {
+                        values.push('%' + valueObj.$notSubstring + '%');
+                        fieldConditions.push(`${this.escapeId(key)} NOT ILIKE $${values.length}`);
+                    }
+                    else if (valueObj.$any !== undefined) {
+                        const anyValues = Array.isArray(valueObj.$any) ? valueObj.$any : [valueObj.$any];
+                        values.push(anyValues);
+                        fieldConditions.push(`${this.escapeId(key)} = ANY($${values.length})`);
+                    }
+                    else if (valueObj.$all !== undefined) {
+                        const allValues = Array.isArray(valueObj.$all) ? valueObj.$all : [valueObj.$all];
+                        values.push(allValues);
+                        fieldConditions.push(`${this.escapeId(key)} = ALL($${values.length})`);
+                    }
+                    else if (valueObj.$in) {
+                        const inValues = valueObj.$in;
+                        values.push(...inValues);
+                        const placeholders = inValues
+                            .map((_, i) => `$${values.length - inValues.length + i + 1}`)
+                            .join(',');
+                        fieldConditions.push(`${this.escapeId(key)} IN (${placeholders})`);
+                    }
+                    else if (valueObj.$notIn) {
+                        const notInValues = valueObj.$notIn;
+                        values.push(...notInValues);
+                        const placeholders = notInValues
+                            .map((_, i) => `$${values.length - notInValues.length + i + 1}`)
+                            .join(',');
+                        fieldConditions.push(`${this.escapeId(key)} NOT IN (${placeholders})`);
+                    }
+                    else if (valueObj.$between) {
+                        const between = valueObj.$between;
+                        values.push(between[0], between[1]);
+                        fieldConditions.push(`${this.escapeId(key)} BETWEEN $${values.length - 1} AND $${values.length}`);
+                    }
+                    else if (valueObj.$notBetween) {
+                        const notBetween = valueObj.$notBetween;
+                        values.push(notBetween[0], notBetween[1]);
+                        fieldConditions.push(`${this.escapeId(key)} NOT BETWEEN $${values.length - 1} AND $${values.length}`);
+                    }
+                    else if (valueObj.$isNull !== undefined) {
+                        if (valueObj.$isNull) {
+                            fieldConditions.push(`${this.escapeId(key)} IS NULL`);
+                        }
+                        else {
+                            fieldConditions.push(`${this.escapeId(key)} IS NOT NULL`);
+                        }
+                    }
+                    else if (valueObj.$exists !== undefined) {
+                        if (valueObj.$exists) {
+                            fieldConditions.push(`EXISTS (${valueObj.$query})`);
+                        }
+                        else {
+                            fieldConditions.push(`NOT EXISTS (${valueObj.$query})`);
+                        }
+                    }
+                    else if (valueObj.$jsonConcat !== undefined) {
+                        // JSONB concatenation (||)
+                        values.push(JSON.stringify(valueObj.$jsonConcat));
+                        fieldConditions.push(`${this.escapeId(key)} || $${values.length}`);
+                    }
+                    else if (valueObj.$jsonDelete !== undefined) {
+                        // JSONB delete key (-)
+                        fieldConditions.push(`${this.escapeId(key)} - '${valueObj.$jsonDelete}'`);
+                    }
+                    else if (valueObj.$jsonDeletePath !== undefined) {
+                        // JSONB delete by path (#-)
+                        const deletePath = valueObj.$jsonDeletePath;
+                        const pgPath = Array.isArray(deletePath)
+                            ? `{${deletePath.join(', ')}}`
+                            : `{${deletePath}}`;
+                        fieldConditions.push(`${this.escapeId(key)} #- '${pgPath}'`);
+                    }
+                    else if (valueObj.$jsonPathExists !== undefined) {
+                        // JSON path exists (@?)
+                        fieldConditions.push(`${this.escapeId(key)} @? '${valueObj.$jsonPathExists}'`);
+                    }
+                    else if (valueObj.$jsonPathQuery !== undefined) {
+                        // JSON path query (@@)
+                        fieldConditions.push(`${this.escapeId(key)} @@ '${valueObj.$jsonPathQuery}'`);
+                    }
+                    else if (valueObj.$jsonTypeOf !== undefined) {
+                        // JSON type of (json_typeof)
+                        values.push(valueObj.$jsonTypeOf);
+                        fieldConditions.push(`json_typeof(${this.escapeId(key)}) = $${values.length}`);
+                    }
+                    else {
+                        values.push(value);
+                        fieldConditions.push(`${this.escapeId(key)} = $${values.length}`);
+                    }
+                }
+                else {
+                    values.push(value);
+                    fieldConditions.push(`${this.escapeId(key)} = $${values.length}`);
+                }
+            }
+            return { sql: fieldConditions.join(' AND '), values };
+        };
+        const result = buildCondition(where);
+        return { sql: result.sql, values: result.values };
+    }
+    /**
+     * Build an ORDER BY clause
+     */
+    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(item);
+            }
+            else if (item && typeof item === 'object') {
+                const itemArr = item;
+                const [modelOrString, field] = itemArr;
+                const model = typeof modelOrString === 'string'
+                    ? modelOrString
+                    : modelOrString.tableName || '';
+                const fieldStr = typeof field === 'string' ? field : '';
+                orderParts.push(`${model ? `${this.escapeId(model)}.` : ''}${this.escapeId(fieldStr)}`);
+            }
+        }
+        return orderParts.length > 0 ? `ORDER BY ${orderParts.join(', ')}` : '';
+    }
+    /**
+     * Build a LIMIT/OFFSET clause
+     */
+    buildLimitOffset(limit, offset) {
+        let sql = '';
+        if (limit !== undefined) {
+            sql += ` LIMIT ${Number(limit)}`;
+            if (offset !== undefined) {
+                sql += ` OFFSET ${Number(offset)}`;
+            }
+        }
+        return sql;
+    }
+    /**
+     * Build an INSERT query with RETURNING support
+     */
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        let paramIndex = 1;
+        // Process each value - handle Literal differently
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                // For Literal values, inline the SQL directly
+                placeholders.push(value.val);
+            }
+            else {
+                // For regular values, use parameterized placeholder
+                placeholders.push(`$${paramIndex}`);
+                processedValues.push(value);
+                paramIndex++;
+            }
+        }
+        // CockroachDB's native `UPSERT INTO` shorthand replaces the row matching
+        // the primary key wholesale and needs no conflict target, unlike
+        // `INSERT ... ON CONFLICT ... DO UPDATE`.
+        // See: https://www.cockroachlabs.com/docs/stable/upsert
+        const useNativeUpsert = !!(options?.upsert && options.nativeUpsert);
+        let sql = `${useNativeUpsert ? 'UPSERT' : 'INSERT'} INTO ${this.escapeId(tableName)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${placeholders.join(', ')})`;
+        // Handle upsert (ON CONFLICT), unless the native UPSERT shorthand above
+        // already provides replace-on-conflict semantics.
+        if (options?.upsert && !useNativeUpsert) {
+            const updateColumns = columns
+                .map((c) => `${this.escapeId(c)} = excluded.${this.escapeId(c)}`)
+                .join(', ');
+            const conflictFields = options.conflictFields || columns;
+            sql += ` ON CONFLICT (${conflictFields.map((c) => this.escapeId(c)).join(', ')}) DO UPDATE SET ${updateColumns}`;
+        }
+        // Handle RETURNING clause
+        if (options?.returning) {
+            if (options.returning === true) {
+                sql += ' RETURNING *';
+            }
+            else if (Array.isArray(options.returning)) {
+                sql += ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+            }
+        }
+        return { sql, values: processedValues };
+    }
+    /**
+     * Build an UPSERT query for CockroachDB
+     * Uses `ON CONFLICT ... DO UPDATE SET` syntax by default, or CockroachDB's
+     * native `UPSERT INTO ... VALUES (...)` shorthand when `options.nativeUpsert`
+     * is set (which replaces the row matching the primary key wholesale and
+     * needs no conflict target).
+     * @see https://www.cockroachlabs.com/docs/stable/upsert
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const placeholders = columns.map((_, i) => `$${i + 1}`).join(', ');
+        const queryValues = Object.values(values);
+        const useNativeUpsert = !!options?.nativeUpsert;
+        let sql = `${useNativeUpsert ? 'UPSERT' : 'INSERT'} INTO ${this.escapeId(tableName)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${placeholders})`;
+        if (!useNativeUpsert) {
+            // Determine which fields to update
+            const updateFields = options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
+                ? options.updateOnDuplicate
+                : columns;
+            // Add ON CONFLICT clause
+            const conflictFields = options?.conflictFields || columns;
+            const updateClauses = updateFields
+                .map((c) => `${this.escapeId(c)} = excluded.${this.escapeId(c)}`)
+                .join(', ');
+            sql += ` ON CONFLICT (${conflictFields.map((c) => this.escapeId(c)).join(', ')}) DO UPDATE SET ${updateClauses}`;
+        }
+        // Handle RETURNING clause
+        if (options?.returning) {
+            if (options.returning === true) {
+                sql += ' RETURNING *';
+            }
+            else if (Array.isArray(options.returning)) {
+                sql += ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+            }
+        }
+        return { sql, values: queryValues };
+    }
+    /**
+     * Build an increment query
+     * @param tableName - Table name
+     * @param fields - Fields to increment
+     * @param where - Where clause
+     * @param options - Query options (by: number)
+     */
+    buildIncrementQuery(tableName, fields, where, options) {
+        const by = options?.by ?? 1;
+        const setClauses = [];
+        const queryValues = [];
+        let paramIndex = 1;
+        // Handle different field formats
+        if (typeof fields === 'string') {
+            // Single field: increment('count')
+            setClauses.push(`${this.escapeId(fields)} = ${this.escapeId(fields)} + $${paramIndex}`);
+            queryValues.push(by);
+            paramIndex++;
+        }
+        else if (Array.isArray(fields)) {
+            // Array of fields: increment(['count', 'value'], { by: 5 })
+            for (const field of fields) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + $${paramIndex}`);
+                queryValues.push(by);
+                paramIndex++;
+            }
+        }
+        else {
+            // Object: increment({ count: 1, value: 10 })
+            for (const [field, value] of Object.entries(fields)) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + $${paramIndex}`);
+                queryValues.push(value);
+                paramIndex++;
+            }
+        }
+        // Build WHERE clause
+        const whereClause = this.buildWhereClause(where);
+        // Adjust parameter indices for where clause
+        const adjustedWhereClause = {
+            sql: whereClause.sql.replace(/\$(\d+)/g, (_, num) => `$${paramIndex + parseInt(num, 10) - 1}`),
+            values: whereClause.values,
+        };
+        queryValues.push(...adjustedWhereClause.values);
+        const sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')} WHERE ${adjustedWhereClause.sql}`;
+        return { sql, values: queryValues };
+    }
+    /**
+     * Build an UPDATE query with RETURNING support
+     */
+    buildUpdateQuery(tableName, values, where, options) {
+        const setClauses = [];
+        const queryValues = [];
+        let paramIndex = 1;
+        for (const [key, value] of Object.entries(values)) {
+            if (value instanceof prorm_1.Literal) {
+                // For Literal values, inline the SQL directly
+                setClauses.push(`${this.escapeId(key)} = ${value.val}`);
+            }
+            else {
+                // For regular values, use parameterized placeholder
+                setClauses.push(`${this.escapeId(key)} = $${paramIndex}`);
+                queryValues.push(value);
+                paramIndex++;
+            }
+        }
+        const whereClause = this.buildWhereClause(where);
+        // Adjust parameter indices for where clause
+        const adjustedWhereClause = {
+            sql: whereClause.sql,
+            values: [...queryValues, ...whereClause.values],
+        };
+        let sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')}`;
+        if (adjustedWhereClause.sql) {
+            sql += ` WHERE ${adjustedWhereClause.sql}`;
+        }
+        if (options?.limit) {
+            sql += ` LIMIT ${options.limit}`;
+        }
+        // Handle RETURNING clause
+        if (options?.returning) {
+            if (options.returning === true) {
+                sql += ' RETURNING *';
+            }
+            else if (Array.isArray(options.returning)) {
+                sql += ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+            }
+        }
+        return { sql, values: adjustedWhereClause.values };
+    }
+    /**
+     * Build a DELETE query with RETURNING support
+     */
+    buildDeleteQuery(tableName, where, options) {
+        const whereClause = this.buildWhereClause(where);
+        let sql = `DELETE FROM ${this.escapeId(tableName)}`;
+        if (whereClause.sql) {
+            sql += ` WHERE ${whereClause.sql}`;
+        }
+        if (options?.limit) {
+            sql += ` LIMIT ${options.limit}`;
+        }
+        // Handle RETURNING clause
+        if (options?.returning) {
+            if (options.returning === true) {
+                sql += ' RETURNING *';
+            }
+            else if (Array.isArray(options.returning)) {
+                sql += ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+            }
+        }
+        // Handle TRUNCATE
+        if (options?.truncate) {
+            const pgOptions = options;
+            sql = `TRUNCATE ${this.escapeId(tableName)}`;
+            if (pgOptions.restartIdentity) {
+                sql += ' RESTART IDENTITY';
+            }
+            if (pgOptions.cascade) {
+                sql += ' CASCADE';
+            }
+        }
+        return { sql, values: whereClause.values };
+    }
+    /**
+     * Check if a value is a function expression (fn('COUNT', ...))
+     */
+    isFnExpression(value) {
+        return value !== null && typeof value === 'object' && value.__type === 'fn';
+    }
+    /**
+     * Check if a value is a column expression (col('name'))
+     */
+    isColExpression(value) {
+        return value !== null && typeof value === 'object' && value.__type === 'col';
+    }
+    /**
+     * Check if a value is a literal expression (literal('sql'))
+     */
+    isLiteralExpression(value) {
+        return value !== null && typeof value === 'object' && value.__type === 'literal';
+    }
+    /**
+     * Compile a function expression to SQL
+     */
+    compileFnExpression(fnExpr) {
+        const args = fnExpr.args.map((arg) => {
+            if (this.isColExpression(arg)) {
+                return this.escapeId(arg.col);
+            }
+            else if (typeof arg === 'string') {
+                return this.escape(arg);
+            }
+            else if (this.isFnExpression(arg)) {
+                return this.compileFnExpression(arg);
+            }
+            else {
+                return String(arg);
+            }
+        });
+        return `${fnExpr.fn}(${args.join(', ')})`;
+    }
+    /**
+     * Build SELECT clause with support for function expressions and aliases
+     * Handles: 'field', ['field'], ['field', 'alias'], [fn('COUNT', 'id'), 'count']
+     */
+    buildSelectClause(attributes) {
+        if (!attributes)
+            return '*';
+        if (Array.isArray(attributes)) {
+            const parts = attributes.map((attr) => {
+                // Handle array format: [expression, alias] or [fn, alias]
+                if (Array.isArray(attr)) {
+                    const [expr, alias] = attr;
+                    let sql;
+                    if (this.isFnExpression(expr)) {
+                        sql = this.compileFnExpression(expr);
+                    }
+                    else if (this.isColExpression(expr)) {
+                        sql = this.escapeId(expr.col);
+                    }
+                    else if (this.isLiteralExpression(expr)) {
+                        sql = expr.sql;
+                    }
+                    else if (typeof expr === 'string') {
+                        // Check if it's a column reference or literal SQL
+                        if (expr.includes('(') || expr.includes(' ')) {
+                            sql = expr; // Literal SQL
+                        }
+                        else {
+                            sql = this.escapeId(expr);
+                        }
+                    }
+                    else {
+                        sql = String(expr);
+                    }
+                    return `${sql} AS ${this.escapeId(alias)}`;
+                }
+                else if (this.isFnExpression(attr)) {
+                    // Function without alias - let DB assign a name
+                    return this.compileFnExpression(attr);
+                }
+                else if (this.isColExpression(attr)) {
+                    return this.escapeId(attr.col);
+                }
+                else if (this.isLiteralExpression(attr)) {
+                    return attr.sql;
+                }
+                else if (typeof attr === 'string') {
+                    // Plain column name
+                    return this.escapeId(attr);
+                }
+                return String(attr);
+            });
+            return parts.join(', ');
+        }
+        else if (attributes.include) {
+            return attributes.include.map((a) => this.escapeId(a)).join(', ');
+        }
+        else if (attributes.exclude) {
+            // CockroachDB supports EXCEPT
+            return `* EXCEPT (${attributes.exclude.map((a) => this.escapeId(a)).join(', ')})`;
+        }
+        return '*';
+    }
+    /**
+     * Build GROUP BY clause with support for function expressions and aliases
+     * Handles: 'field', ['field1', 'field2'], [[fn('COUNT', 'id'), 'count']]
+     */
+    buildGroupByClause(group) {
+        if (!group)
+            return '';
+        const groupArray = Array.isArray(group) ? group : [group];
+        if (groupArray.length === 0)
+            return '';
+        const parts = groupArray.map((field) => {
+            if (Array.isArray(field)) {
+                // Array format: [expression, alias] or [fn, alias]
+                const [expr, alias] = field;
+                let sql;
+                if (this.isFnExpression(expr)) {
+                    sql = this.compileFnExpression(expr);
+                }
+                else if (this.isColExpression(expr)) {
+                    sql = this.escapeId(expr.col);
+                }
+                else if (this.isLiteralExpression(expr)) {
+                    sql = expr.sql;
+                }
+                else if (typeof expr === 'string') {
+                    sql = this.escapeId(expr);
+                }
+                else {
+                    sql = String(expr);
+                }
+                // Alias is optional in GROUP BY
+                if (alias) {
+                    return `${sql} AS ${this.escapeId(alias)}`;
+                }
+                return sql;
+            }
+            else if (this.isFnExpression(field)) {
+                return this.compileFnExpression(field);
+            }
+            else if (this.isColExpression(field)) {
+                return this.escapeId(field.col);
+            }
+            else if (this.isLiteralExpression(field)) {
+                return field.sql;
+            }
+            else if (typeof field === 'string') {
+                if (field.includes('.')) {
+                    return field
+                        .split('.')
+                        .map((part) => this.escapeId(part))
+                        .join('.');
+                }
+                return this.escapeId(field);
+            }
+            return String(field);
+        });
+        return `GROUP BY ${parts.join(', ')}`;
+    }
+    /**
+     * Build a WHERE clause condition using standard operators (Op.gt, Op.eq, etc.)
+     * CockroachDB uses $1, $2, etc. for parameter placeholders
+     */
+    buildCondition(condition, values, paramPrefix = '$') {
+        if (!condition || (typeof condition === 'object' && Object.keys(condition).length === 0)) {
+            return '';
+        }
+        // Handle logical operators
+        if ('$and' in condition) {
+            const andParts = condition.$and.map((c) => this.buildCondition(c, values, paramPrefix));
+            return `(${andParts.join(' AND ')})`;
+        }
+        if ('$or' in condition) {
+            const orParts = condition.$or.map((c) => this.buildCondition(c, values, paramPrefix));
+            return `(${orParts.join(' OR ')})`;
+        }
+        if ('$not' in condition) {
+            return `NOT (${this.buildCondition(condition.$not, values, paramPrefix)})`;
+        }
+        // Handle regular conditions
+        const conditions = [];
+        for (const [key, value] of Object.entries(condition)) {
+            if (key.startsWith('$'))
+                continue; // Skip logical operators
+            let sql = '';
+            const paramIndex = values.length + 1;
+            // Check if value is an operator object
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                const opKeys = Object.keys(value);
+                if (opKeys.length === 1) {
+                    const opKey = opKeys[0];
+                    const opValue = value[opKey];
+                    // Map Op symbol to string
+                    if (opKey === 'Symbol(eq)' || opKey === 'Symbol(operators.eq)') {
+                        sql = `${this.escapeId(key)} = ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(ne)' || opKey === 'Symbol(operators.ne)') {
+                        sql = `${this.escapeId(key)} != ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(gt)' || opKey === 'Symbol(operators.gt)') {
+                        sql = `${this.escapeId(key)} > ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(gte)' || opKey === 'Symbol(operators.gte)') {
+                        sql = `${this.escapeId(key)} >= ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(lt)' || opKey === 'Symbol(operators.lt)') {
+                        sql = `${this.escapeId(key)} < ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(lte)' || opKey === 'Symbol(operators.lte)') {
+                        sql = `${this.escapeId(key)} <= ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(in)' || opKey === 'Symbol(operators.in)') {
+                        const placeholders = opValue
+                            .map((_, i) => `${paramPrefix}${paramIndex + i}`)
+                            .join(', ');
+                        sql = `${this.escapeId(key)} IN (${placeholders})`;
+                        values.push(...opValue);
+                    }
+                    else if (opKey === 'Symbol(notIn)' || opKey === 'Symbol(operators.notIn)') {
+                        const placeholders = opValue
+                            .map((_, i) => `${paramPrefix}${paramIndex + i}`)
+                            .join(', ');
+                        sql = `${this.escapeId(key)} NOT IN (${placeholders})`;
+                        values.push(...opValue);
+                    }
+                    else if (opKey === 'Symbol(between)' || opKey === 'Symbol(operators.between)') {
+                        sql = `${this.escapeId(key)} BETWEEN ${paramPrefix}${paramIndex} AND ${paramPrefix}${paramIndex + 1}`;
+                        values.push(...opValue);
+                    }
+                    else if (opKey === 'Symbol(notBetween)' || opKey === 'Symbol(operators.notBetween)') {
+                        sql = `${this.escapeId(key)} NOT BETWEEN ${paramPrefix}${paramIndex} AND ${paramPrefix}${paramIndex + 1}`;
+                        values.push(...opValue);
+                    }
+                    else if (opKey === 'Symbol(isNull)' || opKey === 'Symbol(operators.isNull)') {
+                        sql = `${this.escapeId(key)} IS NULL`;
+                    }
+                    else if (opKey === 'Symbol(isNotNull)' || opKey === 'Symbol(operators.isNotNull)') {
+                        sql = `${this.escapeId(key)} IS NOT NULL`;
+                    }
+                    else if (opKey === 'Symbol(like)' || opKey === 'Symbol(operators.like)') {
+                        sql = `${this.escapeId(key)} LIKE ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(notLike)' || opKey === 'Symbol(operators.notLike)') {
+                        sql = `${this.escapeId(key)} NOT LIKE ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(iLike)' || opKey === 'Symbol(operators.iLike)') {
+                        sql = `${this.escapeId(key)} ILIKE ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                    else if (opKey === 'Symbol(notILike)' || opKey === 'Symbol(operators.notILike)') {
+                        sql = `${this.escapeId(key)} NOT ILIKE ${paramPrefix}${paramIndex}`;
+                        values.push(opValue);
+                    }
+                }
+                if (!sql) {
+                    // Fallback: treat as equals
+                    sql = `${this.escapeId(key)} = ${paramPrefix}${paramIndex}`;
+                    values.push(value);
+                }
+            }
+            else if (Array.isArray(value)) {
+                // Handle IN arrays
+                const placeholders = value.map((_, i) => `${paramPrefix}${paramIndex + i}`).join(', ');
+                sql = `${this.escapeId(key)} IN (${placeholders})`;
+                values.push(...value);
+            }
+            else {
+                // Simple equality
+                sql = `${this.escapeId(key)} = ${paramPrefix}${paramIndex}`;
+                values.push(value);
+            }
+            if (sql) {
+                conditions.push(sql);
+            }
+        }
+        return conditions.join(' AND ');
+    }
+    /**
+     * Build a HAVING clause with support for standard Op operators
+     */
+    buildHavingClause(having) {
+        const values = [];
+        if (!having || (typeof having === 'object' && Object.keys(having).length === 0)) {
+            return { sql: '', values };
+        }
+        // Use the condition builder with Op operator support
+        const sql = this.buildCondition(having, values);
+        return { sql, values };
+    }
+    /**
+     * Build the expression used after `AS OF SYSTEM TIME` for CockroachDB
+     * time-travel reads.
+     *
+     * Accepts:
+     *  - A relative interval shorthand, e.g. `'-10s'`, `'-500ms'`, `'-1h'`.
+     *  - An absolute ISO-8601 timestamp, e.g. `'2024-01-01T00:00:00Z'`.
+     *  - The literal function call `follower_read_timestamp()` (unquoted).
+     *
+     * The value is validated against a strict allow-list pattern before being
+     * embedded in the SQL string (rather than passed as a bound parameter,
+     * which CockroachDB's `AS OF SYSTEM TIME` clause does not accept) to avoid
+     * SQL injection.
+     *
+     * @see https://www.cockroachlabs.com/docs/stable/as-of-system-time
+     */
+    buildAsOfSystemTimeClause(value) {
+        const trimmed = value.trim();
+        // `follower_read_timestamp()` (and the bounded-staleness variant
+        // `with_min_timestamp`/`with_max_staleness`) are function calls and must
+        // not be quoted.
+        if (/^follower_read_timestamp\(\s*\)$/i.test(trimmed)) {
+            return trimmed;
+        }
+        // Relative interval shorthand: optional leading `-`, digits, optional
+        // decimal portion, optional unit (ms|s|m|h|d).
+        const isRelativeInterval = /^-?\d+(\.\d+)?\s*(ms|s|m|h|d)?$/i.test(trimmed);
+        // Absolute timestamp (ISO-8601-ish: date, optional time, optional
+        // fractional seconds, optional timezone offset/Z).
+        const isAbsoluteTimestamp = /^\d{4}-\d{2}-\d{2}([ T]\d{2}:\d{2}:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/.test(trimmed);
+        if (!isRelativeInterval && !isAbsoluteTimestamp) {
+            throw new Error(`Invalid AS OF SYSTEM TIME value: "${value}". Expected a relative interval ` +
+                `(e.g. "-10s"), an ISO-8601 timestamp, or "follower_read_timestamp()".`);
+        }
+        return `'${trimmed.replace(/'/g, "''")}'`;
+    }
+    /**
+     * Run a SELECT query as of a historical timestamp using CockroachDB's
+     * `AS OF SYSTEM TIME` time-travel read feature.
+     *
+     * @param options - Standard SelectOptions plus the historical timestamp.
+     * @param asOfSystemTime - Relative interval (e.g. `'-10s'`), ISO timestamp,
+     *   or `'follower_read_timestamp()'`.
+     */
+    async queryAsOfSystemTime(options, asOfSystemTime) {
+        const { sql, values } = this.buildSelectQuery({
+            ...options,
+            asOfSystemTime,
+        });
+        return this.query(sql, { replacements: values });
+    }
+    /**
+     * Build a SELECT query with CockroachDB-specific features
+     */
+    buildSelectQuery(options) {
+        const queryValues = [];
+        // Build SELECT clause
+        let selectSql = '*';
+        // Handle DISTINCT ON and DISTINCT with column
+        const distinctOn = options.distinctOn;
+        let distinctClause = '';
+        if (options.distinct) {
+            if (distinctOn && Array.isArray(distinctOn)) {
+                distinctClause = `DISTINCT ON (${distinctOn.map((c) => this.escapeId(c)).join(', ')}) `;
+            }
+            else if (options.col) {
+                // DISTINCT with specific column (e.g., COUNT(DISTINCT col))
+                distinctClause = `DISTINCT ${this.escapeId(options.col)} `;
+            }
+            else {
+                distinctClause = 'DISTINCT ';
+            }
+        }
+        if (options.attributes) {
+            if (Array.isArray(options.attributes)) {
+                selectSql = options.attributes.map((a) => this.escapeId(a)).join(', ');
+            }
+            else if (options.attributes.include) {
+                selectSql = options.attributes.include.map((a) => this.escapeId(a)).join(', ');
+            }
+            else if (options.attributes.exclude) {
+                // CockroachDB supports EXCEPT
+                selectSql = `* EXCEPT (${options.attributes.exclude.map((a) => this.escapeId(a)).join(', ')})`;
+            }
+        }
+        let sql = `SELECT ${distinctClause}${selectSql} FROM ${this.escapeId(options.tableName)}`;
+        // AS OF SYSTEM TIME (CockroachDB time-travel reads). Must immediately
+        // follow the table reference in the FROM clause, before any JOINs/WHERE.
+        // See: https://www.cockroachlabs.com/docs/stable/as-of-system-time
+        const asOfSystemTime = options.asOfSystemTime;
+        if (asOfSystemTime) {
+            sql += ` AS OF SYSTEM TIME ${this.buildAsOfSystemTimeClause(asOfSystemTime)}`;
+        }
+        // Build JOIN clause (for includes)
+        if (options.include && options.include.length > 0) {
+            for (const include of options.include) {
+                // Determine join type - check joinType option first, then fall back to required
+                let joinType;
+                if (include.joinType) {
+                    switch (include.joinType) {
+                        case 'INNER':
+                            joinType = 'INNER JOIN';
+                            break;
+                        case 'LEFT':
+                            joinType = 'LEFT JOIN';
+                            break;
+                        case 'RIGHT':
+                            joinType = 'RIGHT JOIN';
+                            break;
+                        case 'FULL':
+                            joinType = 'FULL OUTER JOIN';
+                            break;
+                        case 'CROSS':
+                            joinType = 'CROSS JOIN';
+                            break;
+                        default:
+                            joinType = include.required ? 'INNER JOIN' : 'LEFT JOIN';
+                    }
+                }
+                else {
+                    joinType = include.required ? 'INNER JOIN' : 'LEFT JOIN';
+                }
+                const modelTableName = include.model.tableName;
+                const modelName = modelTableName ? modelTableName : include.model.toString();
+                const alias = include.as || modelName;
+                // Handle LATERAL keyword (CockroachDB specific)
+                const lateralKeyword = include.lateral ? 'LATERAL ' : '';
+                sql += ` ${joinType}${lateralKeyword ? ' ' + lateralKeyword : ''}${this.escapeId(modelName)} ${this.escapeId(alias)}`;
+                if (include.where) {
+                    const whereClause = this.buildWhereClause(include.where);
+                    sql += ` ON ${whereClause.sql}`;
+                    queryValues.push(...whereClause.values);
+                }
+            }
+        }
+        // Build WHERE clause
+        if (options.where) {
+            const whereClause = this.buildWhereClause(options.where);
+            if (whereClause.sql) {
+                sql += ` WHERE ${whereClause.sql}`;
+                queryValues.push(...whereClause.values);
+            }
+        }
+        // Build GROUP BY clause
+        if (options.group) {
+            const groupByClause = this.buildGroupByClause(options.group);
+            if (groupByClause) {
+                sql += ` ${groupByClause}`;
+            }
+        }
+        // Build HAVING clause
+        if (options.having) {
+            const havingClause = this.buildHavingClause(options.having);
+            if (havingClause.sql) {
+                sql += ` HAVING ${havingClause.sql}`;
+                queryValues.push(...havingClause.values);
+            }
+        }
+        // Build ORDER BY clause
+        if (options.order) {
+            const orderClause = this.buildOrderClause(options.order);
+            if (orderClause) {
+                sql += ` ${orderClause}`;
+            }
+        }
+        // Build LIMIT/OFFSET clause
+        sql += this.buildLimitOffset(options.limit, options.offset);
+        // Handle row-level locking (CockroachDB specific)
+        if (options.lock) {
+            let lockType;
+            // lock: true is equivalent to 'UPDATE'
+            if (options.lock === true) {
+                lockType = 'UPDATE';
+            }
+            else if (typeof options.lock === 'string') {
+                lockType = options.lock;
+            }
+            else if (typeof options.lock === 'object' && options.lock.of) {
+                // lock: { of: Model } - defaults to FOR UPDATE for table-specific locking
+                lockType = 'UPDATE';
+            }
+            if (lockType === 'UPDATE') {
+                sql += ' FOR UPDATE';
+            }
+            else if (lockType === 'SHARE') {
+                sql += ' FOR SHARE';
+            }
+            else if (lockType === 'KEY SHARE') {
+                sql += ' FOR KEY SHARE';
+            }
+            // Handle lock on specific table (CockroachDB supports OF clause)
+            if (typeof options.lock === 'object' && options.lock.of) {
+                const model = options.lock.of;
+                sql += ` OF ${this.escapeId(model.tableName || '')}`;
+            }
+        }
+        // Build UNION clause if provided
+        if (options.union && options.union.length > 0) {
+            const unionType = options.unionType || 'UNION';
+            for (const unionQuery of options.union) {
+                const unionModel = unionQuery.model;
+                const unionTableName = unionModel.tableName || unionModel.name || '';
+                // Build the union query
+                let unionSql = `SELECT * FROM ${this.escapeId(unionTableName)}`;
+                // Add WHERE clause for union query
+                if (unionQuery.where) {
+                    const whereClause = this.buildWhereClause(unionQuery.where);
+                    if (whereClause.sql) {
+                        unionSql += ` WHERE ${whereClause.sql}`;
+                        queryValues.push(...whereClause.values);
+                    }
+                }
+                // Add ORDER BY for union query
+                if (unionQuery.order) {
+                    const orderClause = this.buildOrderClause(unionQuery.order);
+                    if (orderClause) {
+                        unionSql += ` ${orderClause}`;
+                    }
+                }
+                // Add LIMIT for union query
+                if (unionQuery.limit) {
+                    unionSql += ` LIMIT ${unionQuery.limit}`;
+                }
+                // Add OFFSET for union query
+                if (unionQuery.offset) {
+                    unionSql += ` OFFSET ${unionQuery.offset}`;
+                }
+                sql += ` ${unionType} ${unionSql}`;
+            }
+        }
+        return { sql, values: queryValues };
+    }
+    /**
+     * Escape a value for use in a CockroachDB array literal
+     */
+    escapeArray(values) {
+        const escaped = values.map((v) => {
+            if (v === null) {
+                return 'NULL';
+            }
+            if (typeof v === 'string') {
+                return `"${v.replace(/"/g, '""')}"`;
+            }
+            if (typeof v === 'number' || typeof v === 'boolean') {
+                return String(v);
+            }
+            return `"${JSON.stringify(v).replace(/"/g, '""')}"`;
+        });
+        return `ARRAY[${escaped.join(', ')}]`;
+    }
+    /**
+     * Build an array contains operator query (@>)
+     * SELECT * FROM table WHERE column @> ARRAY['elem1', 'elem2']
+     */
+    buildArrayContains(column, values) {
+        const arrayLiteral = this.escapeArray(values);
+        return `${this.escapeId(column)} @> ${arrayLiteral}`;
+    }
+    /**
+     * Build an array contained by operator query (<@)
+     * SELECT * FROM table WHERE column <@ ARRAY['elem1', 'elem2']
+     */
+    buildArrayContainedBy(column, values) {
+        const arrayLiteral = this.escapeArray(values);
+        return `${this.escapeId(column)} <@ ${arrayLiteral}`;
+    }
+    /**
+     * Build an array overlaps operator query (&&)
+     * SELECT * FROM table WHERE column && ARRAY['elem1', 'elem2']
+     */
+    buildArrayOverlaps(column, values) {
+        const arrayLiteral = this.escapeArray(values);
+        return `${this.escapeId(column)} && ${arrayLiteral}`;
+    }
+    /**
+     * Build an array ANY operator query
+     * SELECT * FROM table WHERE 'value' = ANY(column)
+     */
+    buildArrayAny(column, value) {
+        const escaped = this.escape(value);
+        return `${escaped} = ANY(${this.escapeId(column)})`;
+    }
+    /**
+     * Build an array ALL operator query
+     * SELECT * FROM table WHERE 'value' = ALL(column)
+     * or with comparison: SELECT * FROM table WHERE value > ALL(column)
+     */
+    buildArrayAll(column, value, operator) {
+        if (operator) {
+            const escaped = this.escape(value);
+            return `${escaped} ${operator} ALL(${this.escapeId(column)})`;
+        }
+        const escaped = this.escape(value);
+        return `${escaped} = ALL(${this.escapeId(column)})`;
+    }
+    /**
+     * Build a full-text search query
+     */
+    buildFullTextSearchQuery(tableName, searchColumns, searchTerm, options) {
+        const columnList = searchColumns.map((c) => this.escapeId(c)).join(" || ' ' || ");
+        const language = options?.language || 'english';
+        const ranking = options?.ranking || 'ts_rank';
+        const queryValues = [searchTerm];
+        let sql = `SELECT *, ${ranking}(to_tsvector('${language}', ${columnList}), plainto_tsquery('${language}', $1)) as _rank`;
+        sql += ` FROM ${this.escapeId(tableName)}`;
+        sql += ` WHERE to_tsvector('${language}', ${columnList}) @@ plainto_tsquery('${language}', $1)`;
+        if (options?.orderBy) {
+            const orderClause = this.buildOrderClause(options.orderBy);
+            if (orderClause) {
+                sql += ` ${orderClause}`;
+            }
+        }
+        return { sql, values: queryValues };
+    }
+    /**
+     * Build a JSON/JSONB path query
+     */
+    buildJsonPathQuery(column, path, value, operator) {
+        const values = [value];
+        const columnRef = this.escapeId(column);
+        // JSONB operators
+        const jsonOperators = {
+            '@>': 'jsonb_path_query_first',
+            '<@': 'jsonb_path_query_first',
+            '?': 'jsonb_exists',
+            '?|': 'jsonb_exists',
+            '~': '~',
+            '~*': '~*',
+        };
+        let sql;
+        if (jsonOperators[operator]) {
+            sql = `${columnRef} ${operator} $1`;
+        }
+        else if (path) {
+            sql = `${columnRef} #> $1 ${operator} $2`;
+            values.unshift(path);
+        }
+        else {
+            sql = `${columnRef} ${operator} $1`;
+        }
+        return { sql, values };
+    }
+    /**
+     * Get CockroachDB specific lock options
+     */
+    getLockOptions(lock) {
+        const params = [];
+        let sql = '';
+        const lockType = typeof lock === 'string' ? lock : lock?.level;
+        switch (lockType) {
+            case 'UPDATE':
+                sql = 'FOR UPDATE';
+                break;
+            case 'SHARE':
+                sql = 'FOR SHARE';
+                break;
+            case 'KEY SHARE':
+                sql = 'FOR KEY SHARE';
+                break;
+            default:
+                return { sql: '', params };
+        }
+        if (typeof lock === 'object' && lock?.of) {
+            const model = lock.of;
+            sql += ` OF ${this.escapeId(model.tableName || '')}`;
+        }
+        if (typeof lock === 'object' && lock?.nowait) {
+            sql += ' NOWAIT';
+        }
+        else if (typeof lock === 'object' && lock?.skipLocked) {
+            sql += ' SKIP LOCKED';
+        }
+        return { sql, params };
+    }
+    // ---------------------------------------------------------------------------
+    // User / Privilege management — CockroachDB dialect
+    // ---------------------------------------------------------------------------
+    /**
+     * Escape a single-quoted string value (replace ' with '').
+     */
+    escapeStringValue(value) {
+        return value.replace(/'/g, "''");
+    }
+    /**
+     * Build the shared WITH-clause attribute list used by both CREATE USER and
+     * ALTER USER.  Returns a (possibly empty) array of attribute tokens.
+     */
+    buildUserAttributes(options) {
+        const attrs = [];
+        if (options.password !== undefined) {
+            attrs.push(`WITH PASSWORD '${this.escapeStringValue(String(options.password))}'`);
+        }
+        if (options.superuser === true) {
+            attrs.push('SUPERUSER');
+        }
+        else if (options.superuser === false) {
+            attrs.push('NOSUPERUSER');
+        }
+        if (options.createdb === true) {
+            attrs.push('CREATEDB');
+        }
+        else if (options.createdb === false) {
+            attrs.push('NOCREATEDB');
+        }
+        if (options.createrole === true) {
+            attrs.push('CREATEROLE');
+        }
+        else if (options.createrole === false) {
+            attrs.push('NOCREATEROLE');
+        }
+        // accountLocked takes precedence over login
+        if (options.accountLocked === true) {
+            attrs.push('NOLOGIN');
+        }
+        else if (options.login === false) {
+            attrs.push('NOLOGIN');
+        }
+        else {
+            // default: LOGIN
+            attrs.push('LOGIN');
+        }
+        if (options.replication === true) {
+            attrs.push('REPLICATION');
+        }
+        else if (options.replication === false) {
+            attrs.push('NOREPLICATION');
+        }
+        if (options.bypassrls === true) {
+            attrs.push('BYPASSRLS');
+        }
+        else if (options.bypassrls === false) {
+            attrs.push('NOBYPASSRLS');
+        }
+        if (options.maxConnections !== undefined) {
+            attrs.push(`CONNECTION LIMIT ${Number(options.maxConnections)}`);
+        }
+        if (options.expirePassword !== undefined) {
+            if (options.expirePassword === true) {
+                attrs.push(`VALID UNTIL 'epoch'`);
+            }
+            else if (options.expirePassword instanceof Date) {
+                attrs.push(`VALID UNTIL '${this.escapeStringValue(options.expirePassword.toISOString())}'`);
+            }
+            else if (typeof options.expirePassword === 'string') {
+                attrs.push(`VALID UNTIL '${this.escapeStringValue(options.expirePassword)}'`);
+            }
+        }
+        return attrs;
+    }
+    /**
+     * Build a CREATE USER statement.
+     *
+     * CockroachDB treats users as roles with LOGIN.  Supported options:
+     *   ifNotExists, password, superuser, createdb, createrole, login,
+     *   replication, bypassrls, maxConnections, accountLocked, expirePassword,
+     *   defaultRole, requireSSL (noted but skipped — not a standard PG attribute).
+     */
+    buildCreateUserQuery(username, options) {
+        const opts = options || {};
+        let sql = 'CREATE USER';
+        if (opts.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` "${this.escapeStringValue(username)}"`;
+        // requireSSL is not a standard CockroachDB role attribute; emit a comment.
+        if (opts.requireSSL) {
+            sql += ' /* requireSSL: use pg_hba.conf hostssl rules instead */';
+        }
+        const attrs = this.buildUserAttributes(opts);
+        if (attrs.length > 0) {
+            sql += ` ${attrs.join(' ')}`;
+        }
+        if (opts.defaultRole !== undefined) {
+            const roles = Array.isArray(opts.defaultRole) ? opts.defaultRole : [opts.defaultRole];
+            sql += ` IN ROLE ${roles.map((r) => `"${this.escapeStringValue(r)}"`).join(', ')}`;
+        }
+        return sql;
+    }
+    /**
+     * Build an ALTER USER statement.
+     *
+     * Supports the same attribute options as buildCreateUserQuery plus
+     * `options.renameTo` to rename the role.
+     */
+    buildAlterUserQuery(username, options) {
+        const opts = options || {};
+        let sql = `ALTER USER "${this.escapeStringValue(username)}"`;
+        if (opts.renameTo !== undefined) {
+            sql += ` RENAME TO "${this.escapeStringValue(String(opts.renameTo))}"`;
+            // RENAME TO cannot be combined with other clauses in the same statement.
+            return sql;
+        }
+        const attrs = this.buildUserAttributes(opts);
+        if (attrs.length > 0) {
+            sql += ` ${attrs.join(' ')}`;
+        }
+        if (opts.defaultRole !== undefined) {
+            const roles = Array.isArray(opts.defaultRole) ? opts.defaultRole : [opts.defaultRole];
+            sql += ` IN ROLE ${roles.map((r) => `"${this.escapeStringValue(r)}"`).join(', ')}`;
+        }
+        return sql;
+    }
+    /**
+     * Build a DROP USER statement.
+     *
+     * Options: ifExists, cascade, restrict.
+     */
+    buildDropUserQuery(username, options) {
+        const opts = options || {};
+        let sql = 'DROP USER';
+        if (opts.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` "${this.escapeStringValue(username)}"`;
+        if (opts.cascade) {
+            sql += ' CASCADE';
+        }
+        else if (opts.restrict) {
+            sql += ' RESTRICT';
+        }
+        return sql;
+    }
+    /**
+     * Return a query that lists all CockroachDB users (roles with LOGIN).
+     */
+    getUsersQuery() {
+        return [
+            'SELECT usename AS "user", \'\' AS "host",',
+            '       rolcanlogin AS "login", rolsuper AS "superuser",',
+            '       rolpassword IS NOT NULL AS "hasPassword"',
+            'FROM pg_user',
+            'JOIN pg_authid ON pg_user.usesysid = pg_authid.oid',
+            'ORDER BY usename;',
+        ].join('\n');
+    }
+    /**
+     * Create a database user
+     */
+    async createUser(username, options) {
+        const sql = this.buildCreateUserQuery(username, options);
+        await this.query(sql);
+    }
+    /**
+     * Map a generic privilege name to a CockroachDB privilege name.
+     * Returns null when the privilege has no CockroachDB equivalent and
+     * should be silently skipped.
+     */
+    mapPrivilege(priv) {
+        const upper = priv.toUpperCase();
+        if (upper === 'ALL')
+            return 'ALL PRIVILEGES';
+        // MySQL-specific — not valid in CockroachDB
+        if (upper === 'INDEX')
+            return null;
+        return priv;
+    }
+    /**
+     * Build the ON <scope> clause for GRANT / REVOKE.
+     *
+     * Scope shapes:
+     *   { level: 'global' }
+     *   { level: 'database', database: 'dbname' }
+     *   { level: 'schema',   schema: 'schemaname' }
+     *   { level: 'table',    table: 'tablename' }
+     *   { level: 'column',   table: 'tablename', columns: ['col1', 'col2'] }
+     *   { level: 'sequence', schema: 'schemaname' }
+     */
+    buildGrantScope(options) {
+        const level = (options.level || 'global').toLowerCase();
+        switch (level) {
+            case 'database':
+                return `ON DATABASE "${this.escapeStringValue(options.database || '')}"`;
+            case 'schema':
+                return `ON SCHEMA "${this.escapeStringValue(options.schema || '')}"`;
+            case 'table':
+                return `ON TABLE "${this.escapeStringValue(options.table || '')}"`;
+            case 'sequence':
+                return `ON ALL SEQUENCES IN SCHEMA "${this.escapeStringValue(options.schema || 'public')}"`;
+            case 'column':
+                // Handled separately — the caller inserts column names into the
+                // privilege list, not here.
+                return `ON "${this.escapeStringValue(options.table || '')}"`;
+            case 'global':
+            default:
+                return `ON ALL TABLES IN SCHEMA "${this.escapeStringValue(options.schema || 'public')}"`;
+        }
+    }
+    /**
+     * Build a GRANT statement.
+     *
+     * options.privileges  — string | string[]  (e.g. ['SELECT', 'INSERT'])
+     * options.on          — scope object (see buildGrantScope)
+     * options.to          — string | string[]  (grantees)
+     * options.withGrantOption — boolean
+     * options.asUser      — string (GRANTED BY, PG 14+)
+     *
+     * For column-level grants (options.on.level === 'column') the columns are
+     * embedded in each privilege token: SELECT (col1, col2).
+     */
+    buildGrantQuery(options) {
+        const rawPrivileges = Array.isArray(options.privileges)
+            ? options.privileges
+            : [options.privileges || 'ALL'];
+        const isColumnLevel = (options.on || {}).level === 'column';
+        const columnList = isColumnLevel
+            ? (options.on.columns || []).map((c) => `"${this.escapeStringValue(c)}"`)
+            : [];
+        const mappedPrivileges = rawPrivileges
+            .map((p) => this.mapPrivilege(p))
+            .filter((p) => p !== null)
+            .map((p) => isColumnLevel && columnList.length > 0 ? `${p} (${columnList.join(', ')})` : p);
+        if (mappedPrivileges.length === 0) {
+            return '-- No applicable privileges to grant';
+        }
+        const scope = this.buildGrantScope(options.on || {});
+        const grantees = Array.isArray(options.to) ? options.to : [options.to || ''];
+        let sql = `GRANT ${mappedPrivileges.join(', ')} ${scope} TO ${grantees.join(', ')}`;
+        if (options.withGrantOption) {
+            sql += ' WITH GRANT OPTION';
+        }
+        if (options.asUser !== undefined) {
+            sql += ` GRANTED BY "${this.escapeStringValue(String(options.asUser))}"`;
+        }
+        return sql;
+    }
+    /**
+     * Build a REVOKE statement.
+     *
+     * options.privileges      — string | string[]
+     * options.on              — scope object (same as buildGrantQuery)
+     * options.from            — string | string[]  (revokees)
+     * options.grantOptionFor  — boolean (revoke only the GRANT OPTION)
+     * options.cascade         — boolean
+     * options.restrict        — boolean
+     */
+    buildRevokeQuery(options) {
+        const rawPrivileges = Array.isArray(options.privileges)
+            ? options.privileges
+            : [options.privileges || 'ALL'];
+        const isColumnLevel = (options.on || {}).level === 'column';
+        const columnList = isColumnLevel
+            ? (options.on.columns || []).map((c) => `"${this.escapeStringValue(c)}"`)
+            : [];
+        const mappedPrivileges = rawPrivileges
+            .map((p) => this.mapPrivilege(p))
+            .filter((p) => p !== null)
+            .map((p) => isColumnLevel && columnList.length > 0 ? `${p} (${columnList.join(', ')})` : p);
+        if (mappedPrivileges.length === 0) {
+            return '-- No applicable privileges to revoke';
+        }
+        let sql = 'REVOKE';
+        if (options.grantOptionFor) {
+            sql += ' GRANT OPTION FOR';
+        }
+        const scope = this.buildGrantScope(options.on || {});
+        const revokees = Array.isArray(options.from) ? options.from : [options.from || ''];
+        sql += ` ${mappedPrivileges.join(', ')} ${scope} FROM ${revokees.join(', ')}`;
+        if (options.cascade) {
+            sql += ' CASCADE';
+        }
+        else if (options.restrict) {
+            sql += ' RESTRICT';
+        }
+        return sql;
+    }
+    /**
+     * Return a query that shows the privileges granted to a specific user/role.
+     * The optional `host` parameter is ignored — CockroachDB has no host concept.
+     */
+    buildShowGrantsQuery(username, _host) {
+        const escaped = this.escapeStringValue(username);
+        return [
+            `SELECT grantee, privilege_type, table_schema, table_name, column_name, is_grantable`,
+            `FROM information_schema.role_column_grants`,
+            `WHERE grantee = '${escaped}'`,
+            `UNION ALL`,
+            `SELECT grantee, privilege_type, table_schema, table_name, NULL AS column_name, is_grantable`,
+            `FROM information_schema.role_table_grants`,
+            `WHERE grantee = '${escaped}'`,
+            `ORDER BY table_schema, table_name, privilege_type;`,
+        ].join('\n');
+    }
+    /**
+     * CockroachDB applies privilege changes automatically — FLUSH PRIVILEGES is
+     * a MySQL concept.  Return a no-op with an explanatory comment.
+     */
+    buildFlushPrivilegesQuery() {
+        return ('-- CockroachDB automatically applies privilege changes; FLUSH PRIVILEGES is not required\n' +
+            'SELECT 1;');
+    }
+    /**
+     * Build a CREATE ROLE statement.
+     *
+     * Unlike CREATE USER, NOLOGIN is the default for roles.  Pass
+     * `options.login = true` to enable login.
+     *
+     * Supported options: ifNotExists, login, password, superuser, createdb,
+     * createrole, inherit, replication, bypassrls, maxConnections,
+     * expirePassword, accountLocked.
+     */
+    buildCreateRoleQuery(roleName, options) {
+        const opts = options || {};
+        let sql = 'CREATE ROLE';
+        if (opts.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` "${this.escapeStringValue(roleName)}"`;
+        const attrs = [];
+        if (opts.login === true) {
+            attrs.push('LOGIN');
+        }
+        else if (opts.login === false || opts.accountLocked === true) {
+            attrs.push('NOLOGIN');
+        }
+        // No default LOGIN for roles (PG default is already NOLOGIN).
+        if (opts.password !== undefined) {
+            attrs.push(`WITH PASSWORD '${this.escapeStringValue(String(opts.password))}'`);
+        }
+        if (opts.superuser === true) {
+            attrs.push('SUPERUSER');
+        }
+        else if (opts.superuser === false) {
+            attrs.push('NOSUPERUSER');
+        }
+        if (opts.createdb === true) {
+            attrs.push('CREATEDB');
+        }
+        else if (opts.createdb === false) {
+            attrs.push('NOCREATEDB');
+        }
+        if (opts.createrole === true) {
+            attrs.push('CREATEROLE');
+        }
+        else if (opts.createrole === false) {
+            attrs.push('NOCREATEROLE');
+        }
+        if (opts.inherit === false) {
+            attrs.push('NOINHERIT');
+        }
+        else if (opts.inherit === true) {
+            attrs.push('INHERIT');
+        }
+        if (opts.replication === true) {
+            attrs.push('REPLICATION');
+        }
+        else if (opts.replication === false) {
+            attrs.push('NOREPLICATION');
+        }
+        if (opts.bypassrls === true) {
+            attrs.push('BYPASSRLS');
+        }
+        else if (opts.bypassrls === false) {
+            attrs.push('NOBYPASSRLS');
+        }
+        if (opts.maxConnections !== undefined) {
+            attrs.push(`CONNECTION LIMIT ${Number(opts.maxConnections)}`);
+        }
+        if (opts.expirePassword !== undefined) {
+            if (opts.expirePassword === true) {
+                attrs.push(`VALID UNTIL 'epoch'`);
+            }
+            else if (opts.expirePassword instanceof Date) {
+                attrs.push(`VALID UNTIL '${this.escapeStringValue(opts.expirePassword.toISOString())}'`);
+            }
+            else if (typeof opts.expirePassword === 'string') {
+                attrs.push(`VALID UNTIL '${this.escapeStringValue(opts.expirePassword)}'`);
+            }
+        }
+        if (attrs.length > 0) {
+            sql += ` ${attrs.join(' ')}`;
+        }
+        return sql;
+    }
+    /**
+     * Build a DROP ROLE statement.
+     *
+     * Options: ifExists, cascade.
+     */
+    buildDropRoleQuery(roleName, options) {
+        const opts = options || {};
+        let sql = 'DROP ROLE';
+        if (opts.ifExists) {
+            sql += ' IF EXISTS';
+        }
+        sql += ` "${this.escapeStringValue(roleName)}"`;
+        if (opts.cascade) {
+            sql += ' CASCADE';
+        }
+        return sql;
+    }
+    /**
+     * Build a GRANT <role> TO <members> statement.
+     *
+     * Options: withAdminOption.
+     */
+    buildGrantRoleQuery(role, to, options) {
+        const opts = options || {};
+        const members = Array.isArray(to) ? to : [to];
+        let sql = `GRANT "${this.escapeStringValue(role)}" TO ${members.join(', ')}`;
+        if (opts.withAdminOption) {
+            sql += ' WITH ADMIN OPTION';
+        }
+        return sql;
+    }
+    /**
+     * Build a REVOKE <role> FROM <members> statement.
+     *
+     * Options: adminOptionFor, cascade.
+     */
+    buildRevokeRoleQuery(role, from, options) {
+        const opts = options || {};
+        let sql = 'REVOKE';
+        if (opts.adminOptionFor) {
+            sql += ' ADMIN OPTION FOR';
+        }
+        const members = Array.isArray(from) ? from : [from];
+        sql += ` "${this.escapeStringValue(role)}" FROM ${members.join(', ')}`;
+        if (opts.cascade) {
+            sql += ' CASCADE';
+        }
+        return sql;
+    }
+    /**
+     * Return a query that lists all CockroachDB roles that cannot log in
+     * (i.e. "group roles" as opposed to user roles).
+     */
+    getRolesQuery() {
+        return `SELECT rolname AS "rolname" FROM pg_roles WHERE rolcanlogin = false ORDER BY rolname;`;
+    }
+    /**
+     * Generate SQL for creating a CockroachDB database
+     */
+    createDatabaseSQL(options) {
+        const parts = [];
+        parts.push(`CREATE DATABASE ${this.quoteIdentifier(options.name)}`);
+        if (options.encoding) {
+            parts.push(`ENCODING = '${options.encoding}'`);
+        }
+        if (options.lcCollate) {
+            parts.push(`LC_COLLATE = '${options.lcCollate}'`);
+        }
+        if (options.lcCtype) {
+            parts.push(`LC_CTYPE = '${options.lcCtype}'`);
+        }
+        if (options.template) {
+            parts.push(`TEMPLATE = ${this.quoteIdentifier(options.template)}`);
+        }
+        if (options.tablespace) {
+            parts.push(`TABLESPACE = ${this.quoteIdentifier(options.tablespace)}`);
+        }
+        if (options.isTemplate !== undefined) {
+            parts.push(options.isTemplate ? 'IS_TEMPLATE = true' : 'IS_TEMPLATE = false');
+        }
+        return parts.join(' ');
+    }
+    /**
+     * Generate SQL for dropping a CockroachDB database
+     */
+    dropDatabaseSQL(name) {
+        return `DROP DATABASE IF EXISTS ${this.quoteIdentifier(name)}`;
+    }
+    /**
+     * Generate SQL for creating a savepoint
+     */
+    createSavepointSQL(name) {
+        const savepointName = name || `sp_${Date.now()}`;
+        return `SAVEPOINT ${savepointName}`;
+    }
+    /**
+     * Generate SQL for releasing a savepoint
+     */
+    releaseSavepointSQL(name) {
+        return `RELEASE SAVEPOINT ${name}`;
+    }
+    /**
+     * Generate SQL for rolling back to a savepoint
+     */
+    rollbackToSavepointSQL(name) {
+        return `ROLLBACK TO SAVEPOINT ${name}`;
+    }
+    /**
+     * Build a JSON_TABLE-equivalent expression to shred a JSON array into relational rows.
+     * Not supported: CockroachDB implements a subset of Postgres's JSONB function surface
+     * and has neither a native `JSON_TABLE` (PG17+) nor `json_to_recordset`/
+     * `jsonb_to_recordset` (verified absent from CockroachDB's function reference as of
+     * v23.x/v24.x). There is no row-shredding equivalent to fall back to.
+     */
+    buildJsonTable(_jsonExpression, _rowPath, _columns, _alias) {
+        throw new Error('CockroachDB does not support JSON_TABLE, OPENJSON, or json_to_recordset/jsonb_to_recordset; ' +
+            'there is no supported way to shred a JSON array into relational rows');
+    }
+}
+exports.CockroachDBDialect = CockroachDBDialect;
+/**
+ * CockroachDB has no Foreign Data Wrapper (FDW) machinery: no
+ * `CREATE FOREIGN DATA WRAPPER`/`CREATE SERVER`/`CREATE FOREIGN TABLE`/
+ * `CREATE USER MAPPING`/`IMPORT FOREIGN SCHEMA` statements, and no
+ * `pg_foreign_data_wrapper`/`pg_foreign_server` catalogs. These methods
+ * exist only to satisfy the shared `Dialect` interface (which the
+ * Postgres dialect implements for real); rather than silently emitting
+ * Postgres-only DDL that would fail against a real CockroachDB cluster,
+ * they throw a clear "not supported" error. External-data access on
+ * CockroachDB instead goes through `IMPORT`/`EXPORT` or
+ * `CREATE EXTERNAL CONNECTION`, which are out of scope for this ORM's
+ * FDW-shaped API.
+ * @see https://www.cockroachlabs.com/docs/stable/create-external-connection
+ */
+CockroachDBDialect.FDW_NOT_SUPPORTED_MESSAGE = 'Foreign Data Wrappers are not supported in CockroachDB (no CREATE FOREIGN DATA WRAPPER/CREATE SERVER/CREATE FOREIGN TABLE support). ' +
+    'Use IMPORT/EXPORT or CREATE EXTERNAL CONNECTION for external data access instead.';
+/**
+ * CockroachDB does NOT implement PostgreSQL's extension mechanism the way
+ * Postgres does. `CREATE EXTENSION`/`DROP EXTENSION` are accepted by CRDB
+ * purely as no-op compatibility shims for a small, fixed allowlist of
+ * extension names (kept in sync with CockroachDB's documented "Supported
+ * extensions" list) so that ORMs/tools which unconditionally issue
+ * `CREATE EXTENSION IF NOT EXISTS <name>` don't fail outright. No actual
+ * extension code is loaded and most Postgres extensions (arbitrary compiled
+ * extensions, most contrib modules, etc.) are NOT usable at all. Callers
+ * asking for anything outside this allowlist get a clear error instead of
+ * a misleading "success" that doesn't provide any real functionality.
+ */
+CockroachDBDialect.SUPPORTED_EXTENSION_SHIMS = new Set([
+    'citext',
+    'plpgsql',
+    'pg_trgm',
+    'fuzzystrmatch',
+    'hstore',
+    'pgcrypto',
+    'uuid-ossp',
+    'btree_gin',
+    'btree_gist',
+    'cube',
+    'intarray',
+    'ltree',
+    'pg_stat_statements',
+    'vector',
+]);
+/**
+ * CockroachDB-specific transaction class with isolation level support and savepoints
+ */
+class CockroachDBTransaction {
+    constructor(client, depth, options) {
+        this.finished = false;
+        this.parent = null;
+        this.savepoints = [];
+        this.client = null;
+        this.savepointCount = 0;
+        this.id = `tx_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.options = options || {};
+        this.client = client;
+    }
+    /**
+     * Create a savepoint
+     */
+    async createSavepoint(name) {
+        const savepointName = name || `sp_${this.savepointCount++}`;
+        if (this.client) {
+            await this.client.query(`SAVEPOINT ${savepointName}`);
+            this.savepoints.push(savepointName);
+        }
+        return savepointName;
+    }
+    /**
+     * Rollback to a savepoint
+     */
+    async rollbackToSavepoint(name) {
+        if (this.client) {
+            await this.client.query(`ROLLBACK TO SAVEPOINT ${name}`);
+        }
+    }
+    /**
+     * Release a savepoint
+     */
+    async releaseSavepoint(name) {
+        if (this.client) {
+            await this.client.query(`RELEASE SAVEPOINT ${name}`);
+            this.savepoints = this.savepoints.filter((sp) => sp !== name);
+        }
+    }
+    async commit() {
+        if (this.client) {
+            await this.client.query('COMMIT');
+        }
+        this.finished = true;
+    }
+    async rollback() {
+        if (this.client) {
+            await this.client.query('ROLLBACK');
+        }
+        this.finished = true;
+    }
+}
+exports.CockroachDBTransaction = CockroachDBTransaction;
+/**
+ * Create a new CockroachDB dialect instance
+ */
+function createCockroachDBDialect(options) {
+    return new CockroachDBDialect(options || {});
+}
+exports.default = CockroachDBDialect;