@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/clickhouse/plan/diff.js

@@ -0,0 +1,312 @@
+/**
+ * The diff between two ClickHouse schemas, each change classified.
+ *
+ * Identity (#3047 question 3):
+ *
+ * - An object is identified by its export name between two revisions of the
+ *   declarations, so a changed name in the SQL under the same export is a
+ *   rename, not a drop and a create. Against a live server, which has no
+ *   export names, it is identified by `database.name`, and a declaration
+ *   carrying `-- previously: <old name>` before its CREATE is matched to the
+ *   object of that name.
+ * - A column is identified by its name: the SQL form has no column key apart
+ *   from the name. A column renamed in place says so with
+ *   `-- previously: <old name>` on its line; without the hint a renamed
+ *   column reads as a drop and an add, and the diff points that out when the
+ *   two look alike.
+ */
+import { CLASSIFIER_RULES } from "./rules.js";
+import { MERGE_TREE_SETTINGS } from "../../generated/clickhouse.js";
+import { classifiedChange } from "../../core/classifier.js";
+import { changedEntries, matchByIdentity } from "../../core/diff.js";
+const qualified = (o) => (o.database ? `${o.database}.${o.name}` : o.name);
+function change(object, field, rule, before, after, extra = {}) {
+    return classifiedChange(CLASSIFIER_RULES, object, field, rule, before, after, extra);
+}
+/** The column names a key expression mentions. */
+function keyColumns(o) {
+    const out = new Set();
+    for (const k of [o.orderBy, o.primaryKey ?? o.orderBy, o.partitionBy, o.sampleBy]) {
+        for (const word of (k ?? "").split(" "))
+            if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(word))
+                out.add(word);
+    }
+    return out;
+}
+const elements = (key) => (key ? key.replace(/^\( (.*) \)$/, "$1").split(" , ") : []);
+/** An ORDER BY change that only appends columns the same change adds (MODIFY ORDER BY). */
+function appendsAddedColumns(before, after, added) {
+    const b = elements(before);
+    const a = elements(after);
+    if (a.length <= b.length || b.some((e, i) => a[i] !== e))
+        return false;
+    return a.slice(b.length).every((e) => added.has(e));
+}
+function diffColumns(key, before, after, out, hints) {
+    const keys = keyColumns(before);
+    const pk = new Set(elements(before.primaryKey ?? before.orderBy).flatMap((e) => e.split(" ")));
+    const byName = new Map(before.columns.map((c) => [c.name, c]));
+    const afterNames = new Set(after.columns.map((c) => c.name));
+    const matched = new Set();
+    const added = new Set();
+    for (const a of after.columns) {
+        let b = byName.get(a.name);
+        if (!b && a.previously && byName.has(a.previously) && !afterNames.has(a.previously)) {
+            b = byName.get(a.previously);
+            out.push(change(key, `columns.${a.name}`, keys.has(b.name) ? "SQLCH213" : "SQLCH212", b.name, a.name));
+        }
+        if (!b) {
+            added.add(a.name);
+            out.push(change(key, `columns.${a.name}`, "SQLCH201", undefined, a.text));
+            continue;
+        }
+        matched.add(b.name);
+        const field = (f) => `columns.${a.name}.${f}`;
+        if (a.type !== b.type || (a.nullable ?? false) !== (b.nullable ?? false)) {
+            out.push(change(key, field("type"), pk.has(b.name) || keys.has(b.name) ? "SQLCH211" : "SQLCH210", b.type, a.type));
+        }
+        if (a.defaultKind !== b.defaultKind || a.defaultExpr !== b.defaultExpr) {
+            out.push(change(key, field("default"), "SQLCH207", [b.defaultKind, b.defaultExpr].filter(Boolean).join(" "), [a.defaultKind, a.defaultExpr].filter(Boolean).join(" ")));
+        }
+        if (a.codec !== b.codec)
+            out.push(change(key, field("codec"), "SQLCH208", b.codec, a.codec));
+        if (a.ttl !== b.ttl)
+            out.push(change(key, field("ttl"), "SQLCH205", b.ttl, a.ttl));
+        if (a.comment !== b.comment)
+            out.push(change(key, field("comment"), "SQLCH203", b.comment, a.comment));
+    }
+    const dropped = before.columns.filter((c) => !matched.has(c.name));
+    for (const b of dropped) {
+        out.push(change(key, `columns.${b.name}`, keys.has(b.name) ? "SQLCH213" : "SQLCH202", b.text, undefined, { destructive: true }));
+        const twin = after.columns.find((a) => added.has(a.name) && a.type === b.type && a.position === b.position);
+        if (twin) {
+            hints.push(`${key}: column ${b.name} is dropped and ${twin.name} added with the same type in the same place. ` +
+                `If it is a rename, write \`-- previously: ${b.name}\` on ${twin.name}'s line.`);
+        }
+    }
+    // Order, among the columns both sides have (a renamed column by its old name).
+    const beforeOrder = before.columns.map((c) => c.name).filter((n) => matched.has(n));
+    const afterOrder = after.columns
+        .map((c) => (byName.has(c.name) ? c.name : c.previously && matched.has(c.previously) ? c.previously : undefined))
+        .filter((n) => n !== undefined && matched.has(n));
+    if (beforeOrder.join(",") !== afterOrder.join(","))
+        out.push(change(key, "columns.order", "SQLCH209", beforeOrder.join(", "), afterOrder.join(", ")));
+    return added;
+}
+function diffMap(key, field, before, after, rule, out) {
+    for (const name of changedEntries(before, after))
+        out.push(change(key, `${field}.${name}`, rule, before[name], after[name]));
+}
+/**
+ * The clauses chant does not read (#3872), compared as text. One the
+ * declaration has and the server does not, or has differently, is a change
+ * to review (SQLCH290). One only the server prints is a hint, not a change: a
+ * clause a new server prints with its default cannot be told from one
+ * removed from the declaration.
+ */
+function diffUnparsed(key, before, after, out, hints) {
+    const b = before.unparsed ?? {};
+    const a = after.unparsed ?? {};
+    for (const clause of Object.keys(a)) {
+        if (b[clause] !== a[clause])
+            out.push(change(key, `unparsed.${clause}`, "SQLCH290", b[clause], a[clause], { note: "chant does not read this clause; review the change" }));
+    }
+    for (const clause of Object.keys(b)) {
+        if (!(clause in a))
+            hints.push(`${key}: the current definition has ${clause} (${b[clause]}), a clause chant does not read and the declaration does not have; it is not compared`);
+    }
+}
+function diffObject(key, before, after, out, hints) {
+    diffUnparsed(key, before, after, out, hints);
+    if (before.kind !== after.kind) {
+        out.push(change(key, "kind", "SQLCH224", before.kind, after.kind, { destructive: before.kind === "table" }));
+        return;
+    }
+    if (qualified(before) !== qualified(after)) {
+        out.push(change(key, "name", before.kind === "database" ? "SQLCH231" : "SQLCH230", qualified(before), qualified(after)));
+    }
+    if (before.comment !== after.comment)
+        out.push(change(key, "comment", "SQLCH203", before.comment, after.comment));
+    if (before.kind === "database") {
+        // A declaration with no ENGINE takes the server's default database engine
+        // (Atomic; Replicated on Cloud), whatever the server says it is (#3645).
+        if (after.engine !== undefined && before.engine !== after.engine)
+            out.push(change(key, "engine", "SQLCH232", before.engine, after.engine));
+        return;
+    }
+    if (before.kind === "user" || before.kind === "role" || before.kind === "rowPolicy") {
+        const rule = before.kind === "user" ? "SQLCH271" : before.kind === "role" ? "SQLCH270" : "SQLCH272";
+        const b = before.access ?? {};
+        const a = after.access ?? {};
+        const order = ["identified", "host", "validUntil", "defaultRole", "defaultDatabase", "grantees", "settings", "as", "for", "using", "to"];
+        const fields = [...new Set([...Object.keys(b), ...Object.keys(a)])].sort((x, y) => order.indexOf(x) - order.indexOf(y));
+        for (const field of fields) {
+            // A user's authentication is compared only when the declaration says it.
+            if (before.kind === "user" && field === "identified" && a.identified === undefined)
+                continue;
+            if (b[field] !== a[field])
+                out.push(change(key, field, rule, b[field], a[field]));
+        }
+        return;
+    }
+    if (before.kind === "quota" || before.kind === "settingsProfile") {
+        const rule = before.kind === "quota" ? "SQLCH275" : "SQLCH276";
+        const b = before.access ?? {};
+        const a = after.access ?? {};
+        // In the order the server prints them: the key, each interval by length, the settings, whom it applies to.
+        const rank = (f) => (f === "keyed" ? 0 : f.startsWith("interval.") ? 1 + Number(f.slice("interval.".length)) / 1e9 : f === "settings" ? 2 : 3);
+        const fields = [...new Set([...Object.keys(b), ...Object.keys(a)])].sort((x, y) => rank(x) - rank(y));
+        for (const field of fields)
+            if (b[field] !== a[field])
+                out.push(change(key, field, rule, b[field], a[field]));
+        return;
+    }
+    if (before.kind === "grants") {
+        const b = before.access ?? {};
+        const a = after.access ?? {};
+        for (const atom of Object.keys(b))
+            if (!(atom in a))
+                out.push(change(key, `grants.${atom}`, "SQLCH274", atom, undefined));
+        for (const atom of Object.keys(a))
+            if (!(atom in b))
+                out.push(change(key, `grants.${atom}`, "SQLCH273", undefined, atom));
+        return;
+    }
+    if (before.kind === "function") {
+        if (before.lambda !== after.lambda)
+            out.push(change(key, "lambda", "SQLCH260", before.lambda, after.lambda));
+        return;
+    }
+    if (before.kind === "dictionary") {
+        diffDictionary(key, before, after, out);
+        return;
+    }
+    if (before.kind === "view") {
+        if (before.select !== after.select)
+            out.push(change(key, "select", "SQLCH240", before.select, after.select));
+        return;
+    }
+    if (before.kind === "materializedView") {
+        if (before.to !== after.to)
+            out.push(change(key, "to", "SQLCH242", before.to, after.to));
+        if (before.select !== after.select)
+            out.push(change(key, "select", "SQLCH241", before.select, after.select, { note: "rows already in the target are not recomputed" }));
+        if (before.refresh !== after.refresh)
+            out.push(change(key, "refresh", "SQLCH244", before.refresh, after.refresh));
+        for (const f of ["engine", "orderBy", "primaryKey", "partitionBy", "sampleBy", "ttl"]) {
+            if (before[f] !== after[f])
+                out.push(change(key, f, "SQLCH243", before[f], after[f]));
+        }
+        return;
+    }
+    if (before.asFunction !== undefined || after.asFunction !== undefined) {
+        diffTableFunction(key, before, after, out);
+        return;
+    }
+    // A table.
+    if (before.engine !== after.engine)
+        out.push(change(key, "engine", "SQLCH223", before.engine, after.engine));
+    const added = diffColumns(key, before, after, out, hints);
+    const beforePk = before.primaryKey ?? before.orderBy;
+    const afterPk = after.primaryKey ?? after.orderBy;
+    if (before.orderBy !== after.orderBy) {
+        const append = appendsAddedColumns(before.orderBy, after.orderBy, added) && beforePk === afterPk;
+        out.push(change(key, "orderBy", append ? "SQLCH216" : "SQLCH220", before.orderBy, after.orderBy, {
+            ...(appendsAddedColumns(before.orderBy, after.orderBy, added) && beforePk !== afterPk
+                ? { note: `appending new columns keeps the primary key; declare PRIMARY KEY ${beforePk} to make this an ALTER` }
+                : {}),
+        }));
+    }
+    if (beforePk !== afterPk && !(before.orderBy !== after.orderBy && before.primaryKey === undefined && after.primaryKey === undefined)) {
+        out.push(change(key, "primaryKey", "SQLCH221", beforePk, afterPk));
+    }
+    if (before.partitionBy !== after.partitionBy)
+        out.push(change(key, "partitionBy", "SQLCH222", before.partitionBy, after.partitionBy));
+    if (before.sampleBy !== after.sampleBy)
+        out.push(change(key, "sampleBy", "SQLCH217", before.sampleBy, after.sampleBy));
+    if (before.ttl !== after.ttl)
+        out.push(change(key, "ttl", "SQLCH205", before.ttl, after.ttl));
+    for (const name of changedEntries(before.settings, after.settings)) {
+        const spec = MERGE_TREE_SETTINGS[name];
+        out.push(change(key, `settings.${name}`, spec?.readonly ? "SQLCH218" : "SQLCH206", before.settings[name], after.settings[name]));
+    }
+    diffMap(key, "indexes", before.indexes, after.indexes, "SQLCH204", out);
+    diffMap(key, "projections", before.projections, after.projections, "SQLCH214", out);
+    diffMap(key, "constraints", before.constraints, after.constraints, "SQLCH215", out);
+}
+/**
+ * A table over a table function (#3911), on either side. It stores nothing,
+ * so every change but its comment replaces it (SQLCH219); a table with data
+ * of its own becoming one would lose that data, which is a rebuild
+ * (SQLCH223). A declaration with no column list takes the columns the server
+ * infers, so they are compared only when it lists them.
+ */
+function diffTableFunction(key, before, after, out) {
+    if (before.asFunction === undefined) {
+        out.push(change(key, "asFunction", "SQLCH223", before.engine, `AS ${after.asFunction}`));
+        return;
+    }
+    if (before.asFunction !== after.asFunction)
+        out.push(change(key, "asFunction", "SQLCH219", before.asFunction, after.asFunction));
+    if (after.asFunction !== undefined && after.columns.length === 0)
+        return;
+    const column = (c) => [c.type, c.nullable ? "NULL" : "", c.defaultKind ?? "", c.defaultExpr ?? "", c.codec ? `CODEC(${c.codec})` : "", c.comment ? `COMMENT ${c.comment}` : ""].filter(Boolean).join(" ");
+    const b = new Map(before.columns.map((c) => [c.name, column(c)]));
+    const a = new Map(after.columns.map((c) => [c.name, column(c)]));
+    for (const name of new Set([...b.keys(), ...a.keys()])) {
+        if (b.get(name) !== a.get(name))
+            out.push(change(key, `columns.${name}`, "SQLCH219", b.get(name), a.get(name)));
+    }
+    const order = (o) => o.columns.map((c) => c.name).join(", ");
+    if (order(before) !== order(after) && a.size === b.size && [...a.keys()].every((n) => b.has(n)))
+        out.push(change(key, "columns.order", "SQLCH219", order(before), order(after)));
+}
+/** A dictionary: every change but its comment replaces it (SQLCH245). */
+function diffDictionary(key, before, after, out) {
+    const attribute = (c) => [c.type, c.defaultExpr !== undefined ? `DEFAULT ${c.defaultExpr}` : "", c.expression !== undefined ? `EXPRESSION ${c.expression}` : "", c.flags ?? ""].filter(Boolean).join(" ");
+    const b = new Map(before.columns.map((c) => [c.name, attribute(c)]));
+    const a = new Map(after.columns.map((c) => [c.name, attribute(c)]));
+    for (const name of new Set([...b.keys(), ...a.keys()])) {
+        if (b.get(name) !== a.get(name))
+            out.push(change(key, `columns.${name}`, "SQLCH245", b.get(name), a.get(name)));
+    }
+    const order = (o) => o.columns.map((c) => c.name).join(", ");
+    if (order(before) !== order(after) && [...a.keys()].every((n) => b.has(n)) && a.size === b.size)
+        out.push(change(key, "columns.order", "SQLCH245", order(before), order(after)));
+    for (const f of ["primaryKey", "dataSource", "layout", "lifetime", "range"]) {
+        if (before[f] !== after[f])
+            out.push(change(key, f, "SQLCH245", before[f], after[f]));
+    }
+    for (const name of changedEntries(before.settings, after.settings))
+        out.push(change(key, `settings.${name}`, "SQLCH245", before.settings[name], after.settings[name]));
+}
+/**
+ * Diff two schemas. `before` and `after` are matched by key; an `after`
+ * object whose key is new but whose `previously` names a `before` object
+ * with no `after` counterpart is that object, renamed.
+ */
+export function diffSchemas(before, after) {
+    const changes = [];
+    const hints = [];
+    const matches = matchByIdentity(before, after, {
+        qualified,
+        // A function, a user, a role, a row policy and a grantee's grants are not renamed: one under a new name is a create.
+        previously: (o) => (o.kind === "function" || o.kind === "user" || o.kind === "role" || o.kind === "rowPolicy" || o.kind === "quota" || o.kind === "settingsProfile" || o.kind === "grants" ? undefined : o.previously),
+        previousNames: (o, prev) => [prev, `${o.database}.${prev}`],
+    });
+    for (const m of matches) {
+        if (m.kind === "created")
+            changes.push(change(m.after.key, "object", "SQLCH200", undefined, qualified(m.after.canonical)));
+        else if (m.kind === "matched")
+            diffObject(m.after.key, m.before.canonical, m.after.canonical, changes, hints);
+        else if (m.before.canonical.foreign) {
+            // A migration runner's history table (#3676): not chant's to drop.
+            hints.push(`${qualified(m.before.canonical)} is kept by ${m.before.canonical.foreign}; it is not chant's to drop and is left alone`);
+        }
+        else {
+            const b = m.before;
+            changes.push(change(b.key, "object", "SQLCH250", qualified(b.canonical), undefined, { destructive: b.canonical.kind === "table" || b.canonical.kind === "materializedView" }));
+        }
+    }
+    return { changes, rebuilds: changes.filter((c) => c.class === "rebuild"), hints };
+}

package/dist/clickhouse/plan/disruption.js

@@ -0,0 +1,73 @@
+/**
+ * `classifyDisruption()`: what applying a pending update costs, from the
+ * paths `chant lifecycle plan` reports changed, mapped onto the classifier's
+ * rules (`./rules.ts`). A metadata-only change is `in-place`, a background
+ * rewrite `rolling`, a rebuild `replace`.
+ *
+ * A path alone cannot always say which rule applies: a column type change is a
+ * rewrite, or a rebuild when the column is in a key. Those answer `unknown`,
+ * naming both rules; `chant sql plan` resolves them with the whole definition
+ * in hand.
+ */
+import { MERGE_TREE_SETTINGS } from "../../generated/clickhouse.js";
+import { classifyDisruptionWith } from "../../core/classifier.js";
+import { CHANGE_CLASSES, CLASSIFIER_RULES } from "./rules.js";
+function ruleFor(path) {
+    const root = path.split(/[.[]/)[0];
+    if (root === "name" || root === "database")
+        return "SQLCH230";
+    if (root === "comment")
+        return "SQLCH203";
+    if (root === "engine")
+        return "SQLCH223";
+    if (root === "orderBy")
+        return "ambiguous";
+    if (root === "primaryKey")
+        return "SQLCH221";
+    if (root === "partitionBy")
+        return "SQLCH222";
+    if (root === "sampleBy")
+        return "SQLCH217";
+    if (root === "ttl")
+        return "SQLCH205";
+    if (root === "indexes")
+        return "SQLCH204";
+    if (root === "projections")
+        return "SQLCH214";
+    if (root === "constraints")
+        return "SQLCH215";
+    if (root === "select")
+        return "SQLCH240";
+    if (root === "refresh")
+        return "SQLCH244";
+    if (root === "settings") {
+        const key = path.split(".")[1];
+        const spec = key ? MERGE_TREE_SETTINGS[key] : undefined;
+        return spec?.readonly ? "SQLCH218" : "SQLCH206";
+    }
+    if (root === "columns") {
+        const field = /^columns\[\d+\]\.(\w+)/.exec(path)?.[1];
+        if (field === undefined)
+            return "ambiguous"; // a column added, dropped or moved
+        if (field === "type" || field === "nullable" || field === "name")
+            return "ambiguous";
+        if (field === "default")
+            return "SQLCH207";
+        if (field === "codec")
+            return "SQLCH208";
+        if (field === "ttl")
+            return "SQLCH205";
+        if (field === "comment")
+            return "SQLCH203";
+    }
+    return undefined;
+}
+export function classifyDisruption(options) {
+    return classifyDisruptionWith({
+        typePrefix: "ClickHouse::",
+        rules: CLASSIFIER_RULES,
+        classes: CHANGE_CLASSES,
+        ruleFor,
+        ambiguousDetail: "a sorting-key or column change is metadata, a rewrite or a rebuild depending on the whole definition; `chant sql plan` classifies it",
+    }, options);
+}