@intentius/chant-lexicon-sql 0.112.1 → 0.114.0

package/src/clickhouse/apply/statements.ts

@@ -20,9 +20,10 @@ import { isTrivia, tokenizeText, type Token } from "../tokens";
 import { parseCreate, type CreateNode, type Span, type TableNode, type ViewNode } from "../parser";
 import { canonicalObject, type CanonicalObject } from "../plan/normalize";
 import type { Change } from "../plan/diff";
-import { CLASSIFIER_RULES } from "../plan/rules";
+import { CLASSIFIER_RULES, type ChangeClass, type ClassifierRuleId } from "../plan/rules";
 import { stampedComment } from "../ownership";
 import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
+import { renderFor, type Topology } from "../topology";
 
 /** A backquoted identifier. */
 export const ident = (name: string): string => `\`${name.replace(/`/g, "``")}\``;
@@ -53,11 +54,21 @@ export interface DeclaredObject {
   dependsOn: string[];
 }
 
-/** One statement to send, and whether it starts a background rewrite to wait on. */
+/** One statement to send, the change it makes, and whether it starts a background rewrite to wait on. */
 export interface Step {
   sql: string;
   /** A mutation follows on the server; wait on `system.mutations` before the next step. */
   rewrite: boolean;
+  /** The classifier rule of the change it makes. */
+  rule: ClassifierRuleId;
+  /** That rule's class. */
+  class: ChangeClass;
+}
+
+/** The step for a statement that makes a change under `rule`: a rewrite-class rule waits on its mutation. */
+export function stepFor(sql: string, rule: ClassifierRuleId): Step {
+  const cls = CLASSIFIER_RULES[rule].class;
+  return { sql, rewrite: cls === "rewrite", rule, class: cls };
 }
 
 interface Parsed {
@@ -259,7 +270,7 @@ function reorderSteps(t: string, tokens: Token[], node: TableNode, live: Canonic
     if (have === want) continue;
     current.splice(at, 1);
     current.splice(want === undefined ? 0 : current.indexOf(want) + 1, 0, name);
-    steps.push({ sql: `ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, rewrite: false });
+    steps.push(stepFor(`ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, "SQLCH209"));
   }
   return steps;
 }
@@ -267,11 +278,11 @@ function reorderSteps(t: string, tokens: Token[], node: TableNode, live: Canonic
 function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: CanonicalObject | undefined): Step[] {
   const { tokens, node } = parsed(obj) as { tokens: Token[]; node: TableNode };
   const t = objectIdent(obj);
-  const alter = (clause: string, rewrite = false): Step => ({ sql: `ALTER TABLE ${t} ${clause}`, rewrite });
+  const alter = (clause: string, rule: ClassifierRuleId): Step => stepFor(`ALTER TABLE ${t} ${clause}`, rule);
   const steps: Step[] = [];
   const of = (rule: string) => changes.filter((c) => c.rule === rule);
 
-  for (const c of of("SQLCH212")) steps.push(alter(`RENAME COLUMN ${ident(c.before!)} TO ${ident(c.after!)}`));
+  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
@@ -281,10 +292,10 @@ function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: Canon
     .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(", ")));
-  else for (const a of adds) steps.push(alter(a));
+  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)}`));
+  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);
@@ -293,59 +304,56 @@ function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: Canon
     const name = ident(f.column);
     switch (c.rule) {
       case "SQLCH210":
-        steps.push(alter(`MODIFY COLUMN ${name} ${columnType(tokens, node, f.column)}`, true));
+        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)}` : ""}`));
-        else steps.push(alter(`MODIFY COLUMN ${name} REMOVE ${(c.before ?? "DEFAULT").split(" ")[0]}`));
+        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`));
+        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`, true));
+        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 ?? "")}`));
+        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)}`));
+    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)}` : ""}`),
+        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)}`));
+    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)})`));
+    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)}`));
+    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)}`));
+    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", true));
-  }
-  for (const c of of("SQLCH217")) {
-    void c;
-    steps.push(alter(node.sampleBy ? `MODIFY SAMPLE BY ${text(tokens, node.sampleBy)}` : "REMOVE SAMPLE BY"));
+    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}`));
+    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));
@@ -357,11 +365,11 @@ function viewSteps(obj: DeclaredObject, changes: readonly Change[], marker: Owne
   const t = objectIdent(obj);
   const steps: Step[] = [];
   if (!node.materialized) {
-    if (changes.some((c) => c.rule === "SQLCH240")) steps.push({ sql: createStatement(obj, marker, { orReplace: true }), rewrite: false });
+    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({ sql: `ALTER TABLE ${t} MODIFY QUERY ${text(tokens, node.select)}`, rewrite: false });
-  if (changes.some((c) => c.rule === "SQLCH244") && node.refresh) steps.push({ sql: `ALTER TABLE ${t} MODIFY REFRESH ${text(tokens, node.refresh)}`, rewrite: false });
+  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;
 }
 
@@ -376,11 +384,11 @@ function viewSteps(obj: DeclaredObject, changes: readonly Change[], marker: Owne
  */
 export function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts: { live?: CanonicalObject; marker?: OwnershipMarker } = {}): Step[] {
   const steps: Step[] = [];
-  for (const c of changes.filter((x) => x.rule === "SQLCH231")) steps.push({ sql: `RENAME DATABASE ${ident(c.before!)} TO ${ident(c.after!)}`, rewrite: false });
+  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!);
-    steps.push({ sql: `RENAME TABLE ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, rewrite: false });
+    steps.push(stepFor(`RENAME TABLE ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, "SQLCH230"));
   }
   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));
@@ -391,3 +399,132 @@ export function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts
 export function stepsSetComment(obj: DeclaredObject, changes: readonly Change[]): boolean {
   return obj.type === CLICKHOUSE_ENTITY_TYPES.view && changes.some((c) => c.rule === "SQLCH240");
 }
+
+// ── a schema's statements ─────────────────────────────────────────────
+
+/**
+ * What one declared object takes, as the applier and the offline renderer
+ * (`../../migration-statements.ts`) both see it:
+ *
+ * - `create` or `alter`: the statements, in the order they run. An `alter`
+ *   with none is an object already as declared.
+ * - `rebuild`: a change ALTER cannot make; nothing is sent for the object and
+ *   the rebuild migration Op makes it (`detail` names the Op).
+ * - `withheld`: a column drop, which destroys data, in a plan not allowed to
+ *   delete.
+ */
+export type ObjectStatements =
+  | { verdict: "create" | "alter"; obj: DeclaredObject; changes: Change[]; steps: Step[] }
+  | { verdict: "rebuild"; obj: DeclaredObject; changes: Change[]; refused: Change[]; detail: string }
+  | { verdict: "withheld"; obj: DeclaredObject; changes: Change[]; withheld: Change[]; detail: string };
+
+/** An object a schema no longer declares, and the `DROP` for it. */
+export interface DropStatement {
+  /** The key the changes name it by. */
+  key: string;
+  type: ClickHouseEntityType;
+  database?: string;
+  name: string;
+  step: Step;
+}
+
+export interface StatementPlanInput {
+  /** The declared objects, in creation order. */
+  declared: readonly DeclaredObject[];
+  /** The classified changes from the current schema to the declared one. */
+  changes: readonly Change[];
+  /** The current definitions, keyed as the changes key objects. */
+  current: ReadonlyMap<string, CanonicalObject>;
+  /** How the changes key a declared object: `database.name` against a server (the default), the export name between two builds. */
+  keyOf?: (obj: DeclaredObject) => string;
+  /** The marker every `CREATE` and restamped comment carries. */
+  marker?: OwnershipMarker;
+  /** Column drops are planned, not withheld. Default: off. */
+  allowDestructive?: boolean;
+  /** Whether the current object (by its key in `current`) carries the marker already; one that does not is restamped. Default: it does. */
+  carriesMarker?: (currentKey: string) => boolean;
+  /**
+   * The topology every statement is rendered for (`../topology.ts`): `ON
+   * CLUSTER` and the engine. The declarations should be rendered for it too
+   * (`declaredObjects(json, db, topology)`), so the changes compare the
+   * engine the topology runs. Default: the statements as declared.
+   */
+  topology?: Topology;
+}
+
+export interface StatementPlan {
+  /** One entry per declared object, in creation order. */
+  objects: ObjectStatements[];
+  /** The objects the declarations no longer hold, in drop order: what reads from a table first, a database last. */
+  drops: DropStatement[];
+}
+
+/** Drop order: what reads from a table before the table, a database last. */
+const DROP_ORDER: Record<string, number> = { materializedView: 0, view: 1, table: 2, database: 3 };
+
+/**
+ * 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: StatementPlanInput): StatementPlan {
+  const plan = planDeclared(input);
+  if (!input.topology) return plan;
+  const topology = input.topology;
+  const render = (step: Step): 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) })),
+  };
+}
+
+function planDeclared(input: StatementPlanInput): StatementPlan {
+  const keyOf = input.keyOf ?? ((o: DeclaredObject) => o.key);
+  const byObject = new Map<string, Change[]>();
+  for (const c of input.changes) byObject.set(c.object, [...(byObject.get(c.object) ?? []), c]);
+
+  const objects: ObjectStatements[] = input.declared.map((obj): ObjectStatements => {
+    const key = keyOf(obj);
+    const mine = byObject.get(key) ?? [];
+    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);
+    const restamp = !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: DropStatement[] = [];
+  for (const c of input.changes) {
+    if (c.rule !== "SQLCH250") continue;
+    const o = input.current.get(c.object);
+    if (!o) continue;
+    const type = CLICKHOUSE_ENTITY_TYPES[o.kind as keyof typeof CLICKHOUSE_ENTITY_TYPES];
+    const database = o.kind === "database" ? 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: string): string => Object.entries(CLICKHOUSE_ENTITY_TYPES).find(([, t]) => t === type)?.[0] ?? "table";

package/src/clickhouse/live/bind.ts

@@ -7,6 +7,7 @@
 import type { ChantConfig } from "@intentius/chant/config";
 import type { UnobservedReason } from "@intentius/chant/observation";
 import { ClickHouseQueryError, clickhouseQuery, type ClickHouseEndpoint } from "../http";
+import { parseTopology, toTopology, type Topology } from "../topology";
 
 export interface ClickHouseTarget {
   endpoint: ClickHouseEndpoint;
@@ -15,6 +16,13 @@ export interface ClickHouseTarget {
   /** The databases in scope; undefined is every database but the server's own. */
   databases?: string[];
   defaultDatabase: string;
+  /**
+   * The topology the environment runs (`sql.profiles.<env>.topology`, or
+   * `CLICKHOUSE_TOPOLOGY`): what the applier, the plan and the rebuild
+   * render their statements for (`../topology.ts`). Undefined: statements
+   * as declared.
+   */
+  topology?: Topology;
 }
 
 export interface UnresolvedTarget {
@@ -29,7 +37,9 @@ export const isUnresolvedTarget = (v: ClickHouseTarget | UnresolvedTarget): v is
  *
  * 1. `sql.profiles.<environment>`. A profile naming a credential variable that
  *    is not set is `no-credentials`: the profile said how to authenticate.
- * 2. `CLICKHOUSE_URL`, with `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD` when set.
+ * 2. `CLICKHOUSE_URL`, with `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD` when set,
+ *    and `CLICKHOUSE_TOPOLOGY` (`single`, `cluster:<name>`, `replicated`,
+ *    `cloud`).
  * 3. Otherwise `no-binding`.
  */
 export function resolveClickHouseTarget(input: {
@@ -54,6 +64,7 @@ export function resolveClickHouseTarget(input: {
       source,
       ...(profile.databases ? { databases: profile.databases } : {}),
       defaultDatabase: profile.defaultDatabase ?? "default",
+      ...(profile.topology !== undefined ? { topology: toTopology(profile.topology) } : {}),
     };
   }
   const url = env.CLICKHOUSE_URL;
@@ -69,6 +80,7 @@ export function resolveClickHouseTarget(input: {
     },
     source: "env CLICKHOUSE_URL",
     defaultDatabase: "default",
+    ...(env.CLICKHOUSE_TOPOLOGY ? { topology: parseTopology(env.CLICKHOUSE_TOPOLOGY) } : {}),
   };
 }
 

package/src/clickhouse/live/live.test.ts

@@ -65,6 +65,16 @@ describe("binding an environment to a server", () => {
     expect(isUnresolvedTarget(t) && t.reason).toBe("no-credentials");
   });
 
+  test("the topology comes from the profile, or CLICKHOUSE_TOPOLOGY, and is undefined when neither names one (#3645)", () => {
+    const profile = (topology: unknown) =>
+      resolveClickHouseTarget({ environment: "prod", config: { sql: { profiles: { prod: { url: "http://ch:8123", topology } } } } as never, env: {} });
+    expect(profile("cluster:main")).toMatchObject({ topology: { kind: "cluster", cluster: "main" } });
+    expect(profile({ kind: "replicated", cluster: "all" })).toMatchObject({ topology: { kind: "replicated", cluster: "all" } });
+    expect(resolveClickHouseTarget({ env: { CLICKHOUSE_URL: "http://ch:8123", CLICKHOUSE_TOPOLOGY: "cloud" } })).toMatchObject({ topology: { kind: "cloud" } });
+    expect("topology" in resolveClickHouseTarget({ env: { CLICKHOUSE_URL: "http://ch:8123" } })).toBe(false);
+    expect(() => resolveClickHouseTarget({ env: { CLICKHOUSE_URL: "http://ch:8123", CLICKHOUSE_TOPOLOGY: "sharded" } })).toThrow(/unknown topology/);
+  });
+
   test("no profile and no CLICKHOUSE_URL is no-binding", () => {
     const t = resolveClickHouseTarget({ environment: "dev", config: {}, env: {} });
     expect(isUnresolvedTarget(t) && t.reason).toBe("no-binding");

package/src/clickhouse/plan/commands.ts

@@ -4,7 +4,7 @@
  * says `"dialect": "postgres"`) or a Postgres binding goes to
  * `../../postgres/plan/commands.ts`.
  *
- *     chant sql diff <before.json> <after.json> [--json]
+ *     chant sql diff <before.json> <after.json> [--json] [--statements] [--topology <topology>]
  *     chant sql plan <env> <build.json> [--json]
  *
  * `diff` is offline: it compares two `chant build` outputs, say a pull
@@ -14,6 +14,17 @@
  * rebuild, which a plan refuses to make in place, and 0 otherwise; for each
  * refused table they name the `ClickHouseRebuildOp` to run instead
  * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
+ *
+ * `diff --statements` prints the statements instead, for a migration file:
+ * each one the applier would send, with its change's rule and class, and a
+ * refused change as the Op that makes it (`../../migration-statements.ts`).
+ * The marker in each `CREATE` is the project's `ownership` config's.
+ *
+ * `--topology` (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`; `../topology.ts`) renders a ClickHouse diff's declarations and
+ * statements for that topology: `ON CLUSTER` and the engine. `--statements`
+ * renders for `single` without it; the plain diff compares the declarations as
+ * written. `plan` takes the topology from `sql.profiles.<env>.topology`.
  */
 
 import type { CommandGroup, CommandGroupContext } from "@intentius/chant/cli/command-group";
@@ -24,6 +35,7 @@ import { dropFormattingOnly } from "./server-format";
 import { bindClickHouse } from "../live/bind";
 import { rebuildOpSuggestions } from "./rebuild-handoff";
 import { readFileSync } from "node:fs";
+import { parseTopology, type Topology } from "../topology";
 
 /** The dialect a build output names. */
 function outputDialect(path: string): string | undefined {
@@ -34,8 +46,42 @@ function outputDialect(path: string): string | undefined {
   }
 }
 
-function split(args: string[]): { positional: string[]; json: boolean } {
-  return { positional: args.filter((a) => !a.startsWith("--")), json: args.includes("--json") };
+interface DiffArgs {
+  positional: string[];
+  json: boolean;
+  statements: boolean;
+  /** `--topology <t>` or `--topology=<t>`, as written. */
+  topology?: string;
+}
+
+function split(args: string[]): DiffArgs {
+  const positional: string[] = [];
+  let topology: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--topology") topology = args[++i] ?? "";
+    else if (a.startsWith("--topology=")) topology = a.slice("--topology=".length);
+    else if (!a.startsWith("--")) positional.push(a);
+  }
+  return { positional, json: args.includes("--json"), statements: args.includes("--statements"), ...(topology !== undefined ? { topology } : {}) };
+}
+
+/** `chant sql diff --statements`: the statements between two builds, as SQL with comments or as JSON. Exits 2 when a step is an Op or manual. */
+async function runDiffStatements(before: string, after: string, json: boolean, topology: Topology | undefined): Promise<number> {
+  const { diffStatements, renderStatements } = await import("../../migration-statements");
+  const { resolveOwnershipMarker } = await import("../../core/apply");
+  let marker;
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    const config = await loadChantConfig(process.cwd()).then((r) => r.config).catch(() => undefined);
+    marker = resolveOwnershipMarker({}, config, "chant sql diff --statements");
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+  const doc = diffStatements(readFileSync(before, "utf-8"), readFileSync(after, "utf-8"), { ...(marker ? { marker } : {}), ...(topology ? { topology } : {}) });
+  console.log(json ? JSON.stringify(doc, null, 2) : renderStatements(doc));
+  return doc.refused ? 2 : 0;
 }
 
 function emit(diff: SchemaDiff, json: boolean, title: string): number {
@@ -44,17 +90,25 @@ function emit(diff: SchemaDiff, json: boolean, title: string): number {
 }
 
 export async function runDiff(ctx: CommandGroupContext): Promise<number> {
-  const { positional, json } = split(ctx.rawArgs);
+  const { positional, json, statements, topology: topologyArg } = split(ctx.rawArgs);
   if (positional.length !== 2) {
-    console.error("usage: chant sql diff <before.json> <after.json> [--json]");
+    console.error("usage: chant sql diff <before.json> <after.json> [--json] [--statements] [--topology <topology>]");
+    return 1;
+  }
+  let topology: Topology | undefined;
+  try {
+    topology = topologyArg !== undefined ? parseTopology(topologyArg) : undefined;
+  } catch (err) {
+    console.error(`--topology: ${(err as Error).message}`);
     return 1;
   }
+  if (statements) return runDiffStatements(positional[0]!, positional[1]!, json, topology);
   if (outputDialect(positional[1]!) === "postgres") {
     const { diffPgBuildFiles, emitPg, projectMajor } = await import("../../postgres/plan/commands");
     return emitPg(diffPgBuildFiles(positional[0]!, positional[1]!, await projectMajor()), json, `${positional[0]} -> ${positional[1]}`);
   }
-  const after = schemaFromBuildFile(positional[1]!);
-  const diff = diffSchemas(schemaFromBuildFile(positional[0]!), after);
+  const after = schemaFromBuildFile(positional[1]!, "default", topology);
+  const diff = diffSchemas(schemaFromBuildFile(positional[0]!, "default", topology), after);
   const rebuildOps = rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
   return emit(rebuildOps.length > 0 ? { ...diff, rebuildOps } : diff, json, `${positional[0]} -> ${positional[1]}`);
 }
@@ -62,7 +116,7 @@ export async function runDiff(ctx: CommandGroupContext): Promise<number> {
 /** The declared objects against the server, keys and labels by `database.name`. */
 export async function planAgainstServer(environment: string, buildFile: string, options: Parameters<typeof bindClickHouse>[0] = {}): Promise<SchemaDiff> {
   const target = await bindClickHouse({ ...options, environment });
-  const declared = keyedByQualifiedName(schemaFromBuildFile(buildFile, target.defaultDatabase));
+  const declared = keyedByQualifiedName(schemaFromBuildFile(buildFile, target.defaultDatabase, target.topology));
   const databases = new Set(declared.map((o) => o.canonical.database ?? o.canonical.name));
   const live = await schemaFromServer(target, databases);
   const diff = diffSchemas(live, declared);
@@ -95,7 +149,7 @@ export const sqlCommands: CommandGroup = {
   name: "sql",
   description: "Schema changes, classified: between two builds, or a build and a live server",
   commands: [
-    { name: "diff", description: "Classify the change between two chant build outputs (offline)", handler: runDiff },
+    { name: "diff", description: "Classify the change between two chant build outputs (offline); --statements prints the statements it takes, --topology renders them for single, cluster:<name>, replicated or cloud", handler: runDiff },
     { name: "plan", description: "Classify the change from an environment's server to a chant build output", handler: runPlan },
   ],
 };

package/src/clickhouse/plan/deep.ts

@@ -20,6 +20,7 @@ import { bindClickHouse, classifyClickHouseFailure, type BindOptions } from "../
 import { readLiveSchema, type LiveObject } from "../live/catalog";
 import { database, table, view, CLICKHOUSE_ENTITY_TYPES, type ColumnDef } from "../entities";
 import { canonicalObject, type CanonicalColumn, type CanonicalObject } from "./normalize";
+import { renderFor } from "../topology";
 
 type Props = Record<string, unknown>;
 
@@ -109,7 +110,7 @@ export async function observeResourcesDeep(
     const o = byKey.get(`${db ?? ""}.${String(props.name)}`);
     if (!o) continue;
     try {
-      const d = canonicalObject(String(props.ddl), target.defaultDatabase);
+      const d = canonicalObject(renderFor(String(props.ddl), target.topology), target.defaultDatabase);
       const l = canonicalObject(o.statement, target.defaultDatabase);
       resources[name] = {
         type: o.type,

package/src/clickhouse/plan/diff.ts

@@ -127,7 +127,9 @@ function diffObject(key: string, before: CanonicalObject, after: CanonicalObject
   if (before.comment !== after.comment) out.push(change(key, "comment", "SQLCH203", before.comment, after.comment));
 
   if (before.kind === "database") {
-    if (before.engine !== after.engine) out.push(change(key, "engine", "SQLCH232", before.engine, after.engine));
+    // 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;
   }
 

package/src/clickhouse/plan/normalize.ts

@@ -275,8 +275,17 @@ export function canonicalObject(ddl: string, defaultDatabase = "default"): Canon
     // `ENGINE = ReplicatedMergeTree` with no Keeper path and replica name is
     // printed back with the server's defaults filled in; the two say the same.
     if (/^Replicated.*MergeTree$/.test(engine.name) && args[0] === DEFAULT_REPLICA_PATH && args[1] === DEFAULT_REPLICA_NAME) args = args.slice(2);
-    obj.engineName = engine.name;
-    obj.engine = args.length ? `${engine.name}(${args.join(", ")})` : engine.name;
+    // ClickHouse Cloud turns a declared MergeTree-family engine into its
+    // `Shared*` one and prints it back with the path and replica it chose
+    // (#3645, `../topology.ts`): the declaration said the plain family.
+    let name = engine.name;
+    const shared = /^Shared(\w*MergeTree)$/.exec(name);
+    if (shared) {
+      name = shared[1]!;
+      if (/^'.*'$/s.test(args[0] ?? "") && /^'.*'$/s.test(args[1] ?? "")) args = args.slice(2);
+    }
+    obj.engineName = name;
+    obj.engine = args.length ? `${name}(${args.join(", ")})` : name;
   }
   const comment = stringValue(spanText(tokens, node.comment));
   if (comment !== undefined && comment !== "") obj.comment = comment;

package/src/clickhouse/plan/schema.ts

@@ -8,23 +8,24 @@ import { canonicalObject } from "./normalize";
 import type { SchemaObject } from "./diff";
 import type { ClickHouseTarget } from "../live/bind";
 import { readLiveSchema } from "../live/catalog";
+import { renderFor, type Topology } from "../topology";
 
 interface OutputDoc {
   dialect?: string;
   objects?: Array<{ export: string; ddl: string }>;
 }
 
-/** The objects a `chant build` output holds, keyed by export name. */
-export function schemaFromBuildOutput(json: string, defaultDatabase = "default"): SchemaObject[] {
+/** The objects a `chant build` output holds, keyed by export name; with a `topology`, each declaration as rendered for it (`../topology.ts`). */
+export function schemaFromBuildOutput(json: string, defaultDatabase = "default", topology?: Topology): SchemaObject[] {
   const doc = JSON.parse(json) as OutputDoc;
   if (doc.dialect !== "clickhouse" || !Array.isArray(doc.objects)) {
     throw new Error("not a sql lexicon build output: expected { dialect: \"clickhouse\", objects: [...] }");
   }
-  return doc.objects.map((o) => ({ key: o.export, canonical: canonicalObject(o.ddl, defaultDatabase) }));
+  return doc.objects.map((o) => ({ key: o.export, canonical: canonicalObject(renderFor(o.ddl, topology), defaultDatabase) }));
 }
 
-export function schemaFromBuildFile(path: string, defaultDatabase = "default"): SchemaObject[] {
-  return schemaFromBuildOutput(readFileSync(path, "utf-8"), defaultDatabase);
+export function schemaFromBuildFile(path: string, defaultDatabase = "default", topology?: Topology): SchemaObject[] {
+  return schemaFromBuildOutput(readFileSync(path, "utf-8"), defaultDatabase, topology);
 }
 
 /**

package/src/clickhouse/rebuild/backfill.ts

@@ -120,6 +120,7 @@ export async function backfill(run: RebuildRun, deps: BackfillDeps = {}): Promis
     clickhouseReceiptStore(run.target.endpoint, identity, {
       ...(run.runId ? { runId: run.runId } : {}),
       ...(o.replicated ? { replicatedIn: n.database } : {}),
+      ...(run.target.topology ? { topology: run.target.topology } : {}),
       ...(run.replicaTimeoutMs !== undefined ? { replicaTimeoutMs: run.replicaTimeoutMs } : {}),
     });
   const recorded = await receipts.readAll(receiptAddress(identity, `rebuild/${n.key}/`));

package/src/clickhouse/rebuild/receipts.ts

@@ -50,6 +50,7 @@ import { clickhouseQuery, type ClickHouseEndpoint } from "../http";
 import { ident, sqlString } from "../apply/statements";
 import { CLICKHOUSE_COMMENT_OWNERSHIP_KEYS, RECEIPTS_TRAILER_KEY } from "../ownership";
 import { DDL_SETTINGS, syncReplicaWithin } from "./replicas";
+import { renderFor, type Topology } from "../topology";
 
 /** The database the receipts live in. Its comment marks it as chant's, so schema reads leave it out. */
 export const RECEIPTS_DATABASE = "chant_receipts";
@@ -79,22 +80,31 @@ export type ClickHouseReceiptStore = SqlReceiptStore;
  * project's ownership stack and env, which every address starts with.
  * `replicatedIn` names a Replicated database to keep them in instead, and
  * `replicaTimeoutMs` how long a read waits for this replica to catch up there.
+ * `topology` is the environment's (`../topology.ts`): the database and table
+ * are created for it, `ON CLUSTER` and a `Replicated*` engine on a cluster.
+ * In a Replicated database they are created for that database whatever it says.
  */
 export function clickhouseReceiptStore(
   endpoint: ClickHouseEndpoint,
   identity: { stack?: string; env?: string },
-  opts: { runId?: string; replicatedIn?: string; replicaTimeoutMs?: number } = {},
+  opts: { runId?: string; replicatedIn?: string; replicaTimeoutMs?: number; topology?: Topology } = {},
 ): ClickHouseReceiptStore {
   const where = receiptsTable(opts.replicatedIn);
+  const topology: Topology | undefined = opts.replicatedIn ? { kind: "replicated" } : opts.topology;
   const TABLE = `${ident(where.database)}.${ident(where.name)}`;
   let ensured = false;
   const ensure = async () => {
     if (ensured) return;
-    if (!opts.replicatedIn) await clickhouseQuery(endpoint, `CREATE DATABASE IF NOT EXISTS ${ident(RECEIPTS_DATABASE)} COMMENT ${sqlString(COMMENT)}`);
+    if (!opts.replicatedIn) {
+      await clickhouseQuery(endpoint, renderFor(`CREATE DATABASE IF NOT EXISTS ${ident(RECEIPTS_DATABASE)} COMMENT ${sqlString(COMMENT)}`, topology), { settings: DDL_SETTINGS });
+    }
     await clickhouseQuery(
       endpoint,
-      `CREATE TABLE IF NOT EXISTS ${TABLE} (address String, effect String, expectation String, run_id String, written_at DateTime64(3) DEFAULT now64(3)) ` +
-        `ENGINE = ${opts.replicatedIn ? "ReplicatedReplacingMergeTree" : "ReplacingMergeTree"}(written_at) ORDER BY address COMMENT ${sqlString(COMMENT)}`,
+      renderFor(
+        `CREATE TABLE IF NOT EXISTS ${TABLE} (address String, effect String, expectation String, run_id String, written_at DateTime64(3) DEFAULT now64(3)) ` +
+          `ENGINE = ReplacingMergeTree(written_at) ORDER BY address COMMENT ${sqlString(COMMENT)}`,
+        topology,
+      ),
       { settings: DDL_SETTINGS },
     );
     ensured = true;