@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/clickhouse/apply/statements.js

@@ -0,0 +1,545 @@
+/**
+ * The statements that make one classified change (#3208): a `CREATE` with
+ * chant's marker in its comment, the `ALTER`s for the metadata and
+ * background-rewrite classes, and the `DROP` a prune issues.
+ *
+ * Each function here takes a declared object and the changes the classifier
+ * reported for it, and returns SQL; nothing is sent. The applier
+ * (`./apply.ts`) sends them, and the rebuild migration (#3198) builds its new
+ * table and swaps it in with the same pieces.
+ *
+ * The SQL is taken from the declaration's own text wherever it can be: a
+ * column's definition, an index's expression, a TTL, a setting's value are
+ * the spans the parser found in the declared `CREATE`, not the normalized
+ * forms the classifier compared. The normalized form is for comparing; what
+ * the server is sent is what the author wrote.
+ */
+import { isTrivia, tokenizeText } from "../tokens.js";
+import { parseCreate } from "../parser.js";
+import { canonicalObject } from "../plan/normalize.js";
+import { CLASSIFIER_RULES } from "../plan/rules.js";
+import { stampedComment } from "../ownership.js";
+import { CLICKHOUSE_ENTITY_TYPES } from "../entities.js";
+import { renderFor } from "../topology.js";
+import { accessClauseText, alterAccessField, alterQuotaOrProfileField, grantStatement, revokeStatement, SECRETLESS } from "../access.js";
+/** A backquoted identifier. */
+export const ident = (name) => `\`${name.replace(/`/g, "``")}\``;
+/** `database.name` backquoted, or a database's bare name. */
+export const qualifiedIdent = (database, name) => database !== undefined ? `${ident(database)}.${ident(name)}` : ident(name);
+/** A single-quoted string literal. */
+export const sqlString = (value) => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+/** `db.name` split at its first dot. */
+export function splitQualified(name) {
+    const at = name.indexOf(".");
+    return at < 0 ? { name } : { database: name.slice(0, at), name: name.slice(at + 1) };
+}
+/** The step for a statement that makes a change under `rule`: a rewrite-class rule waits on its mutation. */
+export function stepFor(sql, rule) {
+    const cls = CLASSIFIER_RULES[rule].class;
+    return { sql, rewrite: cls === "rewrite", rule, class: cls };
+}
+const parsedCache = new WeakMap();
+function parsed(obj) {
+    let p = parsedCache.get(obj);
+    if (!p) {
+        const tokens = tokenizeText(obj.ddl, 0);
+        p = { tokens, node: parseCreate(tokens) };
+        parsedCache.set(obj, p);
+    }
+    return p;
+}
+const text = (tokens, span) => span && span.to > span.from
+    ? tokens
+        .slice(span.from, span.to)
+        .map((t) => t.text)
+        .join("")
+        .trim()
+    : undefined;
+/** The object's name on the server, quoted. */
+export const objectIdent = (obj) => qualifiedIdent(obj.canonical.database, obj.canonical.name);
+/** The statement's end, past its significant tokens: trailing whitespace, comments and a `;` left out. */
+function statementBody(tokens) {
+    let end = tokens.length;
+    while (end > 0 && (isTrivia(tokens[end - 1]) || tokens[end - 1].text === ";"))
+        end--;
+    return tokens
+        .slice(0, end)
+        .map((t) => t.text)
+        .join("");
+}
+/**
+ * The declared `CREATE` with chant's ownership marker in its comment: the
+ * declared comment, if any, with the trailer after it, or a `COMMENT` clause
+ * added at the end. Set in the `CREATE` itself, so no object is ever created
+ * unmarked. `orReplace` turns `CREATE VIEW` into `CREATE OR REPLACE VIEW`;
+ * `trailer` adds pairs to the marker (the rebuild migration's working
+ * objects, `../rebuild/`).
+ */
+export function createStatement(obj, marker, opts = {}) {
+    const { tokens, node } = parsed(obj);
+    // A function has no comment to carry the marker: it is sent as declared.
+    if (node.statement === "function") {
+        const body = statementBody(tokens);
+        return opts.orReplace && !node.orReplace ? body.replace(/^(\s*(?:--[^\n]*\n\s*)*)CREATE\s+/i, "$1CREATE OR REPLACE ") : body;
+    }
+    const literal = sqlString(stampedComment(obj.canonical.comment, marker, opts.trailer));
+    let sql;
+    if (node.comment) {
+        sql =
+            tokens
+                .slice(0, node.comment.from)
+                .map((t) => t.text)
+                .join("") +
+                literal +
+                statementBody(tokens.slice(node.comment.to));
+    }
+    else {
+        sql = `${statementBody(tokens)} COMMENT ${literal}`;
+    }
+    if (opts.orReplace && (node.statement === "view" || node.statement === "dictionary" || node.statement === "table") && !node.orReplace) {
+        sql = sql.replace(/^(\s*(?:--[^\n]*\n\s*)*)CREATE\s+/i, "$1CREATE OR REPLACE ");
+    }
+    return sql;
+}
+/** Restamp the object's comment: the declared comment with this project's marker. */
+export function commentStatement(obj, marker) {
+    const literal = sqlString(stampedComment(obj.canonical.comment, marker));
+    return obj.type === CLICKHOUSE_ENTITY_TYPES.database
+        ? `ALTER DATABASE ${objectIdent(obj)} MODIFY COMMENT ${literal}`
+        : `ALTER TABLE ${objectIdent(obj)} MODIFY COMMENT ${literal}`;
+}
+/** The `DROP` for an object a prune removes. `SYNC` so the name is free when it returns. */
+export function dropStatement(type, database, name) {
+    if (type === CLICKHOUSE_ENTITY_TYPES.database)
+        return `DROP DATABASE ${ident(name)} SYNC`;
+    if (type === CLICKHOUSE_ENTITY_TYPES.function)
+        return `DROP FUNCTION ${ident(name)}`;
+    const what = type === CLICKHOUSE_ENTITY_TYPES.table ? "TABLE" : type === CLICKHOUSE_ENTITY_TYPES.dictionary ? "DICTIONARY" : "VIEW";
+    return `DROP ${what} ${qualifiedIdent(database, name)} SYNC`;
+}
+/** Changes a plan refuses to make in place: they run as the rebuild migration (#3198). */
+export const isRebuild = (c) => c.class === "rebuild";
+/** Changes that remove data from an object the build still declares: withheld unless the apply may delete. */
+export const isDestructiveAlter = (c) => c.rule === "SQLCH202";
+/**
+ * A refused change in a sentence: the rule, the restriction, where it is
+ * stated, and where the change goes instead: the rebuild migration Op for
+ * the table (`key`, `database.name`), or for a view or database, which the
+ * Op does not rebuild, a drop and a create.
+ */
+export function refusalDetail(changes, key, type) {
+    const parts = changes.map((c) => {
+        const rule = CLASSIFIER_RULES[c.rule];
+        const values = c.before !== undefined || c.after !== undefined ? ` (${c.before ?? "none"} -> ${c.after ?? "none"})` : "";
+        return `${c.rule} ${rule.title} on ${c.field}${values}: ${rule.restriction} ${rule.cite}`;
+    });
+    const instead = type === undefined || type === CLICKHOUSE_ENTITY_TYPES.table
+        ? `Run it as the rebuild migration Op: ClickHouseRebuildOp({ table: ${JSON.stringify(key ?? "<database.table>")}, ... }) from @intentius/chant-lexicon-sql/clickhouse`
+        : "The rebuild migration Op rebuilds tables only; drop and create this object instead";
+    // A clause chant does not read (#3872) is refused for review: whether ALTER can make it is not known.
+    if (changes.every((c) => c.rule === "SQLCH290"))
+        return `needs review, since chant does not read the clause: ${parts.join("; ")}`;
+    return `needs a rebuild, which ALTER cannot make: ${parts.join("; ")}. ${instead}`;
+}
+/**
+ * The declaration under another name in the same database: the rebuild
+ * migration creates its new table from the declared `CREATE` this way.
+ */
+export function renamedDeclaration(obj, name, defaultDatabase = "default") {
+    const { tokens, node } = parsed(obj);
+    if (node.statement === "database")
+        throw new Error(`${obj.key}: a database is not renamed this way`);
+    const ddl = tokens
+        .slice(0, node.name.from)
+        .map((t) => t.text)
+        .join("") +
+        qualifiedIdent(obj.canonical.database ?? defaultDatabase, name) +
+        tokens
+            .slice(node.name.to)
+            .map((t) => t.text)
+            .join("");
+    const canonical = canonicalObject(ddl, defaultDatabase);
+    return { ...obj, ddl, canonical, key: `${canonical.database}.${canonical.name}` };
+}
+// ── tables ────────────────────────────────────────────────────────────
+/** A column's whole definition as declared: from its name to the comma or parenthesis that ends it. */
+function columnDefinition(tokens, node, name) {
+    const col = node.columns.find((c) => c.name === name);
+    if (!col)
+        throw new Error(`no declared column ${name}`);
+    let depth = 0;
+    let i = col.nameSpan.from;
+    for (; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.text === "(" || t.text === "[")
+            depth++;
+        else if (t.text === ")" || t.text === "]") {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        else if (t.text === "," && depth === 0)
+            break;
+    }
+    return tokens
+        .slice(col.nameSpan.from, i)
+        .filter((t) => t.kind !== "comment")
+        .map((t) => t.text)
+        .join("")
+        .trim();
+}
+function columnType(tokens, node, name) {
+    const col = node.columns.find((c) => c.name === name);
+    const type = text(tokens, col.type) ?? "";
+    return `${type}${col.nullable === true ? " NULL" : col.nullable === false ? " NOT NULL" : ""}`;
+}
+/** Where a column goes: after the declared column before it, or first. */
+function position(node, name) {
+    const i = node.columns.findIndex((c) => c.name === name);
+    return i <= 0 ? "FIRST" : `AFTER ${ident(node.columns[i - 1].name)}`;
+}
+/** `columns.<name>` or `columns.<name>.<part>`. */
+function columnField(field) {
+    const m = /^columns\.([^.]+)(?:\.(type|default|codec|ttl|comment))?$/.exec(field);
+    return m ? { column: m[1], ...(m[2] ? { part: m[2] } : {}) } : undefined;
+}
+/**
+ * The column order once the steps before it have run, and the moves that make
+ * it the declared order.
+ */
+function reorderSteps(t, tokens, node, live, changes) {
+    if (!live)
+        return [];
+    const renamed = new Map(changes.filter((c) => c.rule === "SQLCH212").map((c) => [c.before, c.after]));
+    const dropped = new Set(changes.filter((c) => c.rule === "SQLCH202").map((c) => columnField(c.field).column));
+    const declared = node.columns.map((c) => c.name);
+    const current = live.columns.map((c) => renamed.get(c.name) ?? c.name).filter((n) => !dropped.has(n));
+    // Added columns went in at their declared place.
+    for (const [i, name] of declared.entries()) {
+        if (current.includes(name))
+            continue;
+        const prev = i === 0 ? -1 : current.indexOf(declared[i - 1]);
+        current.splice(prev + 1, 0, name);
+    }
+    const steps = [];
+    for (const [i, name] of declared.entries()) {
+        const want = i === 0 ? undefined : declared[i - 1];
+        const at = current.indexOf(name);
+        const have = at <= 0 ? undefined : current[at - 1];
+        if (have === want)
+            continue;
+        current.splice(at, 1);
+        current.splice(want === undefined ? 0 : current.indexOf(want) + 1, 0, name);
+        steps.push(stepFor(`ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, "SQLCH209"));
+    }
+    return steps;
+}
+function tableSteps(obj, changes, live) {
+    const { tokens, node } = parsed(obj);
+    const t = objectIdent(obj);
+    const alter = (clause, rule) => stepFor(`ALTER TABLE ${t} ${clause}`, rule);
+    const steps = [];
+    const of = (rule) => changes.filter((c) => c.rule === rule);
+    for (const c of of("SQLCH212"))
+        steps.push(alter(`RENAME COLUMN ${ident(c.before)} TO ${ident(c.after)}`, "SQLCH212"));
+    // Added columns, in declared order, each at its declared place. Appending
+    // new columns to the sorting key has to happen in the same ALTER as adding
+    // them (SQLCH216), so then they go together.
+    const added = of("SQLCH201")
+        .map((c) => columnField(c.field).column)
+        .sort((a, b) => node.columns.findIndex((c) => c.name === a) - node.columns.findIndex((c) => c.name === b));
+    const adds = added.map((name) => `ADD COLUMN ${columnDefinition(tokens, node, name)} ${position(node, name)}`);
+    const sortKey = of("SQLCH216")[0];
+    if (sortKey)
+        steps.push(alter([...adds, `MODIFY ORDER BY ${text(tokens, node.orderBy)}`].join(", "), "SQLCH216"));
+    else
+        for (const a of adds)
+            steps.push(alter(a, "SQLCH201"));
+    for (const c of of("SQLCH202"))
+        steps.push(alter(`DROP COLUMN ${ident(columnField(c.field).column)}`, "SQLCH202"));
+    for (const c of changes) {
+        const f = columnField(c.field);
+        if (!f?.part)
+            continue;
+        const col = node.columns.find((x) => x.name === f.column);
+        const name = ident(f.column);
+        switch (c.rule) {
+            case "SQLCH210":
+                steps.push(alter(`MODIFY COLUMN ${name} ${columnType(tokens, node, f.column)}`, c.rule));
+                break;
+            case "SQLCH207":
+                if (col.default)
+                    steps.push(alter(`MODIFY COLUMN ${name} ${col.default.kind}${col.default.expr ? ` ${text(tokens, col.default.expr)}` : ""}`, c.rule));
+                else
+                    steps.push(alter(`MODIFY COLUMN ${name} REMOVE ${(c.before ?? "DEFAULT").split(" ")[0]}`, c.rule));
+                break;
+            case "SQLCH208":
+                steps.push(alter(col.codec ? `MODIFY COLUMN ${name} CODEC(${text(tokens, col.codec)})` : `MODIFY COLUMN ${name} REMOVE CODEC`, c.rule));
+                break;
+            case "SQLCH205":
+                steps.push(alter(col.ttl ? `MODIFY COLUMN ${name} TTL ${text(tokens, col.ttl)}` : `MODIFY COLUMN ${name} REMOVE TTL`, c.rule));
+                break;
+            case "SQLCH203":
+                steps.push(alter(`COMMENT COLUMN ${name} ${sqlString(obj.canonical.columns.find((x) => x.name === f.column)?.comment ?? "")}`, c.rule));
+                break;
+        }
+    }
+    for (const c of of("SQLCH204")) {
+        const name = c.field.slice("indexes.".length);
+        if (c.before !== undefined)
+            steps.push(alter(`DROP INDEX ${ident(name)}`, c.rule));
+        const ix = node.indexes.find((x) => x.name === name);
+        if (ix) {
+            steps.push(alter(`ADD INDEX ${ident(name)} ${text(tokens, ix.expr)} TYPE ${text(tokens, ix.type)}${ix.granularity ? ` GRANULARITY ${text(tokens, ix.granularity)}` : ""}`, c.rule));
+        }
+    }
+    for (const c of of("SQLCH214")) {
+        const name = c.field.slice("projections.".length);
+        if (c.before !== undefined)
+            steps.push(alter(`DROP PROJECTION ${ident(name)}`, c.rule));
+        const p = node.projections.find((x) => x.name === name);
+        if (p)
+            steps.push(alter(`ADD PROJECTION ${ident(name)} (${text(tokens, p.body)})`, c.rule));
+    }
+    for (const c of of("SQLCH215")) {
+        const name = c.field.slice("constraints.".length);
+        if (c.before !== undefined)
+            steps.push(alter(`DROP CONSTRAINT ${ident(name)}`, c.rule));
+        const k = node.constraints.find((x) => x.name === name);
+        if (k)
+            steps.push(alter(`ADD CONSTRAINT ${ident(name)} ${k.kind} ${text(tokens, k.expr)}`, c.rule));
+    }
+    for (const c of of("SQLCH205").filter((x) => x.field === "ttl")) {
+        steps.push(alter(node.ttl ? `MODIFY TTL ${text(tokens, node.ttl)}` : "REMOVE TTL", c.rule));
+    }
+    for (const c of of("SQLCH217"))
+        steps.push(alter(node.sampleBy ? `MODIFY SAMPLE BY ${text(tokens, node.sampleBy)}` : "REMOVE SAMPLE BY", c.rule));
+    for (const c of of("SQLCH206")) {
+        const key = c.field.slice("settings.".length);
+        const s = node.settings?.find((x) => x.key === key);
+        // A setting declared at its default compares as absent: set it as written.
+        steps.push(alter(s ? `MODIFY SETTING ${key} = ${text(tokens, s.value)}` : `RESET SETTING ${key}`, c.rule));
+    }
+    if (of("SQLCH209").length > 0)
+        steps.push(...reorderSteps(t, tokens, node, live, changes));
+    return steps;
+}
+function viewSteps(obj, changes, marker) {
+    const { tokens, node } = parsed(obj);
+    const t = objectIdent(obj);
+    const steps = [];
+    if (!node.materialized) {
+        if (changes.some((c) => c.rule === "SQLCH240"))
+            steps.push(stepFor(createStatement(obj, marker, { orReplace: true }), "SQLCH240"));
+        return steps;
+    }
+    if (changes.some((c) => c.rule === "SQLCH241"))
+        steps.push(stepFor(`ALTER TABLE ${t} MODIFY QUERY ${text(tokens, node.select)}`, "SQLCH241"));
+    if (changes.some((c) => c.rule === "SQLCH244") && node.refresh)
+        steps.push(stepFor(`ALTER TABLE ${t} MODIFY REFRESH ${text(tokens, node.refresh)}`, "SQLCH244"));
+    return steps;
+}
+/**
+ * The statements that make an existing object match its declaration, for the
+ * metadata and background-rewrite changes the classifier reported for it.
+ * Rebuild-class changes are not handled here: the caller refuses them.
+ * `live` is the object's current definition, which a column reorder needs.
+ *
+ * The object's own comment, and chant's marker in it, are not set here
+ * (`commentStatement`), except where a plain view is replaced whole.
+ */
+export function alterSteps(obj, changes, opts = {}) {
+    const steps = [];
+    for (const c of changes.filter((x) => x.rule === "SQLCH231"))
+        steps.push(stepFor(`RENAME DATABASE ${ident(c.before)} TO ${ident(c.after)}`, "SQLCH231"));
+    for (const c of changes.filter((x) => x.rule === "SQLCH230")) {
+        const from = splitQualified(c.before);
+        const to = splitQualified(c.after);
+        const what = obj.type === CLICKHOUSE_ENTITY_TYPES.dictionary ? "DICTIONARY" : "TABLE";
+        steps.push(stepFor(`RENAME ${what} ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, "SQLCH230"));
+    }
+    if (obj.type === CLICKHOUSE_ENTITY_TYPES.function && changes.some((c) => c.rule === "SQLCH260")) {
+        steps.push(stepFor(createStatement(obj, opts.marker, { orReplace: true }), "SQLCH260"));
+    }
+    // A dictionary is replaced whole, its comment and marker with it.
+    if (obj.type === CLICKHOUSE_ENTITY_TYPES.dictionary && changes.some((c) => c.rule === "SQLCH245")) {
+        steps.push(stepFor(createStatement(obj, opts.marker, { orReplace: true }), "SQLCH245"));
+    }
+    // A table over a table function stores nothing: it is replaced whole (#3911), its comment and marker with it.
+    if (obj.type === CLICKHOUSE_ENTITY_TYPES.table && changes.some((c) => c.rule === "SQLCH219"))
+        steps.push(stepFor(createStatement(obj, opts.marker, { orReplace: true }), "SQLCH219"));
+    else if (obj.type === CLICKHOUSE_ENTITY_TYPES.table)
+        steps.push(...tableSteps(obj, changes, opts.live));
+    else if (obj.type === CLICKHOUSE_ENTITY_TYPES.view || obj.type === CLICKHOUSE_ENTITY_TYPES.materializedView)
+        steps.push(...viewSteps(obj, changes, opts.marker));
+    return steps;
+}
+/** Whether the steps for these changes already set the object's comment (a plain view replaced whole). */
+export function stepsSetComment(obj, changes) {
+    return ((obj.type === CLICKHOUSE_ENTITY_TYPES.view && changes.some((c) => c.rule === "SQLCH240")) ||
+        (obj.type === CLICKHOUSE_ENTITY_TYPES.table && changes.some((c) => c.rule === "SQLCH219")) ||
+        (obj.type === CLICKHOUSE_ENTITY_TYPES.dictionary && changes.some((c) => c.rule === "SQLCH245")));
+}
+/** Drop order: what reads from a table before the table (a dictionary before its source), a database last. */
+const DROP_ORDER = { materializedView: 0, view: 1, dictionary: 2, table: 3, database: 4, function: 5 };
+/**
+ * The statements that take the current schema to the declared one, from the
+ * classified changes between them. Pure: nothing is read or sent. The applier
+ * (`./apply.ts`) runs the steps against a server; `diffStatements`
+ * (`../../migration-statements.ts`) renders the same steps for a migration
+ * file. Anything that changes the SQL sent for a change belongs here, so
+ * both see it.
+ */
+export function planStatements(input) {
+    const plan = planDeclared(input);
+    if (!input.topology)
+        return plan;
+    const topology = input.topology;
+    const render = (step) => ({ ...step, sql: renderFor(step.sql, topology) });
+    return {
+        objects: plan.objects.map((o) => (o.verdict === "create" || o.verdict === "alter" ? { ...o, steps: o.steps.map(render) } : o)),
+        drops: plan.drops.map((d) => ({ ...d, step: render(d.step) })),
+    };
+}
+const NEVER_DROPPED = new Set(["function", "user", "role", "rowPolicy", "quota", "settingsProfile", "grants"]);
+/** The entity types of access control (`../access.ts`): no comment, no marker, never dropped. */
+export const ACCESS_TYPES = new Set([
+    CLICKHOUSE_ENTITY_TYPES.user,
+    CLICKHOUSE_ENTITY_TYPES.role,
+    CLICKHOUSE_ENTITY_TYPES.rowPolicy,
+    CLICKHOUSE_ENTITY_TYPES.quota,
+    CLICKHOUSE_ENTITY_TYPES.settingsProfile,
+    CLICKHOUSE_ENTITY_TYPES.grant,
+]);
+/** What a user, role, row policy, quota, settings profile or grantee's grants take (`../access.ts`). */
+function accessStatements(obj, mine, live, deferred, environmentCreatesUsers) {
+    const kind = obj.canonical.kind;
+    const name = obj.canonical.name;
+    if (kind === "grants") {
+        const atom = (json) => JSON.parse(json ?? "{}");
+        const declared = obj.canonical.access ?? {};
+        const current = live?.access ?? {};
+        const created = mine.some((c) => c.rule === "SQLCH200");
+        const revokes = created ? [] : mine.filter((c) => c.rule === "SQLCH274").map((c) => stepFor(revokeStatement(atom(current[c.before]), name), "SQLCH274"));
+        const grants = (created ? Object.keys(declared) : mine.filter((c) => c.rule === "SQLCH273").map((c) => c.after)).map((key) => stepFor(grantStatement(atom(declared[key]), name), "SQLCH273"));
+        // A user's DEFAULT ROLE names roles it must already hold: set after its grants.
+        const defaultRole = deferred.get(name);
+        const after = defaultRole ? [defaultRole.step] : [];
+        if (defaultRole)
+            mine = [...mine, defaultRole.change];
+        return { verdict: created ? "create" : "alter", obj, changes: mine, steps: [...revokes, ...grants, ...after] };
+    }
+    const body = statementBody(tokenizeText(obj.ddl, 0));
+    if (mine.some((c) => c.rule === "SQLCH200")) {
+        const method = obj.canonical.access?.identified?.split(" ")[0];
+        if (kind === "user" && (method === undefined || !SECRETLESS.has(method))) {
+            if (environmentCreatesUsers) {
+                // #3717: the environment created the user with its password; the declared clauses are chant's to set.
+                const clauses = accessClauseText(obj.ddl);
+                const steps = USER_CLAUSES.filter((f) => clauses[f] !== undefined && !(f === "defaultRole" && deferred.has(name))).map((f) => stepFor(alterAccessField("user", name, f, obj.canonical.access ?? {}, clauses), "SQLCH271"));
+                return { verdict: "alter", obj, changes: mine, steps };
+            }
+            return {
+                verdict: "withheld",
+                obj,
+                changes: mine,
+                withheld: mine,
+                detail: `the user's password is the environment's, so chant does not create it: create ${name} with its password (CREATE USER ${ident(name)} IDENTIFIED BY ...), and the next apply makes the rest of it as declared`,
+            };
+        }
+        return { verdict: "create", obj, changes: mine, steps: [stepFor(body, "SQLCH200")] };
+    }
+    if (kind === "rowPolicy") {
+        // `CREATE ROW POLICY OR REPLACE`: ClickHouse takes OR REPLACE after the kind.
+        const replace = /^\s*(?:--[^\n]*\n\s*)*CREATE\s+(?:ROW\s+)?POLICY\s+OR\s+REPLACE\b/i.test(body)
+            ? body
+            : body.replace(/^(\s*(?:--[^\n]*\n\s*)*CREATE\s+(?:ROW\s+)?POLICY)\s+(?:IF\s+NOT\s+EXISTS\s+)?/i, "$1 OR REPLACE ");
+        return { verdict: "alter", obj, changes: mine, steps: mine.some((c) => c.rule === "SQLCH272") ? [stepFor(replace, "SQLCH272")] : [] };
+    }
+    if (kind === "quota" || kind === "settingsProfile") {
+        // ALTER, never OR REPLACE: a replaced profile is a new one, and what inherited the old one loses it.
+        const clauses = accessClauseText(obj.ddl);
+        const rule = kind === "quota" ? "SQLCH275" : "SQLCH276";
+        const steps = mine.filter((c) => c.rule === rule).map((c) => stepFor(alterQuotaOrProfileField(kind, name, c.field, obj.canonical.access ?? {}, clauses), rule));
+        return { verdict: "alter", obj, changes: mine, steps };
+    }
+    const clauses = accessClauseText(obj.ddl);
+    const rule = kind === "user" ? "SQLCH271" : "SQLCH270";
+    const steps = mine
+        .filter((c) => c.rule === rule && !(kind === "user" && c.field === "defaultRole" && deferred.has(name)))
+        .map((c) => stepFor(alterAccessField(kind, name, c.field, obj.canonical.access ?? {}, clauses), rule));
+    return { verdict: "alter", obj, changes: mine, steps };
+}
+/** A user's clauses the versioned path sets with `ALTER USER` (#3717), in order; `DEFAULT ROLE` last, since it names roles the user must hold. */
+const USER_CLAUSES = ["host", "validUntil", "defaultDatabase", "grantees", "settings", "defaultRole"];
+function deferredDefaultRoles(declared, byObject, keyOf, environmentCreatesUsers) {
+    const out = new Map();
+    const grantees = new Set(declared.filter((o) => o.canonical.kind === "grants").map((o) => o.canonical.name));
+    for (const o of declared) {
+        if (o.canonical.kind !== "user" || !grantees.has(o.canonical.name))
+            continue;
+        const mine = byObject.get(keyOf(o)) ?? [];
+        // A user the environment creates (#3717) gets its declared DEFAULT ROLE after its grants too.
+        const created = environmentCreatesUsers && o.canonical.access?.defaultRole !== undefined ? mine.find((c) => c.rule === "SQLCH200") : undefined;
+        const change = created ?? mine.find((c) => c.rule === "SQLCH271" && c.field === "defaultRole");
+        if (!change)
+            continue;
+        out.set(o.canonical.name, { step: stepFor(alterAccessField("user", o.canonical.name, "defaultRole", o.canonical.access ?? {}, accessClauseText(o.ddl)), "SQLCH271"), change });
+    }
+    return out;
+}
+function planDeclared(input) {
+    const keyOf = input.keyOf ?? ((o) => o.key);
+    const byObject = new Map();
+    for (const c of input.changes)
+        byObject.set(c.object, [...(byObject.get(c.object) ?? []), c]);
+    const deferred = deferredDefaultRoles(input.declared, byObject, keyOf, input.environmentCreatesUsers === true);
+    const objects = input.declared.map((obj) => {
+        const key = keyOf(obj);
+        const mine = byObject.get(key) ?? [];
+        if (ACCESS_TYPES.has(obj.type))
+            return accessStatements(obj, mine, input.current.get(key), deferred, input.environmentCreatesUsers === true);
+        const refused = mine.filter(isRebuild);
+        if (refused.length > 0)
+            return { verdict: "rebuild", obj, changes: mine, refused, detail: refusalDetail(refused, obj.key, obj.type) };
+        const destructive = mine.filter(isDestructiveAlter);
+        if (destructive.length > 0 && !input.allowDestructive) {
+            return {
+                verdict: "withheld",
+                obj,
+                changes: mine,
+                withheld: destructive,
+                detail: `drops ${destructive.map((c) => c.field).join(", ")}, which destroys the data in it; an apply that may delete (prune, ApplyOp delete "owned-only" or "gated") makes it`,
+            };
+        }
+        if (mine.some((c) => c.rule === "SQLCH200"))
+            return { verdict: "create", obj, changes: mine, steps: [stepFor(createStatement(obj, input.marker), "SQLCH200")] };
+        const renamedFrom = mine.find((c) => c.rule === "SQLCH230" || c.rule === "SQLCH231")?.before;
+        const currentKey = renamedFrom !== undefined && input.current.has(renamedFrom) ? renamedFrom : key;
+        const live = input.current.get(currentKey);
+        // A function has no comment, so nothing to restamp: it never carries the marker.
+        const restamp = obj.type !== CLICKHOUSE_ENTITY_TYPES.function && !stepsSetComment(obj, mine) && (mine.some((c) => c.field === "comment") || !(input.carriesMarker?.(currentKey) ?? true));
+        const steps = [
+            ...alterSteps(obj, mine, { ...(live ? { live } : {}), ...(input.marker ? { marker: input.marker } : {}) }),
+            ...(restamp ? [stepFor(commentStatement(obj, input.marker), "SQLCH203")] : []),
+        ];
+        return { verdict: "alter", obj, changes: mine, steps };
+    });
+    const drops = [];
+    for (const c of input.changes) {
+        if (c.rule !== "SQLCH250")
+            continue;
+        const o = input.current.get(c.object);
+        if (!o)
+            continue;
+        // A function and access control carry no marker, so chant never drops one.
+        if (NEVER_DROPPED.has(o.kind))
+            continue;
+        const type = CLICKHOUSE_ENTITY_TYPES[o.kind];
+        const database = o.kind === "database" || o.kind === "function" ? undefined : o.database;
+        drops.push({ key: c.object, type, ...(database !== undefined ? { database } : {}), name: o.name, step: stepFor(dropStatement(type, database, o.name), "SQLCH250") });
+    }
+    drops.sort((a, b) => (DROP_ORDER[kindOf(a.type)] ?? 9) - (DROP_ORDER[kindOf(b.type)] ?? 9));
+    return { objects, drops };
+}
+const kindOf = (type) => Object.entries(CLICKHOUSE_ENTITY_TYPES).find(([, t]) => t === type)?.[0] ?? "table";

package/dist/clickhouse/catalog-types.js

@@ -0,0 +1,7 @@
+/**
+ * The shapes of the generated ClickHouse catalog tables
+ * (`src/generated/clickhouse.ts`). The data is generated; these types are
+ * not, so the generated module stays data and a reader of it has one place to
+ * look for what a field means.
+ */
+export {};