@intentius/chant-lexicon-sql 0.112.1 → 0.113.0

package/src/migration-statements.test.ts

@@ -0,0 +1,265 @@
+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 { diffStatements, renderStatements, type SchemaStatements, type StatementStep } from "./migration-statements";
+import { diffStatements as fromRoot } from "./index";
+import { clickhouseApply } from "./op/activities/clickhouse-apply";
+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";
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+const dirs: string[] = [];
+const servers: WritableServer[] = [];
+afterAll(async () => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  for (const s of servers) await s.close();
+});
+
+const build = (dialect: string, objects: Obj[], extra: Record<string, unknown> = {}) => ({
+  dialect,
+  ...extra,
+  applyOrder: objects.map((o) => o.export),
+  objects: objects.map((o) => ({ dependsOn: [], ...o })),
+});
+
+function buildFile(doc: object): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-statements-"));
+  dirs.push(dir);
+  const path = join(dir, "schema.json");
+  writeFileSync(path, JSON.stringify(doc));
+  return path;
+}
+
+const MARKER = { stack: "shop", env: "prod" };
+const config = { ownership: { stack: "shop", env: "prod" } };
+const sqlOf = (doc: SchemaStatements) => doc.steps.filter((s): s is StatementStep => s.kind === "statement").map((s) => s.sql);
+
+// ── ClickHouse ─────────────────────────────────────────────────────────
+
+const DB: Obj = { export: "analytics", type: "ClickHouse::Database", ddl: "CREATE DATABASE analytics ENGINE = Atomic" };
+const EVENTS: Obj = {
+  export: "events",
+  type: "ClickHouse::Table",
+  dependsOn: ["analytics"],
+  ddl: "CREATE TABLE analytics.events (ts DateTime, user_id UInt64, kind String) ENGINE = MergeTree ORDER BY (ts, user_id) COMMENT 'Raw events'",
+};
+const EVENTS_V2: Obj = {
+  ...EVENTS,
+  ddl: "CREATE TABLE analytics.events (ts DateTime, user_id UInt64, region String DEFAULT 'eu', kind LowCardinality(String)) ENGINE = MergeTree ORDER BY (ts, user_id) COMMENT 'Raw events'",
+};
+const SESSIONS: Obj = { export: "sessions", type: "ClickHouse::Table", dependsOn: ["analytics"], ddl: "CREATE TABLE analytics.sessions (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY id" };
+const SESSIONS_RESORTED: Obj = { ...SESSIONS, ddl: "CREATE TABLE analytics.sessions (id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY (ts, id)" };
+const OLD: Obj = { export: "old", type: "ClickHouse::Table", dependsOn: ["analytics"], ddl: "CREATE TABLE analytics.old (a UInt8) ENGINE = MergeTree ORDER BY a" };
+const BY_KIND: Obj = { export: "byKind", type: "ClickHouse::View", dependsOn: ["events"], ddl: "CREATE VIEW analytics.by_kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind" };
+
+const CH_BEFORE = build("clickhouse", [DB, EVENTS, SESSIONS, OLD]);
+const CH_AFTER = build("clickhouse", [DB, EVENTS_V2, SESSIONS_RESORTED, BY_KIND]);
+
+describe("ClickHouse", () => {
+  const doc = diffStatements(CH_BEFORE, CH_AFTER, { marker: MARKER });
+
+  test("the statements are ordered, each with its change's rule and class", () => {
+    expect(doc.dialect).toBe("clickhouse");
+    expect(doc.steps.map((s) => [s.kind, s.object, s.kind === "statement" ? s.rule : s.kind === "op" ? s.op : "", s.kind === "statement" ? s.class : ""])).toEqual([
+      ["statement", "events", "SQLCH201", "metadata"],
+      ["statement", "events", "SQLCH210", "rewrite"],
+      ["op", "sessions", "ClickHouseRebuildOp", ""],
+      ["statement", "byKind", "SQLCH200", "create"],
+      ["statement", "old", "SQLCH250", "drop"],
+    ]);
+    expect(sqlOf(doc)).toEqual([
+      "ALTER TABLE `analytics`.`events` ADD COLUMN region String DEFAULT 'eu' AFTER `user_id`",
+      "ALTER TABLE `analytics`.`events` MODIFY COLUMN `kind` LowCardinality(String)",
+      "CREATE VIEW analytics.by_kind 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` SYNC",
+    ]);
+    const rewrite = doc.steps[1] as StatementStep;
+    expect(rewrite.waitsForMutation).toBe(true);
+    expect((doc.steps[4] as StatementStep).destructive).toBe(true);
+  });
+
+  test("a rebuild is a step naming ClickHouseRebuildOp, never DDL", () => {
+    const op = doc.steps.find((s) => s.kind === "op");
+    expect(op).toMatchObject({
+      kind: "op",
+      object: "sessions",
+      type: "ClickHouse::Table",
+      name: "analytics.sessions",
+      op: "ClickHouseRebuildOp",
+      importPath: "@intentius/chant-lexicon-sql/clickhouse",
+      options: { name: "rebuild-analytics-sessions", env: "<env>", table: "analytics.sessions", dualWrite: { mode: "materialized-view", cutoverColumn: "ts" } },
+      changes: [{ rule: "SQLCH220", class: "rebuild", field: "orderBy" }],
+    });
+    expect(sqlOf(doc).some((s) => s.includes("sessions"))).toBe(false);
+    expect(doc.refused).toBe(true);
+  });
+
+  test("a view's rebuild has no Op: it is a manual step", () => {
+    const mv = { export: "mv", type: "ClickHouse::MaterializedView", ddl: "CREATE MATERIALIZED VIEW analytics.mv ENGINE = MergeTree ORDER BY kind AS SELECT kind FROM analytics.events" };
+    const d = diffStatements(build("clickhouse", [DB, EVENTS, mv]), build("clickhouse", [DB, EVENTS, { ...mv, ddl: mv.ddl.replace("ORDER BY kind", "ORDER BY tuple()") }]));
+    expect(d.steps).toEqual([expect.objectContaining({ kind: "manual", object: "mv", changes: [expect.objectContaining({ rule: "SQLCH243", class: "rebuild" })] })]);
+    expect((d.steps[0] as { detail: string }).detail).toMatch(/drop and create this object instead/);
+  });
+
+  test("two identical builds take no steps", () => {
+    expect(diffStatements(CH_BEFORE, CH_BEFORE)).toEqual({ dialect: "clickhouse", defaultDatabase: "default", steps: [], refused: false, hints: [] });
+  });
+
+  test("the applier sends the same statements for the same change", async () => {
+    const s = await writableClickHouse();
+    servers.push(s);
+    const deps = { config, env: { CLICKHOUSE_URL: s.url }, log: () => undefined };
+    await clickhouseApply({ buildPath: buildFile(CH_BEFORE), environment: "test" }, undefined, deps);
+    s.writes.length = 0;
+    const outcome = await clickhouseApply({ buildPath: buildFile(CH_AFTER), environment: "test", prune: true }, undefined, deps);
+    expect(s.writes).toEqual(sqlOf(doc));
+    // The refused rebuild is the same refusal, word for word.
+    const refused = outcome.notAttempted.find((n) => n.name === "analytics.sessions");
+    expect(refused?.detail).toBe((doc.steps.find((x) => x.kind === "op") as { detail: string }).detail);
+  });
+});
+
+// ── Postgres ───────────────────────────────────────────────────────────
+
+const APP: Obj = { export: "app", type: "Postgres::Schema", ddl: "CREATE SCHEMA app" };
+const USERS: Obj = {
+  export: "users",
+  type: "Postgres::Table",
+  dependsOn: ["app"],
+  ddl: "CREATE TABLE app.users (\n  id bigint PRIMARY KEY,\n  email text NOT NULL,\n  nick text\n);\nCOMMENT ON TABLE app.users IS 'Accounts'",
+};
+const USERS_V2: Obj = { ...USERS, ddl: USERS.ddl.replace("nick text", "nick text,\n  name text NOT NULL DEFAULT 'none'") };
+const EMAIL_IDX: Obj = { export: "usersEmail", type: "Postgres::Index", dependsOn: ["users"], ddl: "CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email)" };
+const ORDERS: Obj = { export: "orders", type: "Postgres::Table", dependsOn: ["app"], ddl: "CREATE TABLE app.orders (\n  id bigint,\n  ref text\n)" };
+const ORDERS_RENAMED: Obj = { ...ORDERS, ddl: "CREATE TABLE app.orders (\n  id bigint,\n  reference text -- previously: ref\n)" };
+const EMAILS: Obj = { export: "emails", type: "Postgres::View", dependsOn: ["users"], ddl: "CREATE VIEW app.emails AS SELECT email FROM app.users" };
+
+const PG_BEFORE = build("postgres", [APP, USERS, ORDERS, EMAILS], { postgresMajor: 18 });
+const PG_AFTER = build("postgres", [APP, USERS_V2, EMAIL_IDX, ORDERS_RENAMED], { postgresMajor: 18 });
+
+describe("Postgres", () => {
+  const doc = diffStatements(PG_BEFORE, PG_AFTER, { marker: MARKER, env: "prod" });
+
+  test("the statements are ordered, each with its change's rule and class and whether it may run in a transaction", () => {
+    expect(doc).toMatchObject({ dialect: "postgres", defaultSchema: "public", major: 18 });
+    expect(doc.steps.filter((s): s is StatementStep => s.kind === "statement").map((s) => [s.object, s.sql, s.rule, s.class, s.transactional])).toEqual([
+      ["users", "ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL", "SQLPG201", "metadata", true],
+      ["usersEmail", "CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email)", "SQLPG240", "concurrently", false],
+      ["usersEmail", "COMMENT ON INDEX app.users_email_idx IS '[chant managed-by=chant stack=shop env=prod]'", "SQLPG240", "concurrently", true],
+      ["emails", "DROP VIEW app.emails", "SQLPG270", "drop", true],
+    ]);
+  });
+
+  test("a column rename is a step naming PostgresMigrationOp, never DDL", () => {
+    const op = doc.steps.find((s) => s.kind === "op");
+    expect(op).toMatchObject({
+      kind: "op",
+      object: "orders",
+      type: "Postgres::Table",
+      name: "app.orders",
+      op: "PostgresMigrationOp",
+      importPath: "@intentius/chant-lexicon-sql/postgres",
+      options: { name: "migrate-app-orders-reference", env: "prod", table: "app.orders", column: "reference" },
+      changes: [{ rule: "SQLPG205", class: "expand", field: "columns.reference", before: "ref", after: "reference" }],
+    });
+    expect((op as { declaration: string }).declaration).toContain('PostgresMigrationOp({ name: "migrate-app-orders-reference", env: "prod", table: "app.orders", column: "reference" })');
+    expect(sqlOf(doc).some((s) => s.includes("orders"))).toBe(false);
+  });
+
+  test("a type change across kinds is a PostgresMigrationOp step too", () => {
+    const typed = { ...ORDERS, ddl: "CREATE TABLE app.orders (\n  id text,\n  ref text\n)" };
+    const d = diffStatements(build("postgres", [APP, ORDERS]), build("postgres", [APP, typed]));
+    expect(d.steps).toEqual([expect.objectContaining({ kind: "op", op: "PostgresMigrationOp", options: expect.objectContaining({ column: "id" }), changes: [expect.objectContaining({ rule: "SQLPG208" })] })]);
+  });
+
+  test("an expand-and-contract change no Op makes is a manual step", () => {
+    const partitioned = { ...ORDERS, ddl: "CREATE TABLE app.orders (\n  id bigint NOT NULL\n)" };
+    const d = diffStatements(build("postgres", [APP, { ...ORDERS, ddl: "CREATE TABLE app.orders (\n  ref text\n)" }]), build("postgres", [APP, { ...partitioned, ddl: "CREATE TABLE app.orders (\n  ref text,\n  id bigint NOT NULL\n)" }]));
+    expect(d.steps).toEqual([expect.objectContaining({ kind: "manual", object: "orders", changes: [expect.objectContaining({ rule: "SQLPG203", class: "expand" })] })]);
+    expect(d.refused).toBe(true);
+  });
+
+  test("the applier sends the same statements for the same change", async () => {
+    const s = writablePostgres();
+    const deps = {
+      config,
+      env: { POSTGRES_URL: "postgres://fake:5432/shop" },
+      log: () => undefined,
+      connect: async () => s.client,
+      readLive: () => s.readLive(),
+      serverNormalize: async (_client: unknown, o: unknown) => o,
+    };
+    await postgresApply({ buildPath: buildFile(PG_BEFORE), environment: "test" }, undefined, deps as never);
+    const outcome = await postgresApply({ buildPath: buildFile(PG_AFTER), environment: "test", prune: true }, undefined, deps as never);
+    const offline = doc.steps.filter((x): x is StatementStep => x.kind === "statement");
+    expect(outcome.statements.map((r) => [r.sql, r.class])).toEqual(offline.map((x) => [x.sql, x.class]));
+    // What may not run in a transaction block ran outside one. (A prune's DROP may, and the applier runs each alone.)
+    expect(outcome.statements.filter((r, i) => !offline[i]!.transactional).map((r) => r.transaction)).toEqual([undefined]);
+    expect(outcome.statements.filter((r, i) => offline[i]!.transactional && offline[i]!.class !== "drop").every((r) => r.transaction !== undefined)).toBe(true);
+    const refused = outcome.notAttempted.find((n) => n.name === "app.orders");
+    expect(refused?.detail).toBe((doc.steps.find((x) => x.kind === "op") as { detail: string }).detail);
+  });
+});
+
+describe("the document", () => {
+  test("is plain JSON: it reads back as written", () => {
+    for (const doc of [diffStatements(CH_BEFORE, CH_AFTER), diffStatements(PG_BEFORE, PG_AFTER)]) {
+      expect(JSON.parse(JSON.stringify(doc))).toEqual(doc);
+      expect(JSON.stringify(doc)).not.toContain("undefined");
+    }
+  });
+
+  test("takes build outputs as JSON text or parsed, and is exported from the package root", () => {
+    expect(fromRoot(JSON.stringify(CH_BEFORE), JSON.stringify(CH_AFTER))).toEqual(diffStatements(CH_BEFORE, CH_AFTER));
+  });
+
+  test("takes the sql output of a multi-lexicon build", () => {
+    expect(diffStatements({ sql: PG_BEFORE }, { sql: PG_AFTER })).toEqual(diffStatements(PG_BEFORE, PG_AFTER));
+  });
+
+  test("refuses builds of two dialects", () => {
+    expect(() => diffStatements(CH_BEFORE, PG_AFTER)).toThrow(/different dialects/);
+  });
+
+  test("renders as a migration file's SQL, each statement after its rule and class, an Op as a comment", () => {
+    const sql = renderStatements(diffStatements(PG_BEFORE, PG_AFTER, { env: "prod" }));
+    expect(sql).toContain("-- usersEmail (app.users_email_idx): SQLPG240 concurrently, outside a transaction\nCREATE INDEX CONCURRENTLY users_email_idx ON app.users (email);");
+    expect(sql).toContain("-- orders (app.orders): SQLPG205 made by PostgresMigrationOp, not a statement:");
+    expect(sql).not.toMatch(/^ALTER TABLE app\.orders/m);
+  });
+});
+
+describe("chant sql diff --statements", () => {
+  const capture = async (args: string[]) => {
+    const lines: string[] = [];
+    const log = vi.spyOn(console, "log").mockImplementation((l: unknown) => void lines.push(String(l)));
+    try {
+      return { code: await runDiff({ verb: "diff", rawArgs: args }), out: lines.join("\n") };
+    } finally {
+      log.mockRestore();
+    }
+  };
+
+  test("--json prints the document diffStatements returns, and exits 2 for a step that is an Op", async () => {
+    const r = await capture([buildFile(CH_BEFORE), buildFile(CH_AFTER), "--statements", "--json"]);
+    expect(r.code).toBe(2);
+    expect(JSON.parse(r.out)).toEqual(diffStatements(CH_BEFORE, CH_AFTER));
+  });
+
+  test("without --json prints the SQL, and exits 0 when every step is a statement", async () => {
+    const after = build("postgres", [APP, USERS_V2, ORDERS, EMAILS], { postgresMajor: 18 });
+    const r = await capture([buildFile(PG_BEFORE), buildFile(after), "--statements"]);
+    expect(r.code).toBe(0);
+    expect(r.out).toBe(renderStatements(diffStatements(PG_BEFORE, after)));
+    expect(r.out).toContain("ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL;");
+  });
+});

package/src/migration-statements.ts

@@ -0,0 +1,252 @@
+/**
+ * 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 { 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;
+  /** 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 before = clickhouseDeclared(beforeJson, defaultDatabase);
+  const after = clickhouseDeclared(afterJson, defaultDatabase);
+  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,
+    ...(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, 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
+"
+`;