@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/clickhouse/plan/plan-wiring.test.ts

@@ -0,0 +1,77 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import { classifyDisruption } from "./disruption";
+import { inDeclaredVocabulary } from "./deep";
+import { canonicalObject } from "./normalize";
+import { runDiff } from "./commands";
+import { table } from "../entities";
+
+describe("classifyDisruption", () => {
+  const q = (paths: string[]) => ({ name: "t", type: "ClickHouse::Table", deltas: paths.map((path) => ({ path, oldValue: 1, newValue: 2 })) });
+  const run = (paths: string[]) => classifyDisruption({ environment: "e", changes: [q(paths)] }).t!;
+
+  test("metadata is in-place, a rewrite rolling, a rebuild replace", () => {
+    expect(run(["comment", "indexes[0].name"]).disruption).toBe("in-place");
+    expect(run(["ttl"]).disruption).toBe("rolling");
+    expect(run(["ttl", "partitionBy"])).toMatchObject({ disruption: "replace", because: ["partitionBy"] });
+    expect(run(["settings.index_granularity"]).disruption).toBe("replace");
+  });
+
+  test("a column type or sorting-key change is unknown without the whole definition", () => {
+    expect(run(["columns[2].type"]).disruption).toBe("unknown");
+    expect(run(["orderBy"]).disruption).toBe("unknown");
+  });
+
+  test("another lexicon's entry is left alone", () => {
+    expect(classifyDisruption({ environment: "e", changes: [{ name: "x", type: "K8s::Core::Pod", deltas: [] }] })).toEqual({});
+  });
+});
+
+describe("the deep read in the declaration's vocabulary", () => {
+  const declared = table`CREATE TABLE t (ts DateTime CODEC(Delta, ZSTD), n UInt8) ENGINE = MergeTree ORDER BY ts TTL ts + INTERVAL 1 DAY`;
+  const shown = "CREATE TABLE default.t\n(\n    `ts` DateTime CODEC(Delta(4), ZSTD(1)),\n    `n` UInt8\n)\nENGINE = MergeTree\nORDER BY ts\nTTL ts + toIntervalDay(1)\nSETTINGS index_granularity = 8192";
+  const strings = Object.assign([shown], { raw: [shown] }) as unknown as TemplateStringsArray;
+  const live = table(strings).props as unknown as Record<string, unknown>;
+  const props = declared.props as unknown as Record<string, unknown>;
+
+  test("a field the server only reformatted reads as declared", () => {
+    const out = inDeclaredVocabulary(props, live, canonicalObject(String(props.ddl)), canonicalObject(shown));
+    expect(out.ttl).toBe(props.ttl);
+    expect(out.columns).toEqual(props.columns);
+    expect(out.settings).toBeUndefined();
+  });
+
+  test("a field that really differs keeps the server's value", () => {
+    const changed = shown.replace("toIntervalDay(1)", "toIntervalDay(2)");
+    const s2 = Object.assign([changed], { raw: [changed] }) as unknown as TemplateStringsArray;
+    const out = inDeclaredVocabulary(props, table(s2).props as unknown as Record<string, unknown>, canonicalObject(String(props.ddl)), canonicalObject(changed));
+    expect(out.ttl).toBe("ts + toIntervalDay(2)");
+  });
+});
+
+describe("chant sql diff", () => {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-diff-"));
+  afterAll(() => rmSync(dir, { recursive: true, force: true }));
+  const write = (name: string, ddl: string) => {
+    const file = join(dir, name);
+    writeFileSync(file, JSON.stringify({ dialect: "clickhouse", applyOrder: ["events"], objects: [{ export: "events", ddl }] }));
+    return file;
+  };
+
+  test("exits 2 on a rebuild, 0 otherwise, and prints the classification", async () => {
+    const base = write("base.json", "CREATE TABLE events (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY id");
+    const head = write("head.json", "CREATE TABLE events (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY (ts, id)");
+    const add = write("add.json", "CREATE TABLE events (id UInt64, ts DateTime, x String) ENGINE = MergeTree ORDER BY id");
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    try {
+      expect(await runDiff({ verb: "diff", rawArgs: [base, head] })).toBe(2);
+      expect(String(log.mock.calls.at(-1)?.[0])).toMatch(/SQLCH220/);
+      expect(await runDiff({ verb: "diff", rawArgs: [base, add, "--json"] })).toBe(0);
+      expect(JSON.parse(String(log.mock.calls.at(-1)?.[0])).changes[0].rule).toBe("SQLCH201");
+    } finally {
+      log.mockRestore();
+    }
+  });
+});

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

@@ -0,0 +1,77 @@
+/**
+ * Planning against a live server (#3197): the getting-started example applied
+ * to a pinned server plans with no changes, its deep read reports no drift,
+ * and a change made on the server is reported and classified.
+ *
+ * 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 { build } from "@intentius/chant/build";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../container";
+import { clickhouseQuery } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { splitStatements } from "../import/ir";
+import { planAgainstServer } from "./commands";
+import { observeResourcesDeep, sqlDeepNormalizationHooks } from "./deep";
+import { sqlPlugin } from "../../plugin";
+import { CLICKHOUSE_DDL_FILE, sqlSerializer } from "../../serializer";
+
+const enabled = await dockerAvailable();
+let server: ScratchServer | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-plan-"));
+const buildFile = join(dir, "schema.json");
+let entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-plan" });
+  const src = join(import.meta.dirname, "..", "..", "..", "examples", "getting-started", "src");
+  const result = await build(src, [sqlSerializer], undefined, { fold: true, intrinsics: sqlPlugin.intrinsics!(), lexicons: ["sql"] });
+  const out = result.outputs.get("sql") as SerializerResult;
+  writeFileSync(buildFile, out.primary);
+  for (const stmt of splitStatements(out.files![CLICKHOUSE_DDL_FILE]!)) await clickhouseQuery(server.endpoint, stmt);
+  entities = new Map(
+    [...result.entities].map(([k, v]) => [k, { entityType: v.entityType, props: (v as unknown as { props: Record<string, unknown> }).props }]),
+  );
+}, 600_000);
+
+afterAll(async () => {
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const env = () => ({ config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+
+/** The props a deep diff compares: the declaration's, less what the hooks prune. */
+function compared(props: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(props).filter(([k]) => !sqlDeepNormalizationHooks.prune!({ pattern: k } as never)));
+}
+
+describe.skipIf(!enabled)("planning the getting-started example against a server", () => {
+  test("applied as declared, it plans with no changes and reads back with no drift", async () => {
+    const diff = await planAgainstServer("e2e", buildFile, env());
+    expect(diff.changes).toEqual([]);
+
+    const deep = await observeResourcesDeep({ environment: "e2e", entityNames: [...entities.keys()], entities, ...env() });
+    expect(deep.unobserved ?? {}).toEqual({});
+    for (const [name, e] of entities) {
+      expect(compared(deep.resources[name]!.properties), name).toEqual(JSON.parse(JSON.stringify(compared(e.props))));
+    }
+  }, 120_000);
+
+  test("a change made on the server is drift, classified", async () => {
+    await clickhouseQuery(server!.endpoint, "ALTER TABLE analytics.events MODIFY TTL ts + INTERVAL 90 DAY");
+    await clickhouseQuery(server!.endpoint, "ALTER TABLE analytics.users ADD COLUMN extra String");
+    const diff = await planAgainstServer("e2e", buildFile, env());
+    expect(diff.changes.map((c) => [c.object, c.field, c.rule])).toEqual([
+      ["events (analytics.events)", "ttl", "SQLCH205"],
+      ["users (analytics.users)", "columns.extra", "SQLCH202"],
+    ]);
+    expect(diff.rebuilds).toEqual([]);
+  }, 120_000);
+});

package/src/clickhouse/plan/plan.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, test } from "vitest";
+import { canonicalCodec, canonicalExpression, canonicalObject, canonicalTtl, canonicalType } from "./normalize";
+import { diffSchemas, type SchemaObject } from "./diff";
+import { renderDiff } from "./report";
+import { CLASSIFIER_RULES } from "./rules";
+
+const DECLARED_EVENTS = `CREATE TABLE analytics.events (
+  user_id UUID,
+  kind LowCardinality(String),
+  ts DateTime CODEC(Delta, ZSTD),
+  props Map(String, String),
+  n Nullable(UInt32) DEFAULT 1 COMMENT 'c',
+  INDEX k kind TYPE bloom_filter(0.01) GRANULARITY 4
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (user_id, kind, ts)
+TTL ts + INTERVAL 180 DAY DELETE
+SETTINGS index_granularity = 8192
+COMMENT 'events table'`;
+
+// What clickhouse-server 26.8.15.10 prints for DECLARED_EVENTS.
+const SHOWN_EVENTS = `CREATE TABLE analytics.events
+(
+    \`user_id\` UUID,
+    \`kind\` LowCardinality(String),
+    \`ts\` DateTime CODEC(Delta(4), ZSTD(1)),
+    \`props\` Map(String, String),
+    \`n\` Nullable(UInt32) DEFAULT 1 COMMENT 'c',
+    INDEX k kind TYPE bloom_filter(0.01) GRANULARITY 4
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (user_id, kind, ts)
+TTL ts + toIntervalDay(180)
+SETTINGS index_granularity = 8192
+COMMENT 'events table'`;
+
+const DECLARED_MV = "CREATE MATERIALIZED VIEW analytics.daily_mv TO analytics.daily AS SELECT toDate(ts) AS day, kind, uniqState(user_id) AS users FROM analytics.events GROUP BY day, kind";
+const SHOWN_MV = `CREATE MATERIALIZED VIEW analytics.daily_mv TO analytics.daily
+(
+    \`day\` Date,
+    \`kind\` LowCardinality(String),
+    \`users\` AggregateFunction(uniq, UUID)
+)
+AS SELECT
+    toDate(ts) AS day,
+    kind,
+    uniqState(user_id) AS users
+FROM analytics.events
+GROUP BY
+    day,
+    kind`;
+
+const obj = (key: string, ddl: string): SchemaObject => ({ key, canonical: canonicalObject(ddl) });
+
+describe("normalization", () => {
+  test("what the server prints for a declaration compares equal to the declaration", () => {
+    const noText = (o: ReturnType<typeof canonicalObject>) => ({ ...o, columns: o.columns.map(({ text: _, ...c }) => c) });
+    expect(noText(canonicalObject(SHOWN_EVENTS))).toEqual(noText(canonicalObject(DECLARED_EVENTS)));
+    const shown = canonicalObject(SHOWN_MV);
+    const declared = canonicalObject(DECLARED_MV);
+    expect(shown.select).toBe(declared.select);
+    expect(shown.to).toBe(declared.to);
+    expect(diffSchemas([obj("e", SHOWN_EVENTS), obj("m", SHOWN_MV)], [obj("e", DECLARED_EVENTS), obj("m", DECLARED_MV)]).changes).toEqual([]);
+  });
+
+  test("the server's rewrites are undone", () => {
+    expect(canonicalExpression("ts + INTERVAL 1 DAY")).toBe(canonicalExpression("ts + toIntervalDay(1)"));
+    expect(canonicalExpression("ts+interval 2 hours")).toBe(canonicalExpression("ts + toIntervalHour(2)"));
+    expect(canonicalExpression("(id)")).toBe("id");
+    expect(canonicalExpression("tuple()")).toBe("");
+    expect(canonicalExpression("analytics.events", "analytics")).toBe("events");
+    expect(canonicalType("int")).toBe("Int32");
+    expect(canonicalType("Nullable(BIGINT)")).toBe("Nullable ( Int64 )");
+    expect(canonicalCodec("Delta(8), ZSTD(1)")).toBe(canonicalCodec("Delta, ZSTD"));
+    expect(canonicalCodec("ZSTD(3)")).not.toBe(canonicalCodec("ZSTD"));
+    expect(canonicalTtl("d + INTERVAL 1 MONTH DELETE, d + INTERVAL 1 WEEK TO VOLUME 'cold'")).toBe(
+      canonicalTtl("d + toIntervalMonth(1), d + toIntervalWeek(1) TO VOLUME 'cold'"),
+    );
+  });
+
+  test("a Replicated*MergeTree with no arguments is the one the server prints with its default Keeper path and replica", () => {
+    const shown = (engine: string) => canonicalObject(`CREATE TABLE t (a UInt8, v UInt8) ENGINE = ${engine} ORDER BY a`).engine;
+    expect(shown("ReplicatedMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}')")).toBe(shown("ReplicatedMergeTree"));
+    expect(shown("ReplicatedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', v)")).toBe(shown("ReplicatedReplacingMergeTree(v)"));
+    expect(shown("ReplicatedMergeTree('/clickhouse/tables/{shard}/t', '{replica}')")).not.toBe(shown("ReplicatedMergeTree"));
+  });
+
+  test("a setting at its default is not part of the definition", () => {
+    expect(canonicalObject("CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS index_granularity = 8192").settings).toEqual({});
+    expect(canonicalObject("CREATE TABLE t (a UInt8) ENGINE = MergeTree ORDER BY a SETTINGS min_bytes_for_wide_part = '0'").settings).toEqual({ min_bytes_for_wide_part: "0" });
+  });
+});
+
+const BASE = "CREATE TABLE events (id UInt64, kind String, ts DateTime, n UInt32) ENGINE = MergeTree PARTITION BY toYYYYMM(ts) ORDER BY (id, ts)";
+
+function classify(after: string, before = BASE) {
+  return diffSchemas([obj("events", before)], [obj("events", after)]).changes.map((c) => [c.field, c.rule, c.class]);
+}
+
+describe("classifying a change", () => {
+  test("adding a column is metadata only", () => {
+    expect(classify(BASE.replace("n UInt32)", "n UInt32, extra String)"))).toEqual([["columns.extra", "SQLCH201", "metadata"]]);
+  });
+
+  test("dropping a column destroys its data; a key column cannot be dropped", () => {
+    const d = diffSchemas([obj("events", BASE)], [obj("events", BASE.replace(", n UInt32", ""))]).changes;
+    expect(d.map((c) => [c.rule, c.destructive])).toEqual([["SQLCH202", true]]);
+    expect(classify(BASE.replace("kind String, ", "").replace("(id, ts)", "(id, ts)"))[0]).toEqual(["columns.kind", "SQLCH202", "metadata"]);
+    expect(classify(BASE.replace("id UInt64, ", "").replace("(id, ts)", "ts"))).toContainEqual(["columns.id", "SQLCH213", "rebuild"]);
+  });
+
+  test("a type change rewrites in the background, or needs a rebuild for a key column", () => {
+    expect(classify(BASE.replace("n UInt32", "n UInt64"))).toEqual([["columns.n.type", "SQLCH210", "rewrite"]]);
+    expect(classify(BASE.replace("ts DateTime", "ts DateTime64(3)"))).toEqual([["columns.ts.type", "SQLCH211", "rebuild"]]);
+  });
+
+  test("a renamed column says so with previously; in a key it is a rebuild", () => {
+    expect(classify(BASE.replace("kind String,", "event_kind String, -- previously: kind\n"))).toEqual([["columns.event_kind", "SQLCH212", "metadata"]]);
+    expect(classify(BASE.replace("id UInt64,", "user_id UInt64, -- previously: id\n").replace("(id, ts)", "(user_id, ts)"))).toContainEqual([
+      "columns.user_id",
+      "SQLCH213",
+      "rebuild",
+    ]);
+  });
+
+  test("without the hint a rename is a drop and an add, and a hint says so", () => {
+    const d = diffSchemas([obj("events", BASE)], [obj("events", BASE.replace("kind String", "event_kind String"))]);
+    expect(d.changes.map((c) => c.rule).sort()).toEqual(["SQLCH201", "SQLCH202"]);
+    expect(d.hints[0]).toMatch(/-- previously: kind/);
+  });
+
+  test("the sorting key: appending a new column keeping the primary key is an ALTER, anything else a rebuild", () => {
+    expect(classify(BASE.replace("n UInt32)", "n UInt32, k2 String)").replace("ORDER BY (id, ts)", "PRIMARY KEY (id, ts) ORDER BY (id, ts, k2)"))).toEqual([
+      ["columns.k2", "SQLCH201", "metadata"],
+      ["orderBy", "SQLCH216", "metadata"],
+    ]);
+    expect(classify(BASE.replace("(id, ts)", "(ts, id)"))).toEqual([["orderBy", "SQLCH220", "rebuild"]]);
+  });
+
+  test("the partition key, the engine and the primary key need a rebuild", () => {
+    expect(classify(BASE.replace("toYYYYMM(ts)", "toDate(ts)"))).toEqual([["partitionBy", "SQLCH222", "rebuild"]]);
+    expect(classify(BASE.replace("ENGINE = MergeTree", "ENGINE = ReplacingMergeTree(ts)"))).toEqual([["engine", "SQLCH223", "rebuild"]]);
+    expect(classify(BASE.replace("ORDER BY", "PRIMARY KEY id ORDER BY"))).toEqual([["primaryKey", "SQLCH221", "rebuild"]]);
+  });
+
+  test("TTL rewrites; settings change in place unless fixed at creation; indexes and comments are metadata", () => {
+    expect(classify(`${BASE} TTL ts + INTERVAL 1 DAY`)).toEqual([["ttl", "SQLCH205", "rewrite"]]);
+    expect(classify(`${BASE} SETTINGS merge_with_ttl_timeout = 3600`)).toEqual([["settings.merge_with_ttl_timeout", "SQLCH206", "metadata"]]);
+    expect(classify(`${BASE} SETTINGS index_granularity = 1024`)).toEqual([["settings.index_granularity", "SQLCH218", "rebuild"]]);
+    expect(classify(BASE.replace("n UInt32)", "n UInt32, INDEX ix kind TYPE set(10) GRANULARITY 1)"))).toEqual([["indexes.ix", "SQLCH204", "metadata"]]);
+    expect(classify(`${BASE} COMMENT 'x'`)).toEqual([["comment", "SQLCH203", "metadata"]]);
+  });
+
+  test("a renamed table under the same export is a RENAME", () => {
+    expect(classify(BASE.replace("CREATE TABLE events", "CREATE TABLE raw_events"))).toEqual([["name", "SQLCH230", "metadata"]]);
+  });
+
+  test("views: a plain view's query is replaced; a materialized view's query is modified, its target fixed", () => {
+    const v = "CREATE VIEW v AS SELECT id FROM events";
+    expect(classify("CREATE VIEW v AS SELECT id, ts FROM events", v)).toEqual([["select", "SQLCH240", "metadata"]]);
+    const mv = "CREATE MATERIALIZED VIEW m TO dst AS SELECT id FROM events";
+    expect(classify("CREATE MATERIALIZED VIEW m TO dst AS SELECT id + 1 AS id FROM events", mv)).toEqual([["select", "SQLCH241", "metadata"]]);
+    expect(classify("CREATE MATERIALIZED VIEW m TO dst2 AS SELECT id FROM events", mv)).toEqual([["to", "SQLCH242", "rebuild"]]);
+  });
+
+  test("objects appear and disappear; a table becoming a view is a rebuild", () => {
+    const d = diffSchemas([obj("a", BASE)], [obj("b", "CREATE VIEW b AS SELECT 1")]);
+    expect(d.changes.map((c) => [c.object, c.rule])).toEqual([
+      ["b", "SQLCH200"],
+      ["a", "SQLCH250"],
+    ]);
+    expect(classify("CREATE VIEW events AS SELECT 1")).toEqual([["kind", "SQLCH224", "rebuild"]]);
+  });
+
+  test("against a server, previously before the statement matches the old name", () => {
+    const live = [{ key: "default.events", canonical: canonicalObject(BASE) }];
+    const declared = [{ key: "default.raw_events", canonical: canonicalObject(`-- previously: events\n${BASE.replace("TABLE events", "TABLE raw_events")}`) }];
+    expect(diffSchemas(live, declared).changes.map((c) => c.rule)).toEqual(["SQLCH230"]);
+  });
+});
+
+describe("the rules", () => {
+  test("every rule names a class, a restriction and a ClickHouse documentation page", () => {
+    for (const [id, r] of Object.entries(CLASSIFIER_RULES)) {
+      expect(r.id).toBe(id);
+      expect(r.restriction.length).toBeGreaterThan(20);
+      expect(r.cite).toMatch(/^https:\/\/clickhouse\.com\/docs\//);
+    }
+  });
+
+  test("a rebuild is refused in the report", () => {
+    const d = diffSchemas([obj("events", BASE)], [obj("events", BASE.replace("(id, ts)", "(ts, id)"))]);
+    expect(d.rebuilds).toHaveLength(1);
+    const text = renderDiff(d);
+    expect(text).toMatch(/\[REBUILD\] orderBy/);
+    expect(text).toMatch(/Refused: 1 change\(s\) need a rebuild/);
+    expect(text).toContain("https://clickhouse.com/docs/sql-reference/statements/alter/order-by");
+  });
+});

package/src/clickhouse/plan/rebuild-handoff.ts

@@ -0,0 +1,59 @@
+/**
+ * How a plan hands a rebuild to the rebuild migration Op (#3198).
+ *
+ * `chant sql plan`, `chant sql diff` and the applier refuse a rebuild in
+ * place. What they hand on is the Op to run instead, one per table: a
+ * `ClickHouseRebuildOp` declaration ready to put in an `*.op.ts` file, with
+ * the table's `database.name` filled in and a dual-write mode suggested from
+ * the declared columns (materialized-view mode on the first time column,
+ * otherwise app mode). The Op's own Plan phase then classifies the same
+ * change again against the server, so what it runs is what the plan refused,
+ * read fresh.
+ *
+ * Nothing is written for the user: the Op is a declaration, reviewed in the
+ * pull request like the schema change it carries out. The hand-off's shape is
+ * the shared core's (`../../core/handoff.ts`); the Op and the dual-write
+ * suggestion are ClickHouse's.
+ */
+
+import type { CanonicalObject } from "./normalize";
+import type { SchemaDiff } from "./diff";
+import { migrationOpName, renderMigrationOps, type MigrationOpSuggestion } from "../../core/handoff";
+
+export interface RebuildOpSuggestion extends MigrationOpSuggestion {
+  /** `database.name`, the Op's `table`. */
+  table: string;
+  dualWrite: { mode: "materialized-view"; cutoverColumn: string } | { mode: "app" };
+}
+
+const TIME_TYPE = /^(?:Nullable\s*\(\s*)?(?:Date|Date32|DateTime|DateTime64)\b/;
+
+/**
+ * One suggestion per object the diff refuses as a rebuild. `declared` maps
+ * the diff's object keys to the declared definitions.
+ */
+export function rebuildOpSuggestions(diff: SchemaDiff, declared: ReadonlyMap<string, CanonicalObject>, env: string): RebuildOpSuggestion[] {
+  const out: RebuildOpSuggestion[] = [];
+  for (const key of [...new Set(diff.rebuilds.map((c) => c.object))]) {
+    const c = declared.get(key);
+    if (!c || c.kind !== "table") continue;
+    const table = `${c.database ?? "default"}.${c.name}`;
+    const time = c.columns.find((col) => !col.nullable && TIME_TYPE.test(col.type) && (!col.defaultKind || col.defaultKind === "DEFAULT"));
+    const dualWrite: RebuildOpSuggestion["dualWrite"] = time ? { mode: "materialized-view", cutoverColumn: time.name } : { mode: "app" };
+    const name = migrationOpName("rebuild", table);
+    const dw = dualWrite.mode === "app" ? `{ mode: "app" }` : `{ mode: "materialized-view", cutoverColumn: ${JSON.stringify(dualWrite.cutoverColumn)} }`;
+    out.push({
+      table,
+      name,
+      env,
+      dualWrite,
+      declaration: `export const { op } = ClickHouseRebuildOp({ name: ${JSON.stringify(name)}, env: ${JSON.stringify(env)}, table: ${JSON.stringify(table)}, dualWrite: ${dw} });`,
+    });
+  }
+  return out;
+}
+
+/** The suggestions as text, for the report. */
+export function renderRebuildOps(ops: readonly RebuildOpSuggestion[]): string[] {
+  return renderMigrationOps(ops, { what: "the rebuild migration Op", exportName: "ClickHouseRebuildOp", importPath: "@intentius/chant-lexicon-sql/clickhouse" });
+}

package/src/clickhouse/plan/report.ts

@@ -0,0 +1,19 @@
+/** A schema diff as text, for a terminal or a pull request (the shared core's report, with ClickHouse's refusal). */
+
+import { renderChangeSet } from "../../core/classifier";
+import { CHANGE_CLASSES, CLASSIFIER_RULES } from "./rules";
+import type { SchemaDiff } from "./diff";
+import { renderRebuildOps } from "./rebuild-handoff";
+
+export function renderDiff(diff: SchemaDiff, opts: { title?: string } = {}): string {
+  const trailer =
+    diff.rebuilds.length > 0
+      ? [
+          "",
+          `Refused: ${diff.rebuilds.length} change(s) need a rebuild, which ClickHouse cannot make to the existing table. ` +
+            "A rebuild runs as its own migration (create the new table, backfill, verify, swap), not in place.",
+          ...renderRebuildOps(diff.rebuildOps ?? []),
+        ]
+      : [];
+  return renderChangeSet(diff, { ...(opts.title ? { title: opts.title } : {}), rules: CLASSIFIER_RULES, classes: CHANGE_CLASSES, trailer });
+}