ts-prorm-orm 1.1.0

package/dist/dialects/duckdb/index.js

@@ -0,0 +1,2014 @@
+"use strict";
+/**
+ * DuckDB dialect implementation
+ *
+ * DuckDB is an embedded, in-process OLAP database (similar in deployment
+ * model to SQLite - a single file or `:memory:`, no server/host/port/auth)
+ * but with a genuinely modern analytical SQL engine: real window functions,
+ * recursive CTEs, rich composite types (LIST/STRUCT/MAP), first-class
+ * Parquet/CSV/JSON table functions, native sequences, and a real extension
+ * system (INSTALL/LOAD).
+ *
+ * The `duckdb` npm driver's public API (`duckdb/lib/duckdb.d.ts`) is
+ * callback-based (`new duckdb.Database(path, cb)`, `db.all(sql, ...args, cb)`,
+ * `db.run(sql, ...args, cb)`). All of that is wrapped in Promises here.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDBTransaction = exports.DuckDBDialect = void 0;
+exports.createDuckDBDialect = createDuckDBDialect;
+const duckdb = __importStar(require("duckdb"));
+const query_stream_helper_1 = require("../query-stream-helper");
+const prorm_1 = require("../../prorm");
+const operators_1 = require("../../operators");
+function promisifyAll(target, sql, params) {
+    return new Promise((resolve, reject) => {
+        const cb = (err, rows) => {
+            if (err)
+                reject(err);
+            else
+                resolve(rows);
+        };
+        if (params.length > 0) {
+            target.all(sql, ...params, cb);
+        }
+        else {
+            target.all(sql, cb);
+        }
+    });
+}
+function promisifyRun(target, sql, params) {
+    return new Promise((resolve, reject) => {
+        const cb = (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        };
+        if (params.length > 0) {
+            target.run(sql, ...params, cb);
+        }
+        else {
+            target.run(sql, cb);
+        }
+    });
+}
+function promisifyExec(target, sql) {
+    return new Promise((resolve, reject) => {
+        target.exec(sql, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * DuckDB dialect class implementing the shared `Dialect` interface.
+ */
+class DuckDBDialect {
+    constructor(config) {
+        this.name = 'duckdb';
+        this.library = 'duckdb';
+        this.db = null;
+        this.connection = null;
+        this._isConnected = false;
+        this.transactionDepth = 0;
+        this.config = {
+            storage: ':memory:',
+            ...config,
+        };
+    }
+    /**
+     * Connect to the DuckDB database (embedded - opens a local file or :memory:).
+     * host/port/username/password (if present on the config for API parity with
+     * networked dialects) are intentionally ignored - DuckDB is single-process.
+     */
+    async connect() {
+        try {
+            this.db = await new Promise((resolve, reject) => {
+                let accessMode = this.config.config;
+                if (this.config.readonly) {
+                    if (accessMode && typeof accessMode === 'object') {
+                        // Merge readonly into the existing config object rather than letting
+                        // `config` silently override `readonly`.
+                        accessMode = { ...accessMode, access_mode: 'READ_ONLY' };
+                    }
+                    else if (!accessMode) {
+                        accessMode = duckdb.OPEN_READONLY;
+                    }
+                }
+                const cb = (err) => {
+                    // duckdb.Database's constructor callback fires asynchronously once the
+                    // native handle has actually been opened (or failed to open). Only
+                    // resolve/reject here - resolving eagerly right after construction
+                    // would let open failures (corrupted file, permission denied,
+                    // readonly-open against a locked writer) race past a settled promise
+                    // and surface only later as a confusing error on the first query.
+                    if (err)
+                        reject(err);
+                    else
+                        resolve(database);
+                };
+                const database = accessMode
+                    ? new duckdb.Database(this.config.storage, accessMode, cb)
+                    : new duckdb.Database(this.config.storage, cb);
+            });
+            this.connection = this.db.connect();
+            this._isConnected = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to connect to DuckDB database: ${error}`);
+        }
+    }
+    async disconnect() {
+        if (this.connection) {
+            await new Promise((resolve, reject) => {
+                this.connection.close((err) => (err ? reject(err) : resolve()));
+            }).catch(() => undefined);
+            this.connection = null;
+        }
+        if (this.db) {
+            await new Promise((resolve, reject) => {
+                this.db.close((err) => (err ? reject(err) : resolve()));
+            }).catch(() => undefined);
+            this.db = null;
+        }
+        this._isConnected = false;
+    }
+    getConnection() {
+        return this.connection;
+    }
+    isConnected() {
+        return this._isConnected && this.connection !== null;
+    }
+    /**
+     * Stream query results by paging through `sql` via repeated
+     * dialect-appropriate LIMIT/OFFSET queries (see
+     * `createPaginatedQueryStream()` in `src/dialects/query-stream-helper.ts`)
+     * instead of loading the whole result set into memory at once.
+     * @param sql - The SELECT statement to stream
+     * @param options - Streaming options (batch size, backpressure watermark, model mapping)
+     */
+    queryStream(sql, options) {
+        return (0, query_stream_helper_1.createPaginatedQueryStream)(this, sql, options);
+    }
+    /**
+     * Execute a raw SQL query with retry support.
+     */
+    async query(sql, options) {
+        const defaultQueryRetryOptions = {
+            max: 0,
+            timeout: 1000,
+            match: ['is closed', 'connection', 'write-write conflict', 'database is locked'],
+            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.connection) {
+                throw new Error('Not connected to database');
+            }
+            const sqlUpper = sql.trim().toUpperCase();
+            const isSelect = sqlUpper.startsWith('SELECT') ||
+                sqlUpper.startsWith('WITH') ||
+                sqlUpper.startsWith('PRAGMA') ||
+                sqlUpper.startsWith('SHOW') ||
+                sqlUpper.startsWith('DESCRIBE') ||
+                sqlUpper.startsWith('EXPLAIN');
+            const params = Array.isArray(options?.replacements)
+                ? options.replacements
+                : options?.replacements
+                    ? Object.values(options.replacements)
+                    : Array.isArray(options?.bind)
+                        ? options.bind
+                        : options?.bind
+                            ? Object.values(options.bind)
+                            : [];
+            try {
+                if (isSelect || /\bRETURNING\b/i.test(sql)) {
+                    const rows = await promisifyAll(this.connection, sql, params);
+                    return {
+                        rows: rows,
+                        rowCount: rows.length,
+                        fields: [],
+                    };
+                }
+                else {
+                    await promisifyRun(this.connection, sql, params);
+                    return {
+                        rows: [],
+                        rowCount: 0,
+                        fields: [],
+                    };
+                }
+            }
+            catch (error) {
+                throw new Error(`Query error: ${error}`);
+            }
+        };
+        if (effectiveRetry && effectiveRetry.max > 0) {
+            return this.executeWithRetry(executeQuery, effectiveRetry);
+        }
+        return executeQuery();
+    }
+    async executeWithRetry(fn, retryOptions) {
+        let lastError;
+        for (let attempt = 0; attempt <= retryOptions.max; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                const errorMessage = lastError.message.toLowerCase();
+                const shouldRetry = retryOptions.match.some((pattern) => errorMessage.includes(pattern.toLowerCase()));
+                if (!shouldRetry || attempt === retryOptions.max) {
+                    throw lastError;
+                }
+                await new Promise((resolve) => setTimeout(resolve, retryOptions.timeout));
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Replace placeholders in SQL with actual values.
+     */
+    replaceReplacements(sql, replacements) {
+        if (!replacements) {
+            return sql;
+        }
+        if (Array.isArray(replacements)) {
+            let result = sql;
+            for (const value of replacements) {
+                result = result.replace(/\?/, () => this.escape(value));
+            }
+            return result;
+        }
+        let result = sql;
+        for (const [key, value] of Object.entries(replacements)) {
+            if (Array.isArray(value)) {
+                const escapedValues = value.map((v) => this.escape(v)).join(', ');
+                const regex = new RegExp(`:${key}(?![\\w])`, 'g');
+                result = result.replace(regex, escapedValues);
+            }
+            else if (value === null) {
+                const regex = new RegExp(`:${key}(?![\\w])`, 'g');
+                result = result.replace(regex, 'NULL');
+            }
+            else {
+                const regex = new RegExp(`:${key}(?![\\w])`, 'g');
+                result = result.replace(regex, () => this.escape(value));
+            }
+        }
+        return result;
+    }
+    /**
+     * Escape a value for use in a query. DuckDB uses standard SQL literals -
+     * TRUE/FALSE for booleans (not 0/1), single-quoted strings, and a
+     * `'\x..'::BLOB` cast for binary data.
+     */
+    escape(value) {
+        if (value === null || value === undefined) {
+            return 'NULL';
+        }
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        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 `TIMESTAMP '${value.toISOString().replace('T', ' ').replace('Z', '')}'`;
+        }
+        if (Buffer.isBuffer(value)) {
+            const hex = value.toString('hex').match(/../g)?.map((b) => `\\x${b}`).join('') ?? '';
+            return `'${hex}'::BLOB`;
+        }
+        if (Array.isArray(value)) {
+            return `[${value.map((v) => this.escape(v)).join(', ')}]`;
+        }
+        return `'${this.escapeString(JSON.stringify(value))}'`;
+    }
+    escapeString(str) {
+        return str.replace(/'/g, "''");
+    }
+    escapeId(identifier) {
+        const id = String(identifier ?? '');
+        return `"${id.replace(/"/g, '""')}"`;
+    }
+    quoteIdentifier(identifier) {
+        return this.escapeId(identifier);
+    }
+    quoteTable(tableName, schema) {
+        if (schema) {
+            return `${this.escapeId(schema)}.${this.escapeId(tableName)}`;
+        }
+        return this.escapeId(tableName);
+    }
+    async getDatabaseVersion() {
+        const result = await this.query('SELECT version() AS version');
+        return String(result.rows[0]?.version ?? '');
+    }
+    createDatabaseSQL(options) {
+        // DuckDB has no CREATE DATABASE statement of its own (a "database" is a
+        // file, opened via ATTACH). Document this via attachDatabase() instead.
+        return `ATTACH '${options.name}' AS ${this.escapeId(options.name)}`;
+    }
+    dropDatabaseSQL(name) {
+        return `DETACH ${this.escapeId(name)}`;
+    }
+    /**
+     * Attach another DuckDB (or SQLite/Postgres, via the respective DuckDB
+     * extension) database file under `alias`, making it queryable as
+     * `alias.table`.
+     */
+    async attachDatabase(path, alias, options) {
+        if (!alias || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid database alias: ${alias}`);
+        }
+        const opts = [];
+        if (options?.readOnly)
+            opts.push('READ_ONLY');
+        if (options?.type)
+            opts.push(`TYPE ${options.type.toUpperCase()}`);
+        const optsSql = opts.length > 0 ? ` (${opts.join(', ')})` : '';
+        await this.query(`ATTACH '${path.replace(/'/g, "''")}' AS ${this.escapeId(alias)}${optsSql}`);
+    }
+    async detachDatabase(alias) {
+        if (!alias || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid database alias: ${alias}`);
+        }
+        await this.query(`DETACH ${this.escapeId(alias)}`);
+    }
+    createSavepointSQL(name) {
+        const savepointName = name || `sp_${Date.now()}`;
+        return `SAVEPOINT ${savepointName}`;
+    }
+    releaseSavepointSQL(name) {
+        return `RELEASE SAVEPOINT ${name}`;
+    }
+    rollbackToSavepointSQL(name) {
+        return `ROLLBACK TO SAVEPOINT ${name}`;
+    }
+    // ==================== Schemas ====================
+    async createSchema(schema) {
+        await this.query(`CREATE SCHEMA IF NOT EXISTS ${this.escapeId(schema)}`);
+    }
+    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);
+    }
+    async showAllSchemas() {
+        const result = await this.query(`SELECT schema_name FROM information_schema.schemata ORDER BY schema_name`);
+        return result.rows.map((row) => row.schema_name);
+    }
+    async listSchemas() {
+        return this.showAllSchemas();
+    }
+    // ==================== Extensions (real DuckDB feature) ====================
+    // Unlike SQLite/Postgres extensions, DuckDB's extension system (INSTALL/LOAD)
+    // is a core, well-known part of the engine and is implemented for real here
+    // rather than being stubbed out - it's how `parquet`, `httpfs`, `json`,
+    // `fts`, and `spatial` support are enabled.
+    async createExtension(extensionName, options) {
+        const name = this.escapeId(extensionName).replace(/"/g, '');
+        await this.query(`INSTALL ${name}${options?.version ? ` VERSION '${options.version}'` : ''}`);
+        await this.query(`LOAD ${name}`);
+    }
+    async dropExtension(_extensionName, _options) {
+        // DuckDB has no UNINSTALL/DROP EXTENSION statement - installed extensions
+        // simply live in the local extension directory. There is nothing to run;
+        // to stop using one, just don't LOAD it in future connections.
+        throw new Error('DuckDB does not support dropping/uninstalling extensions once installed. ' +
+            'Simply avoid LOADing the extension in future connections.');
+    }
+    async getExtensions() {
+        const result = await this.query(`SELECT extension_name, installed, loaded, description, extension_version FROM duckdb_extensions()`);
+        return result.rows.map((row) => ({
+            name: row.extension_name,
+            defaultVersion: row.extension_version ?? null,
+            installedVersion: row.installed ? (row.extension_version ?? '') : null,
+            comment: row.description ?? null,
+        }));
+    }
+    async hasExtension(extensionName) {
+        const result = await this.query(`SELECT 1 FROM duckdb_extensions() WHERE extension_name = ? AND loaded = true`, { replacements: [extensionName] });
+        return result.rows.length > 0;
+    }
+    // ==================== Tables ====================
+    async createTable(tableName, columns, options) {
+        // AUTOINCREMENT columns need a backing SEQUENCE created first, since
+        // DuckDB has no AUTOINCREMENT keyword - it uses `DEFAULT nextval('seq')`.
+        for (const [columnName, definition] of Object.entries(columns)) {
+            if (definition.autoIncrement) {
+                const seqName = this._autoIncrementSequenceName(tableName, columnName);
+                await this.query(`CREATE SEQUENCE IF NOT EXISTS ${this.escapeId(seqName)}`);
+            }
+        }
+        const columnDefs = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            const typeObj = definition.type;
+            if (typeObj && typeObj.key === 'VIRTUAL') {
+                continue;
+            }
+            columnDefs.push(this.getColumnDefinitionSql(tableName, columnName, definition));
+        }
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                const constraintSql = this.buildConstraintSql(constraint);
+                if (constraintSql)
+                    columnDefs.push(constraintSql);
+            }
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        if (options?.engine || options?.charset || options?.rowFormat) {
+            console.warn(`DuckDB: engine/charset/rowFormat options are not supported and will be ignored`);
+        }
+        await this.query(sql);
+        if (options?.uniqueKeys) {
+            const uniqueKeysList = Array.isArray(options.uniqueKeys)
+                ? options.uniqueKeys
+                : Object.entries(options.uniqueKeys).map(([keyName, fields]) => ({ name: keyName, fields }));
+            for (const uk of uniqueKeysList) {
+                await this.addIndex(tableName, uk.name || `uq_${tableName}_${uk.fields.join('_')}`, uk.fields, { unique: true });
+            }
+        }
+        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,
+                });
+            }
+        }
+        if (options?.comment) {
+            await this.commentTable(tableName, options.comment);
+        }
+    }
+    _autoIncrementSequenceName(tableName, columnName) {
+        return `seq_${tableName}_${columnName}`;
+    }
+    buildConstraintSql(constraint) {
+        const name = constraint.name ? `CONSTRAINT ${this.escapeId(constraint.name)} ` : '';
+        const fields = constraint.fields?.map((f) => this.escapeId(f)).join(', ') || '';
+        switch (constraint.type) {
+            case 'PRIMARY KEY':
+                return `${name}PRIMARY KEY (${fields})`;
+            case 'UNIQUE':
+                return `${name}UNIQUE (${fields})`;
+            case 'FOREIGN KEY': {
+                if (!constraint.references)
+                    return null;
+                const refField = constraint.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                    : `(${this.escapeId(refField)})`;
+                let fkSql = `${name}FOREIGN KEY (${fields}) REFERENCES ${this.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}CHECK (${constraint.check})`;
+            default:
+                return null;
+        }
+    }
+    getColumnDefinitionSql(tableName, columnName, definition) {
+        let sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type, columnName)}`;
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.autoIncrement) {
+            const seqName = this._autoIncrementSequenceName(tableName, columnName);
+            sql += ` DEFAULT nextval(${this.escape(seqName)})`;
+        }
+        else if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.getDefaultValue(definition.defaultValue)}`;
+        }
+        if (definition.unique) {
+            sql += ' UNIQUE';
+        }
+        if (definition.references) {
+            const refField = definition.references.field;
+            const refFieldSql = Array.isArray(refField)
+                ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                : `(${this.escapeId(refField)})`;
+            sql += ` REFERENCES ${this.escapeId(definition.references.table)}${refFieldSql}`;
+            if (definition.references.onDelete)
+                sql += ` ON DELETE ${definition.references.onDelete}`;
+            if (definition.references.onUpdate)
+                sql += ` ON UPDATE ${definition.references.onUpdate}`;
+        }
+        return sql;
+    }
+    getDefaultValue(value) {
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'string') {
+            if (value.toUpperCase().includes('CURRENT_') || /^nextval\(/i.test(value)) {
+                return value;
+            }
+            return `'${this.escapeString(value)}'`;
+        }
+        if (typeof value === 'number')
+            return String(value);
+        if (typeof value === 'boolean')
+            return value ? 'TRUE' : 'FALSE';
+        if (value instanceof Date)
+            return `TIMESTAMP '${value.toISOString().replace('T', ' ').replace('Z', '')}'`;
+        if (typeof value === 'object' &&
+            value !== null &&
+            typeof value.toDefaultValue === 'function') {
+            return value.toDefaultValue();
+        }
+        return `'${this.escapeString(String(value))}'`;
+    }
+    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);
+    }
+    // ==================== Partitioning (emulated) ====================
+    // DuckDB has no ALTER-TABLE-level partitioning system like PostgreSQL. Its
+    // real partitioning concept lives at the storage/IO layer instead - Hive-
+    // style partitioned Parquet directories, read via `read_parquet(...,
+    // hive_partitioning=true)` and written via `COPY ... TO ... (PARTITION_BY
+    // (...))` (see `copyTo`/`readParquet` below). To still satisfy the shared
+    // partition-table API (used by cross-dialect model code), the same
+    // child-table + metadata-table + UNION ALL view emulation SQLite uses is
+    // applied here.
+    async createPartitionedTable(tableName, columns, options) {
+        const partitions = options?.partitions ?? [];
+        await this.createTable(tableName, columns, { ...options, ifNotExists: options?.ifNotExists ?? true });
+        const metadataTable = `${tableName}_partitions`;
+        await this.query(`CREATE TABLE IF NOT EXISTS ${this.escapeId(metadataTable)} (
+        partition_name VARCHAR PRIMARY KEY,
+        parent_table VARCHAR NOT NULL,
+        bound VARCHAR,
+        is_detached BOOLEAN DEFAULT FALSE,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )`);
+        for (const partition of partitions) {
+            await this.createPartition({
+                parentTable: tableName,
+                name: partition.name,
+                bound: partition.bound,
+                tablespace: partition.tablespace,
+                storageParameters: partition.storageParameters,
+            });
+        }
+        if (partitions.length > 0) {
+            const partitionSelects = partitions
+                .map((p) => `SELECT * FROM ${this.escapeId(p.name)}`)
+                .join('\n  UNION ALL\n  ');
+            await this.createView(`${tableName}_union`, partitionSelects, { replace: true });
+        }
+    }
+    async createPartition(options) {
+        const { parentTable, name, bound } = options;
+        const parentColumns = await this.describeTable(parentTable);
+        const partitionColumns = {};
+        for (const [colName, colDef] of Object.entries(parentColumns)) {
+            partitionColumns[colName] = {
+                type: colDef.type,
+                allowNull: colDef.allowNull,
+                defaultValue: colDef.defaultValue,
+            };
+        }
+        await this.createTable(name, partitionColumns, { ifNotExists: true });
+        const metadataTable = `${parentTable}_partitions`;
+        const boundStr = bound ? this.escape(JSON.stringify(bound)) : 'NULL';
+        await this.query(`INSERT OR IGNORE INTO ${this.escapeId(metadataTable)} (partition_name, parent_table, bound) VALUES (${this.escape(name)}, ${this.escape(parentTable)}, ${boundStr})`);
+    }
+    async attachPartition(options) {
+        const { parentTable, partitionName } = options;
+        const tables = await this.showTables();
+        if (!tables.includes(partitionName)) {
+            throw new Error(`Partition table '${partitionName}' does not exist`);
+        }
+        const metadataTable = `${parentTable}_partitions`;
+        await this.query(`INSERT INTO ${this.escapeId(metadataTable)} (partition_name, parent_table, is_detached) ` +
+            `VALUES (${this.escape(partitionName)}, ${this.escape(parentTable)}, FALSE) ` +
+            `ON CONFLICT (partition_name) DO UPDATE SET is_detached = FALSE`);
+    }
+    async detachPartition(options) {
+        const { partitionName } = options;
+        const partitions = await this.listPartitions(partitionName);
+        if (partitions.length === 0) {
+            throw new Error(`Partition '${partitionName}' not found`);
+        }
+        const metadataTable = `${partitions[0].parent_table}_partitions`;
+        await this.query(`UPDATE ${this.escapeId(metadataTable)} SET is_detached = TRUE WHERE partition_name = ${this.escape(partitionName)}`);
+    }
+    async dropPartition(partitionName, options) {
+        const partitions = await this.listPartitions(partitionName);
+        const parentTable = partitions[0]?.parent_table ?? null;
+        let sql = 'DROP TABLE';
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(partitionName)}`;
+        if (options?.cascade)
+            sql += ' CASCADE';
+        await this.query(sql);
+        if (parentTable) {
+            const metadataTable = `${parentTable}_partitions`;
+            try {
+                await this.query(`DELETE FROM ${this.escapeId(metadataTable)} WHERE partition_name = ${this.escape(partitionName)}`);
+            }
+            catch {
+                // Ignore if metadata table doesn't exist
+            }
+        }
+    }
+    async listPartitions(tableName) {
+        const metadataTable = `${tableName}_partitions`;
+        try {
+            const result = await this.query(`SELECT * FROM ${this.escapeId(metadataTable)}`);
+            return result.rows.map((row) => ({
+                name: row.partition_name,
+                parent_table: row.parent_table,
+                bound: row.bound,
+                is_detached: row.is_detached,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    // ==================== Views ====================
+    async createView(viewName, query, options) {
+        let sql = options?.replace ? 'CREATE OR REPLACE VIEW' : 'CREATE VIEW';
+        sql += ` ${options?.schema ? this.quoteTable(viewName, options.schema) : this.escapeId(viewName)} AS ${query}`;
+        await this.query(sql);
+    }
+    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);
+    }
+    async showViews() {
+        const result = await this.query(`SELECT table_name FROM information_schema.tables WHERE table_type = 'VIEW'`);
+        return result.rows.map((row) => row.table_name);
+    }
+    /**
+     * Materialized views (not supported). DuckDB has no `CREATE MATERIALIZED
+     * VIEW` statement - the closest equivalents are a plain table populated via
+     * `CREATE TABLE ... AS SELECT ...` (refreshed by re-running the query) or
+     * exporting to Parquet with `copyTo()` and reading it back with
+     * `readParquet()`.
+     */
+    async createMaterializedView() {
+        throw new Error('DuckDB does not support materialized views. Use `CREATE TABLE ... AS SELECT ...` ' +
+            '(re-run to refresh) or `copyTo()` to a Parquet file plus `readParquet()` to read it back.');
+    }
+    async refreshMaterializedView() {
+        throw new Error('DuckDB does not support materialized views.');
+    }
+    async dropMaterializedView() {
+        throw new Error('DuckDB does not support materialized views.');
+    }
+    async hasMaterializedView() {
+        return false;
+    }
+    async showMaterializedViews() {
+        return [];
+    }
+    // ==================== Columns ====================
+    async addColumn(tableName, columnName, definition) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${this.getColumnDefinitionSql(tableName, columnName, definition)}`;
+        await this.query(sql);
+    }
+    async removeColumn(tableName, columnName) {
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} DROP COLUMN ${this.escapeId(columnName)}`);
+    }
+    async changeColumn(tableName, columnName, definition) {
+        // DuckDB supports ALTER TABLE ... ALTER COLUMN ... TYPE / SET/DROP DEFAULT
+        // / SET/DROP NOT NULL as separate statements (no single combined form).
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} TYPE ${this.getDataTypeSql(definition.type, columnName)}`);
+        if (definition.defaultValue !== undefined) {
+            await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} SET DEFAULT ${this.getDefaultValue(definition.defaultValue)}`);
+        }
+        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`);
+        }
+    }
+    async renameColumn(tableName, oldColumnName, newColumnName) {
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`);
+    }
+    async addForeignKey(tableName, _columnName, _referencedTableName, _referencedColumnName) {
+        throw new Error(`DuckDB does not support adding foreign keys to an existing table ("${tableName}") via ALTER TABLE. ` +
+            `Define the foreign key when creating the table instead.`);
+    }
+    async bulkInsert(tableName, records, _options) {
+        if (records.length === 0) {
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        const columns = Object.keys(records[0]);
+        const placeholders = records.map(() => `(${columns.map(() => '?').join(', ')})`);
+        const values = records.flatMap((record) => columns.map((col) => record[col]));
+        const sql = `INSERT INTO ${this.quoteTable(tableName)} (${columns
+            .map((c) => this.escapeId(c))
+            .join(', ')}) VALUES ${placeholders.join(', ')}`;
+        return this.query(sql, { replacements: values });
+    }
+    async showTables() {
+        const result = await this.query(`SELECT table_name FROM information_schema.tables WHERE table_type = 'BASE TABLE'`);
+        return result.rows.map((row) => row.table_name);
+    }
+    async showConstraints(tableName) {
+        const result = await this.query(`SELECT constraint_name, constraint_type FROM duckdb_constraints() WHERE table_name = ?`, { replacements: [tableName] });
+        return result.rows;
+    }
+    async addConstraint(tableName, options) {
+        const name = options.name ? `CONSTRAINT ${this.escapeId(options.name)} ` : '';
+        let clause = '';
+        switch (options.type) {
+            case 'UNIQUE':
+                clause = `${name}UNIQUE (${options.fields.map((f) => this.escapeId(f)).join(', ')})`;
+                break;
+            case 'PRIMARY KEY':
+                clause = `${name}PRIMARY KEY (${options.fields.map((f) => this.escapeId(f)).join(', ')})`;
+                break;
+            case 'CHECK':
+                clause = `${name}CHECK (${options.check})`;
+                break;
+            case 'FOREIGN KEY':
+                if (!options.references)
+                    throw new Error('references required for FOREIGN KEY constraint');
+                clause = `${name}FOREIGN KEY (${options.fields.map((f) => this.escapeId(f)).join(', ')}) REFERENCES ${this.escapeId(options.references.table)} (${options.references.fields.map((f) => this.escapeId(f)).join(', ')})`;
+                break;
+        }
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD ${clause}`);
+    }
+    async removeConstraint(tableName, constraintName) {
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`);
+    }
+    async showIndexes(tableName) {
+        const result = await this.query(`SELECT * FROM duckdb_indexes() WHERE table_name = ?`, {
+            replacements: [tableName],
+        });
+        return result.rows;
+    }
+    async describeTable(tableName) {
+        const result = await this.query(`DESCRIBE ${this.escapeId(tableName)}`);
+        const description = {};
+        for (const row of result.rows) {
+            const name = row.column_name;
+            const nullStr = String(row.null ?? 'YES').toUpperCase();
+            const keyStr = String(row.key ?? '');
+            description[name] = {
+                type: row.column_type || 'VARCHAR',
+                allowNull: nullStr !== 'NO',
+                defaultValue: row.default,
+                primaryKey: keyStr.includes('PRI'),
+                autoIncrement: typeof row.default === 'string' && /nextval\(/i.test(row.default),
+            };
+        }
+        return description;
+    }
+    async renameTable(oldName, newName) {
+        await this.query(`ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)}`);
+    }
+    async addIndex(tableName, indexName, fields = [], options) {
+        let sql = 'CREATE';
+        if (options?.unique)
+            sql += ' UNIQUE';
+        sql += ' INDEX';
+        if (options?.ifNotExists !== false)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.escapeId(indexName)} ON ${this.escapeId(tableName)}`;
+        if (options?.expression) {
+            sql += ` (${options.expression})`;
+        }
+        else {
+            sql += ` (${fields.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        // Note: DuckDB indexes do not support partial (WHERE) index predicates;
+        // silently ignoring `options.where` here would hide data-shape bugs, so
+        // surface it clearly instead.
+        if (options?.where) {
+            throw new Error('DuckDB does not support partial indexes (WHERE clause on CREATE INDEX).');
+        }
+        await this.query(sql);
+    }
+    async removeIndex(_tableName, indexName) {
+        await this.query(`DROP INDEX ${this.escapeId(indexName)}`);
+    }
+    async createIndex(tableName, indexDef) {
+        await this.addIndex(tableName, indexDef.name, indexDef.fields, {
+            unique: indexDef.unique,
+            type: indexDef.type,
+            using: indexDef.using,
+            where: indexDef.where,
+        });
+    }
+    async createFulltextIndex() {
+        throw new Error('DuckDB does not have a built-in CREATE FULLTEXT INDEX statement. Install/load the ' +
+            "'fts' extension and use its `PRAGMA create_fts_index(...)` function instead.");
+    }
+    async createSpatialIndex() {
+        throw new Error("DuckDB spatial indexing requires the 'spatial' extension's RTREE index type " +
+            "(CREATE INDEX ... USING RTREE (...)); use createExtension('spatial') then addIndex " +
+            "with { using: 'RTREE' }.");
+    }
+    async dropIndex(_tableName, indexName, _options) {
+        await this.query(`DROP INDEX ${this.escapeId(indexName)}`);
+    }
+    async createConstraint(tableName, constraintDef) {
+        await this.addConstraint(tableName, {
+            type: constraintDef.type,
+            fields: constraintDef.fields || [],
+            name: constraintDef.name,
+            references: constraintDef.references
+                ? { table: constraintDef.references.table, fields: [constraintDef.references.field] }
+                : undefined,
+            check: constraintDef.check,
+        });
+    }
+    async dropConstraint(tableName, constraintName, options) {
+        let sql = `ALTER TABLE ${this.escapeId(tableName)} DROP CONSTRAINT`;
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(constraintName)}`;
+        await this.query(sql);
+    }
+    async changeOwner() {
+        throw new Error('DuckDB has no per-table ownership model to change (it is a single-process embedded database).');
+    }
+    // ==================== Foreign Data Wrappers (PostgreSQL-only feature) ====================
+    fdwNotSupported() {
+        throw new Error('Foreign Data Wrappers are not supported by DuckDB. This is a PostgreSQL-specific feature.');
+    }
+    async createForeignDataWrapper() {
+        this.fdwNotSupported();
+    }
+    async dropForeignDataWrapper() {
+        this.fdwNotSupported();
+    }
+    async createForeignServer() {
+        this.fdwNotSupported();
+    }
+    async dropForeignServer() {
+        this.fdwNotSupported();
+    }
+    async createForeignTable() {
+        this.fdwNotSupported();
+    }
+    buildCreateServerQuery(_name, _opts) {
+        this.fdwNotSupported();
+    }
+    buildAlterServerQuery(_name, _opts) {
+        this.fdwNotSupported();
+    }
+    buildDropServerQuery() {
+        this.fdwNotSupported();
+    }
+    buildCreateUserMappingQuery(_opts) {
+        this.fdwNotSupported();
+    }
+    buildAlterUserMappingQuery(_opts) {
+        this.fdwNotSupported();
+    }
+    buildDropUserMappingQuery() {
+        this.fdwNotSupported();
+    }
+    async createUserMapping() {
+        this.fdwNotSupported();
+    }
+    async dropUserMapping() {
+        this.fdwNotSupported();
+    }
+    buildCreateForeignTableQuery(_tableName, _opts) {
+        this.fdwNotSupported();
+    }
+    buildDropForeignTableQuery() {
+        this.fdwNotSupported();
+    }
+    buildImportForeignSchemaQuery(_remoteSchema, _serverName, _opts) {
+        this.fdwNotSupported();
+    }
+    getServersQuery() {
+        this.fdwNotSupported();
+    }
+    // ==================== Security policies (MSSQL RLS-style feature) ====================
+    async createSecurityPolicy() {
+        throw new Error('Row-level security policies are not supported by DuckDB.');
+    }
+    async dropSecurityPolicy() {
+        throw new Error('Row-level security policies are not supported by DuckDB.');
+    }
+    // ==================== User / privilege management ====================
+    // DuckDB is embedded and single-process/single-user: there is no user or
+    // role system to manage.
+    userMgmtNotSupported() {
+        throw new Error('User/role management is not supported by DuckDB (it is an embedded, single-user database).');
+    }
+    buildCreateUserQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildAlterUserQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildDropUserQuery() {
+        this.userMgmtNotSupported();
+    }
+    getUsersQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildGrantQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildRevokeQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildShowGrantsQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildFlushPrivilegesQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildCreateRoleQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildDropRoleQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildGrantRoleQuery() {
+        this.userMgmtNotSupported();
+    }
+    buildRevokeRoleQuery() {
+        this.userMgmtNotSupported();
+    }
+    getRolesQuery() {
+        this.userMgmtNotSupported();
+    }
+    // ==================== Stored procedures ====================
+    // DuckDB has no procedural SQL language. Its closest analogue is a scalar/
+    // table MACRO (`CREATE MACRO name(args) AS expr`), which is expression-only
+    // (no statement bodies, loops, or side effects), so it cannot faithfully
+    // stand in for a stored procedure - fail clearly rather than pretend.
+    async createStoredProcedure(options) {
+        throw new Error(`DuckDB does not support stored procedures. Cannot create '${options.name}'.\n\n` +
+            `Workarounds:\n` +
+            `- Move logic to application code\n` +
+            `- Use a scalar/table MACRO for simple reusable expressions: ` +
+            `CREATE MACRO ${options.name}(...) AS (...)\n` +
+            `- Use views for read-only reusable queries`);
+    }
+    async createProcedure(options) {
+        return this.createStoredProcedure(options);
+    }
+    async dropStoredProcedure(procedureName, _options) {
+        throw new Error(`DuckDB does not support stored procedures. Cannot drop '${procedureName}'.`);
+    }
+    async dropProcedure(procedureName, options) {
+        return this.dropStoredProcedure(procedureName, options);
+    }
+    async executeStoredProcedure(options) {
+        throw new Error(`DuckDB does not support stored procedures. Cannot execute '${options.procedureName}'. ` +
+            `Run the equivalent SQL directly via query(), or define a MACRO.`);
+    }
+    async hasStoredProcedure() {
+        return false;
+    }
+    // ==================== Triggers (not supported) ====================
+    async createTrigger(options) {
+        throw new Error(`DuckDB does not support triggers. Cannot create '${options.name}' on '${options.tableName}'. ` +
+            `Move the reactive logic into application code around the write path instead.`);
+    }
+    async dropTrigger(triggerName, _tableName, _options) {
+        throw new Error(`DuckDB does not support triggers. Cannot drop '${triggerName}'.`);
+    }
+    async hasTrigger() {
+        return false;
+    }
+    // ==================== Sequences (real, native DuckDB feature) ====================
+    async createSequence(options) {
+        let sql = 'CREATE';
+        if (options.replace)
+            sql += ' OR REPLACE';
+        sql += ' SEQUENCE';
+        if (options.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.quoteTable(options.name, options.schema)}`;
+        if (options.startWith !== undefined)
+            sql += ` START WITH ${options.startWith}`;
+        if (options.incrementBy !== undefined)
+            sql += ` INCREMENT BY ${options.incrementBy}`;
+        if (options.minvalue !== undefined)
+            sql += ` MINVALUE ${options.minvalue}`;
+        if (options.maxvalue !== undefined)
+            sql += ` MAXVALUE ${options.maxvalue}`;
+        if (options.cycle)
+            sql += ' CYCLE';
+        await this.query(sql);
+    }
+    async dropSequence(sequenceName, options) {
+        let sql = 'DROP SEQUENCE';
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.quoteTable(sequenceName, options?.schema)}`;
+        if (options?.cascade)
+            sql += ' CASCADE';
+        await this.query(sql);
+    }
+    async nextSequenceValue(sequenceName) {
+        const result = await this.query(`SELECT nextval(${this.escape(sequenceName)}) AS value`);
+        return Number(result.rows[0].value);
+    }
+    async hasSequence(sequenceName, schema) {
+        const result = await this.query(`SELECT 1 FROM duckdb_sequences() WHERE sequence_name = ?${schema ? ' AND schema_name = ?' : ''}`, { replacements: (schema ? [sequenceName, schema] : [sequenceName]) });
+        return result.rows.length > 0;
+    }
+    async listSequences() {
+        const result = await this.query(`SELECT sequence_name FROM duckdb_sequences()`);
+        return result.rows.map((row) => row.sequence_name);
+    }
+    // ==================== Row-level security (not supported) ====================
+    async createPolicy() {
+        throw new Error('Row-level security is not supported by DuckDB.');
+    }
+    async dropPolicy() {
+        throw new Error('Row-level security is not supported by DuckDB.');
+    }
+    async enableRLS() {
+        throw new Error('Row-level security is not supported by DuckDB.');
+    }
+    async disableRLS() {
+        throw new Error('Row-level security is not supported by DuckDB.');
+    }
+    async hasPolicy() {
+        return false;
+    }
+    // ==================== Comments ====================
+    async commentTable(tableName, comment) {
+        await this.query(`COMMENT ON TABLE ${this.escapeId(tableName)} IS ${this.escape(comment)}`);
+    }
+    async commentColumn(tableName, columnName, comment) {
+        await this.query(`COMMENT ON COLUMN ${this.escapeId(tableName)}.${this.escapeId(columnName)} IS ${this.escape(comment)}`);
+    }
+    // ==================== Advanced indexes ====================
+    async createPartialIndex() {
+        throw new Error('DuckDB does not support partial indexes (WHERE clause on CREATE INDEX).');
+    }
+    async createExpressionIndex(tableName, indexName, expression, options) {
+        let sql = 'CREATE';
+        if (options?.unique)
+            sql += ' UNIQUE';
+        sql += ` INDEX ${this.escapeId(indexName)} ON ${this.escapeId(tableName)} (${expression})`;
+        await this.query(sql);
+    }
+    // ==================== Identity / computed columns ====================
+    async createIdentityColumn(tableName, columnName, options) {
+        // DuckDB has no GENERATED ... AS IDENTITY syntax; emulate with a sequence-backed default.
+        const seqName = this._autoIncrementSequenceName(tableName, columnName);
+        await this.query(`CREATE SEQUENCE IF NOT EXISTS ${this.escapeId(seqName)} START ${options?.startWith ?? 1} INCREMENT ${options?.incrementBy ?? 1}`);
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} SET DEFAULT nextval(${this.escape(seqName)})`);
+    }
+    async createComputedColumn(tableName, columnName, expression, options) {
+        const typeSql = options?.type || 'VARCHAR';
+        const modeSql = options?.persisted ? '' : ' VIRTUAL';
+        await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${this.escapeId(columnName)} ${typeSql} GENERATED ALWAYS AS (${expression})${modeSql}`);
+    }
+    // ==================== Transactions ====================
+    async startTransaction(options) {
+        if (!this.connection) {
+            throw new Error('Not connected to database');
+        }
+        const transaction = new DuckDBTransaction(this.transactionDepth++, options, this);
+        if (this.transactionDepth === 1) {
+            await this.query('BEGIN TRANSACTION');
+        }
+        else {
+            await this.query(`SAVEPOINT sp_${transaction.id}`);
+        }
+        return transaction;
+    }
+    async commitTransaction(transaction) {
+        const tx = transaction;
+        if (this.transactionDepth === 1) {
+            await this.query('COMMIT');
+        }
+        else {
+            await this.query(`RELEASE SAVEPOINT sp_${tx.id}`);
+        }
+        this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+    }
+    async rollbackTransaction(transaction) {
+        const tx = transaction;
+        if (this.transactionDepth === 1) {
+            await this.query('ROLLBACK');
+        }
+        else {
+            await this.query(`ROLLBACK TO SAVEPOINT sp_${tx.id}`);
+        }
+        this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+    }
+    // ==================== Data types ====================
+    getDataTypeSql(dataType, columnName) {
+        if (typeof dataType === 'string') {
+            return dataType;
+        }
+        if (typeof dataType === 'function') {
+            try {
+                dataType = dataType();
+            }
+            catch {
+                return 'VARCHAR';
+            }
+        }
+        if (!dataType || typeof dataType !== 'object') {
+            return 'VARCHAR';
+        }
+        const dt = dataType;
+        switch (dt.key) {
+            case 'STRING':
+                return `VARCHAR(${dt.length || 255})`;
+            case 'CHAR':
+                return `VARCHAR(${dt.length || 1})`;
+            case 'TEXT':
+                return 'VARCHAR';
+            case 'INTEGER':
+                return dt.unsigned ? 'UINTEGER' : 'INTEGER';
+            case 'BIGINT':
+                return dt.unsigned ? 'UBIGINT' : 'BIGINT';
+            case 'FLOAT':
+                return 'REAL';
+            case 'DOUBLE':
+                return 'DOUBLE';
+            case 'DECIMAL':
+                return `DECIMAL(${dt.precision || 18},${dt.scale || 0})`;
+            case 'BOOLEAN':
+                return 'BOOLEAN';
+            case 'DATE':
+                return 'TIMESTAMP';
+            case 'DATEONLY':
+                return 'DATE';
+            case 'TIME':
+                return 'TIME';
+            case 'BLOB':
+                return 'BLOB';
+            case 'ENUM': {
+                // DuckDB supports a native ENUM type, but only via a separately named
+                // type (`CREATE TYPE mood AS ENUM (...)`), which would require a
+                // second DDL statement per enum column and out-of-band lifecycle
+                // management. To keep column definitions self-contained (matching
+                // how every other option here works as a single inline column def),
+                // this uses the same VARCHAR + CHECK emulation SQLite uses rather
+                // than a named DuckDB ENUM type.
+                const colRef = columnName ? this.escapeId(columnName) : 'value';
+                const values = dt.values;
+                return `VARCHAR CHECK(${values ? `${colRef} IN (${values.map((v) => `'${this.escapeString(String(v))}'`).join(',')})` : '1=1'})`;
+            }
+            case 'JSON':
+            case 'JSONB':
+                return 'JSON';
+            case 'UUID':
+                return 'UUID';
+            case 'GEOMETRY':
+                // Requires the 'spatial' extension's GEOMETRY type; falls back to
+                // BLOB when unloaded so schema creation doesn't hard-fail.
+                return 'BLOB';
+            case 'ARRAY':
+            case 'LIST': {
+                // DuckDB LIST columns are written as `<elementType>[]`. Accept both
+                // DataTypes.LIST(elementType)/DataTypes.ARRAY(elementType) (which
+                // expose the element type as `.type`) and a plain
+                // `{ type: 'LIST', subtype: ... }` shape for parity with how other
+                // dialects (e.g. Postgres' ARRAY handling above) accept `.subtype`.
+                const elementType = dt.type ?? dt.subtype;
+                if (elementType) {
+                    return `${this.getDataTypeSql(elementType, columnName)}[]`;
+                }
+                return 'VARCHAR[]';
+            }
+            case 'STRUCT': {
+                // DuckDB STRUCT columns are written as `STRUCT(field TYPE, ...)`.
+                const fields = dt.fields;
+                if (fields && Object.keys(fields).length > 0) {
+                    const parts = Object.entries(fields).map(([name, type]) => `${this.escapeId(name)} ${this.getDataTypeSql(type, name)}`);
+                    return `STRUCT(${parts.join(', ')})`;
+                }
+                return 'STRUCT()';
+            }
+            case 'MAP': {
+                // DuckDB MAP columns are written as `MAP(keyType, valueType)`.
+                const keyType = dt.keyType;
+                const valueType = dt.valueType;
+                if (keyType && valueType) {
+                    return `MAP(${this.getDataTypeSql(keyType, columnName)}, ${this.getDataTypeSql(valueType, columnName)})`;
+                }
+                return 'MAP(VARCHAR, VARCHAR)';
+            }
+            case 'UNION': {
+                // DuckDB UNION columns are written as `UNION(tag TYPE, ...)`.
+                const fields = dt.fields;
+                if (fields && Object.keys(fields).length > 0) {
+                    const parts = Object.entries(fields).map(([tag, type]) => `${this.escapeId(tag)} ${this.getDataTypeSql(type, tag)}`);
+                    return `UNION(${parts.join(', ')})`;
+                }
+                return 'VARCHAR';
+            }
+            case 'VIRTUAL':
+                return '';
+            default:
+                return 'VARCHAR';
+        }
+    }
+    // ==================== Query builders (WHERE/ORDER/LIMIT/INSERT/UPDATE/DELETE/SELECT) ====================
+    // These mirror SQLite's builder implementations closely - DuckDB shares the
+    // same `?` positional placeholder convention and a very similar SQL dialect
+    // for basic DML - but use DuckDB-correct literals (TRUE/FALSE, etc.) via
+    // `escape()`/`escapeId()` above.
+    buildWhereClause(where, _options) {
+        const values = [];
+        if (!where || (Object.keys(where).length === 0 && Object.getOwnPropertySymbols(where).length === 0)) {
+            return { sql: '', values };
+        }
+        const buildCondition = (condition) => {
+            if (!condition)
+                return { sql: '' };
+            if (typeof condition !== 'object') {
+                values.push(condition);
+                return { sql: '?' };
+            }
+            const rawCond = condition;
+            const topSymbols = Object.getOwnPropertySymbols(rawCond);
+            const normalizedCond = { ...rawCond };
+            for (const sym of topSymbols) {
+                const strKey = (0, operators_1.operatorToWhereKey)(sym);
+                if (strKey)
+                    normalizedCond[strKey] = rawCond[sym];
+            }
+            const cond = normalizedCond;
+            if (cond.$and || cond.$or || cond.$not) {
+                const conditions = [];
+                if (cond.$and) {
+                    const parts = cond.$and.map((c) => buildCondition(c).sql);
+                    conditions.push(`(${parts.join(' AND ')})`);
+                }
+                if (cond.$or) {
+                    const parts = cond.$or.map((c) => buildCondition(c).sql);
+                    conditions.push(`(${parts.join(' OR ')})`);
+                }
+                if (cond.$not) {
+                    conditions.push(`NOT (${buildCondition(cond.$not).sql})`);
+                }
+                return { sql: conditions.join(' AND ') };
+            }
+            const fieldConditions = [];
+            for (const [key, value] of Object.entries(cond)) {
+                if (key.startsWith('$'))
+                    continue;
+                if (value && typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) {
+                    const rawValueObj = value;
+                    const symbolKeys = Object.getOwnPropertySymbols(rawValueObj);
+                    const normalizedObj = { ...rawValueObj };
+                    for (const sym of symbolKeys) {
+                        const strKey = (0, operators_1.operatorToWhereKey)(sym);
+                        if (strKey)
+                            normalizedObj[strKey] = rawValueObj[sym];
+                    }
+                    const valueObj = normalizedObj;
+                    if (valueObj.$eq !== undefined) {
+                        values.push(valueObj.$eq);
+                        fieldConditions.push(`${this.escapeId(key)} = ?`);
+                    }
+                    else if (valueObj.$ne !== undefined) {
+                        values.push(valueObj.$ne);
+                        fieldConditions.push(`${this.escapeId(key)} != ?`);
+                    }
+                    else if (valueObj.$gt !== undefined) {
+                        values.push(valueObj.$gt);
+                        fieldConditions.push(`${this.escapeId(key)} > ?`);
+                    }
+                    else if (valueObj.$gte !== undefined) {
+                        values.push(valueObj.$gte);
+                        fieldConditions.push(`${this.escapeId(key)} >= ?`);
+                    }
+                    else if (valueObj.$lt !== undefined) {
+                        values.push(valueObj.$lt);
+                        fieldConditions.push(`${this.escapeId(key)} < ?`);
+                    }
+                    else if (valueObj.$lte !== undefined) {
+                        values.push(valueObj.$lte);
+                        fieldConditions.push(`${this.escapeId(key)} <= ?`);
+                    }
+                    else if (valueObj.$like !== undefined) {
+                        values.push(valueObj.$like);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE ?`);
+                    }
+                    else if (valueObj.$notLike !== undefined) {
+                        values.push(valueObj.$notLike);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE ?`);
+                    }
+                    else if (valueObj.$startsWith !== undefined) {
+                        values.push(`${valueObj.$startsWith}%`);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE ?`);
+                    }
+                    else if (valueObj.$notStartsWith !== undefined) {
+                        values.push(`${valueObj.$notStartsWith}%`);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE ?`);
+                    }
+                    else if (valueObj.$endsWith !== undefined) {
+                        values.push(`%${valueObj.$endsWith}`);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE ?`);
+                    }
+                    else if (valueObj.$notEndsWith !== undefined) {
+                        values.push(`%${valueObj.$notEndsWith}`);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE ?`);
+                    }
+                    else if (valueObj.$substring !== undefined) {
+                        values.push(`%${valueObj.$substring}%`);
+                        fieldConditions.push(`${this.escapeId(key)} LIKE ?`);
+                    }
+                    else if (valueObj.$notSubstring !== undefined) {
+                        values.push(`%${valueObj.$notSubstring}%`);
+                        fieldConditions.push(`${this.escapeId(key)} NOT LIKE ?`);
+                    }
+                    else if (valueObj.$in) {
+                        const inValues = valueObj.$in;
+                        values.push(...inValues);
+                        fieldConditions.push(`${this.escapeId(key)} IN (${inValues.map(() => '?').join(',')})`);
+                    }
+                    else if (valueObj.$notIn) {
+                        const notInValues = valueObj.$notIn;
+                        values.push(...notInValues);
+                        fieldConditions.push(`${this.escapeId(key)} NOT IN (${notInValues.map(() => '?').join(',')})`);
+                    }
+                    else if (valueObj.$between) {
+                        const between = valueObj.$between;
+                        values.push(between[0], between[1]);
+                        fieldConditions.push(`${this.escapeId(key)} BETWEEN ? AND ?`);
+                    }
+                    else if (valueObj.$notBetween) {
+                        const notBetween = valueObj.$notBetween;
+                        values.push(notBetween[0], notBetween[1]);
+                        fieldConditions.push(`${this.escapeId(key)} NOT BETWEEN ? AND ?`);
+                    }
+                    else if (valueObj.$isNull !== undefined) {
+                        fieldConditions.push(valueObj.$isNull ? `${this.escapeId(key)} IS NULL` : `${this.escapeId(key)} IS NOT NULL`);
+                    }
+                    else if (valueObj.$isNotNull !== undefined) {
+                        fieldConditions.push(valueObj.$isNotNull ? `${this.escapeId(key)} IS NOT NULL` : `${this.escapeId(key)} IS NULL`);
+                    }
+                    else if (valueObj.$col !== undefined) {
+                        fieldConditions.push(`${this.escapeId(key)} = ${this.escapeId(String(valueObj.$col))}`);
+                    }
+                    else {
+                        values.push(value);
+                        fieldConditions.push(`${this.escapeId(key)} = ?`);
+                    }
+                }
+                else {
+                    values.push(value);
+                    fieldConditions.push(`${this.escapeId(key)} = ?`);
+                }
+            }
+            return { sql: fieldConditions.join(' AND ') };
+        };
+        const result = buildCondition(where);
+        return { sql: result.sql, values };
+    }
+    buildOrderClause(order) {
+        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(', ')}` : '';
+    }
+    buildLimitOffset(limit, offset) {
+        let sql = '';
+        if (limit !== undefined) {
+            sql += ` LIMIT ${Number(limit)}`;
+            if (offset !== undefined)
+                sql += ` OFFSET ${Number(offset)}`;
+        }
+        else if (offset !== undefined) {
+            sql += ` OFFSET ${Number(offset)}`;
+        }
+        return sql;
+    }
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        if (columns.length === 0) {
+            return { sql: `INSERT INTO ${this.quoteTable(tableName, options?.schema)} DEFAULT VALUES`, values: [] };
+        }
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push('?');
+                processedValues.push(value);
+            }
+        }
+        let sql = `INSERT INTO ${this.quoteTable(tableName, options?.schema)} (${columns
+            .map((c) => this.escapeId(c))
+            .join(', ')}) VALUES (${placeholders.join(', ')})`;
+        if (options?.upsert) {
+            sql += this.buildOnConflictClause(columns, options);
+        }
+        if (options?.returning) {
+            sql +=
+                options.returning === true
+                    ? ' RETURNING *'
+                    : ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+        }
+        return { sql, values: processedValues };
+    }
+    buildOnConflictClause(insertedColumns, options) {
+        if (options.conflictTargets && options.conflictTargets.length > 0) {
+            return this.buildConflictTargetsSql(options.conflictTargets, insertedColumns);
+        }
+        if (options.doNothing) {
+            return options.conflictFields && options.conflictFields.length > 0
+                ? ` ON CONFLICT (${options.conflictFields.map((c) => this.escapeId(c)).join(', ')}) DO NOTHING`
+                : ' ON CONFLICT DO NOTHING';
+        }
+        if (!options.conflictFields || options.conflictFields.length === 0) {
+            throw new Error('DuckDB upsert requires `conflictFields` naming the PRIMARY KEY or UNIQUE columns to ' +
+                'resolve conflicts against (e.g. { conflictFields: ["id"] }), unless `doNothing` is set.');
+        }
+        const updateColumns = options.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? options.updateOnDuplicate
+            : insertedColumns;
+        const setClauses = updateColumns.map((c) => `${this.escapeId(c)} = excluded.${this.escapeId(c)}`).join(', ');
+        return ` ON CONFLICT (${options.conflictFields.map((c) => this.escapeId(c)).join(', ')}) DO UPDATE SET ${setClauses}`;
+    }
+    buildConflictTargetsSql(targets, insertedColumns) {
+        let clause = '';
+        for (const target of targets) {
+            if (!target.fields || target.fields.length === 0) {
+                throw new Error('Each entry in `conflictTargets` requires a non-empty `fields` array naming the ' +
+                    'PRIMARY KEY or UNIQUE columns to resolve conflicts against.');
+            }
+            const targetSql = `ON CONFLICT (${target.fields.map((c) => this.escapeId(c)).join(', ')})`;
+            const action = target.action || 'DO UPDATE';
+            if (action === 'DO NOTHING') {
+                clause += ` ${targetSql} DO NOTHING`;
+            }
+            else {
+                const updateColumns = target.updateColumns && target.updateColumns.length > 0 ? target.updateColumns : insertedColumns;
+                const setClauses = updateColumns.map((c) => `${this.escapeId(c)} = excluded.${this.escapeId(c)}`).join(', ');
+                clause += ` ${targetSql} DO UPDATE SET ${setClauses}`;
+                if (target.where)
+                    clause += ` WHERE ${target.where}`;
+            }
+        }
+        return clause;
+    }
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push('?');
+                processedValues.push(value);
+            }
+        }
+        let sql = `INSERT INTO ${this.quoteTable(tableName, options?.schema)} (${columns
+            .map((c) => this.escapeId(c))
+            .join(', ')}) VALUES (${placeholders.join(', ')})`;
+        if (options) {
+            sql += this.buildOnConflictClause(columns, options);
+        }
+        if (options?.returning) {
+            sql +=
+                options.returning === true
+                    ? ' RETURNING *'
+                    : ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+        }
+        return { sql, values: processedValues };
+    }
+    buildIncrementQuery(tableName, fields, where, options) {
+        const by = options?.by ?? 1;
+        const setClauses = [];
+        const queryValues = [];
+        if (typeof fields === 'string') {
+            setClauses.push(`${this.escapeId(fields)} = ${this.escapeId(fields)} + ?`);
+            queryValues.push(by);
+        }
+        else if (Array.isArray(fields)) {
+            for (const field of fields) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + ?`);
+                queryValues.push(by);
+            }
+        }
+        else {
+            for (const [field, value] of Object.entries(fields)) {
+                setClauses.push(`${this.escapeId(field)} = ${this.escapeId(field)} + ?`);
+                queryValues.push(value);
+            }
+        }
+        const whereClause = this.buildWhereClause(where);
+        queryValues.push(...whereClause.values);
+        const sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')} WHERE ${whereClause.sql}`;
+        return { sql, values: queryValues };
+    }
+    buildUpdateQuery(tableName, values, where, options) {
+        const setClauses = [];
+        const queryValues = [];
+        for (const [key, value] of Object.entries(values)) {
+            if (value instanceof prorm_1.Literal) {
+                setClauses.push(`${this.escapeId(key)} = ${value.val}`);
+            }
+            else {
+                setClauses.push(`${this.escapeId(key)} = ?`);
+                queryValues.push(value);
+            }
+        }
+        const whereClause = this.buildWhereClause(where);
+        let sql = `UPDATE ${this.escapeId(tableName)} SET ${setClauses.join(', ')}`;
+        if (whereClause.sql)
+            sql += ` WHERE ${whereClause.sql}`;
+        if (options?.returning) {
+            sql +=
+                options.returning === true
+                    ? ' RETURNING *'
+                    : ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+        }
+        return { sql, values: [...queryValues, ...whereClause.values] };
+    }
+    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?.returning) {
+            sql +=
+                options.returning === true
+                    ? ' RETURNING *'
+                    : ` RETURNING ${options.returning.map((c) => this.escapeId(c)).join(', ')}`;
+        }
+        return { sql, values: whereClause.values };
+    }
+    buildSelectQuery(options) {
+        const queryValues = [];
+        let selectSql = '*';
+        if (options.attributes) {
+            if (Array.isArray(options.attributes)) {
+                selectSql = options.attributes
+                    .map((a) => {
+                    if (Array.isArray(a)) {
+                        const [expr, alias] = a;
+                        const exprSql = typeof expr === 'string' ? this.formatMaybeExpression(expr) : String(expr);
+                        return `${exprSql} AS ${this.escapeId(alias)}`;
+                    }
+                    return typeof a === 'string' ? this.formatMaybeExpression(a) : String(a);
+                })
+                    .join(', ');
+            }
+            else if (options.attributes.include) {
+                selectSql = options.attributes.include.map((a) => this.escapeId(a)).join(', ');
+            }
+            else if (options.attributes.exclude) {
+                // DuckDB's `SELECT * EXCLUDE (...)` syntax
+                selectSql = `* EXCLUDE (${options.attributes.exclude.map((a) => this.escapeId(a)).join(', ')})`;
+            }
+        }
+        let distinctClause = '';
+        if (options.distinct) {
+            distinctClause = options.col ? `DISTINCT ${this.escapeId(options.col)} ` : 'DISTINCT ';
+        }
+        let sql = `SELECT ${distinctClause}${selectSql} FROM ${this.quoteTable(options.tableName, options.schema)}`;
+        if (options.include && options.include.length > 0) {
+            for (const include of options.include) {
+                const joinType = include.required ? 'INNER JOIN' : 'LEFT JOIN';
+                const includeSchema = include.schema || include.model?.schema;
+                const includeTableName = include.model.tableName;
+                const tableName = includeTableName ? includeTableName : include.model.toString();
+                const alias = include.as || tableName;
+                sql += ` ${joinType} ${this.quoteTable(tableName, includeSchema)} ${this.escapeId(alias)}`;
+                if (include.where) {
+                    const whereClause = this.buildWhereClause(include.where);
+                    sql += ` ON ${whereClause.sql}`;
+                    queryValues.push(...whereClause.values);
+                }
+            }
+        }
+        if (options.where) {
+            const whereClause = this.buildWhereClause(options.where);
+            if (whereClause.sql) {
+                sql += ` WHERE ${whereClause.sql}`;
+                queryValues.push(...whereClause.values);
+            }
+        }
+        if (options.group) {
+            const groupArray = Array.isArray(options.group) ? options.group : [options.group];
+            if (groupArray.length > 0) {
+                sql += ` GROUP BY ${groupArray.map((f) => (f === 'ALL' ? 'ALL' : this.escapeId(f))).join(', ')}`;
+            }
+        }
+        if (options.having) {
+            const havingClause = this.buildWhereClause(options.having);
+            if (havingClause.sql) {
+                sql += ` HAVING ${havingClause.sql}`;
+                queryValues.push(...havingClause.values);
+            }
+        }
+        if (options.order) {
+            const orderClause = this.buildOrderClause(options.order);
+            if (orderClause)
+                sql += ` ${orderClause}`;
+        }
+        sql += this.buildLimitOffset(options.limit, options.offset);
+        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 || '';
+                let unionSql = `SELECT * FROM ${this.escapeId(unionTableName)}`;
+                if (unionQuery.where) {
+                    const whereClause = this.buildWhereClause(unionQuery.where);
+                    if (whereClause.sql) {
+                        unionSql += ` WHERE ${whereClause.sql}`;
+                        queryValues.push(...whereClause.values);
+                    }
+                }
+                if (unionQuery.order) {
+                    const orderClause = this.buildOrderClause(unionQuery.order);
+                    if (orderClause)
+                        unionSql += ` ${orderClause}`;
+                }
+                if (unionQuery.limit)
+                    unionSql += ` LIMIT ${unionQuery.limit}`;
+                if (unionQuery.offset)
+                    unionSql += ` OFFSET ${unionQuery.offset}`;
+                sql += ` ${unionType} ${unionSql}`;
+            }
+        }
+        return { sql, values: queryValues };
+    }
+    /**
+     * Formats a SELECT attribute string: bare identifiers get quoted, anything
+     * that already looks like an expression (function call, `*`, operators,
+     * DuckDB's `EXCLUDE`/`REPLACE` column-transform syntax) passes through
+     * verbatim so callers can supply raw analytical SQL.
+     */
+    formatMaybeExpression(attr) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(attr)) {
+            return attr
+                .split('.')
+                .map((part) => this.escapeId(part))
+                .join('.');
+        }
+        return attr;
+    }
+    // ==================== JSON operations ====================
+    buildJsonExtract(column, path, asText = true) {
+        const columnRef = this.escapeId(column);
+        const normalizedPath = path.startsWith('$.') || path === '$' ? path : `$.${path}`;
+        const extract = `json_extract(${columnRef}, '${this.escapeStringForJsonPath(normalizedPath)}')`;
+        return asText ? `json_extract_string(${columnRef}, '${this.escapeStringForJsonPath(normalizedPath)}')` : extract;
+    }
+    escapeStringForJsonPath(path) {
+        return path.replace(/'/g, "''");
+    }
+    buildJsonQuery(column, path, value, operator = '=') {
+        const values = [];
+        const extract = this.buildJsonExtract(column, path, true);
+        if (value !== undefined) {
+            values.push(value);
+            return { sql: `${extract} ${operator} ?`, values };
+        }
+        return { sql: extract, values };
+    }
+    // ==================== DuckDB-specific value-add: file-as-table functions ====================
+    // DuckDB's signature capability: query Parquet/CSV/JSON files directly as
+    // tables via table functions usable in a FROM clause, and export query
+    // results straight back out to those formats via COPY.
+    /**
+     * Build a `read_parquet(...)` table-function expression usable in a FROM
+     * clause, e.g. `FROM ${dialect.readParquet('data/*.parquet')}`.
+     */
+    readParquet(path, options) {
+        const pathArg = Array.isArray(path)
+            ? `[${path.map((p) => `'${this.escapeString(p)}'`).join(', ')}]`
+            : `'${this.escapeString(path)}'`;
+        const namedArgs = [];
+        if (options?.hivePartitioning !== undefined)
+            namedArgs.push(`hive_partitioning=${options.hivePartitioning}`);
+        if (options?.unionByName !== undefined)
+            namedArgs.push(`union_by_name=${options.unionByName}`);
+        if (options?.filename !== undefined)
+            namedArgs.push(`filename=${options.filename}`);
+        const argsSql = namedArgs.length > 0 ? `, ${namedArgs.join(', ')}` : '';
+        return `read_parquet(${pathArg}${argsSql})`;
+    }
+    /**
+     * Build a `read_csv_auto(...)` (or `read_csv(...)` with explicit options)
+     * table-function expression usable in a FROM clause.
+     */
+    readCsv(path, options) {
+        const pathArg = Array.isArray(path)
+            ? `[${path.map((p) => `'${this.escapeString(p)}'`).join(', ')}]`
+            : `'${this.escapeString(path)}'`;
+        const namedArgs = [];
+        if (options?.header !== undefined)
+            namedArgs.push(`header=${options.header}`);
+        if (options?.delim !== undefined)
+            namedArgs.push(`delim='${this.escapeString(options.delim)}'`);
+        if (options?.allVarchar !== undefined)
+            namedArgs.push(`all_varchar=${options.allVarchar}`);
+        if (options?.columns) {
+            const cols = Object.entries(options.columns)
+                .map(([col, type]) => `'${col}': '${type}'`)
+                .join(', ');
+            namedArgs.push(`columns={${cols}}`);
+        }
+        const fnName = options?.autoDetect === false ? 'read_csv' : 'read_csv_auto';
+        const argsSql = namedArgs.length > 0 ? `, ${namedArgs.join(', ')}` : '';
+        return `${fnName}(${pathArg}${argsSql})`;
+    }
+    /**
+     * Build a `read_json_auto(...)` (or `read_json(...)` with explicit options)
+     * table-function expression usable in a FROM clause.
+     */
+    readJson(path, options) {
+        const pathArg = Array.isArray(path)
+            ? `[${path.map((p) => `'${this.escapeString(p)}'`).join(', ')}]`
+            : `'${this.escapeString(path)}'`;
+        const namedArgs = [];
+        if (options?.format)
+            namedArgs.push(`format='${options.format}'`);
+        if (options?.columns) {
+            const cols = Object.entries(options.columns)
+                .map(([col, type]) => `'${col}': '${type}'`)
+                .join(', ');
+            namedArgs.push(`columns={${cols}}`);
+        }
+        const fnName = options?.autoDetect === false ? 'read_json' : 'read_json_auto';
+        const argsSql = namedArgs.length > 0 ? `, ${namedArgs.join(', ')}` : '';
+        return `${fnName}(${pathArg}${argsSql})`;
+    }
+    /**
+     * Export the results of a query straight to a Parquet/CSV/JSON file via
+     * DuckDB's `COPY (query) TO 'file' (FORMAT ...)`.
+     */
+    async copyTo(query, path, format, options) {
+        const opts = [`FORMAT ${format}`];
+        if (options?.partitionBy && options.partitionBy.length > 0) {
+            opts.push(`PARTITION_BY (${options.partitionBy.map((c) => this.escapeId(c)).join(', ')})`);
+        }
+        if (options?.overwrite)
+            opts.push('OVERWRITE_OR_IGNORE');
+        if (options?.compression)
+            opts.push(`COMPRESSION ${options.compression.toUpperCase()}`);
+        if (format === 'CSV' && options?.header !== undefined)
+            opts.push(`HEADER ${options.header}`);
+        await this.query(`COPY (${query}) TO '${this.escapeString(path)}' (${opts.join(', ')})`);
+    }
+    // ==================== S3 / httpfs credential configuration ====================
+    // `createExtension('httpfs')` only INSTALLs/LOADs the extension - it does not
+    // configure credentials, so `read_parquet('s3://...')` etc. would still fail
+    // with a missing-credentials error against a real bucket. DuckDB supports two
+    // ways to supply S3 credentials, and both are exposed here rather than
+    // picking one:
+    //
+    //  - `SET s3_...` variables (`configureS3Credentials`): simplest, but global
+    //    to the DuckDB instance/connection - one set of credentials at a time,
+    //    with no per-query or per-bucket scoping. This is the original httpfs
+    //    mechanism and still fully supported.
+    //  - `CREATE SECRET ... (TYPE S3, ...)` (`createSecret`/`dropSecret`): the
+    //    newer, DuckDB-recommended mechanism. Secrets are named, can be scoped to
+    //    a specific path prefix (`SCOPE`), can coexist (multiple buckets/
+    //    credentials at once), and can be persisted. Prefer this for anything
+    //    beyond a single quick script.
+    //
+    // See https://duckdb.org/docs/extensions/httpfs/s3api and
+    // https://duckdb.org/docs/configuration/secrets_manager for the underlying
+    // SET variable names (`s3_region`, `s3_access_key_id`, `s3_secret_access_key`,
+    // `s3_session_token`, `s3_endpoint`, `s3_url_style`, `s3_use_ssl`) and
+    // `CREATE SECRET` grammar (`TYPE S3`, `KEY_ID`, `SECRET`, `REGION`,
+    // `SESSION_TOKEN`, `ENDPOINT`, `URL_STYLE`, `USE_SSL`, `SCOPE`) this wraps.
+    /**
+     * Configure S3 access via DuckDB httpfs `SET s3_...` session/global
+     * variables. Only emits a `SET` statement for options that are actually
+     * provided. Simpler than `createSecret()` but global to the instance (later
+     * calls overwrite earlier ones; there is no per-bucket scoping) - prefer
+     * `createSecret()` when multiple credentials/buckets are in play.
+     *
+     * Requires the `httpfs` extension to be installed/loaded first (see
+     * `createExtension('httpfs')`).
+     */
+    async configureS3Credentials(options) {
+        const statements = [];
+        if (options.region !== undefined) {
+            statements.push(`SET s3_region='${this.escapeString(options.region)}'`);
+        }
+        if (options.accessKeyId !== undefined) {
+            statements.push(`SET s3_access_key_id='${this.escapeString(options.accessKeyId)}'`);
+        }
+        if (options.secretAccessKey !== undefined) {
+            statements.push(`SET s3_secret_access_key='${this.escapeString(options.secretAccessKey)}'`);
+        }
+        if (options.sessionToken !== undefined) {
+            statements.push(`SET s3_session_token='${this.escapeString(options.sessionToken)}'`);
+        }
+        if (options.endpoint !== undefined) {
+            statements.push(`SET s3_endpoint='${this.escapeString(options.endpoint)}'`);
+        }
+        if (options.urlStyle !== undefined) {
+            statements.push(`SET s3_url_style='${this.escapeString(options.urlStyle)}'`);
+        }
+        if (options.useSsl !== undefined) {
+            statements.push(`SET s3_use_ssl=${options.useSsl ? 'true' : 'false'}`);
+        }
+        for (const sql of statements) {
+            await this.query(sql);
+        }
+    }
+    /**
+     * Create a named DuckDB Secrets Manager secret of `TYPE S3` for use with
+     * `read_parquet`/`read_csv`/`read_json`/`copyTo` against `s3://` paths.
+     * This is the newer, DuckDB-recommended alternative to
+     * `configureS3Credentials()`'s global `SET s3_...` variables: secrets are
+     * named, can be scoped to a path prefix, and multiple secrets (for
+     * different buckets/credentials) can coexist.
+     *
+     * Requires the `httpfs` extension to be installed/loaded first (see
+     * `createExtension('httpfs')`).
+     */
+    async createSecret(name, options = {}) {
+        const params = ['TYPE S3'];
+        if (options.keyId !== undefined)
+            params.push(`KEY_ID '${this.escapeString(options.keyId)}'`);
+        if (options.secret !== undefined)
+            params.push(`SECRET '${this.escapeString(options.secret)}'`);
+        if (options.region !== undefined)
+            params.push(`REGION '${this.escapeString(options.region)}'`);
+        if (options.sessionToken !== undefined) {
+            params.push(`SESSION_TOKEN '${this.escapeString(options.sessionToken)}'`);
+        }
+        if (options.endpoint !== undefined)
+            params.push(`ENDPOINT '${this.escapeString(options.endpoint)}'`);
+        if (options.urlStyle !== undefined)
+            params.push(`URL_STYLE '${this.escapeString(options.urlStyle)}'`);
+        if (options.useSsl !== undefined)
+            params.push(`USE_SSL ${options.useSsl ? 'true' : 'false'}`);
+        if (options.scope !== undefined) {
+            const scopes = Array.isArray(options.scope) ? options.scope : [options.scope];
+            params.push(`SCOPE '${scopes.map((s) => this.escapeString(s)).join(', ')}'`);
+        }
+        let sql = 'CREATE';
+        if (options.replace)
+            sql += ' OR REPLACE';
+        sql += options.persistent ? ' PERSISTENT SECRET' : ' SECRET';
+        sql += ` ${this.escapeId(name)} (${params.join(', ')})`;
+        await this.query(sql);
+    }
+    /**
+     * Drop a previously created `CREATE SECRET` (see `createSecret()`).
+     */
+    async dropSecret(name, options) {
+        let sql = 'DROP SECRET';
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(name)}`;
+        await this.query(sql);
+    }
+}
+exports.DuckDBDialect = DuckDBDialect;
+/**
+ * DuckDB-specific transaction class. DuckDB supports SAVEPOINT for nested
+ * transactions (in addition to top-level BEGIN/COMMIT/ROLLBACK).
+ */
+class DuckDBTransaction {
+    constructor(depth, options, dialect) {
+        this.dialect = dialect;
+        this.finished = false;
+        this.parent = null;
+        this.savepoints = [];
+        this.id = `${depth}_${Date.now()}_${Math.floor(Math.random() * 1e6)}`;
+        this.options = options || {};
+    }
+    async commit() {
+        if (this.finished)
+            return;
+        if (this.dialect)
+            await this.dialect.commitTransaction(this);
+        this.finished = true;
+    }
+    async rollback() {
+        if (this.finished)
+            return;
+        if (this.dialect)
+            await this.dialect.rollbackTransaction(this);
+        this.finished = true;
+    }
+}
+exports.DuckDBTransaction = DuckDBTransaction;
+/**
+ * Create a new DuckDB dialect instance.
+ */
+function createDuckDBDialect(options) {
+    return new DuckDBDialect(options || {});
+}
+exports.default = DuckDBDialect;