@quark-fw/clisma 0.1.13 → 0.1.14

package/README.md

@@ -119,16 +119,84 @@ const user = await db.users.create({
 | Фабрика            | ClickHouse            | TypeScript |
 |--------------------|-----------------------|------------|
 | `t.string()`       | `String`              | `string`   |
-| `t.uint8()`        | `UInt8`               | `number`   |
-| `t.int32()`        | `Int32`               | `number`   |
-| `t.uint64()`       | `UInt64`              | `bigint`   |
+| `t.uint8()` / `t.uint16()` / `t.uint32()` | `UInt8/16/32` | `number` |
+| `t.int8()` / `t.int16()` / `t.int32()`    | `Int8/16/32`  | `number` |
+| `t.uint64()` / `t.int64()` | `UInt64` / `Int64` | `bigint`   |
+| `t.float32()` / `t.float64()` | `Float32/64`    | `number`   |
+| `t.decimal(p, s)`  | `Decimal(p, s)`       | `string` (без потери точности) |
 | `t.boolean()`      | `Bool`                | `boolean`  |
+| `t.date()` / `t.date32()` | `Date` / `Date32` | `Date`    |
 | `t.datetime()`     | `DateTime`            | `Date`     |
+| `t.datetime64(p, tz?)` | `DateTime64(p[, 'tz'])` | `Date` |
+| `t.enum8({ a: 1, b: 2 })` | `Enum8('a' = 1, 'b' = 2)` | `"a" \| "b"` |
+| `t.lowCardinality(col)` | `LowCardinality(...)` | тот же `T` |
+| `t.ipv4()` / `t.ipv6()` | `IPv4` / `IPv6`    | `string`   |
+| `t.map(k, v)`      | `Map(K, V)`           | `Record<string, V>` |
 | `t.nullable(col)`  | `Nullable(...)`       | `T \| null`|
 | `t.array(col)`     | `Array(...)`          | `T[]`      |
 
-Пока нет: `DateTime64`, `Decimal`, `Enum`, `LowCardinality`, `DEFAULT`,
-`PARTITION BY`, `TTL`.
+Модификаторы (возвращают копию колонки): `t.default(col, expr)`,
+`t.materialized(col, expr)`, `t.alias(col, expr)`, `t.codec(col, "Delta, ZSTD(1)")`,
+`t.comment(col, "…")`.
+
+### Движок и ключи таблицы
+
+```ts
+import { engine, expr, table, t } from "@quark-fw/clisma"
+
+const clicks = table({
+	engine: engine.versionedCollapsingMergeTree("sign", "version"),
+	// путь в Keeper и макрос реплики → ReplicatedVersionedCollapsingMergeTree(...)
+	replication: { path: "/clickhouse/tables/{shard}/analytics/clicks", replica: "{replica}" },
+	partitionBy: expr("toYYYYMM(datetime)"),
+	primaryKey: [expr("toStartOfHour(datetime)"), "sub_id_15"],
+	orderBy: [expr("toStartOfHour(datetime)"), "sub_id_15", "click_id"],
+	indexes: [{ name: "idx_sub", expr: "sub_id_16", type: "bloom_filter", args: [0.01], granularity: 4 }],
+	settings: { index_granularity: 8192 },
+	columns: { /* … */ sign: t.int8(), version: t.uint64() }
+})
+```
+
+- `engine` — строка как раньше **или** спека из `engine.*`: `mergeTree()`,
+  `replacingMergeTree(ver?)`, `collapsingMergeTree(sign)`,
+  `versionedCollapsingMergeTree(sign, version)`, `summingMergeTree(cols?)`,
+  `aggregatingMergeTree()`. Со спекой clisma знает семейство: проверяет колонки
+  знака/версии при объявлении, считает `count()` как `sum(sign)` и требует
+  `final: true` в `findMany` у коллапсирующих таблиц.
+- `expr("…")` — сырое выражение там, где иначе ждут имя колонки (`orderBy`,
+  `primaryKey`, `partitionBy`, `sampleBy`, `indexes[].expr`); имена колонок
+  по-прежнему экранируются.
+- Опции: `primaryKey`, `partitionBy`, `sampleBy`, `indexes`, `ttl`, `settings`,
+  `comment`.
+
+### Словари
+
+```ts
+import { dictionary } from "@quark-fw/clisma"
+
+createClisma({
+	database: "analytics",
+	tables: { /* … */ },
+	dictionaries: {
+		user_subids_dict: dictionary({
+			key: { subid_value: t.uint32() },
+			attributes: { user_id: t.uint32(), team_ids: t.array(t.uint32()) },
+			source: { query: "SELECT subid_value, user_id, team_ids FROM analytics.user_subids FINAL" },
+			// или { table: "user_subids", where: "kind = 'BUYER'" }
+			layout: "hashed",
+			lifetime: { min: 60, max: 300 }
+		})
+	}
+})
+```
+
+Словарь — замена JOIN на измерение: `dictGet` ищет по хешу за O(1) на строку.
+Создаётся на каждой DDL-ноде; `$init` — `CREATE DICTIONARY IF NOT EXISTS`,
+`$migrate` — `CREATE OR REPLACE DICTIONARY` (иначе изменение источника или
+атрибутов никогда бы не доехало). Учётка источника по умолчанию — учётка
+клиента (`USER … PASSWORD …`): без неё ClickHouse читает локальные таблицы
+как `default`, у которого обычно стоит пароль; переопределяется полями
+`user`/`password` в `source`.
 
 ### Колонка `id`
 
@@ -142,16 +210,43 @@ clisma генерирует уникальный `bigint` (timestamp в стар
 
 ```ts
 const db = createClient(schema, {
-	url,                       // http://host:8123
+	url,                       // http://host:8123 — сюда идут все запросы
 	username, password,
 	database,                  // приоритетнее schema.database
-	autoCreateDatabase: true   // $init/$migrate создадут БД
+	autoCreateDatabase: true,  // $init/$migrate создадут БД
+	ddlNodes: [url, replicaUrl] // необязательно: ноды для DDL, первая — источник истины
+	requestTimeoutMs: 300_000, // необязательно: таймаут HTTP-запроса, по умолчанию 30 с драйвера
 })
 ```
 
 - `db.<table>` — клиент таблицы (см. API ниже)
-- `db.$init()` — создать БД и таблицы (`CREATE ... IF NOT EXISTS`), без диффа
+- `db.$init()` — создать БД, таблицы и словари (`CREATE ... IF NOT EXISTS`), без диффа
 - `db.$migrate()` — привести БД к схеме (см. «Миграции»)
+- `db.$query<Row>(sql, { params, settings, columns })` — сырой SELECT
+  (`JSONEachRow`); `columns` — карта колонок результата, чтобы `UInt64`/`DateTime`
+  вернулись как `bigint`/`Date`
+- `db.$queryJson<Row, Totals>(sql, opts)` — тот же запрос в `FORMAT JSON`:
+  `{ data, totals?, rows, rows_before_limit_at_least?, statistics }` — для
+  `WITH TOTALS`, точного числа строк до `LIMIT` (`exact_rows_before_limit = 1`)
+  и статистики чтения
+- `db.$command(sql, { params, settings })` — `INSERT … SELECT`, `ALTER`, `DROP PARTITION`
+- `db.$close()` — закрыть все соединения
+
+Параметры — серверные `{name:Type}` (`Date` уходит unix-секундами), настройки
+запроса сливаются с проводными (`date_time_output_format = iso`,
+`output_format_json_quote_64bit_integers = 1`).
+
+### DDL на несколько нод (`ddlNodes`)
+
+Когда БД `Atomic` и в `remote_servers` нет кластера, `CREATE TABLE` не
+разъезжается по репликам сам: без таблицы на реплике чтение через неё падает с
+`UNKNOWN_TABLE`. С `ddlNodes` clisma создаёт таблицы на первой ноде из схемы,
+а на остальные копирует её `SHOW CREATE TABLE` (Keeper сверяет метаданные реплик
+побайтово, повторный рендер мог бы разойтись); `ALTER` идёт только на первую —
+реплицируемая мутация разъезжается сама; словари создаются на каждой ноде.
+При двух и более нодах принимаются только таблицы с `replication` (или строкой
+движка `Replicated*`) — обычный `MergeTree` на двух нодах был бы двумя
+независимыми таблицами.
 
 ## Миграции: `db.$migrate()`
 
@@ -161,15 +256,21 @@ const db = createClient(schema, {
 - колонки нет → `ALTER TABLE ... ADD COLUMN`
 - тип отличается → `ALTER TABLE ... MODIFY COLUMN`
 
-Возвращает `{ statements, warnings }` — применённые SQL и предупреждения.
-Повторный запуск на совпадающей схеме — пустой план (идемпотентно).
+Возвращает `{ statements, warnings, executed }` — план, предупреждения и
+фактически выполненные SQL с нодой (`executed[].node`). Повторный запуск на
+совпадающей схеме — пустой план (идемпотентно); словари при этом всё равно
+пересоздаются (`CREATE OR REPLACE`, дёшево).
 
 **Ограничения (осознанные):**
 
 - лишние колонки в БД **никогда не удаляются** — только warning;
-- `ENGINE`, `ORDER BY`, `PARTITION BY` не диффятся — их изменение требует
-  пересоздания таблицы вручную;
-- `MODIFY COLUMN` ключевой колонки (из `ORDER BY`) отклонит сам ClickHouse;
+- сравнивается только тип колонки: кодеки, `DEFAULT`, комментарии в диффе не
+  участвуют (в `ADD COLUMN` они рендерятся);
+- `ENGINE`, `ORDER BY`, `PARTITION BY`, индексы, TTL не диффятся — их
+  изменение требует пересоздания таблицы вручную;
+- смена типа ключевой колонки (из `ORDER BY`/`PRIMARY KEY`) — ошибка до
+  выполнения плана: сервер её всё равно отклонит, лучше упасть целиком, чем
+  посреди миграции;
 - нет файлов/истории миграций как у `prisma migrate` — сравнение всегда
   с живой схемой.
 
@@ -179,9 +280,13 @@ const db = createClient(schema, {
 
 ### Чтение
 
-- `findMany({ where?, select?, orderBy?, take?, skip? })` → `Row[]`
+- `findMany({ where?, select?, orderBy?, take?, skip?, final?, settings? })` → `Row[]`
 - `findFirst({ where?, select?, orderBy?, skip? })` → `Row | null`
-- `count({ where? })` → `number`
+- `count({ where? })` → `number`; у коллапсирующих таблиц это `sum(sign)`
+
+`final: true` добавляет `FINAL` таблице без стратегии `replacing`;
+у коллапсирующих таблиц он обязателен для `findMany` (сырые строки содержат
+погашенные версии). `settings` — настройки ClickHouse на этот запрос.
 
 ### Запись
 
@@ -285,9 +390,11 @@ npx tsc --noEmit    # проверка типов — обязательный
 
 ## Ограничения / roadmap
 
-- нет `aggregate`, `groupBy`, `distinct` (план: `LIMIT 1 BY`), `findUnique`, `upsert`;
+- нет `aggregate`, `groupBy`, `distinct` (план: `LIMIT 1 BY`), `findUnique`, `upsert` —
+  агрегаты пишутся сырым SQL через `$query`/`$queryJson`;
 - нет вложенного `not`, `mode: "insensitive"`, операторов для Array-колонок;
-- нет файлов миграций/истории; дифф только add/modify колонок;
-- нет `DateTime64`/`Decimal`/`Enum`/`LowCardinality`, `DEFAULT`, `PARTITION BY`, `TTL`;
+- нет файлов миграций/истории; дифф только add/modify колонок по типу;
+- нет `Nested`-сахара (объявляйте `"players.deposits": t.array(t.float64())`),
+  `Tuple`, `UUID`, материализованных представлений и `Distributed`;
 - `create` без серверного round-trip (см. выше);
-- нет relations/include — ClickHouse-философия: денормализуйте.
+- нет relations/include — ClickHouse-философия: денормализуйте (или словари).

package/dist/assert-replicated-schema.d.ts

@@ -0,0 +1,2 @@
+import type { AnyTable } from "./table.js";
+export declare function assertReplicatedSchema(nodeCount: number, tables: Record<string, AnyTable>): void;

package/dist/assert-replicated-schema.js

@@ -0,0 +1,16 @@
+// src/assert-replicated-schema.ts
+import { isReplicatedEngine } from "./ddl-shared.js";
+// Без кластера в remote_servers DDL не разъезжается сам: таблицу создают на
+// каждой ноде руками. Обычный MergeTree на нескольких нодах — это две
+// независимые таблицы, которые тихо разойдутся по данным, поэтому при
+// нескольких DDL-нодах принимаем только Replicated-движки.
+export function assertReplicatedSchema(nodeCount, tables) {
+    if (nodeCount < 2)
+        return;
+    for (const name in tables) {
+        if (!isReplicatedEngine(tables[name])) {
+            throw new Error(`Table "${name}" must use a Replicated* engine (set \`replication\`) ` +
+                `when DDL targets ${nodeCount} nodes`);
+        }
+    }
+}

package/dist/build-count-query.js

@@ -1,4 +1,5 @@
 // src/build-count-query.ts
+import { countExpr } from "./sql-shared.js";
 import { buildFindManyQuery } from "./build-find-many-query.js";
 export function buildCountQuery(database, tableName, table, where) {
     const inner = buildFindManyQuery(database, tableName, table, { where });
@@ -6,7 +7,7 @@ export function buildCountQuery(database, tableName, table, where) {
     // swap the projection for count()
     const from = inner.sql.indexOf(" FROM ");
     return {
-        sql: "SELECT count() AS count" + inner.sql.slice(from),
+        sql: `SELECT ${countExpr(table)} AS count` + inner.sql.slice(from),
         params: inner.params,
     };
 }

package/dist/build-create-dictionary-query.d.ts

@@ -0,0 +1,2 @@
+import type { AnyDictionary, DictionaryCredentials } from "./dictionary.js";
+export declare function buildCreateDictionarySQL(database: string, name: string, dict: AnyDictionary, credentials?: DictionaryCredentials, mode?: "create" | "replace"): string;

package/dist/build-create-dictionary-query.js

@@ -0,0 +1,51 @@
+// src/build-create-dictionary-query.ts
+import { escapeId } from "./escape-id.js";
+import { quoteString } from "./ddl-shared.js";
+export function buildCreateDictionarySQL(database, name, dict, credentials, 
+// $migrate пересоздаёт словарь: IF NOT EXISTS оставил бы старое
+// определение (источник, учётку, атрибуты) навсегда
+mode = "create") {
+    const columns = [
+        ...Object.entries(dict.key),
+        ...Object.entries(dict.attributes),
+    ]
+        .map(([colName, col]) => `${escapeId(colName)} ${col.clickhouseType}`)
+        .join(",\n");
+    const keys = Object.keys(dict.key).map(escapeId).join(", ");
+    const auth = dict.source.user
+        ? { user: dict.source.user, password: dict.source.password }
+        : credentials;
+    const authSQL = auth
+        ? `USER ${quoteString(auth.user)} PASSWORD ${quoteString(auth.password ?? "")} `
+        : "";
+    // источник — тот же ClickHouse: запрос целиком, либо таблица с фильтром
+    const source = "query" in dict.source
+        ? `CLICKHOUSE(${authSQL}QUERY ${quoteString(dict.source.query)})`
+        : `CLICKHOUSE(${authSQL}DB ${quoteString(dict.source.database ?? database)} ` +
+            `TABLE ${quoteString(dict.source.table)}` +
+            (dict.source.where
+                ? ` WHERE ${quoteString(dict.source.where)}`
+                : "") +
+            ")";
+    const lifetime = typeof dict.lifetime === "number"
+        ? `LIFETIME(${dict.lifetime})`
+        : `LIFETIME(MIN ${dict.lifetime.min} MAX ${dict.lifetime.max})`;
+    const clauses = [
+        `PRIMARY KEY ${keys}`,
+        `SOURCE(${source})`,
+        `LAYOUT(${dict.layout.toUpperCase()}())`,
+        lifetime,
+    ];
+    if (dict.comment)
+        clauses.push(`COMMENT ${quoteString(dict.comment)}`);
+    const verb = mode === "replace"
+        ? "CREATE OR REPLACE DICTIONARY"
+        : "CREATE DICTIONARY IF NOT EXISTS";
+    return `
+    ${verb} ${escapeId(database)}.${escapeId(name)}
+    (
+      ${columns}
+    )
+    ${clauses.join("\n    ")}
+  `.trim();
+}

package/dist/build-find-many-query.js

@@ -12,7 +12,7 @@ export function buildFindManyQuery(database, tableName, table, args = {}) {
         }
     }
     const clauses = [
-        `SELECT ${selectSQL} FROM ${tableRef(database, tableName, table)}`,
+        `SELECT ${selectSQL} FROM ${tableRef(database, tableName, table, args.final)}`,
     ];
     // WHERE
     if (args.where) {

package/dist/build-index-sql.d.ts

@@ -0,0 +1,2 @@
+import type { IndexDefinition } from "./table.js";
+export declare function buildIndexSQL(index: IndexDefinition): string;

package/dist/build-index-sql.js

@@ -0,0 +1,11 @@
+// src/build-index-sql.ts
+import { escapeId } from "./escape-id.js";
+import { renderKeyPart } from "./ddl-shared.js";
+export function buildIndexSQL(index) {
+    const args = index.args?.length ? `(${index.args.join(", ")})` : "";
+    const granularity = index.granularity !== undefined
+        ? ` GRANULARITY ${index.granularity}`
+        : "";
+    return (`INDEX ${escapeId(index.name)} ${renderKeyPart(index.expr)} ` +
+        `TYPE ${index.type}${args}${granularity}`);
+}

package/dist/client.d.ts

@@ -1,18 +1,32 @@
+import { type ClickHouseClient } from "@clickhouse/client";
 import { TableClient } from "./table-client.js";
 import { AnyTable, InferRow } from "./table.js";
+import type { AnyDictionary } from "./dictionary.js";
 import { MigrationPlan } from "./migrate.js";
+import { type DdlStatement } from "./ensure-tables-on-nodes.js";
+import { type QueryJsonResult, type QueryOptions } from "./query.js";
 type ClientOptions = {
     url: string;
     username?: string;
     password?: string;
     database?: string;
     autoCreateDatabase?: boolean;
+    ddlNodes?: string[];
+    requestTimeoutMs?: number;
+};
+export type DdlPlan = MigrationPlan & {
+    executed: DdlStatement[];
 };
 export declare function createClient<TSchema extends {
     database?: string;
     tables: Record<string, AnyTable>;
+    dictionaries?: Record<string, AnyDictionary>;
 }>(schema: TSchema, options: ClientOptions): { [K in keyof TSchema["tables"]]: TableClient<InferRow<TSchema["tables"][K]>>; } & {
-    $init(): Promise<void>;
-    $migrate(): Promise<MigrationPlan>;
+    $init(): Promise<DdlStatement[]>;
+    $migrate(): Promise<DdlPlan>;
+    $query<TRow>(sql: string, opts?: QueryOptions): Promise<TRow[]>;
+    $queryJson<TRow, TTotals = TRow>(sql: string, opts?: QueryOptions): Promise<QueryJsonResult<TRow, TTotals>>;
+    $command(sql: string, opts?: Omit<QueryOptions, "columns">): Promise<void>;
+    $close(): Promise<void>;
 };
-export {};
+export type { ClickHouseClient };

package/dist/client.js

@@ -1,27 +1,37 @@
-import { createClient as createCHClient } from "@clickhouse/client";
+import { createClient as createCHClient, } from "@clickhouse/client";
 import { TableClient } from "./table-client.js";
-import { buildCreateTableSQL } from "./ddl.js";
-import { escapeId } from "./sql.js";
+import { escapeId } from "./escape-id.js";
 import { buildMigrationPlan } from "./migrate.js";
+import { assertReplicatedSchema } from "./assert-replicated-schema.js";
+import { ensureTablesOnNodes, } from "./ensure-tables-on-nodes.js";
+import { ensureDictionariesOnNodes } from "./ensure-dictionaries-on-nodes.js";
+import { runCommand, runQuery, runQueryJson, } from "./query.js";
 export function createClient(schema, options) {
     const database = options.database ?? schema.database ?? "default";
-    const ch = createCHClient({
-        url: options.url,
+    const dictionaries = schema.dictionaries ?? {};
+    const connect = (url, withDatabase) => createCHClient({
+        url,
         username: options.username,
         password: options.password,
-        database,
+        ...(withDatabase ? { database } : {}),
+        ...(options.requestTimeoutMs ? { request_timeout: options.requestTimeoutMs } : {}),
     });
+    const ch = connect(options.url, true);
+    // клиенты DDL-нод создаются один раз; основная нода переиспользует `ch`
+    const ddlUrls = options.ddlNodes?.length ? options.ddlNodes : [options.url];
+    const nodes = ddlUrls.map((url) => ({
+        url,
+        client: url === options.url ? ch : connect(url, true),
+    }));
     const db = {};
     for (const tableName in schema.tables) {
         db[tableName] = new TableClient(database, tableName, schema.tables[tableName], ch);
     }
     const ensureDatabase = async () => {
-        if (options.autoCreateDatabase) {
-            const rootClient = createCHClient({
-                url: options.url,
-                username: options.username,
-                password: options.password,
-            });
+        if (!options.autoCreateDatabase)
+            return;
+        for (const node of nodes) {
+            const rootClient = connect(node.url, false);
             try {
                 await rootClient.command({
                     query: `CREATE DATABASE IF NOT EXISTS ${escapeId(database)}`,
@@ -32,15 +42,19 @@ export function createClient(schema, options) {
             }
         }
     };
+    const ensureEverywhere = async (dictionaryMode) => [
+        ...(await ensureTablesOnNodes(nodes, database, schema.tables)),
+        ...(await ensureDictionariesOnNodes(nodes, database, dictionaries, options.username
+            ? { user: options.username, password: options.password }
+            : undefined, dictionaryMode)),
+    ];
     db.$init = async () => {
+        assertReplicatedSchema(nodes.length, schema.tables);
         await ensureDatabase();
-        for (const tableName in schema.tables) {
-            const table = schema.tables[tableName];
-            const createSQL = buildCreateTableSQL(database, tableName, table);
-            await ch.command({ query: createSQL });
-        }
+        return ensureEverywhere("create");
     };
     db.$migrate = async () => {
+        assertReplicatedSchema(nodes.length, schema.tables);
         await ensureDatabase();
         const result = await ch.query({
             query: `
@@ -54,10 +68,23 @@ export function createClient(schema, options) {
         });
         const existing = await result.json();
         const plan = buildMigrationPlan(database, schema.tables, existing);
+        // план (CREATE недостающих, ALTER ADD/MODIFY) выполняется на первой
+        // ноде: реплицируемый ALTER сам разъезжается по репликам, а недостающие
+        // на репликах таблицы докладывает ensureTablesOnNodes копией SHOW CREATE
+        const executed = [];
         for (const statement of plan.statements) {
             await ch.command({ query: statement });
+            executed.push({ node: options.url, sql: statement });
         }
-        return plan;
+        executed.push(...(await ensureEverywhere("replace")));
+        return { ...plan, executed };
+    };
+    db.$query = (sql, opts) => runQuery(ch, sql, opts);
+    db.$queryJson = (sql, opts) => runQueryJson(ch, sql, opts);
+    db.$command = (sql, opts) => runCommand(ch, sql, opts);
+    db.$close = async () => {
+        for (const node of nodes)
+            await node.client.close();
     };
     return db;
 }

package/dist/column.d.ts

@@ -1,17 +1,46 @@
+export type ColumnDefault = {
+    kind: "DEFAULT" | "MATERIALIZED" | "ALIAS";
+    expr: string;
+};
 export type Column<T> = {
     clickhouseType: string;
     nullable: boolean;
+    default?: ColumnDefault;
+    codec?: string;
+    comment?: string;
     __type?: T;
 };
 type NullableColumn<C extends Column<unknown>> = C extends Column<infer T> ? Column<T | null> : never;
+type ColumnType<C extends Column<unknown>> = C extends Column<infer T> ? T : never;
 export declare const t: {
     string: () => Column<string>;
     uint8: () => Column<number>;
+    uint16: () => Column<number>;
+    uint32: () => Column<number>;
     uint64: () => Column<bigint>;
+    int8: () => Column<number>;
+    int16: () => Column<number>;
     int32: () => Column<number>;
+    int64: () => Column<bigint>;
+    float32: () => Column<number>;
+    float64: () => Column<number>;
+    decimal: (precision: number, scale: number) => Column<string>;
     boolean: () => Column<boolean>;
+    date: () => Column<Date>;
+    date32: () => Column<Date>;
     datetime: () => Column<Date>;
+    datetime64: (precision?: number, timezone?: string) => Column<Date>;
+    ipv4: () => Column<string>;
+    ipv6: () => Column<string>;
+    enum8<TValues extends Record<string, number>>(values: TValues): Column<keyof TValues & string>;
+    lowCardinality<C extends Column<unknown>>(col: C): C;
+    map<K extends Column<unknown>, V extends Column<unknown>>(key: K, value: V): Column<Record<string, ColumnType<V>>>;
     nullable<C extends Column<unknown>>(col: C): NullableColumn<C>;
-    array<C extends Column<unknown>>(col: C): Column<C extends Column<infer T> ? T[] : never>;
+    array<C extends Column<unknown>>(col: C): Column<ColumnType<C>[]>;
+    default<C extends Column<unknown>>(col: C, expr: string): C;
+    materialized<C extends Column<unknown>>(col: C, expr: string): C;
+    alias<C extends Column<unknown>>(col: C, expr: string): C;
+    codec<C extends Column<unknown>>(col: C, codec: string): C;
+    comment<C extends Column<unknown>>(col: C, comment: string): C;
 };
 export {};

package/dist/column.js

@@ -8,12 +8,50 @@ function makeColumn(clickhouseType, nullable = false) {
 export const t = {
     string: () => makeColumn("String"),
     uint8: () => makeColumn("UInt8"),
+    uint16: () => makeColumn("UInt16"),
+    uint32: () => makeColumn("UInt32"),
+    // 64-битные целые не помещаются в number без потерь — только bigint
     uint64: () => makeColumn("UInt64"),
+    int8: () => makeColumn("Int8"),
+    int16: () => makeColumn("Int16"),
     int32: () => makeColumn("Int32"),
+    int64: () => makeColumn("Int64"),
+    float32: () => makeColumn("Float32"),
+    float64: () => makeColumn("Float64"),
+    // Decimal отдаётся строкой: number потерял бы точность, а bigint не знает
+    // про дробную часть — арифметику ведёт вызывающий код
+    decimal: (precision, scale) => makeColumn(`Decimal(${precision}, ${scale})`),
     boolean: () => makeColumn("Bool"),
+    date: () => makeColumn("Date"),
+    date32: () => makeColumn("Date32"),
     datetime: () => makeColumn("DateTime"),
+    datetime64: (precision = 3, timezone) => makeColumn(timezone
+        ? `DateTime64(${precision}, '${timezone}')`
+        : `DateTime64(${precision})`),
+    ipv4: () => makeColumn("IPv4"),
+    ipv6: () => makeColumn("IPv6"),
+    // Enum8: TS-тип — объединение имён значений, на проводе те же строки
+    enum8(values) {
+        const items = Object.entries(values)
+            .map(([name, code]) => `'${name.replace(/'/g, "''")}' = ${code}`)
+            .join(", ");
+        return makeColumn(`Enum8(${items})`);
+    },
+    // LowCardinality не меняет TS-тип и признак nullable: это только способ
+    // хранения словарём, который для строк с малым числом значений даёт
+    // и сжатие, и быстрый GROUP BY
+    lowCardinality(col) {
+        return {
+            ...col,
+            clickhouseType: `LowCardinality(${col.clickhouseType})`,
+        };
+    },
+    map(key, value) {
+        return makeColumn(`Map(${key.clickhouseType}, ${value.clickhouseType})`);
+    },
     nullable(col) {
         return {
+            ...col,
             clickhouseType: `Nullable(${col.clickhouseType})`,
             nullable: true,
         };
@@ -21,4 +59,21 @@ export const t = {
     array(col) {
         return makeColumn(`Array(${col.clickhouseType})`);
     },
+    // модификаторы возвращают копию: одна фабрика может описывать несколько
+    // колонок разных таблиц, общий объект нельзя мутировать
+    default(col, expr) {
+        return { ...col, default: { kind: "DEFAULT", expr } };
+    },
+    materialized(col, expr) {
+        return { ...col, default: { kind: "MATERIALIZED", expr } };
+    },
+    alias(col, expr) {
+        return { ...col, default: { kind: "ALIAS", expr } };
+    },
+    codec(col, codec) {
+        return { ...col, codec };
+    },
+    comment(col, comment) {
+        return { ...col, comment };
+    },
 };

package/dist/ddl-shared.d.ts

@@ -0,0 +1,13 @@
+import type { EngineSpec } from "./engine.js";
+import type { Expr, KeyPart } from "./expr.js";
+import type { AnyTable } from "./table.js";
+export declare function isExpr(part: KeyPart): part is Expr;
+export declare function renderKeyPart(part: KeyPart): string;
+export declare function renderKeyList(parts: KeyPart[]): string;
+export declare function keyColumns(parts: KeyPart[]): string[];
+export declare function quoteString(value: string): string;
+export declare function engineFamily(engine: string | EngineSpec): string;
+export declare function isReplicatedEngine(table: AnyTable): boolean;
+export declare function isReplacingEngine(engine: string | EngineSpec): boolean;
+export declare function collapsingOf(engine: string | EngineSpec): EngineSpec["collapsing"] | undefined;
+export declare function renderEngine(table: AnyTable): string;

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,4 @@
 import { AnyTable } from "./table.js";
+import type { Column } from "./column.js";
+export declare function buildColumnSQL(name: string, col: Column<unknown>): string;
 export declare function buildCreateTableSQL(database: string, tableName: string, table: AnyTable): string;