@intentius/chant-lexicon-sql 0.112.1 → 0.114.0

package/src/migration-statements.ts

@@ -0,0 +1,262 @@
+/**
+ * A schema change's statements, rendered offline (#3644): for two `chant
+ * build` outputs, the ordered statements that take the first to the second,
+ * each with its change's class and rule, for a migration file. No server is
+ * read.
+ *
+ * The statements are the applier's: each dialect's `planStatements` /
+ * `planPgStatements` (`./clickhouse/apply/statements.ts`,
+ * `./postgres/apply/statements.ts`) turns classified changes into steps, and
+ * both the applier and this renderer call it. What differs is only where the
+ * current schema comes from: here the older build, keyed by export name as
+ * `chant sql diff` keys it; in the applier the server's catalog.
+ *
+ * A change the applier refuses in place is a step naming the Op that makes
+ * it, never DDL: a ClickHouse rebuild is `ClickHouseRebuildOp`, a Postgres
+ * column rename or type change across kinds is `PostgresMigrationOp`. One no
+ * Op makes is a manual step. Column and object drops are statements, marked
+ * destructive.
+ *
+ * Where the applier asks the server something, the renderer cannot:
+ *
+ * - ClickHouse: the applier also asks the server's formatter whether a
+ *   difference the rules leave is only formatting; the offline diff is the
+ *   rules' alone, as `chant sql diff` is. Before dropping a database it
+ *   checks the database is empty.
+ * - Postgres: the applier asks the server to normalize expressions the rules
+ *   leave different, and keeps an extension's own comment (from its control
+ *   file) under the trailer when the declaration sets none.
+ * - Both: the applier restamps an object whose comment lost chant's marker;
+ *   offline, the older build's objects carry it.
+ */
+
+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";
+import { planPgStatements, type DeclaredPgObject } from "./postgres/apply/statements";
+import { diffPgSchemas, type PgChange } from "./postgres/plan/diff";
+import { pgBuildMajor } from "./postgres/plan/schema";
+import { migrationOpSuggestions, migrationTarget } from "./postgres/migrate/handoff";
+import { POSTGRES_ENTITY_TYPES } from "./postgres/entity-types";
+import { POSTGRES_LATEST_MAJOR } from "./spec/postgres-pin";
+
+export type { ManualStep, MigrationStep, OpStep, SchemaStatements, StatementChange, StatementStep, StepObject } from "./core/statements";
+export { renderStatements } from "./core/statements";
+
+export interface DiffStatementsOptions {
+  /** The ownership marker every `CREATE` and restamped comment carries, as the applier stamps it. Default: `managed-by=chant` alone. */
+  marker?: OwnershipMarker;
+  /** The environment an Op step's suggested declaration names. Default: `<env>`. */
+  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. */
+  major?: number;
+}
+
+type BuildInput = string | object;
+
+const text = (b: BuildInput): string => (typeof b === "string" ? b : JSON.stringify(b));
+
+/** The dialect a build output names, at its root or under `sql`. */
+function dialectOf(json: string): string | undefined {
+  const raw = JSON.parse(json) as { dialect?: unknown; sql?: { dialect?: unknown } };
+  const d = raw?.sql && typeof raw.sql === "object" ? raw.sql.dialect : raw?.dialect;
+  return typeof d === "string" ? d : undefined;
+}
+
+/**
+ * The statements that take the schema `before` builds to the one `after`
+ * builds. Each is a `chant build` output of the sql lexicon, as JSON text or
+ * parsed. Both must be the same dialect.
+ */
+export function diffStatements(before: BuildInput, after: BuildInput, options: DiffStatementsOptions = {}): SchemaStatements {
+  const b = text(before);
+  const a = text(after);
+  const dialect = dialectOf(a);
+  if (dialectOf(b) !== dialect) throw new Error(`diffStatements: the builds are different dialects (${dialectOf(b) ?? "none"} and ${dialect ?? "none"})`);
+  if (dialect === "postgres") return postgresStatements(b, a, options);
+  if (dialect === "clickhouse") return clickhouseStatements(b, a, options);
+  throw new Error(`diffStatements: not a sql lexicon build output (dialect ${dialect ?? "missing"})`);
+}
+
+const at = (object: string, type: string, name: string): StepObject => ({ object, type, name });
+
+// ── ClickHouse ─────────────────────────────────────────────────────────
+
+function clickhouseStatements(beforeJson: string, afterJson: string, options: DiffStatementsOptions): SchemaStatements {
+  const defaultDatabase = options.defaultDatabase ?? "default";
+  const env = options.env ?? "<env>";
+  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({
+    declared: after,
+    changes: diff.changes,
+    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]));
+  const isDestructive = (changes: readonly Change[], rule: string) => changes.some((c) => c.rule === rule && c.destructive);
+
+  const steps: MigrationStep[] = [];
+  for (const entry of plan.objects) {
+    const where = at(entry.obj.exportName, entry.obj.type, entry.obj.key);
+    if (entry.verdict === "rebuild") {
+      const [op] = rebuildOpSuggestions({ ...diff, rebuilds: entry.refused }, declaredByExport, env);
+      if (op) {
+        steps.push({
+          kind: "op",
+          ...where,
+          op: "ClickHouseRebuildOp",
+          importPath: "@intentius/chant-lexicon-sql/clickhouse",
+          options: { name: op.name, env: op.env, table: op.table, dualWrite: op.dualWrite },
+          declaration: op.declaration,
+          // The rebuild creates the new table from the declaration, so it makes every change to it.
+          changes: entry.changes.map(statementChange),
+          detail: entry.detail,
+        });
+      } else steps.push({ kind: "manual", ...where, changes: entry.refused.map(statementChange), detail: entry.detail });
+      continue;
+    }
+    if (entry.verdict === "withheld") continue; // not reached: destructive changes are planned
+    for (const s of entry.steps) {
+      steps.push({
+        kind: "statement",
+        ...where,
+        sql: s.sql,
+        rule: s.rule,
+        class: s.class,
+        transactional: false,
+        ...(s.rewrite ? { waitsForMutation: true } : {}),
+        ...(s.rule === "SQLCH202" || isDestructive(entry.changes, s.rule) ? { destructive: true } : {}),
+      });
+    }
+  }
+  const beforeByExport = new Map(before.map((o) => [o.exportName, o]));
+  for (const d of plan.drops) {
+    const o = beforeByExport.get(d.key);
+    const change = diff.changes.find((c) => c.object === d.key && c.rule === "SQLCH250");
+    steps.push({
+      kind: "statement",
+      ...at(d.key, d.type, o?.key ?? d.name),
+      sql: d.step.sql,
+      rule: d.step.rule,
+      class: d.step.class,
+      transactional: false,
+      ...(change?.destructive ? { destructive: true } : {}),
+    });
+  }
+  return { dialect: "clickhouse", defaultDatabase, topology: topologyLabel(topology), steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
+}
+
+// ── Postgres ───────────────────────────────────────────────────────────
+
+function postgresStatements(beforeJson: string, afterJson: string, options: DiffStatementsOptions): SchemaStatements {
+  const defaultSchema = options.defaultSchema ?? "public";
+  const env = options.env ?? "<env>";
+  const major = options.major ?? buildMajor(afterJson) ?? buildMajor(beforeJson) ?? POSTGRES_LATEST_MAJOR;
+  const before = postgresDeclared(beforeJson, defaultSchema);
+  const after = postgresDeclared(afterJson, defaultSchema);
+  const keyed = (objs: readonly DeclaredPgObject[]) => objs.map((o) => ({ key: o.exportName, canonical: o.canonical }));
+  const current = keyed(before);
+  const diff = diffPgSchemas(current, keyed(after), { major });
+  const plan = planPgStatements({
+    declared: after,
+    changes: diff.changes,
+    current,
+    keyOf: (o) => o.exportName,
+    major,
+    allowDestructive: true,
+    ...(options.marker ? { marker: options.marker } : {}),
+  });
+  const isDestructive = (changes: readonly PgChange[], rule: string | undefined) => changes.some((c) => c.rule === rule && c.destructive);
+
+  const steps: MigrationStep[] = [];
+  for (const entry of plan.objects) {
+    const where = at(entry.obj.exportName, entry.obj.type, entry.obj.name);
+    switch (entry.verdict) {
+      case "refused": {
+        const handled = new Set<PgChange>();
+        for (const op of migrationOpSuggestions(entry.refused, new Map([[entry.obj.exportName, entry.obj.canonical]]), env, defaultSchema)) {
+          const made = entry.refused.filter((c) => {
+            const t = migrationTarget(c, entry.obj.canonical, defaultSchema);
+            return t !== undefined && t.table === op.table && t.column === op.column;
+          });
+          for (const c of made) handled.add(c);
+          steps.push({
+            kind: "op",
+            ...where,
+            op: "PostgresMigrationOp",
+            importPath: "@intentius/chant-lexicon-sql/postgres",
+            options: { name: op.name, env: op.env, table: op.table, column: op.column },
+            declaration: op.declaration,
+            changes: made.map(statementChange),
+            detail: entry.detail,
+          });
+        }
+        const rest = entry.changes.filter((c) => !handled.has(c));
+        if (rest.length > 0) steps.push(manual(where, rest, handled.size > 0 ? `the applier sends nothing for ${entry.obj.name} while a change to it is refused; these changes are not made by the Op: ${entry.detail}` : entry.detail));
+        continue;
+      }
+      case "unsupported":
+        steps.push(manual(where, entry.changes, entry.detail));
+        continue;
+      case "foreign":
+      case "withheld":
+        continue; // not reached offline: a build declares no foreign object, and destructive changes are planned
+    }
+    for (const s of entry.steps) {
+      steps.push({
+        kind: "statement",
+        ...where,
+        sql: s.sql,
+        rule: s.rule ?? (s.class === "create" ? "SQLPG200" : (entry.changes[0]?.rule ?? "SQLPG200")),
+        class: s.class,
+        transactional: s.transactional,
+        ...(s.rule === "SQLPG204" || isDestructive(entry.changes, s.rule) ? { destructive: true } : {}),
+      });
+    }
+  }
+  const beforeByExport = new Map(before.map((o) => [o.exportName, o]));
+  for (const d of plan.drops) {
+    const o = beforeByExport.get(d.key);
+    const change = diff.changes.find((c) => c.object === d.key && (c.rule === "SQLPG270" || c.rule === "SQLPG242"));
+    steps.push({
+      kind: "statement",
+      ...at(d.key, o?.type ?? POSTGRES_ENTITY_TYPES[d.kind], o?.name ?? d.name),
+      sql: d.step.sql,
+      rule: d.step.rule ?? "SQLPG270",
+      class: d.step.class,
+      transactional: d.step.transactional,
+      ...(change?.destructive ? { destructive: true } : {}),
+    });
+  }
+  return { dialect: "postgres", defaultSchema, major, steps, refused: steps.some((s) => s.kind !== "statement"), hints: diff.hints };
+}
+
+const manual = (where: StepObject, changes: readonly PgChange[], detail: string): ManualStep => ({ kind: "manual", ...where, changes: changes.map(statementChange), detail });
+
+function buildMajor(json: string): number | undefined {
+  const raw = JSON.parse(json) as { sql?: unknown };
+  return pgBuildMajor(raw.sql && typeof raw.sql === "object" ? JSON.stringify(raw.sql) : json);
+}

package/src/op/__snapshots__/watch-pipeline.test.ts.snap

@@ -0,0 +1,93 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`generateOpsPipeline renders the sql drift watch (#3642) > Forgejo: the Op's own cron and the reader's credentials; the runner's token takes no permissions block 1`] = `
+"name: schema-watch
+
+on:
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch: {}
+
+concurrency:
+  group: schema-watch
+  cancel-in-progress: false
+
+jobs:
+  schema-watch:
+    runs-on: docker
+    container: node:22-slim
+    env:
+      CLICKHOUSE_READER_USER: chant_reader
+      CLICKHOUSE_READER_PASSWORD: '\${{ secrets.CLICKHOUSE_READER_PASSWORD }}'
+    steps:
+      - uses: https://code.forgejo.org/actions/checkout@v7
+      - run: npm ci
+      - run: echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"
+      - run: chant run schema-watch
+        env:
+          GITHUB_TOKEN: '\${{ github.token }}'
+"
+`;
+
+exports[`generateOpsPipeline renders the sql drift watch (#3642) > GitHub: the Op's own cron, a read-only token and the reader's credentials 1`] = `
+"name: schema-watch
+
+on:
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch: {}
+
+concurrency:
+  group: schema-watch
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  schema-watch:
+    runs-on: ubuntu-latest
+    container: node:22-slim
+    env:
+      CLICKHOUSE_READER_USER: chant_reader
+      CLICKHOUSE_READER_PASSWORD: '\${{ secrets.CLICKHOUSE_READER_PASSWORD }}'
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm ci
+      - run: echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"
+      - run: chant run schema-watch
+        env:
+          GITHUB_TOKEN: '\${{ github.token }}'
+"
+`;
+
+exports[`generateOpsPipeline renders the sql drift watch (#3642) > GitLab: a schedule-only job with the reader's credentials and no token of its own 1`] = `
+"# chant Ops (#927, #2084, #2293) — one job per Op under stage "ops", each
+# selected by its own rules:. A merge_request_event or push job needs no
+# setup; its rule fires on the event itself.
+#
+# GitLab has no in-file cron. Create one Pipeline Schedule per cron Op
+# below (Settings > CI/CD > Schedules): set its cron to the value noted
+# here and its CHANT_SCHEDULED_OP CI/CD variable to the Op's name, so only
+# that job runs on that schedule.
+#
+#   schema-watch: cron "17 * * * *", CHANT_SCHEDULED_OP="schema-watch", finding-mode report
+
+stages:
+  - ops
+
+schema-watch:
+  stage: ops
+  image: node:22-slim
+  resource_group: schema-watch
+  variables:
+    CLICKHOUSE_READER_USER: chant_reader
+    CLICKHOUSE_READER_PASSWORD: '$CLICKHOUSE_READER_PASSWORD'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP == "schema-watch"'
+  script:
+    - npm ci
+    - export PATH="$PWD/node_modules/.bin:$PATH"
+    - chant run schema-watch
+"
+`;

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);
+});