@intentius/chant-lexicon-sql 0.113.0 → 0.114.0

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,

package/src/op/apply-gate-create.e2e.test.ts

@@ -0,0 +1,280 @@
+/**
+ * An approval for a plan that creates an object does not survive an edit to
+ * that object (#3652), end to end on both dialects.
+ *
+ * For each dialect, a project in a temporary directory declares a table that
+ * does not exist yet and a gated `ApplyOp`. `chant run` stops at the gate and
+ * prints the `chant approve ... --plan <digest>` that answers it; the test
+ * approves that digest, adds a column to the declared table, and runs again.
+ * The gate refuses with "is approved, but not for this plan" and nothing is
+ * created. Approving the new plan then applies the edited table.
+ *
+ * Before #3652 the plan digest was taken over a diff that listed the table by
+ * name only, so the second run applied the edited table under the first
+ * approval.
+ *
+ * Everything is written to the database (ClickHouse) or schema (Postgres)
+ * `yodel_3652`.
+ *
+ * The servers: `CHANT_SQL_GATE_CLICKHOUSE_URL` and
+ * `CHANT_SQL_GATE_POSTGRES_URL` (a `postgres://user@host:port/db` URL, with
+ * `CHANT_SQL_GATE_POSTGRES_PASSWORD`) name running ones, such as the servers
+ * `chant emulator up --lexicon sql` starts. Without them, each dialect starts
+ * a throwaway server at the same pin, and skips cleanly when Docker is not
+ * available.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../clickhouse/container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../clickhouse/http";
+import { clickhouseImage } from "../spec/pin";
+import { startTestPostgres, type TestPostgres } from "../postgres/testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../postgres/live/client";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const NAME = "yodel_3652";
+const OP = "schema-apply";
+
+const givenClickHouse = process.env.CHANT_SQL_GATE_CLICKHOUSE_URL;
+const givenPostgres = process.env.CHANT_SQL_GATE_POSTGRES_URL;
+const docker = givenClickHouse && givenPostgres ? false : await dockerAvailable();
+
+interface Run {
+  code: number;
+  output: string;
+}
+
+const strip = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, "");
+
+/**
+ * A project directory chant can run in: the repository's `node_modules`
+ * linked in, so `@intentius/chant` and the sql lexicon resolve, and a git
+ * repository, which the gate ledger and snapshots are written to.
+ */
+async function project(files: Record<string, string>, env: Record<string, string>) {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-gate-"));
+  symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+  const write = (all: Record<string, string>) => {
+    for (const [path, text] of Object.entries(all)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true });
+      writeFileSync(join(dir, path), text);
+    }
+  };
+  write({
+    "package.json": JSON.stringify({ name: "sql-gate-e2e", private: true, type: "module", scripts: { build: "chant build src --lexicon sql -o dist/schema.json" } }),
+    ".gitignore": "node_modules\ndist\n.chant\n",
+    ...files,
+  });
+  const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+  await git("init", "-q");
+  await git("add", "-A");
+  await git("commit", "-qm", "the schema");
+  const chant = async (...args: string[]): Promise<Run> => {
+    try {
+      const r = await exec(join(BIN, "chant"), args, {
+        cwd: dir,
+        env: { ...process.env, ...env, PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      return { code: 0, output: strip(`${r.stdout}${r.stderr}`) };
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string };
+      return { code: typeof e.code === "number" ? e.code : 1, output: strip(`${e.stdout ?? ""}${e.stderr ?? ""}`) };
+    }
+  };
+  return {
+    dir,
+    chant,
+    async edit(path: string, text: string) {
+      write({ [path]: text });
+      await git("commit", "-qam", `edit ${path}`);
+    },
+  };
+}
+
+/** The `--plan <digest>` the stopped run printed in its approve command. */
+function approvedPlan(run: Run): string {
+  const m = /chant approve \S+ \S+ .*?--plan (jcs1-sha256:[0-9a-f]{64})/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command with a plan:\n${run.output}`);
+  return m[1];
+}
+
+function gateOf(run: Run): string {
+  const m = /chant approve \S+ (\S+)/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command:\n${run.output}`);
+  return m[1];
+}
+
+const OPS = (target: string) => ({
+  "ops/apply.op.ts": `import { ApplyOp } from "@intentius/chant/op";
+const { op } = ApplyOp({ name: "${OP}", env: "admin", target: "${target}", gate: { gate: "approve-schema" } });
+export default op;
+`,
+});
+
+const config = (sql: Record<string, unknown>) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "yodel-3652", env: "admin" },
+  sql: ${JSON.stringify(sql, null, 2)},
+} satisfies ChantConfig;
+`;
+
+/**
+ * The shared scenario: approve a create, edit the declared object, rerun.
+ * `columns` reads the live table's column names.
+ */
+async function approveEditRerun(
+  p: Awaited<ReturnType<typeof project>>,
+  edited: { path: string; text: string },
+  columns: () => Promise<string[]>,
+): Promise<void> {
+  const first = await p.chant("run", OP);
+  expect(first.output).toMatch(/MISSING \(declared, provider reports not in cloud\):[\s\S]*- events .*\[definition [0-9a-f]{64}\]/);
+  const gate = gateOf(first);
+  const digest = approvedPlan(first);
+
+  const approve = await p.chant("approve", OP, gate, "--plan", digest);
+  expect(approve.code, approve.output).toBe(0);
+
+  await p.edit(edited.path, edited.text);
+
+  const second = await p.chant("run", OP);
+  expect(second.output).toContain(`Gate "${gate}" is approved, but not for this plan.`);
+  expect(second.output).toContain(`approved: ${digest}`);
+  expect(second.output).not.toMatch(/Op "schema-apply" completed/);
+  expect(await columns()).toEqual([]);
+
+  // Approving the plan the second run produced applies the edited table.
+  const fresh = approvedPlan(second);
+  expect(fresh).not.toBe(digest);
+  const reapprove = await p.chant("approve", OP, gate, "--plan", fresh);
+  expect(reapprove.code, reapprove.output).toBe(0);
+  const third = await p.chant("run", OP);
+  expect(third.output).toMatch(/Op "schema-apply" completed/);
+  expect(await columns()).toContain("note");
+}
+
+// ── ClickHouse ──────────────────────────────────────────────────────────────
+
+const CH_SCHEMA = (extra: string) => `import { database, table } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const db = database\`CREATE DATABASE ${NAME} ENGINE = Atomic COMMENT 'gate binds creates'\`;
+
+export const events = table\`
+  CREATE TABLE \${db}.events (
+    user_id UInt64,
+    ts      DateTime${extra}
+  )
+  ENGINE = MergeTree
+  ORDER BY (user_id, ts)
+  COMMENT 'Raw events'\`;
+`;
+
+describe.skipIf(!givenClickHouse && !docker)("a gated ApplyOp over ClickHouse refuses an edited create (#3652)", () => {
+  let server: ScratchServer | undefined;
+  let admin: ClickHouseEndpoint;
+  let p: Awaited<ReturnType<typeof project>>;
+  const q = (sql: string) => clickhouseQuery(admin, sql);
+
+  beforeAll(async () => {
+    if (givenClickHouse) admin = { url: givenClickHouse };
+    else {
+      server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-gate" });
+      admin = server.endpoint;
+    }
+    await q(`DROP DATABASE IF EXISTS ${NAME} SYNC`);
+    p = await project(
+      {
+        ...OPS("clickhouse"),
+        "chant.config.ts": config({ dialect: "clickhouse", profiles: { admin: { url: admin.url, databases: [NAME] } } }),
+        "src/schema.ts": CH_SCHEMA(""),
+      },
+      {},
+    );
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) await q(`DROP DATABASE IF EXISTS ${NAME} SYNC`).catch(() => undefined);
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("approve a create, add a column, rerun: the gate refuses", async () => {
+    await approveEditRerun(p, { path: "src/schema.ts", text: CH_SCHEMA(",\n    note    String") }, async () => {
+      const rows = await clickhouseQuery<{ name: string }>(admin, `SELECT name FROM system.columns WHERE database = '${NAME}' AND table = 'events' ORDER BY position`);
+      return rows.map((r) => r.name);
+    });
+  }, 600_000);
+});
+
+// ── Postgres ────────────────────────────────────────────────────────────────
+
+const PG_SCHEMA = (extra: string) => `import { schema, table } from "@intentius/chant-lexicon-sql/postgres";
+
+export const app = schema\`CREATE SCHEMA ${NAME};
+COMMENT ON SCHEMA ${NAME} IS 'gate binds creates'\`;
+
+export const events = table\`
+  CREATE TABLE \${app}.events (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    kind text NOT NULL${extra}
+  )\`;
+`;
+
+describe.skipIf(!givenPostgres && !docker)("a gated ApplyOp over Postgres refuses an edited create (#3652)", () => {
+  let server: TestPostgres | undefined;
+  let endpoint: PostgresEndpoint;
+  let admin: PostgresClient;
+  let p: Awaited<ReturnType<typeof project>>;
+  const q = (sql: string) => admin.query(sql);
+
+  beforeAll(async () => {
+    if (givenPostgres) endpoint = { url: givenPostgres, password: process.env.CHANT_SQL_GATE_POSTGRES_PASSWORD };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await q(`DROP SCHEMA IF EXISTS ${NAME} CASCADE`);
+    p = await project(
+      {
+        ...OPS("postgres"),
+        "chant.config.ts": config({
+          dialect: "postgres",
+          profiles: { admin: { url: endpoint.url, password: { env: "ADMIN_PASSWORD" }, schemas: [NAME] } },
+        }),
+        "src/schema.ts": PG_SCHEMA(""),
+      },
+      { ADMIN_PASSWORD: endpoint.password ?? "" },
+    );
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await q(`DROP SCHEMA IF EXISTS ${NAME} CASCADE`).catch(() => undefined);
+      await admin.end();
+    }
+    await server?.stop();
+    if (p) rmSync(p.dir, { recursive: true, force: true });
+  });
+
+  test("approve a create, add a column, rerun: the gate refuses", async () => {
+    await approveEditRerun(p, { path: "src/schema.ts", text: PG_SCHEMA(",\n    note text") }, async () => {
+      const rows = await admin.query<{ column_name: string }>(
+        `SELECT column_name FROM information_schema.columns WHERE table_schema = '${NAME}' AND table_name = 'events' ORDER BY ordinal_position`,
+      );
+      return rows.map((r) => r.column_name);
+    });
+  }, 600_000);
+});

package/src/plugin.test.ts

@@ -39,6 +39,15 @@ describe("the sql config namespace", () => {
     expect(sqlConfigSchema.safeParse({ provider: "heroku" }).success).toBe(false);
   });
 
+  test("a profile takes a ClickHouse topology in its string or object form (#3645)", () => {
+    for (const topology of ["single", "cluster:main", "cluster:{cluster}", "replicated", "replicated:all", "cloud", { kind: "cluster", cluster: "main", replicaPath: "/ch/{shard}/{table}" }, { kind: "replicated" }]) {
+      expect(sqlConfigSchema.safeParse({ profiles: { prod: { url: "http://x:8123", topology } } }).success, JSON.stringify(topology)).toBe(true);
+    }
+    for (const topology of ["cluster", "sharded", { kind: "cluster" }, { kind: "single", cluster: "x" }]) {
+      expect(sqlConfigSchema.safeParse({ profiles: { prod: { url: "http://x:8123", topology } } }).success, JSON.stringify(topology)).toBe(false);
+    }
+  });
+
   test("accepts a list of dialects", () => {
     expect(sqlConfigSchema.safeParse({ dialect: ["clickhouse"] }).success).toBe(true);
     expect(sqlConfigSchema.safeParse({ dialect: ["clickhouse", "postgres"] }).success).toBe(true);