@intentius/chant-lexicon-sql 0.113.0 → 0.114.1

package/src/clickhouse/topology.e2e.test.ts

@@ -2,7 +2,9 @@
  * The single-node rendering against a server (#3645): one migration source
  * written for a cluster (`ON CLUSTER`, `Replicated*MergeTree` with Keeper
  * paths, a `Replicated` database) is refused by a single node as written
- * and applies once rendered for it, with the plain MergeTree family.
+ * and applies once rendered for it, with the plain MergeTree family: as
+ * statements, and through the applier with `CLICKHOUSE_TOPOLOGY=single`,
+ * which then finds nothing left to change.
  *
  * Runs against `CLICKHOUSE_URL` when it is set (the emulator, `chant
  * emulator up --lexicon sql`), else a scratch server of the pinned image.
@@ -10,7 +12,11 @@
  * other; skips cleanly without Docker.
  */
 
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { clickhouseApply } from "../op/activities/clickhouse-apply";
 import { dockerAvailable, startScratchServer, type ScratchServer } from "./container";
 import { clickhouseQuery, type ClickHouseEndpoint } from "./http";
 import { clickhouseImage } from "../spec/pin";
@@ -39,9 +45,12 @@ beforeAll(async () => {
   await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
 }, 600_000);
 
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-topology-"));
+
 afterAll(async () => {
   if (enabled) await q(`DROP DATABASE IF EXISTS ${DB} SYNC`).catch(() => undefined);
   await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
 });
 
 const SINGLE: Topology = { kind: "single" };
@@ -98,3 +107,77 @@ describe.skipIf(!enabled)("the single-node rendering against a server (#3645)",
     expect(cols.map((c) => c.name)).toEqual(["id", "ts", "kind", "source"]);
   });
 });
+
+describe.skipIf(!enabled)("the applier with a single-node topology (#3645)", () => {
+  interface Obj {
+    export: string;
+    type: string;
+    ddl: string;
+    dependsOn?: string[];
+  }
+  const writeBuild = (file: string, objects: Obj[]): string => {
+    const path = join(dir, file);
+    writeFileSync(path, JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+    return path;
+  };
+  const objects = (extraColumn = ""): Obj[] => [
+    { export: "db", type: "ClickHouse::Database", ddl: `CREATE DATABASE ${DB} ON CLUSTER main ENGINE = Replicated('/clickhouse/databases/${DB}', '{shard}', '{replica}')` },
+    {
+      export: "events",
+      type: "ClickHouse::Table",
+      dependsOn: ["db"],
+      ddl: `CREATE TABLE ${DB}.events ON CLUSTER main (id UInt64, ts DateTime, kind String${extraColumn}) ENGINE = ReplicatedReplacingMergeTree('/clickhouse/tables/{shard}/${DB}/events', '{replica}', ts) ORDER BY id`,
+    },
+    {
+      export: "byKind",
+      type: "ClickHouse::MaterializedView",
+      dependsOn: ["events"],
+      ddl: `CREATE MATERIALIZED VIEW ${DB}.by_kind ON CLUSTER main ENGINE = ReplicatedSummingMergeTree ORDER BY kind AS SELECT kind, count() AS n FROM ${DB}.events GROUP BY kind`,
+    },
+  ];
+  const apply = async (buildPath: string, topology?: string) => {
+    const sent: string[] = [];
+    const env: Record<string, string> = { CLICKHOUSE_URL: endpoint.url, ...(topology ? { CLICKHOUSE_TOPOLOGY: topology } : {}) };
+    if (endpoint.user) env.CLICKHOUSE_USER = endpoint.user;
+    if (endpoint.password) env.CLICKHOUSE_PASSWORD = endpoint.password;
+    const outcome = await clickhouseApply({ buildPath, environment: "test" }, undefined, {
+      config: { ownership: { stack: "yodel", env: "e2e" } },
+      env,
+      // The statements it sent; the log's other lines report each object.
+      log: (l) => void (/^[A-Z]+ /.test(l) && sent.push(l)),
+    }).catch((err: unknown) => ({ error: err as Error }));
+    return { outcome, sent };
+  };
+
+  test("as declared, the cluster's source fails on a single node; rendered for it, it applies and converges", async () => {
+    await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
+    const v1 = writeBuild("v1.json", objects());
+
+    const asDeclared = await apply(v1);
+    expect("error" in asDeclared.outcome || asDeclared.outcome.failed.length > 0).toBe(true);
+    await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
+
+    const first = await apply(v1, "single");
+    expect("error" in first.outcome).toBe(false);
+    expect(first.sent.join("\n")).not.toMatch(/ON CLUSTER|Replicated/);
+    expect(first.sent).toHaveLength(3);
+    const tables = await q<{ name: string; engine: string }>(`SELECT name, engine FROM system.tables WHERE database = '${DB}' ORDER BY name`);
+    expect(tables.map((t) => [t.name.startsWith(".inner") ? ".inner" : t.name, t.engine])).toEqual([
+      [".inner", "SummingMergeTree"],
+      ["by_kind", "MaterializedView"],
+      ["events", "ReplacingMergeTree"],
+    ]);
+
+    // Again: the server's plain engines are what the source renders to on a single node, so nothing is sent.
+    const again = await apply(v1, "single");
+    expect(again.sent).toEqual([]);
+    expect("error" in again.outcome ? again.outcome.error : again.outcome.notAttempted).toEqual([]);
+
+    // A change to the cluster's source applies as a single node's ALTER.
+    const v2 = writeBuild("v2.json", objects(", source String DEFAULT 'web'"));
+    const change = await apply(v2, "single");
+    expect(change.sent).toEqual([`ALTER TABLE \`${DB}\`.\`events\` ADD COLUMN source String DEFAULT 'web' AFTER \`kind\``]);
+    const cols = await q<{ name: string }>(`SELECT name FROM system.columns WHERE database = '${DB}' AND table = 'events' ORDER BY position`);
+    expect(cols.map((c) => c.name)).toEqual(["id", "ts", "kind", "source"]);
+  });
+});

package/src/clickhouse/topology.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { canonicalObject } from "./plan/normalize";
+import { diffSchemas } from "./plan/diff";
 import type { Change } from "./plan/diff";
 import { alterSteps, createStatement, dropStatement, type DeclaredObject } from "./apply/statements";
 import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "./entities";
@@ -274,3 +275,35 @@ describe("the applier's own statements", () => {
     expect(renderSteps(steps, SINGLE)).toEqual(steps);
   });
 });
+
+describe("the classifier compares the engine a topology runs", () => {
+  const declared = "CREATE TABLE db.t (id UInt64, v UInt64) ENGINE = ReplacingMergeTree(v) ORDER BY id";
+  const changes = (live: string, topology: Topology) =>
+    diffSchemas([{ key: "t", canonical: canonicalObject(live) }], [{ key: "t", canonical: canonicalObject(renderStatement(declared, topology)) }]).changes;
+
+  test("a cluster's table, as the server prints it, is the rendered declaration", () => {
+    expect(changes("CREATE TABLE db.t (`id` UInt64, `v` UInt64) ENGINE = ReplicatedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', v) ORDER BY id", CLUSTER)).toEqual([]);
+  });
+
+  test("a Replicated database's table, printed with the default path and replica, is the declaration with none", () => {
+    expect(changes("CREATE TABLE db.t (`id` UInt64, `v` UInt64) ENGINE = ReplicatedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', v) ORDER BY id", REPLICATED)).toEqual([]);
+  });
+
+  test("Cloud's Shared engine is the plain family it was declared as", () => {
+    expect(changes("CREATE TABLE db.t (`id` UInt64, `v` UInt64) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', v) ORDER BY id", CLOUD)).toEqual([]);
+  });
+
+  test("a database declared with no engine takes whatever the server's default is, so a single node's Atomic is no change", () => {
+    const db = (live: string, declared: string) => diffSchemas([{ key: "d", canonical: canonicalObject(live) }], [{ key: "d", canonical: canonicalObject(declared) }]).changes;
+    const declaredForCluster = "CREATE DATABASE d ON CLUSTER main ENGINE = Replicated('/clickhouse/databases/d', '{shard}', '{replica}')";
+    expect(db("CREATE DATABASE d\nENGINE = Atomic", renderStatement(declaredForCluster, SINGLE))).toEqual([]);
+    expect(db("CREATE DATABASE d\nENGINE = Replicated('/clickhouse/databases/d', '{shard}', '{replica}')", renderStatement("CREATE DATABASE d", REPLICATED))).toEqual([]);
+    expect(db("CREATE DATABASE d\nENGINE = Atomic", "CREATE DATABASE d ENGINE = Lazy(60)")).toEqual([expect.objectContaining({ rule: "SQLCH232" })]);
+  });
+
+  test("the engine a topology does not run is still a change", () => {
+    expect(changes("CREATE TABLE db.t (`id` UInt64, `v` UInt64) ENGINE = ReplacingMergeTree(v) ORDER BY id", CLUSTER)).toEqual([
+      expect.objectContaining({ field: "engine", rule: "SQLCH223", class: "rebuild" }),
+    ]);
+  });
+});

package/src/clickhouse/topology.ts

@@ -449,3 +449,29 @@ export function renderStatement(sql: string, topology: Topology): string {
 export function renderSteps<S extends { sql: string }>(steps: readonly S[], topology: Topology): S[] {
   return steps.map((s) => ({ ...s, sql: renderStatement(s.sql, topology) }));
 }
+
+/**
+ * A statement for a topology that may not be configured: with none, the
+ * statement as the source wrote it. The applier, the plan and the rebuild
+ * migration render only when an environment names its topology
+ * (`sql.profiles.<env>.topology`, `CLICKHOUSE_TOPOLOGY`), so a project that
+ * names none sends what it declared, as before.
+ */
+export const renderFor = (sql: string, topology: Topology | undefined): string => (topology ? renderStatement(sql, topology) : sql);
+
+/** A topology from its string form or its object form (`sql.profiles.<env>.topology`). */
+export function toTopology(value: string | Topology): Topology {
+  return typeof value === "string" ? parseTopology(value) : value;
+}
+
+/** The topology's string form, as `parseTopology` reads it. Replica path options are not part of it. */
+export function topologyLabel(topology: Topology): string {
+  switch (topology.kind) {
+    case "cluster":
+      return `cluster:${topology.cluster}`;
+    case "replicated":
+      return topology.cluster ? `replicated:${topology.cluster}` : "replicated";
+    default:
+      return topology.kind;
+  }
+}

package/src/clickhouse.ts

@@ -61,3 +61,19 @@ export {
 } from "./clickhouse/rebuild/op";
 export type { DualWrite } from "./clickhouse/rebuild/observe";
 export { RECEIPTS_DATABASE, RECEIPTS_TABLE } from "./clickhouse/rebuild/receipts";
+export {
+  DEFAULT_REPLICA_NAME,
+  DEFAULT_REPLICA_PATH,
+  onClusterClause,
+  parseTopology,
+  renderEngine,
+  renderFor,
+  renderStatement,
+  renderSteps,
+  replicatedDatabasePath,
+  topologyLabel,
+  toTopology,
+  type EngineClause,
+  type Topology,
+  type TopologyKind,
+} from "./clickhouse/topology";

package/src/codegen/classifier-page.ts

@@ -70,6 +70,8 @@ ALTER TABLE \`analytics\`.\`events\` MODIFY COLUMN \`kind\` LowCardinality(Strin
 
 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.
 
+\`--topology\` renders the statements for where they will run: \`single\` (the default), \`cluster:<name>\`, \`replicated\` or \`cloud\`. On a cluster every statement carries \`ON CLUSTER\` and a MergeTree-family table becomes \`Replicated*MergeTree\` with its Keeper path; in a \`Replicated\` database the tables are \`Replicated*MergeTree\` with no path and no \`ON CLUSTER\`. \`diffStatements(before, after, { topology })\` takes the same choice; see [Applying to a Server](../applying/#topology).
+
 ## 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/config.ts

@@ -45,6 +45,7 @@ import type { ChantConfig } from "@intentius/chant/config";
 import { PLANNED_SQL_DIALECTS, SQL_DIALECTS } from "./dialects";
 import { POSTGRES_PROVIDERS } from "./postgres/providers/types";
 import { POSTGRES_MAJORS } from "./spec/postgres-pin";
+import { parseTopology } from "./clickhouse/topology";
 
 const envRef = z.strictObject({ env: z.string() });
 
@@ -53,6 +54,27 @@ const providerName = z.enum(POSTGRES_PROVIDERS, {
   error: () => `expected a Postgres provider (${POSTGRES_PROVIDERS.join(", ")})`,
 });
 
+/** A ClickHouse topology, in its string form or its object form (`./clickhouse/topology.ts`). */
+const topologySchema = z.union([
+  z.string().refine(
+    (v) => {
+      try {
+        parseTopology(v);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { error: "expected single, cluster:<name>, replicated, replicated:<cluster> or cloud" },
+  ),
+  z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("single") }),
+    z.strictObject({ kind: z.literal("cluster"), cluster: z.string().min(1), replicaPath: z.string().optional(), replicaName: z.string().optional() }),
+    z.strictObject({ kind: z.literal("replicated"), cluster: z.string().min(1).optional() }),
+    z.strictObject({ kind: z.literal("cloud") }),
+  ]),
+]);
+
 export const sqlProfileSchema = z.strictObject({
   /**
    * Where the server is. ClickHouse: the base URL of its HTTP interface
@@ -73,6 +95,17 @@ export const sqlProfileSchema = z.strictObject({
   databases: z.array(z.string()).optional(),
   /** The database an unqualified declaration is created in. `default` when omitted. */
   defaultDatabase: z.string().optional(),
+  /**
+   * ClickHouse: the topology this environment runs, which the applier, the
+   * plan and the rebuild migration render every statement for: `single`,
+   * `cluster:<name>` (`ON CLUSTER`, `Replicated*MergeTree` with a Keeper
+   * path), `replicated` (a `Replicated` database; `replicated:<cluster>`
+   * creates the databases on that cluster) or `cloud`. The object form sets
+   * a cluster's Keeper path and replica name:
+   * `{ kind: "cluster", cluster: "main", replicaPath, replicaName }`. When
+   * omitted, statements are sent as declared.
+   */
+  topology: topologySchema.optional(),
   /**
    * Postgres: the schemas this environment's schema lives in. Import and
    * observation read these and nothing else; when omitted, every schema except

package/src/core/statements.ts

@@ -85,6 +85,8 @@ export interface SchemaStatements {
   dialect: "clickhouse" | "postgres";
   /** ClickHouse: the database a bare name means. */
   defaultDatabase?: string;
+  /** ClickHouse: the topology the statements are rendered for, in its string form (`single`, `cluster:<name>`, `replicated`, `cloud`). */
+  topology?: 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. */

package/src/migration-statements.test.ts

@@ -9,6 +9,7 @@ import { postgresApply } from "./op/activities/postgres-apply";
 import { runDiff } from "./clickhouse/plan/commands";
 import { writableClickHouse, type WritableServer } from "./clickhouse/testing/writable-server";
 import { writablePostgres } from "./postgres/testing/writable-server";
+import type { Topology } from "./clickhouse/topology";
 
 interface Obj {
   export: string;
@@ -111,7 +112,7 @@ describe("ClickHouse", () => {
   });
 
   test("two identical builds take no steps", () => {
-    expect(diffStatements(CH_BEFORE, CH_BEFORE)).toEqual({ dialect: "clickhouse", defaultDatabase: "default", steps: [], refused: false, hints: [] });
+    expect(diffStatements(CH_BEFORE, CH_BEFORE)).toEqual({ dialect: "clickhouse", defaultDatabase: "default", topology: "single", steps: [], refused: false, hints: [] });
   });
 
   test("the applier sends the same statements for the same change", async () => {
@@ -263,3 +264,121 @@ describe("chant sql diff --statements", () => {
     expect(r.out).toContain("ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL;");
   });
 });
+
+// ── ClickHouse topologies (#3645) ──────────────────────────────────────
+
+describe("ClickHouse statements per topology", () => {
+  const EMPTY = build("clickhouse", []);
+  const MV: Obj = {
+    export: "counts",
+    type: "ClickHouse::MaterializedView",
+    dependsOn: ["events"],
+    ddl: "CREATE MATERIALIZED VIEW analytics.counts ENGINE = SummingMergeTree ORDER BY kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind",
+  };
+  const FIRST = build("clickhouse", [DB, EVENTS, SESSIONS, OLD, MV]);
+  const TOPOLOGIES: Array<[string, Topology]> = [
+    ["single", { kind: "single" }],
+    ["cluster:main", { kind: "cluster", cluster: "main" }],
+    ["replicated", { kind: "replicated" }],
+    ["cloud", { kind: "cloud" }],
+  ];
+  const created = (t: Topology) => sqlOf(diffStatements(EMPTY, FIRST, { marker: MARKER, topology: t })).map((s) => s.replace(/ COMMENT '[^']*\[chant[^']*'$/, ""));
+  const R = "'/clickhouse/tables/{uuid}/{shard}', '{replica}'";
+
+  test("single is the default, and the declarations as written", () => {
+    expect(diffStatements(EMPTY, FIRST, { marker: MARKER })).toEqual(diffStatements(EMPTY, FIRST, { marker: MARKER, topology: { kind: "single" } }));
+    expect(created({ kind: "single" })).toEqual([
+      "CREATE DATABASE analytics ENGINE = Atomic",
+      "CREATE TABLE analytics.events (ts DateTime, user_id UInt64, kind String) ENGINE = MergeTree ORDER BY (ts, user_id)",
+      "CREATE TABLE analytics.sessions (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY id",
+      "CREATE TABLE analytics.old (a UInt8) ENGINE = MergeTree ORDER BY a",
+      "CREATE MATERIALIZED VIEW analytics.counts ENGINE = SummingMergeTree ORDER BY kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind",
+    ]);
+    expect(diffStatements(EMPTY, FIRST).topology).toBe("single");
+  });
+
+  test("a cluster creates everything ON CLUSTER, with Replicated engines and their Keeper path", () => {
+    expect(created({ kind: "cluster", cluster: "main" })).toEqual([
+      "CREATE DATABASE analytics ON CLUSTER `main` ENGINE = Atomic",
+      `CREATE TABLE analytics.events ON CLUSTER \`main\` (ts DateTime, user_id UInt64, kind String) ENGINE = ReplicatedMergeTree(${R}) ORDER BY (ts, user_id)`,
+      `CREATE TABLE analytics.sessions ON CLUSTER \`main\` (id UInt64, ts DateTime) ENGINE = ReplicatedMergeTree(${R}) ORDER BY id`,
+      `CREATE TABLE analytics.old ON CLUSTER \`main\` (a UInt8) ENGINE = ReplicatedMergeTree(${R}) ORDER BY a`,
+      `CREATE MATERIALIZED VIEW analytics.counts ON CLUSTER \`main\` ENGINE = ReplicatedSummingMergeTree(${R}) ORDER BY kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind`,
+    ]);
+    expect(diffStatements(EMPTY, FIRST, { topology: { kind: "cluster", cluster: "main" } }).topology).toBe("cluster:main");
+  });
+
+  test("a Replicated database: the database Replicated, its tables Replicated with no path, no ON CLUSTER", () => {
+    expect(created({ kind: "replicated" })).toEqual([
+      "CREATE DATABASE analytics ENGINE = Replicated('/clickhouse/databases/analytics', '{shard}', '{replica}')",
+      "CREATE TABLE analytics.events (ts DateTime, user_id UInt64, kind String) ENGINE = ReplicatedMergeTree ORDER BY (ts, user_id)",
+      "CREATE TABLE analytics.sessions (id UInt64, ts DateTime) ENGINE = ReplicatedMergeTree ORDER BY id",
+      "CREATE TABLE analytics.old (a UInt8) ENGINE = ReplicatedMergeTree ORDER BY a",
+      "CREATE MATERIALIZED VIEW analytics.counts ENGINE = ReplicatedSummingMergeTree ORDER BY kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind",
+    ]);
+  });
+
+  test("Cloud takes the plain family", () => {
+    expect(created({ kind: "cloud" })).toEqual(created({ kind: "single" }));
+  });
+
+  test("a source written for a cluster renders back to plain DDL for a single node", () => {
+    const clustered = build("clickhouse", [
+      { ...EVENTS, ddl: `CREATE TABLE analytics.events ON CLUSTER prod (ts DateTime, user_id UInt64, kind String) ENGINE = ReplicatedMergeTree('/t/{shard}/events', '{replica}') ORDER BY (ts, user_id)` },
+    ]);
+    expect(sqlOf(diffStatements(EMPTY, clustered))[0]).toMatch(/^CREATE TABLE analytics\.events \(ts DateTime, user_id UInt64, kind String\) ENGINE = MergeTree\(\) ORDER BY \(ts, user_id\) COMMENT /);
+  });
+
+  test("the changes between two builds: ON CLUSTER on every ALTER and DROP on a cluster, as written elsewhere", () => {
+    const base = sqlOf(diffStatements(CH_BEFORE, CH_AFTER, { marker: MARKER }));
+    for (const t of [{ kind: "replicated" }, { kind: "cloud" }] as Topology[]) expect(sqlOf(diffStatements(CH_BEFORE, CH_AFTER, { marker: MARKER, topology: t }))).toEqual(base);
+    expect(sqlOf(diffStatements(CH_BEFORE, CH_AFTER, { marker: MARKER, topology: { kind: "cluster", cluster: "main" } }))).toEqual([
+      "ALTER TABLE `analytics`.`events` ON CLUSTER `main` ADD COLUMN region String DEFAULT 'eu' AFTER `user_id`",
+      "ALTER TABLE `analytics`.`events` ON CLUSTER `main` MODIFY COLUMN `kind` LowCardinality(String)",
+      "CREATE VIEW analytics.by_kind ON CLUSTER `main` AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind COMMENT '[chant managed-by=chant stack=shop env=prod]'",
+      "DROP TABLE `analytics`.`old` ON CLUSTER `main` SYNC",
+    ]);
+  });
+
+  test("an engine the topology changes is no change: a cluster's Replicated engine compares equal to the declared MergeTree", () => {
+    for (const [, t] of TOPOLOGIES) expect(diffStatements(FIRST, FIRST, { topology: t }).steps).toEqual([]);
+  });
+
+  test.each(TOPOLOGIES)("the applier sends the same statements as the offline renderer for %s", async (label, t) => {
+    const s = await writableClickHouse();
+    servers.push(s);
+    const deps = { config, env: { CLICKHOUSE_URL: s.url, CLICKHOUSE_TOPOLOGY: label }, log: () => undefined };
+    await clickhouseApply({ buildPath: buildFile(FIRST), environment: "test" }, undefined, deps);
+    expect(s.writes).toEqual(sqlOf(diffStatements(EMPTY, FIRST, { marker: MARKER, topology: t })));
+    // Applied again: nothing to send, the engines it created compare equal to the declarations rendered for it.
+    s.writes.length = 0;
+    await clickhouseApply({ buildPath: buildFile(FIRST), environment: "test" }, undefined, deps);
+    expect(s.writes).toEqual([]);
+    const after = build("clickhouse", [DB, EVENTS_V2, SESSIONS_RESORTED, BY_KIND, MV]);
+    await clickhouseApply({ buildPath: buildFile(after), environment: "test", prune: true }, undefined, deps);
+    expect(s.writes).toEqual(sqlOf(diffStatements(FIRST, after, { marker: MARKER, topology: t })));
+  });
+
+  test("chant sql diff --statements --topology renders for that topology", async () => {
+    const lines: string[] = [];
+    const log = vi.spyOn(console, "log").mockImplementation((l: unknown) => void lines.push(String(l)));
+    try {
+      expect(await runDiff({ verb: "diff", rawArgs: [buildFile(EMPTY), buildFile(FIRST), "--statements", "--json", "--topology", "cluster:main"] })).toBe(0);
+      expect(await runDiff({ verb: "diff", rawArgs: [buildFile(EMPTY), buildFile(FIRST), "--statements", "--json", "--topology=replicated"] })).toBe(0);
+    } finally {
+      log.mockRestore();
+    }
+    expect(JSON.parse(lines[0]!)).toEqual(diffStatements(EMPTY, FIRST, { topology: { kind: "cluster", cluster: "main" } }));
+    expect(JSON.parse(lines[1]!)).toEqual(diffStatements(EMPTY, FIRST, { topology: { kind: "replicated" } }));
+  });
+
+  test("chant sql diff refuses a topology it does not know", async () => {
+    const err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+      expect(await runDiff({ verb: "diff", rawArgs: [buildFile(EMPTY), buildFile(FIRST), "--statements", "--topology", "sharded"] })).toBe(1);
+      expect(err.mock.calls[0]![0]).toMatch(/--topology: unknown topology "sharded"/);
+    } finally {
+      err.mockRestore();
+    }
+  });
+});

package/src/migration-statements.ts

@@ -34,6 +34,7 @@ import type { OwnershipMarker } from "@intentius/chant/ownership";
 import { statementChange, type ManualStep, type MigrationStep, type SchemaStatements, type StepObject } from "./core/statements";
 import { declaredObjects as clickhouseDeclared } from "./clickhouse/apply/apply";
 import { planStatements, type DeclaredObject } from "./clickhouse/apply/statements";
+import { topologyLabel, type Topology } from "./clickhouse/topology";
 import { diffSchemas, type Change } from "./clickhouse/plan/diff";
 import { rebuildOpSuggestions } from "./clickhouse/plan/rebuild-handoff";
 import { declaredObjects as postgresDeclared } from "./postgres/apply/apply";
@@ -54,6 +55,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. */
@@ -93,8 +101,9 @@ const at = (object: string, type: string, name: string): StepObject => ({ object
 function clickhouseStatements(beforeJson: string, afterJson: string, options: DiffStatementsOptions): SchemaStatements {
   const defaultDatabase = options.defaultDatabase ?? "default";
   const env = options.env ?? "<env>";
-  const before = clickhouseDeclared(beforeJson, defaultDatabase);
-  const after = clickhouseDeclared(afterJson, defaultDatabase);
+  const topology: Topology = options.topology ?? { kind: "single" };
+  const before = clickhouseDeclared(beforeJson, defaultDatabase, topology);
+  const after = clickhouseDeclared(afterJson, defaultDatabase, topology);
   const keyed = (objs: readonly DeclaredObject[]) => objs.map((o) => ({ key: o.exportName, canonical: o.canonical }));
   const diff = diffSchemas(keyed(before), keyed(after));
   const plan = planStatements({
@@ -103,6 +112,7 @@ function clickhouseStatements(beforeJson: string, afterJson: string, options: Di
     current: new Map(before.map((o) => [o.exportName, o.canonical])),
     keyOf: (o) => o.exportName,
     allowDestructive: true,
+    topology,
     ...(options.marker ? { marker: options.marker } : {}),
   });
   const declaredByExport = new Map(after.map((o) => [o.exportName, o.canonical]));
@@ -156,7 +166,7 @@ function clickhouseStatements(beforeJson: string, afterJson: string, options: Di
       ...(change?.destructive ? { destructive: true } : {}),
     });
   }
-  return { dialect: "clickhouse", defaultDatabase, steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
+  return { dialect: "clickhouse", defaultDatabase, topology: topologyLabel(topology), steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
 }
 
 // ── Postgres ───────────────────────────────────────────────────────────

package/src/op/activities/clickhouse-apply.ts

@@ -84,7 +84,7 @@ export async function clickhouseApply(args: ClickHouseApplyArgs, signal?: AbortS
     if (!(err instanceof ClickHouseBindingError)) throw err;
     return refused(declaredObjects(json), err.unresolved.reason, err.unresolved.detail);
   }
-  const declared = declaredObjects(json, target.defaultDatabase);
+  const declared = declaredObjects(json, target.defaultDatabase, target.topology);
   let outcome: ClickHouseApplyOutcome;
   try {
     outcome = await applyClickHouse(target, declared, {

package/src/op/activities/clickhouse-rebuild.ts

@@ -59,7 +59,7 @@ export async function rebuildRun(args: ClickHouseRebuildArgs, signal: AbortSigna
   const config = deps.config ?? (await loadConfig(cwd));
   const marker = resolveMarker(args, config);
   const target = await bindClickHouse({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
-  const declared = declaredTable(declaredObjects(readFileSync(resolve(cwd, args.buildPath), "utf8"), target.defaultDatabase), args.table);
+  const declared = declaredTable(declaredObjects(readFileSync(resolve(cwd, args.buildPath), "utf8"), target.defaultDatabase, target.topology), args.table);
   const runId = currentOpRun()?.runId;
   return {
     target,