@quark-fw/clisma 0.1.13 → 0.1.15

package/dist/ddl-shared.js

@@ -0,0 +1,54 @@
+// src/ddl-shared.ts
+// Общие хелперы рендера DDL: разбор движка и ключей, экранирование.
+import { escapeId } from "./escape-id.js";
+export function isExpr(part) {
+    return typeof part === "object" && part !== null && "__expr" in part;
+}
+export function renderKeyPart(part) {
+    return isExpr(part) ? part.__expr : escapeId(part);
+}
+export function renderKeyList(parts) {
+    return `(${parts.map(renderKeyPart).join(", ")})`;
+}
+// имена колонок ключа без выражений — для проверок «ключ нельзя менять»
+export function keyColumns(parts) {
+    return parts.filter((p) => typeof p === "string");
+}
+export function quoteString(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+export function engineFamily(engine) {
+    if (typeof engine !== "string")
+        return engine.family;
+    // у сырой строки семейство — имя до скобки, без префикса Replicated
+    return engine
+        .replace(/^Replicated/, "")
+        .replace(/\(.*$/s, "")
+        .trim();
+}
+export function isReplicatedEngine(table) {
+    if (typeof table.engine === "string") {
+        return table.engine.startsWith("Replicated");
+    }
+    return table.replication !== undefined;
+}
+export function isReplacingEngine(engine) {
+    return engineFamily(engine).includes("ReplacingMergeTree");
+}
+export function collapsingOf(engine) {
+    return typeof engine === "string" ? undefined : engine.collapsing;
+}
+export function renderEngine(table) {
+    if (typeof table.engine === "string")
+        return table.engine;
+    const { family, args } = table.engine;
+    if (!table.replication) {
+        return args.length ? `${family}(${args.join(", ")})` : family;
+    }
+    const replicated = [
+        quoteString(table.replication.path),
+        quoteString(table.replication.replica),
+        ...args,
+    ];
+    return `Replicated${family}(${replicated.join(", ")})`;
+}

package/dist/ddl.d.ts

@@ -1,2 +1,5 @@
 import { AnyTable } from "./table.js";
+import type { Column } from "./column.js";
+export declare function renderSettings(settings: Record<string, string | number>): string;
+export declare function buildColumnSQL(name: string, col: Column<unknown>): string;
 export declare function buildCreateTableSQL(database: string, tableName: string, table: AnyTable): string;

package/dist/ddl.js

@@ -1,15 +1,50 @@
 // src/ddl.ts
-import { escapeId } from "./sql.js";
+import { escapeId } from "./escape-id.js";
+import { buildIndexSQL } from "./build-index-sql.js";
+import { quoteString, renderEngine, renderKeyList, renderKeyPart, } from "./ddl-shared.js";
+// список для `SETTINGS` / `MODIFY SETTING`: числа как есть, строки в кавычках
+export function renderSettings(settings) {
+    return Object.entries(settings)
+        .map(([key, value]) => typeof value === "number" ? `${key} = ${value}` : `${key} = ${quoteString(value)}`)
+        .join(", ");
+}
+export function buildColumnSQL(name, col) {
+    const parts = [escapeId(name), col.clickhouseType];
+    if (col.default)
+        parts.push(`${col.default.kind} ${col.default.expr}`);
+    if (col.codec)
+        parts.push(`CODEC(${col.codec})`);
+    if (col.comment)
+        parts.push(`COMMENT ${quoteString(col.comment)}`);
+    return parts.join(" ");
+}
 export function buildCreateTableSQL(database, tableName, table) {
-    const columnsSQL = Object.entries(table.columns)
-        .map(([name, col]) => `${escapeId(name)} ${col.clickhouseType}`)
-        .join(",\n");
+    const body = [
+        ...Object.entries(table.columns).map(([name, col]) => buildColumnSQL(name, col)),
+        ...(table.indexes ?? []).map(buildIndexSQL),
+    ].join(",\n");
+    const clauses = [`ENGINE = ${renderEngine(table)}`];
+    if (table.partitionBy) {
+        clauses.push(`PARTITION BY ${renderKeyPart(table.partitionBy)}`);
+    }
+    if (table.primaryKey) {
+        clauses.push(`PRIMARY KEY ${renderKeyList(table.primaryKey)}`);
+    }
+    clauses.push(`ORDER BY ${renderKeyList(table.orderBy)}`);
+    if (table.sampleBy)
+        clauses.push(`SAMPLE BY ${renderKeyPart(table.sampleBy)}`);
+    if (table.ttl)
+        clauses.push(`TTL ${table.ttl}`);
+    if (table.settings && Object.keys(table.settings).length) {
+        clauses.push(`SETTINGS ${renderSettings(table.settings)}`);
+    }
+    if (table.comment)
+        clauses.push(`COMMENT ${quoteString(table.comment)}`);
     return `
     CREATE TABLE IF NOT EXISTS ${escapeId(database)}.${escapeId(tableName)}
     (
-      ${columnsSQL}
+      ${body}
     )
-    ENGINE = ${table.engine}
-    ORDER BY (${table.orderBy.map(escapeId).join(", ")})
+    ${clauses.join("\n    ")}
   `.trim();
 }

package/dist/dictionary.d.ts

@@ -0,0 +1,26 @@
+import type { Column } from "./column.js";
+export type DictionaryCredentials = {
+    user: string;
+    password?: string;
+};
+export type DictionarySource = ({
+    query: string;
+} | {
+    table: string;
+    database?: string;
+    where?: string;
+}) & Partial<DictionaryCredentials>;
+export type DictionaryLayout = "flat" | "hashed" | "sparse_hashed" | "hashed_array" | "complex_key_hashed";
+export type DictionaryDefinition<TKey extends Record<string, Column<unknown>>, TAttributes extends Record<string, Column<unknown>>> = {
+    key: TKey;
+    attributes: TAttributes;
+    source: DictionarySource;
+    layout: DictionaryLayout;
+    lifetime: number | {
+        min: number;
+        max: number;
+    };
+    comment?: string;
+};
+export type AnyDictionary = DictionaryDefinition<Record<string, Column<unknown>>, Record<string, Column<unknown>>>;
+export declare function dictionary<TKey extends Record<string, Column<unknown>>, TAttributes extends Record<string, Column<unknown>>>(def: DictionaryDefinition<TKey, TAttributes>): DictionaryDefinition<TKey, TAttributes>;

package/dist/dictionary.js

@@ -0,0 +1,7 @@
+// src/dictionary.ts
+export function dictionary(def) {
+    if (Object.keys(def.key).length === 0) {
+        throw new Error("Dictionary requires at least one key column");
+    }
+    return def;
+}

package/dist/engine.d.ts

@@ -0,0 +1,16 @@
+export type EngineSpec = {
+    family: "MergeTree" | "ReplacingMergeTree" | "CollapsingMergeTree" | "VersionedCollapsingMergeTree" | "SummingMergeTree" | "AggregatingMergeTree";
+    args: string[];
+    collapsing?: {
+        sign: string;
+        version?: string;
+    };
+};
+export declare const engine: {
+    mergeTree: () => EngineSpec;
+    replacingMergeTree: (version?: string) => EngineSpec;
+    collapsingMergeTree: (sign: string) => EngineSpec;
+    versionedCollapsingMergeTree: (sign: string, version: string) => EngineSpec;
+    summingMergeTree: (columns?: string[]) => EngineSpec;
+    aggregatingMergeTree: () => EngineSpec;
+};

package/dist/engine.js

@@ -0,0 +1,26 @@
+// src/engine.ts
+export const engine = {
+    mergeTree: () => ({ family: "MergeTree", args: [] }),
+    replacingMergeTree: (version) => ({
+        family: "ReplacingMergeTree",
+        args: version ? [version] : [],
+    }),
+    collapsingMergeTree: (sign) => ({
+        family: "CollapsingMergeTree",
+        args: [sign],
+        collapsing: { sign },
+    }),
+    versionedCollapsingMergeTree: (sign, version) => ({
+        family: "VersionedCollapsingMergeTree",
+        args: [sign, version],
+        collapsing: { sign, version },
+    }),
+    summingMergeTree: (columns = []) => ({
+        family: "SummingMergeTree",
+        args: columns.length ? [`(${columns.join(", ")})`] : [],
+    }),
+    aggregatingMergeTree: () => ({
+        family: "AggregatingMergeTree",
+        args: [],
+    }),
+};

package/dist/ensure-dictionaries-on-nodes.d.ts

@@ -0,0 +1,3 @@
+import type { AnyDictionary, DictionaryCredentials } from "./dictionary.js";
+import type { DdlNode, DdlStatement } from "./ensure-tables-on-nodes.js";
+export declare function ensureDictionariesOnNodes(nodes: DdlNode[], database: string, dictionaries: Record<string, AnyDictionary>, credentials?: DictionaryCredentials, mode?: "create" | "replace"): Promise<DdlStatement[]>;

package/dist/ensure-dictionaries-on-nodes.js

@@ -0,0 +1,15 @@
+// src/ensure-dictionaries-on-nodes.ts
+import { buildCreateDictionarySQL } from "./build-create-dictionary-query.js";
+// Словарь не реплицируется — это локальный кэш каждой ноды над её же
+// данными, поэтому он создаётся из схемы на каждой ноде отдельно.
+export async function ensureDictionariesOnNodes(nodes, database, dictionaries, credentials, mode = "create") {
+    const executed = [];
+    for (const node of nodes) {
+        for (const name in dictionaries) {
+            const sql = buildCreateDictionarySQL(database, name, dictionaries[name], credentials, mode);
+            await node.client.command({ query: sql });
+            executed.push({ node: node.url, sql });
+        }
+    }
+    return executed;
+}

package/dist/ensure-tables-on-nodes.d.ts

@@ -0,0 +1,11 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { AnyTable } from "./table.js";
+export type DdlNode = {
+    url: string;
+    client: ClickHouseClient;
+};
+export type DdlStatement = {
+    node: string;
+    sql: string;
+};
+export declare function ensureTablesOnNodes(nodes: DdlNode[], database: string, tables: Record<string, AnyTable>): Promise<DdlStatement[]>;

package/dist/ensure-tables-on-nodes.js

@@ -0,0 +1,39 @@
+// src/ensure-tables-on-nodes.ts
+import { buildCreateTableSQL } from "./ddl.js";
+import { escapeId } from "./escape-id.js";
+async function tableExists(client, database, tableName) {
+    const result = await client.query({
+        query: `EXISTS TABLE ${escapeId(database)}.${escapeId(tableName)}`,
+        format: "JSONEachRow",
+    });
+    const rows = await result.json();
+    return Number(rows[0]?.result) === 1;
+}
+// Первая нода — источник истины: на ней таблица создаётся из схемы, а на
+// остальные копируется её SHOW CREATE TABLE. Копия, а не повторный рендер —
+// потому что Keeper сверяет метаданные реплик побайтово (порядок колонок,
+// дефолты), и любое расхождение рендера оставило бы реплику вне набора.
+export async function ensureTablesOnNodes(nodes, database, tables) {
+    const [primary, ...secondaries] = nodes;
+    const executed = [];
+    for (const tableName in tables) {
+        const createSQL = buildCreateTableSQL(database, tableName, tables[tableName]);
+        await primary.client.command({ query: createSQL });
+        executed.push({ node: primary.url, sql: createSQL });
+    }
+    for (const node of secondaries) {
+        for (const tableName in tables) {
+            if (await tableExists(node.client, database, tableName))
+                continue;
+            const shown = await primary.client.query({
+                query: `SHOW CREATE TABLE ${escapeId(database)}.${escapeId(tableName)}`,
+                format: "JSONEachRow",
+            });
+            const [{ statement }] = await shown.json();
+            const copySQL = statement.replace(/^CREATE TABLE /, "CREATE TABLE IF NOT EXISTS ");
+            await node.client.command({ query: copySQL });
+            executed.push({ node: node.url, sql: copySQL });
+        }
+    }
+    return executed;
+}

package/dist/escape-id.d.ts

@@ -0,0 +1 @@
+export declare function escapeId(name: string): string;

package/dist/escape-id.js

@@ -0,0 +1,4 @@
+// src/escape-id.ts
+export function escapeId(name) {
+    return "`" + name.replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`";
+}

package/dist/expr.d.ts

@@ -0,0 +1,5 @@
+export type Expr = {
+    readonly __expr: string;
+};
+export type KeyPart = string | Expr;
+export declare function expr(sql: string): Expr;

package/dist/expr.js

@@ -0,0 +1,4 @@
+// src/expr.ts
+export function expr(sql) {
+    return { __expr: sql };
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./column.js";
+export * from "./expr.js";
+export * from "./engine.js";
 export * from "./table.js";
+export * from "./dictionary.js";
 export * from "./schema.js";
 export * from "./client.js";
 export * from "./where.js";
@@ -7,3 +10,7 @@ export * from "./sql.js";
 export * from "./table-client.js";
 export * from "./rows.js";
 export * from "./migrate.js";
+export * from "./ddl.js";
+export * from "./build-create-dictionary-query.js";
+export type { QueryOptions, QueryJsonResult, QuerySettings } from "./query.js";
+export type { DdlNode, DdlStatement } from "./ensure-tables-on-nodes.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from "./column.js";
+export * from "./expr.js";
+export * from "./engine.js";
 export * from "./table.js";
+export * from "./dictionary.js";
 export * from "./schema.js";
 export * from "./client.js";
 export * from "./where.js";
@@ -7,3 +10,5 @@ export * from "./sql.js";
 export * from "./table-client.js";
 export * from "./rows.js";
 export * from "./migrate.js";
+export * from "./ddl.js";
+export * from "./build-create-dictionary-query.js";

package/dist/migrate.d.ts

@@ -4,8 +4,11 @@ export type DbColumn = {
     name: string;
     type: string;
 };
+export type DbTableSettings = Record<string, Record<string, string>>;
 export type MigrationPlan = {
     statements: string[];
     warnings: string[];
 };
+export declare function parseEngineSettings(engineFull: string): Record<string, string>;
 export declare function buildMigrationPlan(database: string, tables: Record<string, AnyTable>, existing: DbColumn[]): MigrationPlan;
+export declare function buildSettingsPlan(database: string, tables: Record<string, AnyTable>, existingSettings: DbTableSettings): string[];

package/dist/migrate.js

@@ -1,6 +1,20 @@
 // src/migrate.ts
-import { buildCreateTableSQL } from "./ddl.js";
-import { escapeId } from "./sql.js";
+import { buildColumnSQL, buildCreateTableSQL, renderSettings } from "./ddl.js";
+import { escapeId } from "./escape-id.js";
+import { keyColumns } from "./ddl-shared.js";
+// `SETTINGS a = 1, b = 'x'` из хвоста `system.tables.engine_full`
+export function parseEngineSettings(engineFull) {
+    const out = {};
+    const at = engineFull.lastIndexOf(" SETTINGS ");
+    if (at === -1)
+        return out;
+    const re = /(\w+)\s*=\s*('(?:[^'\\]|\\.)*'|[^,]+)/g;
+    for (const m of engineFull.slice(at + " SETTINGS ".length).matchAll(re)) {
+        const raw = m[2].trim();
+        out[m[1]] = raw.startsWith("'") ? raw.slice(1, -1).replace(/\\(.)/g, "$1") : raw;
+    }
+    return out;
+}
 export function buildMigrationPlan(database, tables, existing) {
     const statements = [];
     const warnings = [];
@@ -21,14 +35,23 @@ export function buildMigrationPlan(database, tables, existing) {
             continue;
         }
         const tableRef = `${escapeId(database)}.${escapeId(tableName)}`;
+        const keys = keyColumns([...def.orderBy, ...(def.primaryKey ?? [])]);
         for (const colName in def.columns) {
-            const wanted = def.columns[colName].clickhouseType;
+            const col = def.columns[colName];
+            const wanted = col.clickhouseType;
             const actual = dbCols.get(colName);
             if (actual === undefined) {
-                statements.push(`ALTER TABLE ${tableRef} ADD COLUMN ${escapeId(colName)} ${wanted}`);
+                statements.push(`ALTER TABLE ${tableRef} ADD COLUMN ${buildColumnSQL(colName, col)}`);
             }
             else if (actual !== wanted) {
-                statements.push(`ALTER TABLE ${tableRef} MODIFY COLUMN ${escapeId(colName)} ${wanted}`);
+                // ключевую колонку сервер менять не даст; лучше внятная ошибка
+                // до выполнения плана, чем упавшая посередине миграция
+                if (keys.includes(colName)) {
+                    throw new Error(`Column "${colName}" of ${database}.${tableName} is part of the ` +
+                        `sorting key and cannot change type (${actual} → ${wanted}); ` +
+                        `recreate the table instead`);
+                }
+                statements.push(`ALTER TABLE ${tableRef} MODIFY COLUMN ${buildColumnSQL(colName, col)}`);
             }
         }
         for (const dbColName of dbCols.keys()) {
@@ -40,3 +63,27 @@ export function buildMigrationPlan(database, tables, existing) {
     }
     return { statements, warnings };
 }
+// Настройки таблицы — локальные метаданные каждой ноды: MODIFY SETTING не
+// реплицируется (в отличие от ADD/MODIFY COLUMN), поэтому план настроек
+// строится и выполняется на каждой ноде по её `system.tables`. Только
+// объявленные в схеме настройки и только существующие на ноде таблицы —
+// новые получат их из CREATE (или из SHOW CREATE копии). Правка метаданных,
+// данные не переписываются.
+export function buildSettingsPlan(database, tables, existingSettings) {
+    const statements = [];
+    for (const tableName in tables) {
+        const declared = tables[tableName].settings;
+        const actual = existingSettings[tableName];
+        if (!declared || !actual)
+            continue;
+        const changed = {};
+        for (const [key, value] of Object.entries(declared)) {
+            if (actual[key] !== String(value))
+                changed[key] = value;
+        }
+        if (Object.keys(changed).length) {
+            statements.push(`ALTER TABLE ${escapeId(database)}.${escapeId(tableName)} MODIFY SETTING ${renderSettings(changed)}`);
+        }
+    }
+    return statements;
+}

package/dist/query.d.ts

@@ -0,0 +1,26 @@
+import type { ClickHouseClient } from "@clickhouse/client";
+import type { AnyColumns } from "./table.js";
+export type QuerySettings = Record<string, string | number | boolean>;
+export type QueryOptions = {
+    params?: Record<string, unknown>;
+    settings?: QuerySettings;
+    columns?: AnyColumns;
+};
+export type QueryJsonResult<TRow, TTotals = TRow> = {
+    data: TRow[];
+    totals?: TTotals;
+    rows: number;
+    rows_before_limit_at_least?: number;
+    meta: {
+        name: string;
+        type: string;
+    }[];
+    statistics: {
+        elapsed: number;
+        rows_read: number;
+        bytes_read: number;
+    };
+};
+export declare function runQuery<TRow>(client: ClickHouseClient, sql: string, options?: QueryOptions): Promise<TRow[]>;
+export declare function runQueryJson<TRow, TTotals = TRow>(client: ClickHouseClient, sql: string, options?: QueryOptions): Promise<QueryJsonResult<TRow, TTotals>>;
+export declare function runCommand(client: ClickHouseClient, sql: string, options?: Omit<QueryOptions, "columns">): Promise<void>;

package/dist/query.js

@@ -0,0 +1,60 @@
+// src/query.ts
+// Сырые запросы поверх @clickhouse/client: агрегаты, GROUP BY и DDL не
+// выражаются Prisma-синтаксисом, а второй клиент в приложении — дубль
+// соединения и настроек.
+import { deserializeRows } from "./rows.js";
+// те же настройки, что у findMany: ISO-даты без таймзонной неоднозначности и
+// 64-битные целые строками, чтобы BigInt() был без потерь
+const WIRE_SETTINGS = {
+    date_time_output_format: "iso",
+    output_format_json_quote_64bit_integers: 1,
+};
+function serializeParams(params = {}) {
+    const out = {};
+    for (const key in params) {
+        const value = params[key];
+        out[key] =
+            value instanceof Date ? Math.floor(value.getTime() / 1000) : value;
+    }
+    return out;
+}
+export async function runQuery(client, sql, options = {}) {
+    const result = await client.query({
+        query: sql,
+        query_params: serializeParams(options.params),
+        format: "JSONEachRow",
+        clickhouse_settings: { ...WIRE_SETTINGS, ...options.settings },
+    });
+    const rows = await result.json();
+    return options.columns
+        ? deserializeRows(rows, options.columns)
+        : rows;
+}
+// FORMAT JSON нужен, когда важны totals (WITH TOTALS), точный
+// rows_before_limit_at_least и статистика чтения — JSONEachRow их не отдаёт
+export async function runQueryJson(client, sql, options = {}) {
+    const result = await client.query({
+        query: sql,
+        query_params: serializeParams(options.params),
+        format: "JSON",
+        clickhouse_settings: { ...WIRE_SETTINGS, ...options.settings },
+    });
+    // у FORMAT JSON клиент типизирует поля как необязательные; сервер отдаёт их всегда
+    const body = (await result.json());
+    if (!options.columns)
+        return body;
+    return {
+        ...body,
+        data: deserializeRows(body.data, options.columns),
+        totals: body.totals
+            ? deserializeRows([body.totals], options.columns)[0]
+            : undefined,
+    };
+}
+export async function runCommand(client, sql, options = {}) {
+    await client.command({
+        query: sql,
+        query_params: serializeParams(options.params),
+        clickhouse_settings: options.settings,
+    });
+}

package/dist/rows.js

@@ -13,12 +13,21 @@ function convertValue(value, chType) {
     const nullable = /^Nullable\((.+)\)$/.exec(chType);
     if (nullable)
         return convertValue(value, nullable[1]);
+    // LowCardinality — способ хранения, на значение не влияет
+    const lowCardinality = /^LowCardinality\((.+)\)$/.exec(chType);
+    if (lowCardinality)
+        return convertValue(value, lowCardinality[1]);
     const array = /^Array\((.+)\)$/.exec(chType);
     if (array) {
         return value.map((v) => convertValue(v, array[1]));
     }
     if (BIGINT_TYPES.has(chType))
         return BigInt(value);
+    // Float может прийти строкой (inf/nan или quote_64bit_integers у Float64
+    // на старых серверах) — приводим к number; Decimal, Enum, IPv4/6 и Map
+    // приходят уже в нужном виде
+    if (chType.startsWith("Float"))
+        return Number(value);
     if (chType.startsWith("DateTime") || chType.startsWith("Date")) {
         return new Date(value);
     }

package/dist/schema.d.ts

@@ -1,6 +1,8 @@
 import { AnyTable } from "./table.js";
-export type ClismaSchema<TTables extends Record<string, AnyTable>> = {
+import type { AnyDictionary } from "./dictionary.js";
+export type ClismaSchema<TTables extends Record<string, AnyTable>, TDictionaries extends Record<string, AnyDictionary> = Record<string, never>> = {
     database?: string;
     tables: TTables;
+    dictionaries?: TDictionaries;
 };
-export declare function createClisma<TTables extends Record<string, AnyTable>>(schema: ClismaSchema<TTables>): ClismaSchema<TTables>;
+export declare function createClisma<TTables extends Record<string, AnyTable>, TDictionaries extends Record<string, AnyDictionary> = Record<string, never>>(schema: ClismaSchema<TTables, TDictionaries>): ClismaSchema<TTables, TDictionaries>;

package/dist/sql-shared.d.ts

@@ -15,8 +15,10 @@ export type FindManyArgs<T> = {
     orderBy?: OrderByInput<T> | OrderByInput<T>[];
     take?: number;
     skip?: number;
+    final?: boolean;
+    settings?: Record<string, unknown>;
 };
-export declare function escapeId(name: string): string;
+export { escapeId } from "./escape-id.js";
 export declare const NO_LIMIT = "18446744073709551615";
 export declare function createBuildContext(tableName: string, columns: AnyColumns): {
     params: Record<string, unknown>;
@@ -25,6 +27,7 @@ export declare function createBuildContext(tableName: string, columns: AnyColumn
     addParam: (value: unknown, type: string) => string;
     whereSQL: (where: Record<string, unknown>) => string;
 };
-export declare function tableRef(database: string, tableName: string, table: AnyTable): string;
+export declare function tableRef(database: string, tableName: string, table: AnyTable, final?: boolean): string;
+export declare function countExpr(table: AnyTable): string;
 export declare function checkPagination(name: string, value: number): void;
 export declare function validateUpdateData(table: AnyTable, tableName: string, data: Record<string, unknown>): string[];

package/dist/sql-shared.js

@@ -1,8 +1,10 @@
 // src/sql-shared.ts
 // Shared helpers and types for the SQL builders (build-*.ts).
-export function escapeId(name) {
-    return "`" + name.replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`";
-}
+import { escapeId } from "./escape-id.js";
+import { collapsingOf, keyColumns } from "./ddl-shared.js";
+// escapeId живёт отдельным файлом: он нужен и рендеру DDL, и билдерам
+// запросов, а взаимный импорт между ними создал бы цикл модулей
+export { escapeId } from "./escape-id.js";
 // UInt64 max — used to emulate a bare OFFSET (skip without take)
 export const NO_LIMIT = "18446744073709551615";
 // DateTime is second-precision; the client would send Date with
@@ -136,10 +138,17 @@ export function createBuildContext(tableName, columns) {
     }
     return { params, colRef, baseType, addParam, whereSQL };
 }
-export function tableRef(database, tableName, table) {
+export function tableRef(database, tableName, table, final = false) {
     const ref = `${escapeId(database)}.${escapeId(tableName)}`;
-    // replacing tables must read the latest row versions
-    return table.mutations === "replacing" ? `${ref} FINAL` : ref;
+    // replacing-таблицы обязаны читать последние версии строк; для остальных
+    // FINAL включается явно (например, чтобы прочитать коллапсирующую таблицу)
+    return table.mutations === "replacing" || final ? `${ref} FINAL` : ref;
+}
+// у коллапсирующих таблиц строка «существует», только если её знак не
+// погашен парой -1 — count() посчитал бы обе строки пары
+export function countExpr(table) {
+    const collapsing = collapsingOf(table.engine);
+    return collapsing ? `sum(${escapeId(collapsing.sign)})` : "count()";
 }
 export function checkPagination(name, value) {
     if (!Number.isInteger(value) || value < 0) {
@@ -153,7 +162,7 @@ export function validateUpdateData(table, tableName, data) {
         throw new Error(`updateMany requires non-empty data`);
     }
     for (const key of keys) {
-        if (table.orderBy.includes(key)) {
+        if (keyColumns(table.orderBy).includes(key)) {
             throw new Error(`Cannot update ORDER BY key column "${key}" ` +
                 `of table "${tableName}"`);
         }

package/dist/table-client.js

@@ -1,6 +1,7 @@
 // src/table-client.ts
 import { buildFindManyQuery, buildCountQuery, buildUpdateQuery, buildDeleteQuery, buildLightweightDeleteQuery, validateUpdateData, escapeId, } from "./sql.js";
 import { deserializeRows } from "./rows.js";
+import { collapsingOf } from "./ddl-shared.js";
 // process-unique id: ms timestamp in the high bits + 20-bit counter
 let idCounter = 0n;
 function generateId() {
@@ -20,12 +21,13 @@ export class TableClient {
     get tableRef() {
         return `${escapeId(this.database)}.${escapeId(this.tableName)}`;
     }
-    async runQuery(sql, params) {
+    async runQuery(sql, params, settings = {}) {
         const result = await this.client.query({
             query: sql,
             query_params: params,
             format: "JSONEachRow",
             clickhouse_settings: {
+                ...settings,
                 // ISO with Z: the default DateTime rendering is in server
                 // timezone with no offset, which is unparseable correctly
                 date_time_output_format: "iso",
@@ -37,8 +39,13 @@ export class TableClient {
         return result.json();
     }
     async findMany(args) {
+        // сырые строки коллапсирующей таблицы содержат и погашенные версии —
+        // без FINAL такой результат вводит в заблуждение
+        if (collapsingOf(this.table.engine) && !args?.final) {
+            throw new Error(`Table "${this.tableName}" uses a collapsing engine: pass final: true to findMany`);
+        }
         const { sql, params } = buildFindManyQuery(this.database, this.tableName, this.table, args);
-        const rows = await this.runQuery(sql, params);
+        const rows = await this.runQuery(sql, params, args?.settings);
         return deserializeRows(rows, this.table.columns);
     }
     async findFirst(args) {