@intentius/chant-lexicon-sql 0.113.0 → 0.114.0

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

@@ -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;

package/src/clickhouse/rebuild/steps.ts

@@ -14,6 +14,7 @@ import type { ClickHouseTarget } from "../live/bind";
 import { carriesMarker, readTrailerPairs, REBUILD_TRAILER_KEY, stampedComment } from "../ownership";
 import { createStatement, ident, qualifiedIdent, renamedDeclaration, sqlString, type DeclaredObject } from "../apply/statements";
 import { waitForMutations } from "../apply/mutations";
+import { renderFor } from "../topology";
 import { DDL_SETTINGS, syncReplicaWithin } from "./replicas";
 import {
   changesBetween,
@@ -60,12 +61,14 @@ export const utcLiteral = (ms: number): string => `toDateTime64(${sqlString(sqlU
 export const observe = (run: RebuildRun): Promise<RebuildObservation> => observeRebuild(run.target, run.declared, run.marker);
 
 /**
- * One DDL statement. In a Replicated database it goes on without the
- * replicas that are down, which run it from the database's log when they
- * come back (`./replicas.ts`).
+ * One DDL statement, rendered for the environment's topology when it names
+ * one (`../topology.ts`: `ON CLUSTER` and the engine). In a Replicated
+ * database it goes on without the replicas that are down, which run it from
+ * the database's log when they come back (`./replicas.ts`).
  */
-const q = (run: RebuildRun, sql: string) => {
+const q = (run: RebuildRun, statement: string) => {
   run.signal?.throwIfAborted();
+  const sql = renderFor(statement, run.target.topology);
   run.log(sql);
   return clickhouseQuery(run.target.endpoint, sql, { settings: DDL_SETTINGS, ...(run.signal ? { signal: run.signal } : {}) });
 };
@@ -373,7 +376,7 @@ export async function compensate(run: Pick<RebuildRun, "target" | "declared" | "
     const row = rows.find((r) => r.name === name);
     const pairs = readTrailerPairs(row?.comment);
     if (!row || pairs?.get(REBUILD_TRAILER_KEY) !== n.key || pairs.get("role") !== role || !carriesMarker(row.comment, run.marker)) continue;
-    const sql = `DROP ${what} ${qualifiedIdent(n.database, name)} SYNC`;
+    const sql = renderFor(`DROP ${what} ${qualifiedIdent(n.database, name)} SYNC`, run.target.topology);
     run.log(sql);
     await clickhouseQuery(run.target.endpoint, sql, { settings: DDL_SETTINGS });
     dropped.push(`${n.database}.${name}`);

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

@@ -0,0 +1,125 @@
+/**
+ * The replicated topology against a Replicated database (#3645): two
+ * replicas of the pinned server, Keeper embedded in the first (the scratch
+ * cluster the Replicated rebuild runs on).
+ *
+ * The source is written for a single node: a plain database, MergeTree
+ * tables. Applied with `CLICKHOUSE_TOPOLOGY=replicated`, the database is a
+ * `Replicated` one and its tables `Replicated*MergeTree` with no path, so
+ * the second replica gets them from the database's log and rows written on
+ * one reach the other. Applied again on the other replica, the server's
+ * printed engines (with the default Keeper path filled in) compare equal to
+ * the declarations, and nothing is sent; a change applies there and reaches
+ * the first.
+ *
+ * The scratch cluster names no cluster in `remote_servers`, so the second
+ * replica joins the database with the `CREATE DATABASE` the applier sent to
+ * the first, as an operator would (`replicated:<cluster>` sends it `ON
+ * CLUSTER` instead). Needs Docker; skips cleanly without it.
+ */
+
+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 { dockerAvailable, startScratchCluster, type ScratchCluster } from "./container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "./http";
+import { clickhouseImage } from "../spec/pin";
+import { clickhouseApply } from "../op/activities/clickhouse-apply";
+import { renderStatement } from "./topology";
+
+const DB = "yodel_3645";
+const enabled = await dockerAvailable();
+let cluster: ScratchCluster | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-topology-repl-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  cluster = await startScratchCluster(clickhouseImage(), { replicas: 2, namePrefix: "chant-sql-topology-repl" });
+}, 600_000);
+
+afterAll(async () => {
+  await cluster?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+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}` },
+  {
+    export: "events",
+    type: "ClickHouse::Table",
+    dependsOn: ["db"],
+    ddl: `CREATE TABLE ${DB}.events (id UInt64, ts DateTime, kind String${extraColumn}) ENGINE = ReplacingMergeTree(ts) ORDER BY id`,
+  },
+  {
+    export: "byKind",
+    type: "ClickHouse::MaterializedView",
+    dependsOn: ["events"],
+    ddl: `CREATE MATERIALIZED VIEW ${DB}.by_kind ENGINE = SummingMergeTree ORDER BY kind AS SELECT kind, count() AS n FROM ${DB}.events GROUP BY kind`,
+  },
+];
+
+const q = <T = Record<string, unknown>>(at: ClickHouseEndpoint, sql: string) => clickhouseQuery<T>(at, sql);
+
+async function apply(at: ClickHouseEndpoint, buildPath: string) {
+  const sent: string[] = [];
+  const outcome = await clickhouseApply({ buildPath, environment: "test" }, undefined, {
+    config: { ownership: { stack: "yodel", env: "e2e" } },
+    env: { CLICKHOUSE_URL: at.url, CLICKHOUSE_TOPOLOGY: "replicated" },
+    log: (l) => void (/^[A-Z]+ /.test(l) && sent.push(l)),
+  });
+  return { outcome, sent };
+}
+
+describe.skipIf(!enabled)("the replicated topology on a Replicated database (#3645)", () => {
+  test("a single node's source becomes a Replicated database that both replicas hold, and converges on either", async () => {
+    const [r1, r2] = cluster!.replicas as [ClickHouseEndpoint, ClickHouseEndpoint];
+    expect(renderStatement(`CREATE DATABASE ${DB}`, { kind: "replicated" })).toBe(`CREATE DATABASE ${DB} ENGINE = Replicated('/clickhouse/databases/${DB}', '{shard}', '{replica}')`);
+
+    const v1 = writeBuild("v1.json", objects());
+    const first = await apply(r1, v1);
+    expect(first.outcome.failed).toEqual([]);
+    // The second replica joins the database with the statement the applier sent to the first, and replays its tables from the log.
+    expect(first.sent[0]).toMatch(new RegExp(`^CREATE DATABASE ${DB} ENGINE = Replicated\\('/clickhouse/databases/${DB}', '\\{shard\\}', '\\{replica\\}'\\) COMMENT `));
+    await q(r2, first.sent[0]!);
+    await q(r2, `SYSTEM SYNC DATABASE REPLICA ${DB}`);
+    expect(first.sent.join("\n")).not.toMatch(/ON CLUSTER/);
+    expect(first.sent[1]).toMatch(/ENGINE = ReplicatedReplacingMergeTree\(ts\) ORDER BY id/);
+
+    await q(r1, `INSERT INTO ${DB}.events (id, ts, kind) VALUES (1, now(), 'click'), (2, now(), 'view')`);
+    await q(r2, `SYSTEM SYNC REPLICA ${DB}.events`);
+    expect(Number((await q<{ n: string | number }>(r2, `SELECT count() AS n FROM ${DB}.events`))[0]!.n)).toBe(2);
+    const engines = await q<{ name: string; engine: string }>(r2, `SELECT name, engine FROM system.tables WHERE database = '${DB}' ORDER BY name`);
+    expect(engines.map((t) => [t.name.startsWith(".inner") ? ".inner" : t.name, t.engine])).toEqual([
+      [".inner", "ReplicatedSummingMergeTree"],
+      ["by_kind", "MaterializedView"],
+      ["events", "ReplicatedReplacingMergeTree"],
+    ]);
+    expect((await q<{ engine: string }>(r2, `SELECT engine FROM system.databases WHERE name = '${DB}'`))[0]!.engine).toBe("Replicated");
+
+    // On the other replica: the printed engines (default Keeper path filled in) are the declarations; nothing to send.
+    const again = await apply(r2, v1);
+    expect(again.sent).toEqual([]);
+    expect(again.outcome.notAttempted).toEqual([]);
+
+    // A change there reaches the first replica through the database's log.
+    const change = await apply(r2, writeBuild("v2.json", objects(", source String DEFAULT 'web'")));
+    expect(change.sent).toEqual([`ALTER TABLE \`${DB}\`.\`events\` ADD COLUMN source String DEFAULT 'web' AFTER \`kind\``]);
+    await q(r1, `SYSTEM SYNC DATABASE REPLICA ${DB}`);
+    const cols = await q<{ name: string }>(r1, `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"]);
+  }, 300_000);
+});

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";