@quark-fw/clisma 0.1.14 → 0.1.16

package/README.md

@@ -255,6 +255,15 @@ const db = createClient(schema, {
 - таблицы нет → `CREATE TABLE`
 - колонки нет → `ALTER TABLE ... ADD COLUMN`
 - тип отличается → `ALTER TABLE ... MODIFY COLUMN`
+- объявленная в `settings` настройка отличается от `system.tables.engine_full` →
+  `ALTER TABLE ... MODIFY SETTING` (правка метаданных, данные не переписываются);
+  настройки, которых нет в схеме, не трогаются. Настройки — локальные метаданные
+  ноды и **не реплицируются**, поэтому сравниваются и меняются на каждой ноде из
+  `ddlNodes` отдельно (`plan.settings`: `{ node, sql }`)
+
+`db.$migrate({ dryRun: true })` только строит план: ничего не выполняет, не
+создаёт БД и таблицы на нодах (`executed` пустой) — проверка перед прогоном на
+живой базе.
 
 Возвращает `{ statements, warnings, executed }` — план, предупреждения и
 фактически выполненные SQL с нодой (`executed[].node`). Повторный запуск на
@@ -266,7 +275,7 @@ const db = createClient(schema, {
 - лишние колонки в БД **никогда не удаляются** — только warning;
 - сравнивается только тип колонки: кодеки, `DEFAULT`, комментарии в диффе не
   участвуют (в `ADD COLUMN` они рендерятся);
-- `ENGINE`, `ORDER BY`, `PARTITION BY`, индексы, TTL не диффятся — их
+- `ENGINE`, `ORDER BY`, `PARTITION BY`, индексы, TTL не диффятся (настройки — диффятся) — их
   изменение требует пересоздания таблицы вручную;
 - смена типа ключевой колонки (из `ORDER BY`/`PRIMARY KEY`) — ошибка до
   выполнения плана: сервер её всё равно отклонит, лучше упасть целиком, чем

package/dist/client.d.ts

@@ -15,15 +15,19 @@ type ClientOptions = {
     requestTimeoutMs?: number;
 };
 export type DdlPlan = MigrationPlan & {
+    settings: DdlStatement[];
     executed: DdlStatement[];
 };
+export type MigrateOptions = {
+    dryRun?: boolean;
+};
 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<DdlStatement[]>;
-    $migrate(): Promise<DdlPlan>;
+    $migrate(opts?: MigrateOptions): 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>;

package/dist/client.js

@@ -1,10 +1,11 @@
 import { createClient as createCHClient, } from "@clickhouse/client";
 import { TableClient } from "./table-client.js";
 import { escapeId } from "./escape-id.js";
-import { buildMigrationPlan } from "./migrate.js";
+import { buildMigrationPlan, buildSettingsPlan, parseEngineSettings, } 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 { MigrationError } from "./migration-error.js";
 import { runCommand, runQuery, runQueryJson, } from "./query.js";
 export function createClient(schema, options) {
     const database = options.database ?? schema.database ?? "default";
@@ -14,7 +15,9 @@ export function createClient(schema, options) {
         username: options.username,
         password: options.password,
         ...(withDatabase ? { database } : {}),
-        ...(options.requestTimeoutMs ? { request_timeout: options.requestTimeoutMs } : {}),
+        ...(options.requestTimeoutMs
+            ? { request_timeout: options.requestTimeoutMs }
+            : {}),
     });
     const ch = connect(options.url, true);
     // клиенты DDL-нод создаются один раз; основная нода переиспользует `ch`
@@ -23,6 +26,9 @@ export function createClient(schema, options) {
         url,
         client: url === options.url ? ch : connect(url, true),
     }));
+    // источник истины схемы: `url` может быть балансировщиком или нодой вне
+    // ddlNodes, и план с него разошёлся бы с тем, куда пишется DDL
+    const primary = nodes[0];
     const db = {};
     for (const tableName in schema.tables) {
         db[tableName] = new TableClient(database, tableName, schema.tables[tableName], ch);
@@ -48,15 +54,28 @@ export function createClient(schema, options) {
             ? { user: options.username, password: options.password }
             : undefined, dictionaryMode)),
     ];
+    const readTableSettings = async (client) => {
+        const result = await client.query({
+            query: `SELECT name, engine_full FROM system.tables WHERE database = {db:String}`,
+            query_params: { db: database },
+            format: "JSONEachRow",
+        });
+        const out = {};
+        for (const row of await result.json()) {
+            out[row.name] = parseEngineSettings(row.engine_full);
+        }
+        return out;
+    };
     db.$init = async () => {
         assertReplicatedSchema(nodes.length, schema.tables);
         await ensureDatabase();
         return ensureEverywhere("create");
     };
-    db.$migrate = async () => {
+    db.$migrate = async (opts) => {
         assertReplicatedSchema(nodes.length, schema.tables);
-        await ensureDatabase();
-        const result = await ch.query({
+        if (!opts?.dryRun)
+            await ensureDatabase();
+        const result = await primary.client.query({
             query: `
 				SELECT table, name, type
 				FROM system.columns
@@ -68,16 +87,46 @@ export function createClient(schema, options) {
         });
         const existing = await result.json();
         const plan = buildMigrationPlan(database, schema.tables, existing);
+        const settings = [];
+        for (const node of nodes) {
+            for (const sql of buildSettingsPlan(database, schema.tables, await readTableSettings(node.client))) {
+                settings.push({ node: node.url, sql });
+            }
+        }
+        // dryRun: только план — ни CREATE DATABASE, ни DDL на нодах
+        if (opts?.dryRun)
+            return { ...plan, settings, executed: [] };
         // план (CREATE недостающих, ALTER ADD/MODIFY) выполняется на первой
         // ноде: реплицируемый ALTER сам разъезжается по репликам, а недостающие
-        // на репликах таблицы докладывает ensureTablesOnNodes копией SHOW CREATE
+        // на репликах таблицы докладывает ensureTablesOnNodes копией SHOW CREATE.
+        // Сбой посередине — MigrationError со списком уже выполненного
         const executed = [];
-        for (const statement of plan.statements) {
-            await ch.command({ query: statement });
-            executed.push({ node: options.url, sql: statement });
+        const run = async (node, sql) => {
+            try {
+                await node.client.command({ query: sql });
+            }
+            catch (cause) {
+                throw new MigrationError({
+                    executed,
+                    failed: { node: node.url, sql },
+                    cause,
+                });
+            }
+            executed.push({ node: node.url, sql });
+        };
+        for (const statement of plan.statements)
+            await run(primary, statement);
+        try {
+            executed.push(...(await ensureEverywhere("replace")));
+        }
+        catch (cause) {
+            throw new MigrationError({ executed, cause });
+        }
+        for (const statement of settings) {
+            const node = nodes.find((n) => n.url === statement.node);
+            await run(node, statement.sql);
         }
-        executed.push(...(await ensureEverywhere("replace")));
-        return { ...plan, executed };
+        return { ...plan, settings, executed };
     };
     db.$query = (sql, opts) => runQuery(ch, sql, opts);
     db.$queryJson = (sql, opts) => runQueryJson(ch, sql, opts);

package/dist/ddl.d.ts

@@ -1,4 +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

@@ -2,6 +2,14 @@
 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)
@@ -30,12 +38,7 @@ export function buildCreateTableSQL(database, tableName, table) {
     if (table.ttl)
         clauses.push(`TTL ${table.ttl}`);
     if (table.settings && Object.keys(table.settings).length) {
-        const settings = Object.entries(table.settings)
-            .map(([key, value]) => typeof value === "number"
-            ? `${key} = ${value}`
-            : `${key} = ${quoteString(value)}`)
-            .join(", ");
-        clauses.push(`SETTINGS ${settings}`);
+        clauses.push(`SETTINGS ${renderSettings(table.settings)}`);
     }
     if (table.comment)
         clauses.push(`COMMENT ${quoteString(table.comment)}`);

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./table-client.js";
 export * from "./rows.js";
 export * from "./migrate.js";
 export * from "./ddl.js";
+export * from "./migration-error.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

@@ -11,4 +11,5 @@ export * from "./table-client.js";
 export * from "./rows.js";
 export * from "./migrate.js";
 export * from "./ddl.js";
+export * from "./migration-error.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,7 +1,22 @@
 // src/migrate.ts
-import { buildColumnSQL, buildCreateTableSQL } from "./ddl.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 = [];
@@ -50,3 +65,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/migration-error.d.ts

@@ -0,0 +1,10 @@
+import type { DdlStatement } from "./ensure-tables-on-nodes.js";
+export declare class MigrationError extends Error {
+    readonly executed: DdlStatement[];
+    readonly failed?: DdlStatement;
+    constructor(args: {
+        executed: DdlStatement[];
+        failed?: DdlStatement;
+        cause: unknown;
+    });
+}

package/dist/migration-error.js

@@ -0,0 +1,24 @@
+// src/migration-error.ts
+// DDL в ClickHouse не транзакционен: упавший посередине $migrate оставляет
+// выполненную часть на нодах. Без списка выполненного вызывающий не знает,
+// что уже применено, поэтому ошибка несёт его вместе с упавшим оператором.
+export class MigrationError extends Error {
+    // успешно выполненные до сбоя операторы, в порядке выполнения
+    executed;
+    // упавший оператор; нет, если сбой внутри докладки таблиц/словарей на
+    // ноды — тогда их выполненная часть видна только по самим нодам
+    failed;
+    constructor(args) {
+        const reason = args.cause instanceof Error
+            ? args.cause.message
+            : String(args.cause);
+        super(`$migrate failed after ${args.executed.length} statement(s)` +
+            (args.failed
+                ? ` on ${args.failed.node}: ${args.failed.sql}`
+                : "") +
+            `\n${reason}`, { cause: args.cause });
+        this.name = "MigrationError";
+        this.executed = args.executed;
+        this.failed = args.failed;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/clisma",
-	"version": "0.1.14",
+	"version": "0.1.16",
 	"description": "Prisma-like typed client and schema migrator for ClickHouse",
 	"keywords": [
 		"clickhouse",
@@ -31,9 +31,9 @@
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
 		"typecheck": "tsc --noEmit",
-		"test": "tsx --env-file=./src/test/.env ./src/test/index.ts",
-		"test:unit": "tsx --test src/test/unit.test.ts src/test/ddl.test.ts",
-		"prepublishOnly": "npm run typecheck && npm run test:unit && npm run build"
+		"test:integration": "tsx --env-file=./src/test/.env ./src/test/index.ts",
+		"test": "tsx --test src/test/unit.test.ts src/test/ddl.test.ts src/test/migrate-nodes.test.ts",
+		"prepublishOnly": "npm run typecheck && npm test && npm run build"
 	},
 	"dependencies": {
 		"@clickhouse/client": "^1.17.0"