@intentius/chant-lexicon-sql 0.112.0 → 0.113.0

package/src/clickhouse/topology.ts

@@ -0,0 +1,451 @@
+/**
+ * One ClickHouse statement rendered for the topology it runs on (#3645):
+ * a single node, a cluster (`ON CLUSTER`), a `Replicated` database, or
+ * ClickHouse Cloud.
+ *
+ * A migration source is written once. What differs between topologies is
+ * two things, and this module rewrites only those:
+ *
+ * - `ON CLUSTER`. A cluster's DDL carries it so every host runs the
+ *   statement. A single node has no cluster to name. A `Replicated`
+ *   database replicates its own DDL and refuses `ON CLUSTER` naming any
+ *   other cluster ("ON CLUSTER is not allowed for Replicated database",
+ *   code 80 on 26.8) unless `ignore_on_cluster_for_replicated_database` is
+ *   set (default 0). Cloud's databases are Replicated, so the same holds
+ *   there.
+ * - The table engine. A MergeTree-family table replicates its rows only as
+ *   `Replicated*MergeTree`. On a cluster that engine names its Keeper path
+ *   and replica; inside a `Replicated` database it takes no path arguments,
+ *   since `database_replicated_allow_replicated_engine_arguments` defaults to
+ *   0 (refuse them) and the database supplies its own. A single node has no
+ *   Keeper to replicate through, so it gets the plain family. Cloud converts
+ *   every MergeTree and `Replicated*` engine to its `Shared*` equivalent
+ *   itself ("You don't add a `Shared` or `Replicated` prefix yourself",
+ *   https://clickhouse.com/docs/whats-new/cloud-compatibility), so it gets
+ *   the plain family as well, with no path arguments to clash.
+ *
+ * Every function here is pure: SQL in, SQL out, nothing sent. Statements
+ * this module does not recognize (`INSERT`, `SELECT`, `SYSTEM`) come back
+ * unchanged, so a caller can pass every statement it sends.
+ */
+
+import { isTrivia, tokenizeText, type Token } from "./tokens";
+import { parseCreate, unquote, type CreateNode, type Span } from "./parser";
+
+/** Where the statements run. */
+export type Topology =
+  | { kind: "single" }
+  | {
+      kind: "cluster";
+      /** The cluster's name in `remote_servers`, or a macro such as `{cluster}`. */
+      cluster: string;
+      /** Keeper path for a `Replicated*MergeTree` the renderer writes. Default {@link DEFAULT_REPLICA_PATH}. */
+      replicaPath?: string;
+      /** Replica name for a `Replicated*MergeTree` the renderer writes. Default {@link DEFAULT_REPLICA_NAME}. */
+      replicaName?: string;
+    }
+  | {
+      kind: "replicated";
+      /**
+       * A cluster to create and drop the `Replicated` databases themselves
+       * on, as `CREATE DATABASE ... ON CLUSTER` reaches every replica.
+       * Statements inside the database never carry it.
+       */
+      cluster?: string;
+    }
+  | { kind: "cloud" };
+
+export type TopologyKind = Topology["kind"];
+
+/**
+ * The Keeper path a cluster's `Replicated*MergeTree` gets: the server's own
+ * `default_replica_path`. `{uuid}` is the same on every host because the
+ * `CREATE` runs `ON CLUSTER`, and it does not change when the table is
+ * renamed or exchanged, so a rebuild's new table never shares the old one's
+ * path.
+ */
+export const DEFAULT_REPLICA_PATH = "/clickhouse/tables/{uuid}/{shard}";
+/** The replica name a cluster's `Replicated*MergeTree` gets: the server's `default_replica_name`. */
+export const DEFAULT_REPLICA_NAME = "{replica}";
+
+/** The Keeper path a `Replicated` database is created with in the `replicated` topology. */
+export const replicatedDatabasePath = (database: string): string => `/clickhouse/databases/${database}`;
+
+/**
+ * Read a topology from its string form, as a command-line flag or an
+ * environment variable gives it: `single`, `cluster:<name>`, `replicated`,
+ * `replicated:<cluster>`, `cloud`.
+ */
+export function parseTopology(value: string): Topology {
+  const at = value.indexOf(":");
+  const kind = (at < 0 ? value : value.slice(0, at)).trim();
+  const arg = at < 0 ? undefined : value.slice(at + 1).trim();
+  switch (kind) {
+    case "single":
+    case "cloud":
+      if (arg !== undefined) throw new Error(`topology ${kind} takes no argument: ${JSON.stringify(value)}`);
+      return { kind };
+    case "cluster":
+      if (!arg) throw new Error(`topology cluster needs the cluster's name: cluster:<name>, got ${JSON.stringify(value)}`);
+      return { kind, cluster: arg };
+    case "replicated":
+      return arg ? { kind, cluster: arg } : { kind };
+    default:
+      throw new Error(`unknown topology ${JSON.stringify(value)}: expected single, cluster:<name>, replicated or cloud`);
+  }
+}
+
+// ── engines ───────────────────────────────────────────────────────────
+
+/** An engine as a statement names it: its name and, if it has a parenthesised list, each argument's text. */
+export interface EngineClause {
+  name: string;
+  args?: string[];
+}
+
+const FAMILY = /^(Replicated)?(\w*MergeTree)$/;
+const isStringLiteral = (arg: string | undefined): boolean => arg !== undefined && /^'(?:[^'\\]|\\.)*'$/s.test(arg.trim());
+const sqlString = (value: string): string => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+
+/**
+ * A MergeTree-family engine split into its family and its own arguments,
+ * with the Keeper path and replica name a `Replicated*` engine names taken
+ * apart. Undefined for any other engine (`Log`, `Distributed`) and for a
+ * `Shared*` one, which only Cloud writes.
+ *
+ * As ClickHouse reads it, a `Replicated*MergeTree` names a path and replica
+ * when its first argument is a string literal; otherwise every argument is
+ * the family's own (`ReplicatedReplacingMergeTree(ver)`).
+ */
+function mergeTreeFamily(engine: EngineClause): { family: string; replicated: boolean; replica?: [string, string]; args: string[] } | undefined {
+  const m = FAMILY.exec(engine.name);
+  if (!m || m[2]!.startsWith("Shared")) return undefined;
+  const args = (engine.args ?? []).map((a) => a.trim());
+  if (m[1] && isStringLiteral(args[0]) && isStringLiteral(args[1])) {
+    return { family: m[2]!, replicated: true, replica: [args[0]!, args[1]!], args: args.slice(2) };
+  }
+  return { family: m[2]!, replicated: m[1] !== undefined, args };
+}
+
+/**
+ * The engine a table gets on a topology. A MergeTree-family engine becomes
+ * `Replicated*` on a cluster (with the path and replica it declared, or the
+ * topology's) and in a Replicated database (with none); the plain family on
+ * a single node and on Cloud. Any other engine is returned as declared.
+ */
+export function renderEngine(engine: EngineClause, topology: Topology): EngineClause {
+  const f = mergeTreeFamily(engine);
+  if (!f) return engine;
+  const parens = engine.args !== undefined;
+  const withArgs = (name: string, args: string[]): EngineClause => (args.length > 0 || parens ? { name, args } : { name });
+  switch (topology.kind) {
+    case "single":
+    case "cloud":
+      return withArgs(f.family, f.args);
+    case "replicated":
+      return withArgs(`Replicated${f.family}`, f.args);
+    case "cluster": {
+      const replica = f.replica ?? [sqlString(topology.replicaPath ?? DEFAULT_REPLICA_PATH), sqlString(topology.replicaName ?? DEFAULT_REPLICA_NAME)];
+      return { name: `Replicated${f.family}`, args: [...replica, ...f.args] };
+    }
+  }
+}
+
+const engineText = (e: EngineClause): string => (e.args === undefined ? e.name : `${e.name}(${e.args.join(", ")})`);
+
+// ── statements ────────────────────────────────────────────────────────
+
+/** `ON CLUSTER` and the name after it: a backquoted identifier, or a string literal for a macro (`'{cluster}'`). */
+export function onClusterClause(cluster: string): string {
+  return `ON CLUSTER ${/[{}]/.test(cluster) ? sqlString(cluster) : `\`${cluster.replace(/`/g, "``")}\``}`;
+}
+
+interface Edit {
+  /** Token index the replaced range starts at. */
+  from: number;
+  /** Token index past its end; equal to `from` for an insertion. */
+  to: number;
+  text: string;
+}
+
+function applyEdits(tokens: Token[], edits: Edit[]): string {
+  const sorted = [...edits].sort((a, b) => a.from - b.from);
+  let out = "";
+  let at = 0;
+  for (const e of sorted) {
+    out += tokens.slice(at, e.from).map((t) => t.text).join("") + e.text;
+    at = e.to;
+  }
+  return out + tokens.slice(at).map((t) => t.text).join("");
+}
+
+const word = (t: Token | undefined, ...words: string[]): boolean => t !== undefined && t.kind === "ident" && words.includes(t.text.toUpperCase());
+const isName = (t: Token | undefined): boolean => t !== undefined && (t.kind === "ident" || t.kind === "qident" || t.kind === "number" || t.kind === "ref");
+
+/** A walker over the significant tokens, which knows each one's index in the full list. */
+class Walk {
+  private readonly sig: number[];
+  p = 0;
+  constructor(readonly tokens: Token[]) {
+    this.sig = tokens.flatMap((t, i) => (isTrivia(t) ? [] : [i]));
+  }
+  peek(n = 0): Token | undefined {
+    const i = this.sig[this.p + n];
+    return i === undefined ? undefined : this.tokens[i];
+  }
+  /** Index in `tokens` of the significant token `n` ahead, or the end. */
+  index(n = 0): number {
+    return this.sig[this.p + n] ?? this.tokens.length;
+  }
+  /** Index in `tokens` just past the last significant token consumed. */
+  end(): number {
+    return this.p === 0 ? 0 : this.sig[this.p - 1]! + 1;
+  }
+  accept(...words: string[]): boolean {
+    if (!word(this.peek(), ...words)) return false;
+    this.p++;
+    return true;
+  }
+  acceptSeq(...words: string[]): boolean {
+    if (!words.every((w, i) => word(this.peek(i), w))) return false;
+    this.p += words.length;
+    return true;
+  }
+  /** `name` or `db.name`. False when no name is here. */
+  name(): boolean {
+    if (!isName(this.peek())) return false;
+    this.p++;
+    while (this.peek()?.text === "." && isName(this.peek(1))) this.p += 2;
+    return true;
+  }
+  /** The significant token index of the last top-level `SETTINGS`, outside any parentheses, or undefined. */
+  topLevelSettings(): number | undefined {
+    let depth = 0;
+    let found: number | undefined;
+    for (let k = this.p; k < this.sig.length; k++) {
+      const t = this.tokens[this.sig[k]!]!;
+      if (t.text === "(") depth++;
+      else if (t.text === ")") depth--;
+      else if (depth === 0 && word(t, "SETTINGS")) found = k;
+    }
+    return found;
+  }
+  /** Index in `tokens` of the significant token `k` (absolute), or the end of the statement. */
+  at(k: number): number {
+    return this.sig[k] ?? this.tokens.length;
+  }
+  /** Index in `tokens` past the last significant token, ignoring a trailing `;`. */
+  bodyEnd(): number {
+    let k = this.sig.length - 1;
+    if (k >= 0 && this.tokens[this.sig[k]!]!.text === ";") k--;
+    return k < 0 ? 0 : this.sig[k]! + 1;
+  }
+}
+
+/**
+ * The edit that makes the `ON CLUSTER` at the walker's position what the
+ * topology wants: replaced with the topology's cluster, removed, or (when
+ * there is none and `cluster` is given) inserted at `insertAt`.
+ */
+function onClusterEdit(w: Walk, cluster: string | undefined, insertAt: number): Edit | undefined {
+  if (word(w.peek(), "ON") && word(w.peek(1), "CLUSTER")) {
+    // Back to the end of the token before ON, so removing it takes its leading space too.
+    const from = w.end();
+    w.p += 2;
+    if (!w.name() && w.peek()?.kind === "string") w.p++;
+    const to = w.end();
+    return { from, to, text: cluster === undefined ? "" : ` ${onClusterClause(cluster)}` };
+  }
+  return cluster === undefined ? undefined : { from: insertAt, to: insertAt, text: ` ${onClusterClause(cluster)}` };
+}
+
+/** The cluster a statement on a table or view carries on this topology, if any. */
+const objectCluster = (topology: Topology): string | undefined => (topology.kind === "cluster" ? topology.cluster : undefined);
+/**
+ * The cluster a statement on a database itself carries on this topology, if
+ * any. In the replicated topology only creating and dropping the database
+ * reach every replica this way; an `ALTER` or `RENAME` of a Replicated
+ * database is replicated by the database.
+ */
+const databaseCluster = (topology: Topology, createOrDrop = false): string | undefined =>
+  topology.kind === "cluster" ? topology.cluster : topology.kind === "replicated" && createOrDrop ? topology.cluster : undefined;
+
+const text = (tokens: Token[], span: Span): string =>
+  tokens
+    .slice(span.from, span.to)
+    .map((t) => t.text)
+    .join("")
+    .trim();
+
+/** The `ON CLUSTER` edit for a parsed `CREATE`: after the name and any `UUID '...'`. */
+function createClusterEdit(tokens: Token[], node: CreateNode, cluster: string | undefined): Edit | undefined {
+  if (node.onCluster) {
+    let on = node.onCluster.from - 1;
+    // Back over the trivia and the CLUSTER and ON keywords, to the end of what came before.
+    let seen = 0;
+    while (on >= 0 && seen < 2) {
+      if (!isTrivia(tokens[on]!)) seen++;
+      on--;
+    }
+    while (on >= 0 && isTrivia(tokens[on]!)) on--;
+    return { from: on + 1, to: node.onCluster.to, text: cluster === undefined ? "" : ` ${onClusterClause(cluster)}` };
+  }
+  if (cluster === undefined) return undefined;
+  const at = afterName(tokens, node);
+  return { from: at, to: at, text: ` ${onClusterClause(cluster)}` };
+}
+
+/** Index in `tokens` past a `CREATE`'s name and any `UUID '...'` after it: where `ON CLUSTER` goes. */
+function afterName(tokens: Token[], node: CreateNode): number {
+  const w = new Walk(tokens.slice(node.name.to));
+  if (w.accept("UUID") && w.peek()?.kind === "string") {
+    w.p++;
+    return node.name.to + w.end();
+  }
+  return node.name.to;
+}
+
+function renderCreate(tokens: Token[], node: CreateNode, topology: Topology): string {
+  const edits: Edit[] = [];
+  if (node.statement === "database") {
+    const cluster = createClusterEdit(tokens, node, databaseCluster(topology, true));
+    if (cluster) edits.push(cluster);
+    const declared = node.engine?.name;
+    if (topology.kind === "replicated") {
+      if (declared !== "Replicated") {
+        const name = unquote(text(tokens, node.name));
+        const clause = `ENGINE = Replicated(${sqlString(replicatedDatabasePath(name))}, '{shard}', '{replica}')`;
+        if (node.engine) edits.push({ from: node.engine.span.from, to: node.engine.span.to, text: clause });
+        else {
+          // After ON CLUSTER as declared, or where an inserted one goes; edits at one index apply in the order pushed.
+          const at = node.onCluster ? node.onCluster.to : afterName(tokens, node);
+          edits.push({ from: at, to: at, text: ` ${clause}` });
+        }
+      }
+    } else if (declared === "Replicated" && node.engine) {
+      // Only the replicated topology runs a Replicated database; elsewhere the server's default (Atomic, or Cloud's own).
+      let from = node.engine.span.from;
+      while (from > 0 && isTrivia(tokens[from - 1]!)) from--;
+      edits.push({ from, to: node.engine.span.to, text: "" });
+    }
+    return applyEdits(tokens, edits);
+  }
+
+  const cluster = createClusterEdit(tokens, node, objectCluster(topology));
+  if (cluster) edits.push(cluster);
+  if (node.engine) {
+    const declared: EngineClause = { name: node.engine.name, ...(node.engine.args ? { args: node.engine.args.map((a) => text(tokens, a)) } : {}) };
+    const rendered = renderEngine(declared, topology);
+    if (engineText(rendered) !== engineText(declared)) {
+      // From the engine's name to the end of its argument list; `ENGINE =` stays as written.
+      edits.push({ from: node.engine.nameSpan.from, to: node.engine.span.to, text: engineText(rendered) });
+    }
+  }
+  return applyEdits(tokens, edits);
+}
+
+/** A `CREATE` the parser does not take (`CREATE TABLE ... AS`, a dictionary): `ON CLUSTER` after the name, the rest as written. */
+function renderOtherCreate(tokens: Token[], topology: Topology): string {
+  const w = new Walk(tokens);
+  w.accept("CREATE");
+  if (w.accept("OR")) w.accept("REPLACE");
+  w.accept("TEMPORARY");
+  let database = false;
+  if (w.accept("DATABASE")) database = true;
+  else if (w.accept("MATERIALIZED", "LIVE", "WINDOW")) w.accept("VIEW");
+  else if (!w.accept("TABLE", "VIEW", "DICTIONARY")) return applyEdits(tokens, []);
+  w.acceptSeq("IF", "NOT", "EXISTS");
+  if (!w.name()) return applyEdits(tokens, []);
+  let at = w.end();
+  if (w.accept("UUID") && w.peek()?.kind === "string") {
+    w.p++;
+    at = w.end();
+  }
+  const edit = onClusterEdit(w, database ? databaseCluster(topology) : objectCluster(topology), at);
+  return applyEdits(tokens, edit ? [edit] : []);
+}
+
+/**
+ * The `ON CLUSTER` for a statement whose clause follows the object's name:
+ * `ALTER`, `DROP`, `TRUNCATE`, `OPTIMIZE`, `DETACH`, `ATTACH`.
+ */
+function renderAfterName(tokens: Token[], w: Walk, cluster: string | undefined): string {
+  w.acceptSeq("IF", "NOT", "EXISTS") || w.acceptSeq("IF", "EXISTS");
+  if (!w.name()) return applyEdits(tokens, []);
+  const edit = onClusterEdit(w, cluster, w.end());
+  return applyEdits(tokens, edit ? [edit] : []);
+}
+
+/** `RENAME ... TO ...` and `EXCHANGE ... AND ...`: `ON CLUSTER` at the end, before any `SETTINGS`. */
+function renderAtEnd(tokens: Token[], w: Walk, cluster: string | undefined): string {
+  // An `ON CLUSTER` already written, after the renames.
+  for (let n = 0; w.peek(n) !== undefined; n++) {
+    if (word(w.peek(n), "ON") && word(w.peek(n + 1), "CLUSTER")) {
+      w.p += n;
+      return applyEdits(tokens, [onClusterEdit(w, cluster, 0)!]);
+    }
+  }
+  if (cluster === undefined) return applyEdits(tokens, []);
+  const settings = w.topLevelSettings();
+  let at: number;
+  if (settings !== undefined) {
+    at = w.at(settings);
+    while (at > 0 && isTrivia(tokens[at - 1]!)) at--;
+  } else at = w.bodyEnd();
+  return applyEdits(tokens, [{ from: at, to: at, text: ` ${onClusterClause(cluster)}` }]);
+}
+
+/**
+ * One statement as it runs on `topology`: `ON CLUSTER` added, replaced or
+ * removed, and in a `CREATE`, the engine the topology needs. Comments,
+ * spacing and everything else in the statement are kept as written.
+ * A statement that is not DDL on a database, table or view is returned
+ * unchanged, as is `KILL QUERY`/`KILL MUTATION` everywhere but a cluster,
+ * where it gains `ON CLUSTER` (inside a Replicated database
+ * `KILL QUERY ON CLUSTER '<db>'` names the database's own cluster and is kept).
+ */
+export function renderStatement(sql: string, topology: Topology): string {
+  const tokens = tokenizeText(sql, 0);
+  const w = new Walk(tokens);
+  const head = w.peek();
+  if (word(head, "CREATE")) {
+    let node: CreateNode | undefined;
+    try {
+      node = parseCreate(tokens);
+    } catch {
+      node = undefined;
+    }
+    return node ? renderCreate(tokens, node, topology) : renderOtherCreate(tokens, topology);
+  }
+  if (word(head, "ALTER", "DROP", "DETACH", "ATTACH", "TRUNCATE", "OPTIMIZE", "UNDROP")) {
+    w.p++;
+    if (word(head, "DROP", "DETACH", "ATTACH")) w.accept("TEMPORARY");
+    if (w.accept("DATABASE")) return renderAfterName(tokens, w, databaseCluster(topology, word(head, "DROP")));
+    // `TRUNCATE t` may leave out TABLE.
+    if (w.accept("TABLE", "VIEW", "DICTIONARY") || word(head, "TRUNCATE")) return renderAfterName(tokens, w, objectCluster(topology));
+    return sql;
+  }
+  if (word(head, "RENAME")) {
+    w.p++;
+    if (w.accept("DATABASE")) return renderAtEnd(tokens, w, databaseCluster(topology));
+    if (w.accept("TABLE", "DICTIONARY")) return renderAtEnd(tokens, w, objectCluster(topology));
+    return sql;
+  }
+  if (word(head, "EXCHANGE")) {
+    w.p++;
+    if (w.accept("TABLES", "DICTIONARIES")) return renderAtEnd(tokens, w, objectCluster(topology));
+    return sql;
+  }
+  if (word(head, "KILL") && topology.kind === "cluster") {
+    w.p++;
+    if (!w.accept("QUERY", "MUTATION")) return sql;
+    const edit = onClusterEdit(w, topology.cluster, w.end());
+    return applyEdits(tokens, edit ? [edit] : []);
+  }
+  return sql;
+}
+
+/** Each step's statement rendered for `topology`; every other field of a step is kept. */
+export function renderSteps<S extends { sql: string }>(steps: readonly S[], topology: Topology): S[] {
+  return steps.map((s) => ({ ...s, sql: renderStatement(s.sql, topology) }));
+}

package/src/codegen/classifier-page.ts

@@ -53,6 +53,23 @@ The plan only reports. [\`clickhouseApply\`](../applying/) makes the metadata-on
 
 \`chant migrate\` plays no part in any of this. It translates a file from one lexicon's format into another's, such as a GitHub Actions workflow into GitLab CI, and does not run schema migrations.
 
+## Statements for a migration file
+
+\`chant sql diff base.json head.json --statements\` prints the statements that take the base schema to the head one, offline: each one the applier would send for the same change, after a comment naming its object, rule and class. \`--json\` prints them as one document, which \`diffStatements(before, after)\` from \`@intentius/chant-lexicon-sql\` also returns:
+
+\`\`\`sql
+-- events (analytics.events): SQLCH201 metadata
+ALTER TABLE \`analytics\`.\`events\` ADD COLUMN region String DEFAULT 'eu' AFTER \`user_id\`;
+
+-- events (analytics.events): SQLCH210 rewrite, waits for its mutation
+ALTER TABLE \`analytics\`.\`events\` MODIFY COLUMN \`kind\` LowCardinality(String);
+
+-- sessions (analytics.sessions): SQLCH220 made by ClickHouseRebuildOp, not a statement:
+--   export const { op } = ClickHouseRebuildOp({ name: "rebuild-analytics-sessions", env: "<env>", table: "analytics.sessions", dualWrite: { mode: "materialized-view", cutoverColumn: "ts" } });
+\`\`\`
+
+A rebuild is never DDL: it is a step naming \`ClickHouseRebuildOp\`, or for a view or a database, which the Op does not rebuild, a manual step. A column or object drop is a statement marked destructive. Each \`CREATE\` carries the project's ownership marker, as the applier stamps it. The command exits 2 when a step is not a statement. Two things the applier asks the server are left out: whether a difference is formatting only, and whether a database is empty before it is dropped.
+
 ## Identity and renames
 
 An object is identified by its export name between two builds, so a changed name in the SQL under the same export is a rename. Against a server, which has no export names, an object is identified by \`database.name\`; a declaration renamed since the server last saw it says so with \`-- previously: <old name>\` before its CREATE.

package/src/codegen/postgres-classifier-page.ts

@@ -44,6 +44,23 @@ chant sql plan prod schema.json        # a build output against the prod server
 
 Both read the build's \`dialect\` and exit 2 when a change can only be made as expand and contract. \`--json\` prints the changes, the hints, the refused changes and the migration Op suggestions as one document. \`chant sql diff\` compares a pull request's base and head builds with no server. \`chant sql plan\` reads the server \`sql.profiles.<env>\` binds (else \`POSTGRES_URL\`), in the profile's \`schemas\` when it lists them, otherwise in the default schema and every schema the build declares an object in. Where the normalization rules leave an expression different, it asks that server: the declared view, or the table's column types, defaults, generated expressions and checks, are created as temporary objects in a transaction that is always rolled back, and read back with the same printers, so a view's \`SELECT *\` and the server's added parentheses are not reported as changes.
 
+## Statements for a migration file
+
+\`chant sql diff base.json head.json --statements\` prints the statements that take the base schema to the head one, offline: each one the applier would send for the same change, after a comment naming its object, rule and class, and whether it has to run outside a transaction block. \`--json\` prints them as one document, which \`diffStatements(before, after)\` from \`@intentius/chant-lexicon-sql\` also returns, each statement with \`transactional\` set:
+
+\`\`\`sql
+-- users (app.users): SQLPG201 metadata
+ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL;
+
+-- usersEmail (app.users_email_idx): SQLPG240 concurrently, outside a transaction
+CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email);
+
+-- orders (app.orders): SQLPG205 made by PostgresMigrationOp, not a statement:
+--   export const { op } = PostgresMigrationOp({ name: "migrate-app-orders-reference", env: "<env>", table: "app.orders", column: "reference" });
+\`\`\`
+
+A column rename or a type change across kinds is never DDL: it is a step naming \`PostgresMigrationOp\`, one per column. Any other expand-and-contract change, and the refused table's other changes, which the applier also holds back, are a manual step. A column or object drop is a statement marked destructive. Statements use the default schema for a bare name, as the applier sets \`search_path\`. The command exits 2 when a step is not a statement. What the applier asks the server is left out: its normalization of expressions the rules leave different, and an extension's own comment.
+
 ## Which major
 
 Two rules change class across the supported majors: a STORED generated column's expression (SQLPG212) is a rewrite from 17 and expand and contract before it, and a table's access method (SQLPG226) is a rewrite from 15 and expand and contract before it.

package/src/core/statements.ts

@@ -0,0 +1,127 @@
+/**
+ * The statements a schema change takes, rendered offline (#3644), the same
+ * shape in every dialect: what `diffStatements`
+ * (`../migration-statements.ts`) returns and `chant sql diff --statements
+ * --json` prints, for a migration file to hold.
+ *
+ * Every value is plain JSON: strings, booleans, arrays and objects, no
+ * `undefined` left in, so the document reads back as it was written. Steps
+ * are in the order they run.
+ */
+
+/** A classified change, as a step names the changes it makes. */
+export interface StatementChange {
+  /** The classifier rule, e.g. `SQLCH201`, `SQLPG240`. */
+  rule: string;
+  /** That rule's class, e.g. `metadata`, `rewrite`, `concurrently`. */
+  class: string;
+  /** What changed, e.g. `columns.region`, `orderBy`. */
+  field: string;
+  before?: string;
+  after?: string;
+  /** Data is removed and not recoverable. */
+  destructive?: boolean;
+  note?: string;
+}
+
+/** What every step says about the object it is for. */
+export interface StepObject {
+  /** The object's export name: in the newer build, or the older one for an object it drops. */
+  object: string;
+  /** Its entity type, e.g. `ClickHouse::Table`, `Postgres::Index`. */
+  type: string;
+  /** Its name on the server: `database.name` or `schema.name`, or a database's, schema's or extension's own name. */
+  name: string;
+}
+
+/** One statement, as the applier would send it. */
+export interface StatementStep extends StepObject {
+  kind: "statement";
+  sql: string;
+  /** The rule of the change it makes. */
+  rule: string;
+  /** That rule's class. */
+  class: string;
+  /** False for a statement that may not run inside a transaction block (Postgres `CONCURRENTLY`, `ALTER TYPE ... ADD VALUE`). Always false for ClickHouse, which has none. */
+  transactional: boolean;
+  /** ClickHouse: the statement starts a mutation; wait for it in `system.mutations` before the next one. */
+  waitsForMutation?: boolean;
+  /** The statement removes data that is not recoverable (a column or table drop). */
+  destructive?: boolean;
+}
+
+/** A change no statement makes in place, made by a migration Op. */
+export interface OpStep extends StepObject {
+  kind: "op";
+  /** The Op's export name. */
+  op: "ClickHouseRebuildOp" | "PostgresMigrationOp";
+  /** The module the Op is imported from. */
+  importPath: string;
+  /** The Op's options as the hand-off suggests them: `name`, `env`, `table`, and `dualWrite` (ClickHouse) or `column` (Postgres). */
+  options: Record<string, unknown>;
+  /** The Op's declaration, ready for an `*.op.ts` file. */
+  declaration: string;
+  /** The changes the Op makes. */
+  changes: StatementChange[];
+  /** The refusal as the applier reports it: each rule, its restriction, and the Op. */
+  detail: string;
+}
+
+/**
+ * A change neither a statement nor an Op makes: a rebuild of a view or a
+ * database, an expand-and-contract change no Op covers, a change with no
+ * in-place statement, or the object's other changes that the applier holds
+ * back while one of its changes is refused.
+ */
+export interface ManualStep extends StepObject {
+  kind: "manual";
+  changes: StatementChange[];
+  detail: string;
+}
+
+export type MigrationStep = StatementStep | OpStep | ManualStep;
+
+export interface SchemaStatements {
+  dialect: "clickhouse" | "postgres";
+  /** ClickHouse: the database a bare name means. */
+  defaultDatabase?: string;
+  /** Postgres: the schema a bare name means; the applier sets `search_path` to it. */
+  defaultSchema?: string;
+  /** Postgres: the major the changes were classified for. */
+  major?: number;
+  /** In the order they run: each object's in the newer build's creation order, then the drops. */
+  steps: MigrationStep[];
+  /** True when a step is an Op or manual: the schema change is more than statements. */
+  refused: boolean;
+  /** What the diff points out besides the changes (a likely rename written as a drop and an add). */
+  hints: string[];
+}
+
+/** A classified change as a step names it, with no `undefined` fields. */
+export function statementChange(c: { rule: string; class: string; field: string; before?: string; after?: string; destructive?: boolean; note?: string }): StatementChange {
+  return {
+    rule: c.rule,
+    class: c.class,
+    field: c.field,
+    ...(c.before !== undefined ? { before: c.before } : {}),
+    ...(c.after !== undefined ? { after: c.after } : {}),
+    ...(c.destructive ? { destructive: true } : {}),
+    ...(c.note !== undefined ? { note: c.note } : {}),
+  };
+}
+
+/** The steps as a migration file's SQL: each statement after a comment naming its object, rule and class; an Op or manual step as a comment. */
+export function renderStatements(doc: SchemaStatements): string {
+  const out: string[] = [];
+  for (const s of doc.steps) {
+    if (s.kind === "statement") {
+      const notes = [s.transactional || doc.dialect !== "postgres" ? "" : "outside a transaction", s.waitsForMutation ? "waits for its mutation" : "", s.destructive ? "destructive" : ""].filter(Boolean);
+      out.push(`-- ${s.object} (${s.name}): ${s.rule} ${s.class}${notes.length ? `, ${notes.join(", ")}` : ""}`, `${s.sql};`, "");
+    } else if (s.kind === "op") {
+      out.push(`-- ${s.object} (${s.name}): ${s.changes.map((c) => c.rule).join(", ")} made by ${s.op}, not a statement:`, `--   ${s.declaration}`, "");
+    } else {
+      out.push(`-- ${s.object} (${s.name}): ${s.changes.map((c) => c.rule).join(", ")} has no statement and no Op: ${s.detail}`, "");
+    }
+  }
+  return out.join("\n");
+}

package/src/index.ts

@@ -19,3 +19,18 @@ export { database, table, view, literal } from "./clickhouse/entities";
 // `@intentius/chant-lexicon-sql/postgres` is Postgres's. Declarations import
 // them from the dialect subpath.
 export { schema, index, sequence, type, domain, extension } from "./postgres/entities";
+
+// A schema change's statements between two builds, rendered offline for a
+// migration file (#3644); also at `@intentius/chant-lexicon-sql/migration-statements`.
+export {
+  diffStatements,
+  renderStatements,
+  type DiffStatementsOptions,
+  type ManualStep,
+  type MigrationStep,
+  type OpStep,
+  type SchemaStatements,
+  type StatementChange,
+  type StatementStep,
+  type StepObject,
+} from "./migration-statements";