@intentius/chant-lexicon-sql 0.113.0 → 0.114.1

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "7ab753de4cb73a505119a2b83d37d9b946d947c50dedc3a393c18829b64935a5",
+    "manifest.json": "82beced7beffe2bdd0dcf24728910539758d9d4dc85c94fe6418167bcbea9636",
     "meta.json": "5b7a5d171aa8bd21c0d55cfbe421143d67da02b7ef924a9b66166790c3fc7b22",
     "types/index.d.ts": "0286ebb367773e84c76818b0f69cb14cff8328fd2f8c65ed87563c8d5815458c",
     "rules/postgres-templates.ts": "f7244417426c441180ccb5c52da32cd812960d6d4eaba1fbdb17f47fcae707b2",
@@ -57,5 +57,5 @@
     "rules/sqlpg117.ts": "3d5c2d57ccdee3cf91c3ba3cb6363750787a850df8ebd75e9cc3f33113303827",
     "rules/sqlpg118.ts": "e2a40a88a9374c4d99d02118ca4c60877ba0c6eb1ce603a93b24f5fd23d81dde"
   },
-  "composite": "037aaec584d5d150c300e93cf38e051a570ff45b611d7a38eaea5736a39f71b9"
+  "composite": "619bc77b9a85523857c04bc2fd6ab9a538a97bca5c6824aadf06c3b58a517b76"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "sql",
-  "version": "0.113.0",
+  "version": "0.114.1",
   "chantVersion": ">=0.1.0",
   "namespace": "SQL",
   "intrinsics": [],

package/dist/migration-statements.d.ts

@@ -31,6 +31,7 @@
  */
 import type { OwnershipMarker } from "@intentius/chant/ownership";
 import { type SchemaStatements } from "./core/statements.js";
+import { type Topology } from "./clickhouse/topology.js";
 export type { ManualStep, MigrationStep, OpStep, SchemaStatements, StatementChange, StatementStep, StepObject } from "./core/statements.js";
 export { renderStatements } from "./core/statements.js";
 export interface DiffStatementsOptions {
@@ -40,6 +41,13 @@ export interface DiffStatementsOptions {
     env?: string;
     /** ClickHouse: the database a bare name means. Default: `default`. */
     defaultDatabase?: string;
+    /**
+     * ClickHouse: the topology to render the statements for
+     * (`./clickhouse/topology.ts`): `ON CLUSTER` and the engine, on both
+     * builds' declarations before they are compared, so the steps are the ones
+     * the applier sends to an environment with that topology. Default: `single`.
+     */
+    topology?: Topology;
     /** Postgres: the schema a bare name means. Default: `public`. */
     defaultSchema?: string;
     /** Postgres: the major to classify for. Default: the newer build's `postgresMajor`, else the older's, else the newest pinned. */

package/dist/migration-statements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-statements.d.ts","sourceRoot":"","sources":["../src/migration-statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAwD,KAAK,gBAAgB,EAAmB,MAAM,mBAAmB,CAAC;AAajI,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACzI,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,sIAAsI;IACtI,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iIAAiI;IACjI,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAWlC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B,GAAG,gBAAgB,CAQ3H"}
+{"version":3,"file":"migration-statements.d.ts","sourceRoot":"","sources":["../src/migration-statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAwD,KAAK,gBAAgB,EAAmB,MAAM,mBAAmB,CAAC;AAGjI,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAWrE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACzI,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,sIAAsI;IACtI,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iIAAiI;IACjI,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAWlC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B,GAAG,gBAAgB,CAQ3H"}

package/dist/postgres/plan/deep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep.d.ts","sourceRoot":"","sources":["../../../src/postgres/plan/deep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAmB,KAAK,qBAAqB,EAAgC,MAAM,mCAAmC,CAAC;AAE9H,OAAO,EAAyC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI7E,OAAO,EAAkD,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErG,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAcrC,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,KAAK,CAGhD;AA6CD,uGAAuG;AACvG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAwCpH;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAwChC"}
+{"version":3,"file":"deep.d.ts","sourceRoot":"","sources":["../../../src/postgres/plan/deep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAmB,KAAK,qBAAqB,EAAgC,MAAM,mCAAmC,CAAC;AAE9H,OAAO,EAAyC,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI7E,OAAO,EAAkD,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErG,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAcrC,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,KAAK,CAGhD;AA6CD,uGAAuG;AACvG,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAmDpH;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC/E,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,GACnC,OAAO,CAAC,qBAAqB,CAAC,CAwChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.113.0",
+  "version": "0.114.1",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -70,7 +70,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.113.0",
+    "@intentius/chant": "^0.114.1",
     "typescript": "^5.9.3"
   }
 }

package/src/clickhouse/apply/apply.ts

@@ -51,6 +51,7 @@ import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities"
 import { carriesMarker, isChantManaged } from "../ownership";
 import { planStatements, sqlString, type DeclaredObject, type DropStatement, type Step } from "./statements";
 import { waitForMutations } from "./mutations";
+import { renderFor, type Topology } from "../topology";
 
 export type { FailedObject } from "../../core/apply";
 
@@ -58,15 +59,20 @@ export type { FailedObject } from "../../core/apply";
  * The objects a `chant build` output declares, in creation order. Takes the
  * sql lexicon's primary output, or a multi-lexicon output holding it under
  * `sql` (the shared core's reader).
+ *
+ * With a `topology`, each declaration is rendered for it first
+ * (`../topology.ts`): the engine and `ON CLUSTER` it runs with there, which
+ * is what the changes compare and every `CREATE` sends.
  */
-export function declaredObjects(json: string, defaultDatabase = "default"): DeclaredObject[] {
+export function declaredObjects(json: string, defaultDatabase = "default", topology?: Topology): DeclaredObject[] {
   return readBuildObjects(json, "clickhouse", (o) => {
-    const canonical = canonicalObject(o.ddl, defaultDatabase);
+    const ddl = renderFor(o.ddl, topology);
+    const canonical = canonicalObject(ddl, defaultDatabase);
     return {
       exportName: o.export,
       type: o.type as ClickHouseEntityType,
       key: canonical.database !== undefined ? `${canonical.database}.${canonical.name}` : canonical.name,
-      ddl: o.ddl,
+      ddl,
       canonical,
       dependsOn: o.dependsOn,
     };
@@ -165,6 +171,7 @@ export async function applyClickHouse(target: ClickHouseTarget, declared: readon
     current: live,
     allowDestructive: opts.prune === true,
     carriesMarker: (key) => carriesMarker(liveByKey.get(key)?.comment, opts.marker),
+    ...(target.topology ? { topology: target.topology } : {}),
     ...(opts.marker ? { marker: opts.marker } : {}),
   });
 

package/src/clickhouse/apply/statements.ts

@@ -23,6 +23,7 @@ import type { Change } from "../plan/diff";
 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, "``")}\``;
@@ -442,6 +443,13 @@ export interface StatementPlanInput {
   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 {
@@ -463,6 +471,17 @@ const DROP_ORDER: Record<string, number> = { materializedView: 0, view: 1, table
  * 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]);

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] [--statements]
+ *     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
@@ -19,6 +19,12 @@
  * 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";
@@ -29,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 {
@@ -39,12 +46,28 @@ function outputDialect(path: string): string | undefined {
   }
 }
 
-function split(args: string[]): { positional: string[]; json: boolean; statements: boolean } {
-  return { positional: args.filter((a) => !a.startsWith("--")), json: args.includes("--json"), statements: args.includes("--statements") };
+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): Promise<number> {
+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;
@@ -56,7 +79,7 @@ async function runDiffStatements(before: string, after: string, json: boolean):
     console.error(err instanceof Error ? err.message : String(err));
     return 1;
   }
-  const doc = diffStatements(readFileSync(before, "utf-8"), readFileSync(after, "utf-8"), marker ? { marker } : {});
+  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;
 }
@@ -67,18 +90,25 @@ function emit(diff: SchemaDiff, json: boolean, title: string): number {
 }
 
 export async function runDiff(ctx: CommandGroupContext): Promise<number> {
-  const { positional, json, statements } = 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] [--statements]");
+    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);
+  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]}`);
 }
@@ -86,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);
@@ -119,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); --statements prints the statements it takes", 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

@@ -41,6 +41,21 @@
  * With a replica down (#3270) the kill goes on without it, and each sync
  * either finds nothing that replica alone has and returns, or stops the step
  * naming it (`./replicas.ts`).
+ *
+ * In materialized-view mode a partition is copied in two parts
+ * (INTENTIUS/sql-yodeler#45). The rows before the cut-over are copied as
+ * above. The rows at or after it are the view's only when they were written
+ * after the view was made; the ones the old table already held (a booking
+ * next month, an expiry date) reach the new table only through the backfill.
+ * The two kinds cannot be told apart by their values, so the second part
+ * copies the difference: for each distinct row at or after the cut-over, as
+ * many copies as the old table has more of it than the new one. That copy
+ * converges on its own, so a run killed during it, or a partition copied
+ * again, copies only what is still missing. A row the view is a moment from
+ * committing can be copied by both: the copy is followed by a check for rows
+ * the new table holds more often than the old one, which deletes and copies
+ * those again. Whatever is left, the verification finds, and the swap does
+ * not go ahead.
  */
 
 import { EffectReceipt, receiptExpectation } from "@intentius/chant/effect-receipt";
@@ -50,6 +65,7 @@ import { clickhouseReceiptStore, receiptAddress, type ClickHouseReceiptStore } f
 import { RebuildRefusal, type RebuildObservation } from "./observe";
 import { DDL_SETTINGS } from "./replicas";
 import { sourcePartitionExpression, sourcePartitions } from "./partitions";
+import { rowHash } from "./verify";
 import { cutoverOf, observe, serverNow, syncReplica, utcLiteral, waitOn, type RebuildRun } from "./steps";
 
 export interface BackfillResult {
@@ -62,6 +78,8 @@ export interface BackfillResult {
   skipped: number;
   /** Partitions this run found partly copied and cleared before copying again. */
   cleared: number;
+  /** Distinct rows at or after the cut-over found in the new table too often (copied while the view was writing them), deleted and copied again. */
+  repaired: number;
 }
 
 /** The effect a partition's copy is, and its receipt's address suffix. */
@@ -74,7 +92,15 @@ export function partitionExpectation(o: RebuildObservation, partition: string, c
     EffectReceipt(effect, {
       effect,
       flavor: "hash",
-      inputs: { table: o.names.key, newTable: o.newTable!.uuid, partition, copied: o.copied, cutover: cutover === undefined ? null : new Date(cutover).toISOString() },
+      inputs: {
+        table: o.names.key,
+        newTable: o.newTable!.uuid,
+        partition,
+        copied: o.copied,
+        cutover: cutover === undefined ? null : new Date(cutover).toISOString(),
+        // The rows at or after the cut-over the old table held are copied too (sql-yodeler#45); a receipt from before that copied fewer.
+        ...(cutover === undefined ? {} : { after: "difference" }),
+      },
     }),
   );
 }
@@ -88,7 +114,7 @@ export interface BackfillDeps {
 
 export async function backfill(run: RebuildRun, deps: BackfillDeps = {}): Promise<BackfillResult> {
   const o = await observe(run);
-  const result: BackfillResult = { state: o.state, partitions: 0, copied: 0, skipped: 0, cleared: 0 };
+  const result: BackfillResult = { state: o.state, partitions: 0, copied: 0, skipped: 0, cleared: 0, repaired: 0 };
   if (o.state !== "rebuild") return result;
   if (!o.newTable) throw new RebuildRefusal(`${o.names.key}: the new table is not there yet; the Create phase makes it`);
   const n = o.names;
@@ -113,6 +139,7 @@ export async function backfill(run: RebuildRun, deps: BackfillDeps = {}): Promis
   const fromOld = sourcePartitionExpression(o.live.partitionKey, o.newTable.partitionKey, o.copied);
   const columns = o.copied.map((c) => ident(c.name)).join(", ");
   const select = o.copied.map((c) => ident(c.source)).join(", ");
+  const later = cutColumn && cutover !== undefined ? await laterRowsCopy(run, o, cutColumn, cutover, fromOld) : undefined;
 
   const identity = { ...(run.marker?.stack ? { stack: run.marker.stack } : {}), ...(run.marker?.env ? { env: run.marker.env } : {}) };
   const receipts =
@@ -120,6 +147,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}/`));
@@ -136,17 +164,19 @@ export async function backfill(run: RebuildRun, deps: BackfillDeps = {}): Promis
     }
 
     const queryId = `chant-rebuild-${o.newTable.uuid}-${p}`;
+    const laterQueryId = `${queryId}-after`;
+    const killWhere = `query_id IN (${sqlString(queryId)}, ${sqlString(laterQueryId)})`;
     if (o.replicated) {
       // On every replica that answers: the copy may be running on another one
       // than this run's. A replica that is down is skipped once Keeper sees it
       // inactive; nothing of its can be running a copy that still writes,
       // and a part it wrote before going down is waited for by the sync below.
-      await clickhouseQuery(run.target.endpoint, `KILL QUERY ON CLUSTER ${sqlString(n.database)} WHERE query_id = ${sqlString(queryId)} SYNC`, {
+      await clickhouseQuery(run.target.endpoint, `KILL QUERY ON CLUSTER ${sqlString(n.database)} WHERE ${killWhere} SYNC`, {
         settings: DDL_SETTINGS,
       });
       await syncReplica(run, o, n.database, n.newName);
     } else {
-      await clickhouseQuery(run.target.endpoint, `KILL QUERY WHERE query_id = ${sqlString(queryId)} SYNC`);
+      await clickhouseQuery(run.target.endpoint, `KILL QUERY WHERE ${killWhere} SYNC`);
     }
     const mine = `${fromOld} = ${sqlString(p)}${targetRange}`;
     const [left] = await clickhouseQuery<{ n: string | number }>(run.target.endpoint, `SELECT count() AS n FROM ${n.newTable} WHERE ${mine}`);
@@ -162,15 +192,107 @@ export async function backfill(run: RebuildRun, deps: BackfillDeps = {}): Promis
     const sql = `INSERT INTO ${n.newTable} (${columns}) SELECT ${select} FROM ${n.table} WHERE _partition_id = ${sqlString(p)}${sourceRange}`;
     run.log(sql);
     await clickhouseQuery(run.target.endpoint, sql, { queryId, settings: { async_insert: "0", insert_deduplicate: "0" }, ...(run.signal ? { signal: run.signal } : {}) });
+    if (later) result.repaired += await copyAfterCutover(run, o, later, p, laterQueryId);
     // The receipt, last, on success only.
     await receipts.write({ name: effect, effect, flavor: "hash", inputs: {} }, expectation);
     result.copied++;
     await deps.afterPartition?.(p);
   }
-  run.log(`-- backfill of ${n.key}: ${result.partitions} partition(s), ${result.copied} copied, ${result.skipped} already copied, ${result.cleared} cleared first`);
+  run.log(`-- backfill of ${n.key}: ${result.partitions} partition(s), ${result.copied} copied, ${result.skipped} already copied, ${result.cleared} cleared first${result.repaired > 0 ? `, ${result.repaired} row(s) after the cut-over copied twice and repaired` : ""}`);
   return result;
 }
 
+/** The statements that copy one old partition's rows at or after the cut-over. */
+interface LaterRows {
+  /**
+   * Per distinct row (by its hash), the old table's copies past the number
+   * the new table holds, into the new table.
+   */
+  copy: (partition: string) => string;
+  /** The hashes of the rows the new table holds more copies of than the old one. */
+  extras: (partition: string) => string;
+  /** Delete every copy of those rows from the new table. */
+  drop: (partition: string, hashes: readonly string[]) => string;
+}
+
+/** The most extra rows one partition's repair deletes and copies again; past that the verification decides. */
+const REPAIR_LIMIT = 1000;
+const REPAIR_ROUNDS = 3;
+
+/**
+ * The statements for the rows at or after the cut-over. The old side casts
+ * each column to its type in the new table before hashing, as the
+ * verification does, so a row and its copy hash the same.
+ */
+async function laterRowsCopy(
+  run: RebuildRun,
+  o: RebuildObservation,
+  cut: RebuildObservation["copied"][number],
+  cutover: number,
+  fromOld: string,
+): Promise<LaterRows> {
+  const n = o.names;
+  const types = new Map(
+    (
+      await clickhouseQuery<{ name: string; type: string }>(
+        run.target.endpoint,
+        `SELECT name, type FROM system.columns WHERE database = ${sqlString(n.database)} AND table = ${sqlString(n.newName)}`,
+      )
+    ).map((c) => [c.name, c.type]),
+  );
+  const oldHash = rowHash(o.copied.map((c) => `CAST(${ident(c.source)}, ${sqlString(types.get(c.name) ?? "String")})`));
+  const newHash = rowHash(o.copied.map((c) => ident(c.name)));
+  const columns = o.copied.map((c) => ident(c.name)).join(", ");
+  const aliases = o.copied.map((_, i) => `__chant_c${i}`);
+  const fromOldSide = o.copied.map((c, i) => `${ident(c.source)} AS ${aliases[i]}`).join(", ");
+  const oldRows = (p: string) => `FROM ${n.table} WHERE _partition_id = ${sqlString(p)} AND ${ident(cut.source)} >= ${utcLiteral(cutover)}`;
+  const newRows = (p: string) => `FROM ${n.newTable} WHERE ${fromOld} = ${sqlString(p)} AND ${ident(cut.name)} >= ${utcLiteral(cutover)}`;
+  return {
+    copy: (p) =>
+      `INSERT INTO ${n.newTable} (${columns}) SELECT ${aliases.join(", ")} FROM (` +
+      `SELECT ${fromOldSide}, ${oldHash} AS __chant_h, row_number() OVER (PARTITION BY __chant_h) AS __chant_k ${oldRows(p)}` +
+      `) AS old_rows LEFT JOIN (SELECT ${newHash} AS __chant_h, count() AS __chant_n ${newRows(p)} GROUP BY __chant_h) AS new_rows ` +
+      `USING (__chant_h) WHERE __chant_k > ifNull(__chant_n, 0)`,
+    extras: (p) =>
+      `SELECT toString(__chant_h) AS h FROM (SELECT ${newHash} AS __chant_h, count() AS __chant_n ${newRows(p)} GROUP BY __chant_h) AS new_rows ` +
+      `LEFT JOIN (SELECT ${oldHash} AS __chant_h, count() AS __chant_o ${oldRows(p)} GROUP BY __chant_h) AS old_rows ` +
+      `USING (__chant_h) WHERE __chant_n > ifNull(__chant_o, 0) LIMIT ${REPAIR_LIMIT + 1}`,
+    drop: (p, hashes) => `ALTER TABLE ${n.newTable} DELETE WHERE ${fromOld} = ${sqlString(p)} AND ${ident(cut.name)} >= ${utcLiteral(cutover)} AND ${newHash} IN (${hashes.join(", ")})`,
+  };
+}
+
+/**
+ * Copy one old partition's rows at or after the cut-over that the new table
+ * lacks. A row the view had written to the old table but not yet to the new
+ * one when the copy read them is copied by both, and is then in the new
+ * table once too often: every copy of such a row is deleted from the new
+ * table and the difference copied again, a few rounds at most. What is left
+ * after that, the verification finds. Returns the rows repaired.
+ */
+async function copyAfterCutover(run: RebuildRun, o: RebuildObservation, later: LaterRows, p: string, queryId: string): Promise<number> {
+  const n = o.names;
+  const insert = async () => {
+    const sql = later.copy(p);
+    run.log(sql);
+    await clickhouseQuery(run.target.endpoint, sql, { queryId, settings: { async_insert: "0", insert_deduplicate: "0" }, ...(run.signal ? { signal: run.signal } : {}) });
+  };
+  await insert();
+  let repaired = 0;
+  for (let round = 0; round < REPAIR_ROUNDS; round++) {
+    await syncReplica(run, o, n.database, n.newName);
+    const extras = (await clickhouseQuery<{ h: string }>(run.target.endpoint, later.extras(p))).map((r) => r.h);
+    if (extras.length === 0 || extras.length > REPAIR_LIMIT) break;
+    run.log(`-- partition ${p}: ${extras.length} row(s) after the cut-over in the new table more often than in the old one; deleting them and copying again`);
+    const sql = later.drop(p, extras);
+    run.log(sql);
+    await clickhouseQuery(run.target.endpoint, sql);
+    await waitOn(run, n.database, n.newName);
+    repaired += extras.length;
+    await insert();
+  }
+  return repaired;
+}
+
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     const t = setTimeout(resolve, ms);