ts-prorm-orm 1.1.0

package/dist/dialects/clickhouse/index.js

@@ -0,0 +1,1742 @@
+"use strict";
+/**
+ * ClickHouse dialect implementation for the TypeScript ORM
+ *
+ * ClickHouse is a columnar OLAP database, not an OLTP relational database like the
+ * other dialects in this codebase. Several assumptions the rest of this ORM makes
+ * about "a SQL database" do not hold for ClickHouse, and this file tries to be
+ * explicit (in comments, thrown errors, and generated SQL) about where ClickHouse
+ * genuinely behaves differently rather than papering over the differences:
+ *
+ *  - `CREATE TABLE` requires an `ENGINE = ...` clause (e.g. `MergeTree()`), and
+ *    MergeTree-family engines require an `ORDER BY` clause - ClickHouse's sorting
+ *    key, which stands in for a traditional single-column auto-increment primary
+ *    key (there is no such concept here).
+ *  - There is no enforced FOREIGN KEY, UNIQUE, or (traditionally) PRIMARY KEY
+ *    constraint. ClickHouse will happily store duplicate "keys" - the ORDER BY
+ *    key only controls physical sort order/merges, it does not deduplicate or
+ *    enforce uniqueness unless combined with a ReplacingMergeTree engine and a
+ *    subsequent (asynchronous, background) merge/`OPTIMIZE ... FINAL`.
+ *  - There are no synchronous, transactional UPDATE/DELETE statements. ClickHouse
+ *    supports `ALTER TABLE ... UPDATE` / `ALTER TABLE ... DELETE`, but these are
+ *    asynchronous *mutations*: the statement returns as soon as the mutation is
+ *    scheduled, and the actual rewrite happens in the background (progress is
+ *    visible in `system.mutations`).
+ *  - There is no multi-statement ACID transaction support (no BEGIN/COMMIT/
+ *    ROLLBACK spanning multiple statements). A single INSERT is atomic at the
+ *    block level; nothing else is. `startTransaction`/`commitTransaction`/
+ *    `rollbackTransaction` throw a clear error rather than silently no-op-ing,
+ *    matching how this codebase signals genuinely unsupported capabilities
+ *    elsewhere (see MSSQL's partition methods, or the FDW/extension stubs on
+ *    non-PostgreSQL dialects).
+ *  - "Upsert" is not a synchronous `ON CONFLICT` / `MERGE` statement. The
+ *    idiomatic ClickHouse pattern is: insert a new row into a
+ *    ReplacingMergeTree(-family) table and let ClickHouse's background merges
+ *    asynchronously drop older rows sharing the same ORDER BY key (optionally
+ *    keeping the row with the greatest `version` column). `buildUpsertQuery()`
+ *    therefore just emits a plain INSERT and documents this loudly instead of
+ *    pretending to provide synchronous upsert semantics ClickHouse doesn't have.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickHouseDialect = void 0;
+exports.createClickHouseDialect = createClickHouseDialect;
+const client_1 = require("@clickhouse/client");
+const query_stream_helper_1 = require("../query-stream-helper");
+const prorm_1 = require("../../prorm");
+/**
+ * ClickHouse dialect class that implements the Dialect interface.
+ *
+ * Uses the official `@clickhouse/client` (Promise-native) driver, talking to
+ * ClickHouse's HTTP interface (default port 8123).
+ */
+class ClickHouseDialect {
+    constructor(config) {
+        this.name = 'clickhouse';
+        this.library = '@clickhouse/client';
+        this.client = null;
+        this._isConnected = false;
+        this.config = {
+            host: 'localhost',
+            port: 8123,
+            protocol: 'http',
+            database: 'default',
+            username: 'default',
+            engine: 'MergeTree()',
+            ...config,
+        };
+    }
+    // ==================== Connection ====================
+    async connect() {
+        try {
+            this.client = (0, client_1.createClient)({
+                url: `${this.config.protocol}://${this.config.host}:${this.config.port}`,
+                username: this.config.username,
+                password: this.config.password,
+                database: this.config.database,
+                request_timeout: this.config.requestTimeout,
+                clickhouse_settings: this.config.clickhouseSettings,
+            });
+            // Verify connectivity up front, matching the "test the connection" behavior
+            // of the pool-based dialects (pg/mysql/mariadb) in this codebase.
+            const ping = await this.client.ping();
+            if (!ping.success) {
+                throw new Error(ping.error?.message || 'ClickHouse ping failed');
+            }
+            this._isConnected = true;
+        }
+        catch (error) {
+            this._isConnected = false;
+            throw new Error(`Failed to connect to ClickHouse: ${error}`);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+            this._isConnected = false;
+        }
+    }
+    getConnection() {
+        return this.client;
+    }
+    isConnected() {
+        return this._isConnected && this.client !== null;
+    }
+    async getDatabaseVersion() {
+        const result = await this.query('SELECT version() AS version');
+        return result.rows[0]?.version || 'unknown';
+    }
+    /**
+     * 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 statement.
+     *
+     * `@clickhouse/client` exposes distinct methods for statements that return
+     * data (`query()`, used here for SELECT/SHOW/DESCRIBE/EXPLAIN) versus
+     * statements that don't (`command()`, used here for everything else - DDL,
+     * INSERT, and the ALTER TABLE ... UPDATE/DELETE mutations built below).
+     * `command()` does not return row data, so non-SELECT statements always come
+     * back with `rows: []`; in particular, `rowCount` after an
+     * `ALTER TABLE ... UPDATE/DELETE` mutation is NOT the number of rows the
+     * mutation will eventually touch - ClickHouse only reports that
+     * asynchronously via `system.mutations`.
+     */
+    async query(sql, options) {
+        if (!this.client) {
+            throw new Error('Not connected to database');
+        }
+        const replacements = options?.replacements ?? options?.bindings;
+        const finalSql = replacements !== undefined ? this.replaceReplacements(sql, replacements) : sql;
+        const trimmed = finalSql.trim();
+        const upper = trimmed.toUpperCase();
+        const isSelect = upper.startsWith('SELECT') ||
+            upper.startsWith('WITH') ||
+            upper.startsWith('SHOW') ||
+            upper.startsWith('DESCRIBE') ||
+            upper.startsWith('DESC ') ||
+            upper.startsWith('EXPLAIN') ||
+            upper.startsWith('EXISTS');
+        try {
+            if (isSelect) {
+                const resultSet = await this.client.query({ query: finalSql, format: 'JSONEachRow' });
+                const rows = await resultSet.json();
+                const fields = rows.length
+                    ? Object.keys(rows[0]).map((name) => ({
+                        name,
+                        type: 'unknown',
+                        length: 0,
+                        tableID: 0,
+                        columnID: 0,
+                        nullable: true,
+                        isEnum: false,
+                        isPrimaryKey: false,
+                    }))
+                    : [];
+                return { rows, rowCount: rows.length, fields };
+            }
+            await this.client.command({ query: finalSql });
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        catch (error) {
+            throw new Error(`ClickHouse Query error: ${error}`);
+        }
+    }
+    /**
+     * Substitute `?` (positional) or `:name` (named) placeholders with escaped
+     * literal values. ClickHouse's HTTP client sends a single opaque SQL string
+     * per request - unlike the pg/mysql2/mssql drivers used by the other
+     * dialects in this codebase, there is no native positional-parameter binding
+     * for arbitrary values and WHERE trees (ClickHouse's own `{name:Type}` query
+     * parameters require a separate `query_params` map and only support scalar
+     * substitution). So, exactly like the SQLite/PostgreSQL dialects already do
+     * when `options.replacements` is supplied to `query()`, this performs plain
+     * string substitution with escaped literals before the SQL is sent.
+     */
+    replaceReplacements(sql, replacements) {
+        if (!replacements) {
+            return sql;
+        }
+        if (Array.isArray(replacements)) {
+            let i = 0;
+            return sql.replace(/\?/g, () => this.escape(replacements[i++]));
+        }
+        let result = sql;
+        for (const [key, value] of Object.entries(replacements)) {
+            result = result.replace(new RegExp(`:${key}\\b`, 'g'), this.escape(value));
+        }
+        return result;
+    }
+    // ==================== Escaping ====================
+    escape(value) {
+        if (value instanceof prorm_1.Literal) {
+            return value.val;
+        }
+        if (value === null || value === undefined) {
+            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') {
+            // ClickHouse's Bool type accepts/renders as true/false, but 1/0 is also
+            // valid for the underlying UInt8 representation used pre-Bool-type.
+            return value ? 'true' : 'false';
+        }
+        if (value instanceof Date) {
+            return `'${this.formatDateTime(value)}'`;
+        }
+        if (Buffer.isBuffer(value)) {
+            return `'${this.escapeString(value.toString('utf8'))}'`;
+        }
+        if (Array.isArray(value)) {
+            // ClickHouse Array literal syntax: [1, 2, 3] / ['a', 'b'].
+            return `[${value.map((v) => this.escape(v)).join(', ')}]`;
+        }
+        return `'${this.escapeString(JSON.stringify(value))}'`;
+    }
+    escapeString(str) {
+        // ClickHouse string literals use backslash escaping (like MySQL), not the
+        // SQL-standard doubled-quote escaping PostgreSQL uses.
+        return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    }
+    formatDateTime(date) {
+        const pad = (n, len = 2) => String(n).padStart(len, '0');
+        const base = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+        // Preserve sub-second precision (DateTime64) rather than silently truncating
+        // it. Plain `DateTime` columns in ClickHouse don't accept a fractional
+        // part, but JS `Date` only has millisecond resolution anyway, so only emit
+        // the fraction when the value actually carries one; whole-second values
+        // stay compatible with both `DateTime` and `DateTime64`.
+        const ms = date.getMilliseconds();
+        if (ms !== 0) {
+            return `${base}.${pad(ms, 3)}`;
+        }
+        return base;
+    }
+    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);
+    }
+    // ==================== Schemas (ClickHouse "databases") ====================
+    async createSchema(schema) {
+        await this.query(`CREATE DATABASE IF NOT EXISTS ${this.escapeId(schema)}`);
+    }
+    async dropSchema(schema, options) {
+        let sql = 'DROP DATABASE';
+        if (options?.ifExists !== false)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(schema)}`;
+        await this.query(sql);
+        void options?.cascade; // ClickHouse databases always drop their contained tables; no separate CASCADE keyword.
+    }
+    async showAllSchemas() {
+        const result = await this.query('SELECT name FROM system.databases ORDER BY name');
+        return result.rows.map((row) => row.name);
+    }
+    async listSchemas() {
+        return this.showAllSchemas();
+    }
+    createDatabaseSQL(options) {
+        // ClickHouse ignores encoding/collation/template concepts entirely; only the
+        // database engine is configurable (Atomic is the modern default).
+        return `CREATE DATABASE IF NOT EXISTS ${this.quoteIdentifier(options.name)} ENGINE = Atomic`;
+    }
+    dropDatabaseSQL(name) {
+        return `DROP DATABASE IF EXISTS ${this.quoteIdentifier(name)}`;
+    }
+    // ==================== Savepoints (unsupported: no transactions) ====================
+    createSavepointSQL(_name) {
+        throw new Error('ClickHouse does not support savepoints: it has no multi-statement transactions to save a point within.');
+    }
+    releaseSavepointSQL(_name) {
+        throw new Error('ClickHouse does not support savepoints.');
+    }
+    rollbackToSavepointSQL(_name) {
+        throw new Error('ClickHouse does not support savepoints.');
+    }
+    // ==================== Extensions (PostgreSQL-only concept) ====================
+    createExtension(_extensionName, _options) {
+        throw new Error('Extensions are not supported by ClickHouse. This is a PostgreSQL-specific feature.');
+    }
+    dropExtension(_extensionName, _options) {
+        throw new Error('Extensions are not supported by ClickHouse. This is a PostgreSQL-specific feature.');
+    }
+    getExtensions() {
+        throw new Error('Extensions are not supported by ClickHouse. This is a PostgreSQL-specific feature.');
+    }
+    hasExtension(_extensionName) {
+        throw new Error('Extensions are not supported by ClickHouse. This is a PostgreSQL-specific feature.');
+    }
+    // ==================== Tables ====================
+    /**
+     * Resolve the ORDER BY (sorting key) clause for a MergeTree-family table:
+     * an explicit `orderBy` (non-standard extension read off `options` since
+     * `TableOptions` doesn't declare it), else column(s) marked `primaryKey`,
+     * else the dialect-level default, else the first declared column, else
+     * `tuple()` (ClickHouse's explicit "no sorting key" spelling).
+     */
+    resolveOrderBy(columns, options) {
+        const explicit = options?.orderBy;
+        if (explicit) {
+            return Array.isArray(explicit)
+                ? `(${explicit.map((f) => this.escapeId(f)).join(', ')})`
+                : explicit;
+        }
+        const pkFields = Object.entries(columns)
+            .filter(([, def]) => def.primaryKey)
+            .map(([name]) => name);
+        if (pkFields.length > 0) {
+            return `(${pkFields.map((f) => this.escapeId(f)).join(', ')})`;
+        }
+        if (this.config.orderBy) {
+            return Array.isArray(this.config.orderBy)
+                ? `(${this.config.orderBy.map((f) => this.escapeId(f)).join(', ')})`
+                : this.config.orderBy;
+        }
+        const firstColumn = Object.keys(columns)[0];
+        return firstColumn ? this.escapeId(firstColumn) : 'tuple()';
+    }
+    /**
+     * Build a validated `ENGINE = ...` clause for one of the MergeTree-family
+     * engines from a typed `MergeTreeEngineConfig`, checking the distinct
+     * required-column rules each engine variant has (see the doc comment on
+     * `MergeTreeEngineConfig` above) against the table's declared columns.
+     * Throws a descriptive error - rather than emitting SQL ClickHouse would
+     * reject at CREATE TABLE or (worse) silently misbehave on at merge time -
+     * when a required column is missing or the wrong type.
+     */
+    buildMergeTreeEngineClause(config, columns) {
+        const resolvedType = (columnName) => {
+            const def = columns[columnName];
+            return def ? this.getDataTypeSql(def.type) : undefined;
+        };
+        const requireColumn = (columnName, engineName, role) => {
+            if (!columns[columnName]) {
+                throw new Error(`ClickHouse ${engineName} requires a '${role}' column named '${columnName}', but no such column ` +
+                    'was declared on this table.');
+            }
+        };
+        const requireInt8 = (columnName, engineName, role) => {
+            requireColumn(columnName, engineName, role);
+            const type = resolvedType(columnName) || '';
+            if (!/^(Nullable\()?Int8\)?$/.test(type)) {
+                throw new Error(`ClickHouse ${engineName} requires its '${role}' column ('${columnName}') to be typed Int8 ` +
+                    `(ClickHouse's Sign column convention: 1 = insert, -1 = cancel), but it resolved to '${type}'.`);
+            }
+        };
+        const requireNumeric = (columnName, engineName, role) => {
+            requireColumn(columnName, engineName, role);
+            const type = resolvedType(columnName) || '';
+            if (!/^(Nullable\()?(U?Int\d+|Float(32|64)|Decimal)/.test(type)) {
+                throw new Error(`ClickHouse ${engineName} requires its '${role}' column ('${columnName}') to be a numeric type, ` +
+                    `but it resolved to '${type}'.`);
+            }
+        };
+        switch (config.type) {
+            case 'MergeTree':
+                return 'MergeTree()';
+            case 'ReplacingMergeTree': {
+                const args = [];
+                if (config.version) {
+                    requireColumn(config.version, 'ReplacingMergeTree', 'version');
+                    args.push(this.escapeId(config.version));
+                }
+                if (config.isDeleted) {
+                    if (!config.version) {
+                        throw new Error('ClickHouse ReplacingMergeTree: `isDeleted` requires `version` to also be provided ' +
+                            '(is_deleted only makes sense paired with a version column).');
+                    }
+                    requireColumn(config.isDeleted, 'ReplacingMergeTree', 'is_deleted');
+                    args.push(this.escapeId(config.isDeleted));
+                }
+                return `ReplacingMergeTree(${args.join(', ')})`;
+            }
+            case 'SummingMergeTree': {
+                if (config.columns && config.columns.length > 0) {
+                    for (const col of config.columns) {
+                        requireNumeric(col, 'SummingMergeTree', 'summed');
+                    }
+                    return `SummingMergeTree((${config.columns.map((c) => this.escapeId(c)).join(', ')}))`;
+                }
+                return 'SummingMergeTree()';
+            }
+            case 'AggregatingMergeTree': {
+                const hasAggregateColumn = Object.values(columns).some((def) => {
+                    const type = this.getDataTypeSql(def.type);
+                    return /^(Simple)?AggregateFunction\(/.test(type);
+                });
+                if (!hasAggregateColumn) {
+                    throw new Error('ClickHouse AggregatingMergeTree requires at least one AggregateFunction(...) or ' +
+                        'SimpleAggregateFunction(...) column to merge partial aggregate states into; none was found ' +
+                        'on this table. Pass a raw type string like `{ type: \'AggregateFunction(sum, UInt64)\' }` for ' +
+                        "the column(s) that hold aggregate state (this dialect's DataType abstraction has no dedicated " +
+                        'variant for it, so it must be supplied as a literal type string).');
+                }
+                return 'AggregatingMergeTree()';
+            }
+            case 'CollapsingMergeTree': {
+                requireInt8(config.sign, 'CollapsingMergeTree', 'Sign');
+                return `CollapsingMergeTree(${this.escapeId(config.sign)})`;
+            }
+            case 'VersionedCollapsingMergeTree': {
+                requireInt8(config.sign, 'VersionedCollapsingMergeTree', 'Sign');
+                requireNumeric(config.version, 'VersionedCollapsingMergeTree', 'Version');
+                return `VersionedCollapsingMergeTree(${this.escapeId(config.sign)}, ${this.escapeId(config.version)})`;
+            }
+            default: {
+                const exhaustive = config;
+                throw new Error(`ClickHouse: unknown MergeTree engine config: ${JSON.stringify(exhaustive)}`);
+            }
+        }
+    }
+    /**
+     * Build a projection body - `name (SELECT ... [GROUP BY ...] [ORDER BY ...])`
+     * - shared by the inline `PROJECTION` clause in `CREATE TABLE` and
+     * `ALTER TABLE ... ADD PROJECTION`, since both use the exact same grammar.
+     */
+    buildProjectionClause(name, def) {
+        if (!def.select) {
+            throw new Error(`ClickHouse: projection '${name}' requires a 'select' column list/expression.`);
+        }
+        let body = `SELECT ${def.select}`;
+        if (def.groupBy) {
+            body += ` GROUP BY ${Array.isArray(def.groupBy) ? def.groupBy.join(', ') : def.groupBy}`;
+        }
+        if (def.orderBy) {
+            body += ` ORDER BY ${Array.isArray(def.orderBy) ? def.orderBy.join(', ') : def.orderBy}`;
+        }
+        return `${this.escapeId(name)} (${body})`;
+    }
+    getColumnDefinitionSql(columnName, definition) {
+        let type = this.getDataTypeSql(definition.type);
+        // ClickHouse columns are NOT NULL by default (the opposite default of
+        // standard SQL); Nullable(T) must be requested explicitly, and it disables
+        // some storage optimizations, so we only add it when allowNull isn't false.
+        if (definition.allowNull !== false && !/^(Array|Nullable|LowCardinality|Map|Tuple)\(/.test(type)) {
+            type = `Nullable(${type})`;
+        }
+        let sql = `${this.escapeId(columnName)} ${type}`;
+        if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.getDefaultValue(definition.defaultValue)}`;
+        }
+        if (definition.autoIncrement) {
+            // eslint-disable-next-line no-console
+            console.warn(`ClickHouse: column '${columnName}' requested autoIncrement, but ClickHouse has no native ` +
+                `auto-increment/IDENTITY mechanism. Consider a DEFAULT of generateUUIDv4() (for UUID columns) ` +
+                `or an application-maintained counter; the option is ignored here.`);
+        }
+        if (definition.primaryKey || definition.unique || definition.references) {
+            // eslint-disable-next-line no-console
+            console.warn(`ClickHouse: column '${columnName}' has primaryKey/unique/references set, but ClickHouse does ` +
+                `not enforce PRIMARY KEY, UNIQUE, or FOREIGN KEY constraints. 'primaryKey' only feeds this ` +
+                `dialect's ORDER BY (sorting key) inference; 'unique'/'references' are ignored entirely.`);
+        }
+        if (definition.comment) {
+            sql += ` COMMENT ${this.escape(definition.comment)}`;
+        }
+        // Column-level TTL: e.g. `TTL created_at + INTERVAL 30 DAY` (optionally
+        // `... TO DISK 'cold'` / `... TO VOLUME 'cold_volume'` to tier the column
+        // to different storage rather than dropping it). Not part of the shared
+        // `ColumnDefinition` type, so read off as a loosely-typed extension the
+        // same way `orderBy`/`partitionBy` are elsewhere in this file.
+        const columnTtl = definition.ttl;
+        if (columnTtl) {
+            sql += ` TTL ${columnTtl}`;
+        }
+        return sql;
+    }
+    getDefaultValue(value) {
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'object' &&
+            value !== null &&
+            typeof value.toDefaultValue === 'function') {
+            return value.toDefaultValue();
+        }
+        if (typeof value === 'string') {
+            if (/^(now|today|generateUUIDv4)\s*\(/i.test(value) || 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.formatDateTime(value)}'`;
+        return `'${this.escapeString(String(value))}'`;
+    }
+    async createTable(tableName, columns, options) {
+        const columnDefs = Object.entries(columns).map(([name, def]) => this.getColumnDefinitionSql(name, def));
+        if (options?.constraints?.some((c) => c.type !== 'CHECK')) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: PRIMARY KEY/UNIQUE/FOREIGN KEY table constraints are not enforced and are ignored ' +
+                "(similar gotcha to Redshift). Only CHECK constraints map to real ClickHouse syntax; use ORDER BY " +
+                'and a ReplacingMergeTree engine if you need "latest row per key" semantics instead of uniqueness.');
+        }
+        if (options?.uniqueKeys) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: uniqueKeys are not enforced by ClickHouse and are ignored.');
+        }
+        for (const constraint of options?.constraints ?? []) {
+            if (constraint.type === 'CHECK' && constraint.check) {
+                columnDefs.push(`CONSTRAINT ${this.escapeId(constraint.name || `${tableName}_check`)} CHECK (${constraint.check})`);
+            }
+        }
+        // Inline `PROJECTION name (SELECT ... [GROUP BY ...] [ORDER BY ...])`
+        // clause(s), one per entry in the loosely-typed `projections` extension
+        // (like `mergeTreeEngine`/`orderBy`/`ttl` above, read off `options`
+        // since `TableOptions` doesn't declare it) keyed by projection name.
+        // Equivalent to calling `addProjection()` once per projection right after
+        // creation, but lets ClickHouse build the projection alongside the table
+        // instead of as a separate mutation against (still-empty) data.
+        const projections = options?.projections;
+        if (projections) {
+            for (const [name, def] of Object.entries(projections)) {
+                columnDefs.push(`PROJECTION ${this.buildProjectionClause(name, def)}`);
+            }
+        }
+        let sql = 'CREATE TABLE';
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.quoteTable(tableName)} (${columnDefs.join(', ')})`;
+        // ENGINE is mandatory in ClickHouse; MergeTree() is the sane general-purpose default.
+        // `mergeTreeEngine` (a typed `MergeTreeEngineConfig`) takes precedence over a raw
+        // `engine` string when supplied, since it gets validated required-column checks
+        // (e.g. CollapsingMergeTree's `Sign Int8` column) that a hand-written engine
+        // string cannot. Read off as a loosely-typed extension (like `orderBy`/`ttl`
+        // elsewhere in this file) since `TableOptions` doesn't declare it.
+        const mergeTreeEngine = options?.mergeTreeEngine;
+        const engineClause = mergeTreeEngine
+            ? this.buildMergeTreeEngineClause(mergeTreeEngine, columns)
+            : options?.engine || this.config.engine || 'MergeTree()';
+        sql += ` ENGINE = ${engineClause}`;
+        if (options?.partitionBy) {
+            sql += ` PARTITION BY ${options.partitionBy}`;
+        }
+        // ORDER BY is mandatory for MergeTree-family engines - ClickHouse's stand-in
+        // for a traditional primary key (it controls physical sort/merge order, not
+        // uniqueness).
+        sql += ` ORDER BY ${this.resolveOrderBy(columns, options)}`;
+        // Table-level TTL: ClickHouse's automatic data expiration/tiered-storage
+        // mechanism, e.g. `TTL created_at + INTERVAL 30 DAY` (rows older than the
+        // expression are dropped on the next merge) or
+        // `TTL created_at + INTERVAL 30 DAY TO VOLUME 'cold'` (moved to a
+        // different storage volume/disk instead of deleted). Read off as a
+        // loosely-typed extension (like `partitionBy`/`orderBy` above) since
+        // `TableOptions` doesn't declare it.
+        const tableTtl = options?.ttl;
+        if (tableTtl) {
+            sql += ` TTL ${tableTtl}`;
+        }
+        if (options?.comment) {
+            sql += ` COMMENT ${this.escape(options.comment)}`;
+        }
+        if (options?.rowFormat) {
+            // eslint-disable-next-line no-console
+            console.warn(`ClickHouse: rowFormat option '${options.rowFormat}' has no equivalent and is ignored.`);
+        }
+        if (options?.initialAutoIncrement) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: initialAutoIncrement has no equivalent (no auto-increment support) and is ignored.');
+        }
+        await this.query(sql);
+        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 });
+            }
+        }
+    }
+    async dropTable(tableName, options) {
+        let sql = 'DROP TABLE';
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.quoteTable(tableName)}`;
+        if (options?.cascade) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: DROP TABLE has no CASCADE keyword (there are no FK constraints to cascade); ignored.');
+        }
+        await this.query(sql);
+    }
+    // ==================== Partitions ====================
+    //
+    // ClickHouse's PARTITION BY groups rows *within a single table* by an
+    // expression (e.g. `toYYYYMM(date)`); it is not PostgreSQL-style declarative
+    // partitioning where each partition is a separate child table you create,
+    // attach, or detach independently ahead of time. Partitions come into
+    // existence automatically the first time a row with a given partition-key
+    // value is inserted.
+    async createPartitionedTable(tableName, columns, options) {
+        const partitionColumn = Array.isArray(options?.partitionBy?.column)
+            ? `(${options.partitionBy.column.map((c) => this.escapeId(c)).join(', ')})`
+            : this.escapeId(options?.partitionBy?.column);
+        await this.createTable(tableName, columns, { ...options, partitionBy: partitionColumn });
+        if (options?.partitions && options.partitions.length > 0) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: pre-declared partitions are ignored. Unlike PostgreSQL, ClickHouse partitions are ' +
+                'created automatically the first time a row with a given PARTITION BY value is inserted - there ' +
+                'is no way to declare an empty partition ahead of time.');
+        }
+    }
+    async createPartition(_options) {
+        throw new Error('ClickHouse does not support explicitly pre-creating a partition. Partitions are automatically ' +
+            'materialized based on the PARTITION BY expression of rows you INSERT; there is no equivalent of ' +
+            "PostgreSQL's CREATE TABLE ... PARTITION OF.");
+    }
+    async attachPartition(options) {
+        // Unlike detachPartition/dropPartition below, AttachPartitionOptions does
+        // carry a parentTable, so this can map onto real ClickHouse syntax.
+        const sql = `ALTER TABLE ${this.quoteTable(options.parentTable)} ATTACH PARTITION ${this.formatPartitionExpr(options.partitionName)}`;
+        await this.query(sql);
+    }
+    async detachPartition(_options) {
+        throw new Error("ClickHouse's ALTER TABLE ... DETACH PARTITION requires the table name, but this ORM's " +
+            'DetachPartitionOptions (modeled on PostgreSQL, where a partition is itself a table) only carries ' +
+            "a partition name. Call query(`ALTER TABLE <table> DETACH PARTITION <expr>`) directly instead.");
+    }
+    async dropPartition(_partitionName, _options) {
+        throw new Error("ClickHouse's ALTER TABLE ... DROP PARTITION requires the table name, but this ORM's dropPartition " +
+            "signature (modeled on PostgreSQL, where a partition is itself a droppable table) doesn't carry one. " +
+            'Call query(`ALTER TABLE <table> DROP PARTITION <expr>`) directly instead.');
+    }
+    /** Format a partition value/expression for ATTACH/DETACH/DROP PARTITION. */
+    formatPartitionExpr(partitionName) {
+        // A bare hex partition ID (as reported by system.parts.partition_id) is
+        // referenced via `PARTITION ID '...'`; anything else is treated as an
+        // already-formatted partition expression/value (e.g. "'2024-01-01'" or "(1,2)").
+        if (/^[0-9a-f]{8,}(_[0-9a-f]+)*$/i.test(partitionName)) {
+            return `ID '${this.escapeString(partitionName)}'`;
+        }
+        return partitionName;
+    }
+    // ==================== Views ====================
+    async createView(viewName, query, options) {
+        let sql = options?.replace ? 'CREATE OR REPLACE VIEW' : 'CREATE VIEW';
+        sql += ` ${this.quoteTable(viewName, options?.schema)} AS ${query}`;
+        await this.query(sql);
+    }
+    /**
+     * `CREATE MATERIALIZED VIEW ... TO <target> AS SELECT ...` - ClickHouse's
+     * real materialized-view syntax. Unlike a plain (or most other databases')
+     * view, a ClickHouse materialized view is a push-based, insert-triggered
+     * transform: every time a row is INSERTed into the underlying source
+     * table(s) referenced by `query`'s FROM clause, ClickHouse runs `query`
+     * against just the newly-inserted block and appends the result into the
+     * `to` target table - it is NOT recomputed at read time the way a normal
+     * view or a re-run query would be, and it does not "backfill" existing
+     * rows already in the source table unless `populate: true` is given.
+     *
+     * `showViews()` already queries `system.tables` for `engine =
+     * 'MaterializedView'`, so this is the corresponding write-side method that
+     * was previously entirely missing (only plain, non-materialized
+     * `CREATE VIEW` existed via `createView()` above).
+     *
+     * Two real ClickHouse forms are supported:
+     *   - `{ to: 'target_table' }`: the common, recommended form - the target
+     *     table is created separately (with its own ENGINE/ORDER BY, e.g. an
+     *     AggregatingMergeTree for rollups) and the materialized view just
+     *     describes the transform feeding it.
+     *   - Omitting `to` (with an inline `engine`/`orderBy0`): ClickHouse also
+     *     allows a materialized view to own an implicit hidden target table
+     *     (`CREATE MATERIALIZED VIEW ... ENGINE = ... AS SELECT ...`); provide
+     *     `engine`/`orderBy` in that case instead of `to`.
+     */
+    async createMaterializedView(viewName, query, options) {
+        if (!options?.to && !options?.engine) {
+            throw new Error('ClickHouse createMaterializedView(): either `to` (a target table to write into) or `engine` ' +
+                '(so the materialized view can own an implicit hidden target table) must be provided.');
+        }
+        let sql = options?.replace ? 'CREATE OR REPLACE MATERIALIZED VIEW' : 'CREATE MATERIALIZED VIEW';
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.quoteTable(viewName, options?.schema)}`;
+        if (options?.to) {
+            sql += ` TO ${this.quoteTable(options.to, options.schema)}`;
+        }
+        else {
+            sql += ` ENGINE = ${options?.engine}`;
+            if (options?.orderBy) {
+                const orderBy = Array.isArray(options.orderBy)
+                    ? `(${options.orderBy.map((f) => this.escapeId(f)).join(', ')})`
+                    : options.orderBy;
+                sql += ` ORDER BY ${orderBy}`;
+            }
+        }
+        // POPULATE backfills existing source-table rows into the target at
+        // creation time; without it, the view only sees rows inserted AFTER
+        // creation. ClickHouse's own docs warn POPULATE races with concurrent
+        // inserts (rows written during the backfill may be double-counted or
+        // missed), so this is opt-in, not the default.
+        if (options?.populate) {
+            sql += ' POPULATE';
+        }
+        sql += ` AS ${query}`;
+        await this.query(sql);
+    }
+    async dropView(viewName, options) {
+        let sql = 'DROP VIEW';
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.quoteTable(viewName)}`;
+        await this.query(sql);
+        void options?.cascade; // no dependent-object cascading concept for views in ClickHouse
+    }
+    async showViews() {
+        const result = await this.query(`SELECT name FROM system.tables WHERE database = currentDatabase() AND engine IN ('View', 'MaterializedView') ORDER BY name`);
+        return result.rows.map((row) => row.name);
+    }
+    async showTables() {
+        const result = await this.query(`SELECT name FROM system.tables WHERE database = currentDatabase() AND engine NOT IN ('View', 'MaterializedView') ORDER BY name`);
+        return result.rows.map((row) => row.name);
+    }
+    // ==================== Columns ====================
+    async addColumn(tableName, columnName, definition) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD COLUMN ${this.getColumnDefinitionSql(columnName, definition)}`);
+    }
+    async removeColumn(tableName, columnName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP COLUMN ${this.escapeId(columnName)}`);
+    }
+    async changeColumn(tableName, columnName, definition) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} MODIFY COLUMN ${this.getColumnDefinitionSql(columnName, definition)}`);
+    }
+    async renameColumn(tableName, oldColumnName, newColumnName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`);
+    }
+    async addForeignKey(_tableName, _columnName, _referencedTableName, _referencedColumnName, _options) {
+        throw new Error('ClickHouse does not support FOREIGN KEY constraints (similar gotcha to Redshift). Referential ' +
+            'integrity, if needed, must be enforced by the application.');
+    }
+    // ==================== Bulk insert ====================
+    async bulkInsert(tableName, records, _options) {
+        if (records.length === 0) {
+            return { rows: [], rowCount: 0, fields: [] };
+        }
+        if (!this.client) {
+            throw new Error('Not connected to database');
+        }
+        // Use the driver's native `insert()` (JSONEachRow streaming) instead of
+        // building one giant literal-escaped `INSERT ... VALUES (...), (...)` SQL
+        // string. The hand-built-SQL approach risks exceeding ClickHouse's max
+        // query size (and holding the whole batch as one string in memory) for
+        // large batches, and duplicates format handling the client already does
+        // correctly (chunked/streamed encoding).
+        const columns = Object.keys(records[0]);
+        const values = records.map((record) => {
+            const row = {};
+            for (const column of columns) {
+                const value = record[column];
+                if (value instanceof prorm_1.Literal) {
+                    row[column] = value.val;
+                }
+                else if (value instanceof Date) {
+                    // JSONEachRow expects ClickHouse's own `YYYY-MM-DD HH:MM:SS[.fff]`
+                    // wire format for DateTime/DateTime64, not JS's default ISO-8601
+                    // (with a `T`/`Z`) that `JSON.stringify` would otherwise produce.
+                    row[column] = this.formatDateTime(value);
+                }
+                else {
+                    row[column] = value;
+                }
+            }
+            return row;
+        });
+        try {
+            await this.client.insert({
+                table: this.quoteTable(tableName),
+                values,
+                format: 'JSONEachRow',
+            });
+        }
+        catch (error) {
+            throw new Error(`ClickHouse Query error: ${error}`);
+        }
+        return { rows: [], rowCount: records.length, fields: [] };
+    }
+    // ==================== Constraints ====================
+    //
+    // ClickHouse only supports CHECK constraints (validated on INSERT only, not
+    // retroactively on existing data). PRIMARY KEY/UNIQUE/FOREIGN KEY constraints
+    // don't exist and are rejected here rather than silently accepted and ignored,
+    // since - unlike optional table/column decorations - callers relying on these
+    // for integrity need to find out immediately.
+    async showConstraints(_tableName) {
+        // No dedicated, version-stable system table exposes CHECK constraints, and
+        // there are no PK/FK/UNIQUE constraints to report.
+        return [];
+    }
+    async addConstraint(tableName, options) {
+        if (options.type !== 'CHECK') {
+            throw new Error(`ClickHouse does not enforce ${options.type} constraints (no traditional PK/UNIQUE/FK support).`);
+        }
+        const name = options.name || `${tableName}_check`;
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD CONSTRAINT ${this.escapeId(name)} CHECK (${options.check})`);
+    }
+    async removeConstraint(tableName, constraintName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP CONSTRAINT ${this.escapeId(constraintName)}`);
+    }
+    async createConstraint(tableName, constraintDef) {
+        if (constraintDef.type !== 'CHECK') {
+            throw new Error(`ClickHouse does not enforce ${constraintDef.type} constraints (no traditional PK/UNIQUE/FK support).`);
+        }
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD CONSTRAINT ${this.escapeId(constraintDef.name)} CHECK (${constraintDef.check})`);
+    }
+    async dropConstraint(tableName, constraintName, _options) {
+        await this.removeConstraint(tableName, constraintName);
+    }
+    // ==================== Indexes ====================
+    //
+    // ClickHouse's `ADD INDEX` creates a lightweight "data skipping index" (e.g.
+    // minmax/set/bloom_filter), which lets scans skip whole granules that can't
+    // match a predicate. This is NOT a traditional B-Tree index that guarantees
+    // O(log n) point lookups the way a PostgreSQL/MySQL index does.
+    async showIndexes(tableName) {
+        const result = await this.query(`SELECT name, type, expr, granularity FROM system.data_skipping_indices WHERE table = ${this.escape(tableName)} AND database = currentDatabase()`);
+        return result.rows;
+    }
+    async addIndex(tableName, indexName, fields = [], options) {
+        const expr = options?.expression || (fields.length > 1 ? `(${fields.map((f) => this.escapeId(f)).join(', ')})` : this.escapeId(fields[0]));
+        const type = options?.type || 'minmax';
+        const granularity = 1;
+        let sql = 'ALTER TABLE';
+        sql += ` ${this.quoteTable(tableName)} ADD INDEX`;
+        if (options?.ifNotExists)
+            sql += ' IF NOT EXISTS';
+        sql += ` ${this.escapeId(indexName)} ${expr} TYPE ${type} GRANULARITY ${granularity}`;
+        await this.query(sql);
+    }
+    async removeIndex(tableName, indexName) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} DROP INDEX ${this.escapeId(indexName)}`);
+    }
+    async createIndex(tableName, indexDef) {
+        await this.addIndex(tableName, indexDef.name, indexDef.fields, {
+            type: indexDef.type,
+            using: indexDef.using,
+        });
+    }
+    async dropIndex(tableName, indexName, options) {
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} DROP INDEX`;
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(indexName)}`;
+        await this.query(sql);
+    }
+    // ==================== Projections ====================
+    //
+    // A MergeTree-family "projection" is an alternate, ClickHouse-maintained
+    // physical layout of (a subset of) a table's columns - its own sort order
+    // and, optionally, its own pre-aggregation - kept in sync automatically on
+    // every INSERT/merge. ClickHouse's query planner transparently substitutes
+    // a matching projection in place of the base table when doing so answers a
+    // query more cheaply, without the caller having to name it in the query.
+    // This is not part of the shared `Dialect` interface - other dialects have
+    // no equivalent concept - so `addProjection`/`dropProjection` are exposed
+    // as ClickHouse-specific extra public methods, the same way `uniq()`/
+    // `quantile()`/etc. are below.
+    /**
+     * `ALTER TABLE table ADD PROJECTION name (SELECT ... [GROUP BY ...] [ORDER BY ...])`.
+     *
+     * Adding a projection only registers its definition; ClickHouse does not
+     * retroactively backfill it for existing parts. Call
+     * `materializeProjection()` (`ALTER TABLE ... MATERIALIZE PROJECTION`)
+     * afterwards to build it for data that already exists - new
+     * inserts/merges are kept in sync automatically from this point on
+     * either way.
+     */
+    async addProjection(tableName, projectionName, definition) {
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD PROJECTION ${this.buildProjectionClause(projectionName, definition)}`);
+    }
+    /**
+     * `ALTER TABLE table DROP PROJECTION [IF EXISTS] name`.
+     *
+     * Implemented as a mutation: removes the projection's definition from the
+     * table's metadata and deletes its files from disk.
+     */
+    async dropProjection(tableName, projectionName, options) {
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} DROP PROJECTION`;
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(projectionName)}`;
+        await this.query(sql);
+    }
+    /**
+     * `ALTER TABLE table MATERIALIZE PROJECTION [IF EXISTS] name [IN PARTITION partition]`.
+     *
+     * Builds (or rebuilds) a projection for existing data. Needed after
+     * `addProjection()` on a table that already has rows - a freshly-added
+     * projection definition otherwise only applies to data inserted/merged
+     * after it was added.
+     */
+    async materializeProjection(tableName, projectionName, options) {
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} MATERIALIZE PROJECTION`;
+        if (options?.ifExists)
+            sql += ' IF EXISTS';
+        sql += ` ${this.escapeId(projectionName)}`;
+        if (options?.partition)
+            sql += ` IN PARTITION ${options.partition}`;
+        await this.query(sql);
+    }
+    async createFulltextIndex(tableName, indexName, fields, _options) {
+        // ClickHouse's closest equivalent is the experimental `inverted`/`ngrambf_v1`
+        // data-skipping index type, not a real full-text index engine.
+        const expr = fields.length > 1 ? `(${fields.map((f) => this.escapeId(f)).join(', ')})` : this.escapeId(fields[0]);
+        await this.query(`ALTER TABLE ${this.quoteTable(tableName)} ADD INDEX ${this.escapeId(indexName)} ${expr} TYPE inverted GRANULARITY 1`);
+    }
+    async createSpatialIndex(_tableName, _indexName, _fields, _options) {
+        throw new Error('ClickHouse has geo functions (pointInPolygon, geoDistance, etc.) but no dedicated spatial index type.');
+    }
+    // ==================== Describe / rename ====================
+    async describeTable(tableName) {
+        const result = await this.query(`DESCRIBE TABLE ${this.quoteTable(tableName)}`);
+        const description = {};
+        for (const row of result.rows) {
+            const r = row;
+            const isNullable = /^Nullable\(/.test(r.type || '');
+            description[r.name] = {
+                type: r.type,
+                allowNull: isNullable,
+                defaultValue: r.default_expression || null,
+                primaryKey: false,
+                autoIncrement: false,
+            };
+        }
+        const sortingKeyResult = await this.query(`SELECT sorting_key FROM system.tables WHERE database = currentDatabase() AND name = ${this.escape(tableName)}`);
+        const sortingKey = sortingKeyResult.rows[0]?.sorting_key || '';
+        for (const column of sortingKey.split(',').map((c) => c.trim())) {
+            if (description[column]) {
+                description[column].primaryKey = true;
+            }
+        }
+        return description;
+    }
+    async renameTable(oldName, newName) {
+        await this.query(`RENAME TABLE ${this.quoteTable(oldName)} TO ${this.quoteTable(newName)}`);
+    }
+    async changeOwner(_newOwner, _tableName) {
+        throw new Error('ClickHouse has no per-table ownership model to change (access is role/user-grant based).');
+    }
+    // ==================== Row policies (ClickHouse's real RLS feature) ====================
+    async createSecurityPolicy(policyName, tableName, options) {
+        const predicate = options?.predicate || '1';
+        await this.query(`CREATE ROW POLICY IF NOT EXISTS ${this.escapeId(policyName)} ON ${this.quoteTable(tableName)} USING ${predicate} TO ALL`);
+    }
+    async dropSecurityPolicy(policyName, tableName) {
+        await this.query(`DROP ROW POLICY IF EXISTS ${this.escapeId(policyName)} ON ${this.quoteTable(tableName)}`);
+    }
+    // ==================== Transactions (unsupported) ====================
+    //
+    // ClickHouse has no multi-statement, cross-request ACID transactions: no
+    // BEGIN/COMMIT/ROLLBACK spanning more than one statement. A single INSERT is
+    // atomic at the block level, and that's the extent of it. Rather than
+    // silently no-op-ing (which would let application code believe a rollback
+    // undid earlier statements when nothing of the sort happened), these throw -
+    // matching this codebase's convention for a genuinely unsupported capability
+    // (e.g. MSSQL's partition methods, or FDW/extension stubs on non-PostgreSQL
+    // dialects).
+    async startTransaction(_options) {
+        throw new Error('ClickHouse does not support multi-statement transactions (no BEGIN/COMMIT/ROLLBACK spanning ' +
+            'multiple statements). Only a single INSERT is atomic (at the block level). Do not rely on ' +
+            'startTransaction()/commitTransaction()/rollbackTransaction() with this dialect.');
+    }
+    async commitTransaction(_transaction) {
+        throw new Error('ClickHouse does not support transactions; there is nothing to commit.');
+    }
+    async rollbackTransaction(_transaction) {
+        throw new Error('ClickHouse does not support transactions; there is nothing to roll back.');
+    }
+    // ==================== Data types ====================
+    getDataTypeSql(dataType) {
+        if (typeof dataType === 'string')
+            return dataType;
+        if (!dataType || typeof dataType !== 'object')
+            return 'String';
+        const dt = dataType;
+        switch (dt.key) {
+            case 'STRING':
+            case 'CHAR':
+            case 'TEXT':
+                return 'String';
+            case 'INTEGER':
+                return dt.unsigned ? 'UInt32' : 'Int32';
+            case 'BIGINT':
+                return dt.unsigned ? 'UInt64' : 'Int64';
+            case 'FLOAT':
+                return 'Float32';
+            case 'DOUBLE':
+                return 'Float64';
+            case 'DECIMAL':
+                return `Decimal(${dt.precision || 10}, ${dt.scale || 0})`;
+            case 'BOOLEAN':
+                return 'Bool';
+            case 'DATE':
+                return dt.precision ? `DateTime64(${dt.precision})` : 'DateTime';
+            case 'DATEONLY':
+                return 'Date';
+            case 'TIME':
+                // ClickHouse has no dedicated TIME type.
+                return 'String';
+            case 'BLOB':
+                return 'String';
+            case 'ENUM': {
+                const values = dt.values || [];
+                // ClickHouse `Enum8` is backed by Int8 and can only represent up to
+                // 127 distinct values; `Enum16` (Int16-backed) supports up to 32767.
+                // Emitting `Enum8` unconditionally silently overflows/fails for larger
+                // enum sets, so pick the right width based on the number of values.
+                const enumType = values.length > 127 ? 'Enum16' : 'Enum8';
+                return `${enumType}(${values.map((v, i) => `'${this.escapeString(v)}' = ${i + 1}`).join(', ')})`;
+            }
+            case 'JSON':
+            case 'JSONB':
+                // The native `JSON` column type is still experimental across ClickHouse
+                // versions; `String` (storing serialized JSON, queried with JSON*
+                // functions) is the safe, version-stable default.
+                return 'String';
+            case 'UUID':
+                return 'UUID';
+            case 'INET':
+                // `DataTypes.INET` defaults to IPv4 (matching the previous
+                // unconditional mapping below) but ClickHouse has a genuinely
+                // distinct fixed-width `IPv6` column type; `DataTypes.INET({ version: 6 })`
+                // / `DataTypes.INET6` opts into it.
+                return dt.version === 6 ? 'IPv6' : 'IPv4';
+            case 'CIDR':
+            case 'MACADDR':
+            case 'HSTORE':
+            case 'RANGE':
+            case 'GEOMETRY':
+                return 'String';
+            case 'ARRAY': {
+                const elementType = dt.type || dt.subtype;
+                return elementType ? `Array(${this.getDataTypeSql(elementType)})` : 'Array(String)';
+            }
+            case 'VIRTUAL':
+                return '';
+            default:
+                return 'String';
+        }
+    }
+    // ==================== Approximate aggregate function helpers ====================
+    //
+    // ClickHouse's approximate/probabilistic aggregate functions - cardinality
+    // estimation (`uniq*`) and percentile estimation (`quantile*`) at scale -
+    // are central to its analytics use case. Nothing in this dialect (or any
+    // other dialect in this codebase) previously surfaced them as first-class,
+    // typed helpers; callers had to know the exact ClickHouse function name and
+    // hand-write it into a raw `attributes`/`group` string. These return a
+    // `Literal` (this ORM's existing "raw SQL fragment" escape hatch, see
+    // `prorm.ts`) with the column/level correctly identifier-escaped, so
+    // the result can be dropped directly into `attributes`, e.g.
+    // `attributes: [dialect.uniqCombined('user_id', 'unique_users')]`.
+    /**
+     * `uniq(column)` - ClickHouse's default approximate distinct-count
+     * (adaptive sampling, small constant memory, ~1-2% error). The fastest and
+     * least memory-hungry of the `uniq*` family; prefer this unless you need
+     * `uniqExact`'s precision or `uniqCombined`'s tunable accuracy/memory
+     * trade-off.
+     */
+    uniq(column, alias) {
+        return new prorm_1.Literal(`uniq(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `uniqCombined([precision])(column)` - approximate distinct count that
+     * blends an array, a hash table, and HyperLogLog depending on cardinality,
+     * giving better accuracy-per-byte than plain `uniq` at the cost of a bit
+     * more CPU. `precision` (`HLL_precision`, default 17) trades memory for
+     * accuracy: higher precision = more memory, lower error.
+     */
+    uniqCombined(column, alias, precision) {
+        const fn = precision !== undefined ? `uniqCombined(${precision})` : 'uniqCombined';
+        return new prorm_1.Literal(`${fn}(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /** `uniqHLL12(column)` - classic HyperLogLog-based approximate distinct count. */
+    uniqHLL12(column, alias) {
+        return new prorm_1.Literal(`uniqHLL12(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `uniqExact(column)` - EXACT distinct count (not approximate - despite
+     * living in the `uniq*` family). Included here for symmetry/discoverability
+     * since callers reaching for `uniq*` helpers need an easy way to opt into
+     * exactness when cardinality is low enough that the memory/CPU cost is
+     * acceptable.
+     */
+    uniqExact(column, alias) {
+        return new prorm_1.Literal(`uniqExact(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `quantile(level)(column)` - approximate percentile/quantile estimation
+     * (reservoir sampling) - e.g. `quantile(0.99)(latency_ms)` for p99 latency.
+     * `level` must be in `[0, 1]`.
+     */
+    quantile(level, column, alias) {
+        this.assertQuantileLevel(level);
+        return new prorm_1.Literal(`quantile(${level})(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `quantiles(level1, level2, ...)(column)` - like `quantile()`, but computes
+     * several quantiles in one pass (e.g. p50/p90/p99 together is cheaper than
+     * three separate `quantile()` calls since ClickHouse shares the sample).
+     * Returns an Array(Float64) column.
+     */
+    quantiles(levels, column, alias) {
+        if (!levels || levels.length === 0) {
+            throw new Error('ClickHouse quantiles(): at least one quantile level must be provided.');
+        }
+        levels.forEach((l) => this.assertQuantileLevel(l));
+        return new prorm_1.Literal(`quantiles(${levels.join(', ')})(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `quantileExact(level)(column)` - EXACT quantile (loads all values into
+     * memory; use for small-to-medium datasets where precision matters more
+     * than the approximate functions' bounded memory usage).
+     */
+    quantileExact(level, column, alias) {
+        this.assertQuantileLevel(level);
+        return new prorm_1.Literal(`quantileExact(${level})(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    /**
+     * `quantileTDigest(level)(column)` - approximate quantile via the t-digest
+     * algorithm: lower memory than `quantileExact`, better accuracy at extreme
+     * percentiles (e.g. p99.9) than the default reservoir-sampling `quantile()`.
+     */
+    quantileTDigest(level, column, alias) {
+        this.assertQuantileLevel(level);
+        return new prorm_1.Literal(`quantileTDigest(${level})(${this.escapeId(column)})${alias ? ` AS ${this.escapeId(alias)}` : ''}`);
+    }
+    assertQuantileLevel(level) {
+        if (typeof level !== 'number' || Number.isNaN(level) || level < 0 || level > 1) {
+            throw new Error(`ClickHouse quantile level must be a number in [0, 1], got ${level}.`);
+        }
+    }
+    // ==================== Query builders ====================
+    //
+    // buildWhereClause/buildOrderClause/buildInsertQuery/buildUpdateQuery/
+    // buildDeleteQuery/buildSelectQuery/buildUpsertQuery/buildIncrementQuery all
+    // embed escaped literal values directly into the returned `sql` string
+    // rather than returning `?`/`$N`-style placeholders (see the comment on
+    // replaceReplacements() above for why: the ClickHouse HTTP client has no
+    // native positional-parameter binding for arbitrary values). Each returned
+    // `sql` is therefore directly executable via `query(sql)`; the returned
+    // `values` arrays are kept empty for shape-parity with the Dialect interface.
+    buildWhereClause(where, _options) {
+        if (!where || Object.keys(where).length === 0) {
+            return { sql: '', values: [] };
+        }
+        const buildCondition = (condition) => {
+            if (!condition)
+                return '';
+            if (typeof condition !== 'object')
+                return this.escape(condition);
+            const cond = condition;
+            if (cond.$and || cond.$or || cond.$not) {
+                const parts = [];
+                if (cond.$and) {
+                    parts.push(`(${cond.$and.map(buildCondition).join(' AND ')})`);
+                }
+                if (cond.$or) {
+                    parts.push(`(${cond.$or.map(buildCondition).join(' OR ')})`);
+                }
+                if (cond.$not) {
+                    parts.push(`NOT (${buildCondition(cond.$not)})`);
+                }
+                return parts.join(' AND ');
+            }
+            const fieldConditions = [];
+            for (const [key, value] of Object.entries(cond)) {
+                if (key.startsWith('$'))
+                    continue;
+                const col = this.escapeId(key);
+                if (value && typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) {
+                    const v = value;
+                    if (v.$eq !== undefined)
+                        fieldConditions.push(`${col} = ${this.escape(v.$eq)}`);
+                    else if (v.$ne !== undefined)
+                        fieldConditions.push(`${col} != ${this.escape(v.$ne)}`);
+                    else if (v.$gt !== undefined)
+                        fieldConditions.push(`${col} > ${this.escape(v.$gt)}`);
+                    else if (v.$gte !== undefined)
+                        fieldConditions.push(`${col} >= ${this.escape(v.$gte)}`);
+                    else if (v.$lt !== undefined)
+                        fieldConditions.push(`${col} < ${this.escape(v.$lt)}`);
+                    else if (v.$lte !== undefined)
+                        fieldConditions.push(`${col} <= ${this.escape(v.$lte)}`);
+                    else if (v.$like !== undefined)
+                        fieldConditions.push(`${col} LIKE ${this.escape(v.$like)}`);
+                    else if (v.$notLike !== undefined)
+                        fieldConditions.push(`${col} NOT LIKE ${this.escape(v.$notLike)}`);
+                    else if (v.$startsWith !== undefined)
+                        fieldConditions.push(`${col} LIKE ${this.escape(`${v.$startsWith}%`)}`);
+                    else if (v.$endsWith !== undefined)
+                        fieldConditions.push(`${col} LIKE ${this.escape(`%${v.$endsWith}`)}`);
+                    else if (v.$substring !== undefined)
+                        fieldConditions.push(`${col} LIKE ${this.escape(`%${v.$substring}%`)}`);
+                    else if (v.$in) {
+                        const vals = v.$in.map((x) => this.escape(x)).join(', ');
+                        fieldConditions.push(`${col} IN (${vals})`);
+                    }
+                    else if (v.$notIn) {
+                        const vals = v.$notIn.map((x) => this.escape(x)).join(', ');
+                        fieldConditions.push(`${col} NOT IN (${vals})`);
+                    }
+                    else if (v.$between) {
+                        const [a, b] = v.$between;
+                        fieldConditions.push(`${col} BETWEEN ${this.escape(a)} AND ${this.escape(b)}`);
+                    }
+                    else if (v.$notBetween) {
+                        const [a, b] = v.$notBetween;
+                        fieldConditions.push(`${col} NOT BETWEEN ${this.escape(a)} AND ${this.escape(b)}`);
+                    }
+                    else if (v.$isNull !== undefined) {
+                        fieldConditions.push(v.$isNull ? `${col} IS NULL` : `${col} IS NOT NULL`);
+                    }
+                    else {
+                        fieldConditions.push(`${col} = ${this.escape(value)}`);
+                    }
+                }
+                else if (value === null) {
+                    fieldConditions.push(`${col} IS NULL`);
+                }
+                else if (Array.isArray(value)) {
+                    fieldConditions.push(`${col} IN (${value.map((v) => this.escape(v)).join(', ')})`);
+                }
+                else {
+                    fieldConditions.push(`${col} = ${this.escape(value)}`);
+                }
+            }
+            return fieldConditions.join(' AND ');
+        };
+        return { sql: buildCondition(where), values: [] };
+    }
+    buildOrderClause(order, _options) {
+        if (!order || (Array.isArray(order) && order.length === 0))
+            return '';
+        const parts = [];
+        const processItem = (item) => {
+            if (typeof item === 'string') {
+                const [field, dir] = item.split(' ');
+                parts.push(dir ? `${this.escapeId(field)} ${dir.toUpperCase()}` : this.escapeId(field));
+            }
+            else if (Array.isArray(item)) {
+                const [field, dir] = item;
+                parts.push(dir ? `${this.escapeId(field)} ${dir.toUpperCase()}` : this.escapeId(field));
+            }
+            else if (item && typeof item === 'object') {
+                for (const [key, value] of Object.entries(item)) {
+                    parts.push(`${this.escapeId(key)} ${String(value).toUpperCase()}`);
+                }
+            }
+        };
+        if (Array.isArray(order))
+            order.forEach(processItem);
+        else
+            processItem(order);
+        return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : '';
+    }
+    buildLimitOffset(limit, offset) {
+        let sql = '';
+        if (limit !== undefined)
+            sql += ` LIMIT ${Number(limit)}`;
+        if (offset !== undefined)
+            sql += ` OFFSET ${Number(offset)}`;
+        return sql;
+    }
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const rendered = columns.map((c) => {
+            const v = values[c];
+            return v instanceof prorm_1.Literal ? v.val : this.escape(v);
+        });
+        let sql = `INSERT INTO ${this.quoteTable(tableName, options?.schema)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${rendered.join(', ')})`;
+        if (options?.returning) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: INSERT has no RETURNING clause; the `returning` option is ignored.');
+        }
+        if (options?.upsert) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: INSERT has no ON CONFLICT/ON DUPLICATE KEY UPDATE clause. Emitting a plain INSERT; ' +
+                'use buildUpsertQuery()/a ReplacingMergeTree engine for "last write wins" semantics instead.');
+        }
+        return { sql, values: [] };
+    }
+    /**
+     * ClickHouse has no synchronous UPSERT / `ON CONFLICT` / `MERGE` statement.
+     * The idiomatic ClickHouse pattern is: insert a new row into a
+     * ReplacingMergeTree(-family) table and let ClickHouse's background merges
+     * asynchronously drop older rows sharing the same ORDER BY key (optionally
+     * keeping the row with the greatest `version` column, if the engine and
+     * table were set up with one). Until that merge runs, duplicate rows for
+     * the same key coexist, and reads must use `SELECT ... FINAL` (or the table
+     * must be `OPTIMIZE ... FINAL`-ed) to see "the latest" value.
+     *
+     * This method therefore only ever builds a plain INSERT - `conflictFields`/
+     * `updateOnDuplicate` are accepted (to satisfy the shared Dialect signature)
+     * but silently have no effect, and that is called out loudly below rather
+     * than pretending this performs a real, synchronous upsert.
+     *
+     * IMPORTANT: pass `{ final: true }` to `buildSelectQuery()` on subsequent
+     * reads of this table (`SELECT ... FROM <table> FINAL`) to force ClickHouse
+     * to apply ReplacingMergeTree's merge-time dedup logic at query time -
+     * otherwise a plain SELECT can return duplicate/stale rows for the same
+     * ORDER BY key until a background merge happens. See the doc comment on
+     * `buildSelectQuery()`'s `final` handling for why this is opt-in rather
+     * than automatic.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        // eslint-disable-next-line no-console
+        console.warn('ClickHouse buildUpsertQuery(): emitting a plain INSERT. ClickHouse has no ON CONFLICT/MERGE ' +
+            "statement; conflictFields/updateOnDuplicate are ignored. Use a ReplacingMergeTree table and query " +
+            'with FINAL (or run OPTIMIZE TABLE ... FINAL) to actually deduplicate by the ORDER BY key.');
+        return this.buildInsertQuery(tableName, values, { schema: options?.schema, returning: options?.returning });
+    }
+    /**
+     * `ALTER TABLE ... UPDATE` is an asynchronous ClickHouse *mutation*, not a
+     * synchronous, transactional UPDATE. The statement returns as soon as the
+     * mutation is scheduled; ClickHouse rewrites the affected data parts in the
+     * background (progress/completion is visible via `system.mutations`), so
+     * `query()`'s `rowCount` for this statement is always 0 - it reflects "rows
+     * returned by this HTTP request", not "rows the mutation will touch".
+     */
+    buildUpdateQuery(tableName, values, where, options) {
+        const setClauses = Object.entries(values).map(([key, value]) => `${this.escapeId(key)} = ${value instanceof prorm_1.Literal ? value.val : this.escape(value)}`);
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} UPDATE ${setClauses.join(', ')}`;
+        const whereClause = this.buildWhereClause(where);
+        if (whereClause.sql)
+            sql += ` WHERE ${whereClause.sql}`;
+        if (options?.limit) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: ALTER TABLE ... UPDATE has no LIMIT clause; the `limit` option is ignored.');
+        }
+        if (options?.returning) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: ALTER TABLE ... UPDATE has no RETURNING clause; the `returning` option is ignored.');
+        }
+        return { sql, values: [] };
+    }
+    /**
+     * `ALTER TABLE ... DELETE` is likewise an asynchronous mutation (see
+     * buildUpdateQuery's doc comment above) - not a synchronous, transactional
+     * DELETE. ClickHouse also offers a syntactically lighter `DELETE FROM ...
+     * WHERE ...` ("lightweight delete", available since v23.3) which marks rows
+     * deleted immediately for query purposes while physically removing them in
+     * the background; this builder intentionally uses the classic, more widely
+     * supported `ALTER TABLE ... DELETE` mutation form instead.
+     */
+    buildDeleteQuery(tableName, where, options) {
+        if (options?.truncate && (!where || Object.keys(where).length === 0)) {
+            return { sql: `TRUNCATE TABLE ${this.quoteTable(tableName)}`, values: [] };
+        }
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} DELETE`;
+        const whereClause = this.buildWhereClause(where);
+        // ClickHouse requires a WHERE clause on ALTER TABLE ... DELETE; "delete
+        // everything" should go through TRUNCATE TABLE instead (see above).
+        sql += whereClause.sql ? ` WHERE ${whereClause.sql}` : ' WHERE 1';
+        if (options?.limit) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: ALTER TABLE ... DELETE has no LIMIT clause; the `limit` option is ignored.');
+        }
+        if (options?.returning) {
+            // eslint-disable-next-line no-console
+            console.warn('ClickHouse: ALTER TABLE ... DELETE has no RETURNING clause; the `returning` option is ignored.');
+        }
+        return { sql, values: [] };
+    }
+    buildSelectQuery(options) {
+        let selectSql = '*';
+        if (options.attributes) {
+            if (Array.isArray(options.attributes)) {
+                // A `Literal` (e.g. the output of `uniq()`/`quantile()`/etc. below, or any
+                // other raw-SQL escape hatch) is passed through verbatim rather than
+                // identifier-escaped, since it's already a complete SQL expression
+                // (function call + optional `AS alias`), not a bare column name.
+                selectSql = options.attributes
+                    .map((a) => (a === '*' ? a : a instanceof prorm_1.Literal ? a.val : this.escapeId(a)))
+                    .join(', ');
+            }
+            else if (options.attributes.include) {
+                selectSql = options.attributes.include.map((a) => this.escapeId(a)).join(', ');
+            }
+            else if (options.attributes.exclude) {
+                // ClickHouse supports `SELECT * EXCEPT (...)` natively, same as SQLite's dialect uses.
+                selectSql = `* EXCEPT (${options.attributes.exclude.map((a) => this.escapeId(a)).join(', ')})`;
+            }
+        }
+        const distinct = options.distinct ? (options.col ? `DISTINCT ${this.escapeId(options.col)} ` : 'DISTINCT ') : '';
+        let sql = `SELECT ${distinct}${selectSql} FROM ${this.quoteTable(options.tableName, options.schema)}`;
+        /**
+         * `FINAL` fixes the correctness bug documented on `buildUpsertQuery()`
+         * above: without it, a `SELECT` against a ReplacingMergeTree(-family)
+         * table can return duplicate rows for the same ORDER BY key (or rows that
+         * a later-arriving "replacement" row was supposed to supersede) for as
+         * long as ClickHouse's background merges haven't run - which can be
+         * minutes to indefinitely on a lightly-written table. Appending `FINAL`
+         * right after the table reference (ClickHouse's real syntax - it goes
+         * before any join/alias, not at the end of the query) forces ClickHouse
+         * to perform the merge-time dedup logic at query time instead.
+         *
+         * Deliberately OPT-IN, not auto-detected from the table's engine:
+         *   - This dialect does not persist per-table engine metadata anywhere
+         *     (see `resolveOrderBy()`/`createTable()` above - `options.engine` is
+         *     used once, at CREATE TABLE time, and never stored). Auto-applying
+         *     FINAL would require an extra round-trip query against
+         *     `system.tables` on every single SELECT to look up the engine,
+         *     which is both a synchronous-API mismatch (this method is
+         *     synchronous and returns plain SQL text - it cannot await a
+         *     metadata lookup) and a real latency/load cost on hot paths.
+         *   - FINAL is also not free even when it IS what you want: it forces a
+         *     merge-on-read, which can be significantly slower than a plain
+         *     SELECT and doesn't scale well to very large tables/parts counts.
+         *     Silently forcing it on every read against something that merely
+         *     *might* be a ReplacingMergeTree table would be a surprising,
+         *     hard-to-diagnose performance regression for callers who don't
+         *     need dedup for a given query (e.g. aggregates that tolerate
+         *     eventual consistency).
+         *   - An explicit `final: true` is the same shape as the loud
+         *     documentation already on `buildUpsertQuery()`: callers who choose
+         *     ReplacingMergeTree + this upsert pattern must consciously opt in
+         *     to FINAL on the reads that require deduplicated/latest-row
+         *     semantics, rather than have correctness depend on an inference
+         *     this dialect cannot safely make at this layer.
+         */
+        if (options.final) {
+            sql += ' FINAL';
+        }
+        if (options.include && options.include.length > 0) {
+            for (const include of options.include) {
+                const joinType = include.required ? 'INNER JOIN' : 'LEFT JOIN';
+                const joinModel = include.model;
+                const joinTable = joinModel.tableName || String(include.model);
+                const alias = include.as || joinTable;
+                sql += ` ${joinType} ${this.quoteTable(joinTable)} AS ${this.escapeId(alias)}`;
+                if (include.where) {
+                    const onClause = this.buildWhereClause(include.where);
+                    if (onClause.sql)
+                        sql += ` ON ${onClause.sql}`;
+                }
+            }
+        }
+        /**
+         * ClickHouse's `ARRAY JOIN` / `LEFT ARRAY JOIN` clause "unnests" Array-typed
+         * columns into multiple rows (roughly analogous to PostgreSQL's `unnest()`,
+         * but its own clause with different NULL-handling: `LEFT ARRAY JOIN` keeps a
+         * source row with an empty array by producing one row with the array
+         * element's default value, whereas plain `ARRAY JOIN` drops it). It is
+         * positioned after FROM/JOIN and before WHERE, matching ClickHouse's real
+         * grammar. `(options as any).arrayJoin` accepts either a single expression
+         * string (optionally `'col AS alias'`) or an array of such expressions;
+         * `(options as any).leftArrayJoin` selects the LEFT variant.
+         */
+        const arrayJoinExprs = options.arrayJoin ?? options.leftArrayJoin;
+        if (arrayJoinExprs) {
+            const exprs = Array.isArray(arrayJoinExprs) ? arrayJoinExprs : [arrayJoinExprs];
+            const keyword = options.leftArrayJoin ? 'LEFT ARRAY JOIN' : 'ARRAY JOIN';
+            sql += ` ${keyword} ${exprs.join(', ')}`;
+        }
+        if (options.where) {
+            const whereClause = this.buildWhereClause(options.where);
+            if (whereClause.sql)
+                sql += ` WHERE ${whereClause.sql}`;
+        }
+        if (options.group) {
+            const groupBy = Array.isArray(options.group) ? options.group : [options.group];
+            sql += ` GROUP BY ${groupBy.map((g) => this.escapeId(g)).join(', ')}`;
+            if (options.having) {
+                const havingClause = this.buildWhereClause(options.having);
+                if (havingClause.sql)
+                    sql += ` HAVING ${havingClause.sql}`;
+            }
+        }
+        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}`;
+                }
+                if (unionQuery.order) {
+                    const orderClause = this.buildOrderClause(unionQuery.order);
+                    if (orderClause)
+                        unionSql += ` ${orderClause}`;
+                }
+                unionSql += this.buildLimitOffset(unionQuery.limit, unionQuery.offset);
+                sql += ` ${unionType} ${unionSql}`;
+            }
+        }
+        return { sql, values: [] };
+    }
+    /**
+     * Increment/decrement is built on the same asynchronous ALTER TABLE ...
+     * UPDATE mutation mechanism as buildUpdateQuery() - see its doc comment.
+     */
+    buildIncrementQuery(tableName, fields, where, options) {
+        const by = options?.by ?? 1;
+        let setClauses;
+        if (typeof fields === 'string') {
+            setClauses = [`${this.escapeId(fields)} = ${this.escapeId(fields)} + ${by}`];
+        }
+        else if (Array.isArray(fields)) {
+            setClauses = fields.map((f) => `${this.escapeId(f)} = ${this.escapeId(f)} + ${by}`);
+        }
+        else {
+            setClauses = Object.entries(fields).map(([f, v]) => `${this.escapeId(f)} = ${this.escapeId(f)} + ${v}`);
+        }
+        let sql = `ALTER TABLE ${this.quoteTable(tableName)} UPDATE ${setClauses.join(', ')}`;
+        const whereClause = this.buildWhereClause(where);
+        if (whereClause.sql)
+            sql += ` WHERE ${whereClause.sql}`;
+        return { sql, values: [] };
+    }
+    // ==================== Foreign Data Wrappers (unsupported) ====================
+    //
+    // ClickHouse has table functions/engines for federation (mysql(), postgresql(),
+    // s3(), etc.), but nothing matching PostgreSQL's FDW/foreign-server/user-mapping
+    // object model that this part of the Dialect interface is shaped around.
+    fdwUnsupported() {
+        throw new Error('Foreign Data Wrappers are not supported by ClickHouse. This is a PostgreSQL-specific feature. ' +
+            'ClickHouse offers table functions/engines for federation instead (e.g. mysql(), postgresql(), s3()).');
+    }
+    buildCreateServerQuery(_name, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildAlterServerQuery(_name, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildDropServerQuery(_name, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildCreateUserMappingQuery(_opts) {
+        return this.fdwUnsupported();
+    }
+    buildAlterUserMappingQuery(_opts) {
+        return this.fdwUnsupported();
+    }
+    buildDropUserMappingQuery(_serverName, _user, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildCreateForeignTableQuery(_tableName, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildDropForeignTableQuery(_tableName, _opts) {
+        return this.fdwUnsupported();
+    }
+    buildImportForeignSchemaQuery(_remoteSchema, _serverName, _opts) {
+        return this.fdwUnsupported();
+    }
+    getServersQuery() {
+        return this.fdwUnsupported();
+    }
+    async createForeignDataWrapper(_fdwName, _options) {
+        this.fdwUnsupported();
+    }
+    async dropForeignDataWrapper(_fdwName, _options) {
+        this.fdwUnsupported();
+    }
+    async createForeignServer(_serverName, _fdwName, _options) {
+        this.fdwUnsupported();
+    }
+    async dropForeignServer(_serverName, _options) {
+        this.fdwUnsupported();
+    }
+    async createForeignTable(_tableName, _columns, _options) {
+        this.fdwUnsupported();
+    }
+    async createUserMapping(_userName, _serverName, _options) {
+        this.fdwUnsupported();
+    }
+    async dropUserMapping(_userName, _serverName, _options) {
+        this.fdwUnsupported();
+    }
+    // ==================== User / role / privilege management ====================
+    //
+    // ClickHouse does support SQL-driven access control (CREATE USER/ROLE, GRANT/
+    // REVOKE) when `access_management` is enabled server-side; the syntax below
+    // uses ClickHouse's real grammar (distinct from MySQL/PostgreSQL's).
+    buildCreateUserQuery(username, options) {
+        let sql = `CREATE USER${options?.ifNotExists ? ' IF NOT EXISTS' : ''} ${this.escapeId(username)}`;
+        if (options?.password) {
+            sql += ` IDENTIFIED WITH plaintext_password BY '${this.escapeString(options.password)}'`;
+        }
+        return sql;
+    }
+    buildAlterUserQuery(username, options) {
+        let sql = `ALTER USER ${this.escapeId(username)}`;
+        if (options?.password) {
+            sql += ` IDENTIFIED WITH plaintext_password BY '${this.escapeString(options.password)}'`;
+        }
+        return sql;
+    }
+    buildDropUserQuery(username, options) {
+        return `DROP USER${options?.ifExists ? ' IF EXISTS' : ''} ${this.escapeId(username)}`;
+    }
+    getUsersQuery() {
+        return 'SELECT name, storage, auth_type FROM system.users';
+    }
+    buildGrantQuery(options) {
+        const privileges = (options.privileges || []).join(', ');
+        const scope = options.on?.level === 'table'
+            ? `${options.on.database ? `${this.escapeId(options.on.database)}.` : ''}${this.escapeId(options.on.table)}`
+            : options.on?.level === 'database'
+                ? `${this.escapeId(options.on.database)}.*`
+                : '*.*';
+        const recipients = (Array.isArray(options.to) ? options.to : [options.to]).map((r) => this.escapeId(r)).join(', ');
+        let sql = `GRANT ${privileges} ON ${scope} TO ${recipients}`;
+        if (options.withGrantOption)
+            sql += ' WITH GRANT OPTION';
+        return sql;
+    }
+    buildRevokeQuery(options) {
+        const privileges = (options.privileges || []).join(', ');
+        const scope = options.on?.level === 'table'
+            ? `${options.on.database ? `${this.escapeId(options.on.database)}.` : ''}${this.escapeId(options.on.table)}`
+            : options.on?.level === 'database'
+                ? `${this.escapeId(options.on.database)}.*`
+                : '*.*';
+        const targets = (Array.isArray(options.from) ? options.from : [options.from]).map((r) => this.escapeId(r)).join(', ');
+        return `REVOKE ${privileges} ON ${scope} FROM ${targets}`;
+    }
+    buildShowGrantsQuery(username, _host) {
+        return `SHOW GRANTS FOR ${this.escapeId(username)}`;
+    }
+    buildFlushPrivilegesQuery() {
+        // ClickHouse re-reads users.xml/access-storage automatically; there is no
+        // FLUSH PRIVILEGES statement. SYSTEM RELOAD USERS is the closest analog.
+        return 'SYSTEM RELOAD USERS';
+    }
+    buildCreateRoleQuery(roleName, options) {
+        return `CREATE ROLE${options?.ifNotExists ? ' IF NOT EXISTS' : ''} ${this.escapeId(roleName)}`;
+    }
+    buildDropRoleQuery(roleName, options) {
+        return `DROP ROLE${options?.ifExists ? ' IF EXISTS' : ''} ${this.escapeId(roleName)}`;
+    }
+    buildGrantRoleQuery(role, to, _options) {
+        const recipients = (Array.isArray(to) ? to : [to]).map((r) => this.escapeId(r)).join(', ');
+        return `GRANT ${this.escapeId(role)} TO ${recipients}`;
+    }
+    buildRevokeRoleQuery(role, from, _options) {
+        const targets = (Array.isArray(from) ? from : [from]).map((r) => this.escapeId(r)).join(', ');
+        return `REVOKE ${this.escapeId(role)} FROM ${targets}`;
+    }
+    getRolesQuery() {
+        return 'SELECT name FROM system.roles';
+    }
+    // ==================== Stored procedures (unsupported) ====================
+    //
+    // ClickHouse has no stored procedure language. The closest analogs are
+    // materialized views (for insert-triggered transformations) and user-defined
+    // functions (SQL or executable UDFs), neither of which offers arbitrary
+    // procedural logic or resembles this interface's shape.
+    async createStoredProcedure(_options) {
+        throw new Error('ClickHouse has no stored procedure language. Consider a materialized view (for insert-triggered ' +
+            'transformations) or a user-defined function (CREATE FUNCTION) instead.');
+    }
+    async createProcedure(options) {
+        return this.createStoredProcedure(options);
+    }
+    async dropStoredProcedure(_procedureName, _options) {
+        throw new Error('ClickHouse has no stored procedure language.');
+    }
+    async dropProcedure(procedureName, options) {
+        return this.dropStoredProcedure(procedureName, options);
+    }
+    async executeStoredProcedure(_options) {
+        throw new Error('ClickHouse has no stored procedure language.');
+    }
+    async hasStoredProcedure(_procedureName, _schema) {
+        return false;
+    }
+    /**
+     * Build an expression to shred a JSON document/array into relational rows.
+     * ClickHouse has no `JSON_TABLE`/`OPENJSON` function; the real equivalent composes
+     * `JSONExtractArrayRaw` (split a JSON array into raw per-element JSON strings) with
+     * `arrayJoin` (explode an array into rows), then per-column `JSONExtract*` functions
+     * (chosen by the requested column type) to pull typed values out of each element.
+     * ClickHouse: (SELECT JSONExtractString(elem, 'name') AS name, ... FROM
+     *   (SELECT arrayJoin(JSONExtractArrayRaw(expr, 'rowPath')) AS elem)) AS alias
+     */
+    buildJsonTable(jsonExpression, rowPath, columns, alias) {
+        const jsonExtractFn = {
+            string: 'JSONExtractString',
+            varchar: 'JSONExtractString',
+            text: 'JSONExtractString',
+            int: 'JSONExtractInt',
+            integer: 'JSONExtractInt',
+            bigint: 'JSONExtractInt',
+            uint64: 'JSONExtractUInt',
+            float: 'JSONExtractFloat',
+            float64: 'JSONExtractFloat',
+            double: 'JSONExtractFloat',
+            decimal: 'JSONExtractFloat',
+            bool: 'JSONExtractBool',
+            boolean: 'JSONExtractBool',
+        };
+        const normalizedRowPath = rowPath ? rowPath.replace(/^\$\.?/, '') : '';
+        const rowPathArg = normalizedRowPath ? `, '${normalizedRowPath}'` : '';
+        const selectCols = columns
+            .map((col) => {
+            if (col.forOrdinality) {
+                return `rowNumberInBlock() AS ${this.escapeId(col.name)}`;
+            }
+            const key = (col.path || col.name).replace(/^\$\.?/, '');
+            const fn = (col.type && jsonExtractFn[col.type.toLowerCase()]) || 'JSONExtractRaw';
+            return `${fn}(elem, '${key}') AS ${this.escapeId(col.name)}`;
+        })
+            .join(', ');
+        return (`(SELECT ${selectCols} FROM ` +
+            `(SELECT arrayJoin(JSONExtractArrayRaw(${jsonExpression}${rowPathArg})) AS elem)) AS ${this.escapeId(alias)}`);
+    }
+}
+exports.ClickHouseDialect = ClickHouseDialect;
+function createClickHouseDialect(config) {
+    return new ClickHouseDialect(config);
+}