@quark-fw/clisma 0.1.14 → 0.1.15

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,7 +1,7 @@
 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";
@@ -48,14 +48,27 @@ 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();
+        if (!opts?.dryRun)
+            await ensureDatabase();
         const result = await ch.query({
             query: `
 				SELECT table, name, type
@@ -68,6 +81,15 @@ 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
@@ -77,7 +99,12 @@ export function createClient(schema, options) {
             executed.push({ node: options.url, sql: statement });
         }
         executed.push(...(await ensureEverywhere("replace")));
-        return { ...plan, executed };
+        for (const statement of settings) {
+            const node = nodes.find((n) => n.url === statement.node);
+            await node.client.command({ query: statement.sql });
+            executed.push(statement);
+        }
+        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,12 @@
 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 +36,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/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,20 @@
 // 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 +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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/clisma",
-	"version": "0.1.14",
+	"version": "0.1.15",
 	"description": "Prisma-like typed client and schema migrator for ClickHouse",
 	"keywords": [
 		"clickhouse",