@intentius/chant-lexicon-sql 0.124.45 → 0.124.48

package/src/postgres/apply/statements.ts

@@ -108,10 +108,12 @@ export const pgQualified = (schema: string | undefined, name: string): string =>
 export const objectIdent = (o: { kind: CanonicalKind; schema?: string; name: string; signature?: string }): string =>
   o.kind === "cast"
     ? o.name
-    : o.kind === "schema" || o.kind === "extension" || o.kind === "role" || o.kind === "eventTrigger"
+    : o.kind === "schema" || o.kind === "extension" || o.kind === "role" || o.kind === "eventTrigger" || o.kind === "foreignDataWrapper" || o.kind === "foreignServer" || o.kind === "publication"
     ? quoteIdent(o.name)
     : o.kind === "trigger" || o.kind === "policy"
       ? `${quoteIdent(o.name)}${o.signature ?? ""}`
+      : o.kind === "operator"
+        ? `${o.schema ? `${quoteIdent(o.schema)}.` : ""}${o.name}${o.signature ?? ""}`
       : `${pgQualified(o.schema, o.name)}${o.signature ?? ""}`;
 
 /** The words a statement names the object's kind with. */
@@ -133,6 +135,11 @@ export const KIND_WORDS: Readonly<Record<CanonicalKind, string>> = {
   collation: "COLLATION",
   cast: "CAST",
   eventTrigger: "EVENT TRIGGER",
+  operator: "OPERATOR",
+  statistics: "STATISTICS",
+  foreignDataWrapper: "FOREIGN DATA WRAPPER",
+  foreignServer: "SERVER",
+  publication: "PUBLICATION",
   trigger: "TRIGGER",
   policy: "POLICY",
   role: "ROLE",
@@ -569,6 +576,62 @@ export function setNotNullSteps(table: string, column: string, live?: Pick<PgDif
   return steps;
 }
 
+/** An `OPTIONS (...)` clause that takes the options `have` to `want`: ADD, SET and DROP per option; empty when they agree. */
+function optionsClause(want: unknown, have: unknown): string {
+  const w = (want ?? {}) as Record<string, string>;
+  const h = (have ?? {}) as Record<string, string>;
+  const parts = [
+    ...Object.keys(w).filter((k) => !(k in h)).map((k) => `ADD ${quoteIdent(k)} ${pgString(w[k]!)}`),
+    ...Object.keys(w).filter((k) => k in h && h[k] !== w[k]).map((k) => `SET ${quoteIdent(k)} ${pgString(w[k]!)}`),
+    ...Object.keys(h).filter((k) => !(k in w)).map((k) => `DROP ${quoteIdent(k)}`),
+  ];
+  return parts.length > 0 ? `OPTIONS (${parts.join(", ")})` : "";
+}
+
+/** A publication's table as `ADD TABLE` writes it: its name, column list and row filter. */
+const publicationTable = (t: { table: string; columns?: string[]; where?: string }): string =>
+  `${t.table}${t.columns && t.columns.length > 0 ? ` (${t.columns.map(quoteIdent).join(", ")})` : ""}${t.where ? ` WHERE (${t.where})` : ""}`;
+
+/**
+ * The ALTER statements that take a foreign data wrapper, a foreign server or
+ * a publication to the declaration, in place (SQLPG303): one ALTER for a
+ * wrapper or server; for a publication one SET (...) for its options, and a
+ * DROP and ADD per table or schema that changed.
+ */
+function alteredSteps(d: PgDiffObject, live: PgDiffObject, target: string): PgStep[] {
+  const out: string[] = [];
+  const f = d.fields;
+  const l = live.fields;
+  if (d.kind === "foreignDataWrapper") {
+    const clauses = [
+      !same(f.handler, l.handler) ? (f.handler ? `HANDLER ${String(f.handler)}` : "NO HANDLER") : "",
+      !same(f.validator, l.validator) ? (f.validator ? `VALIDATOR ${String(f.validator)}` : "NO VALIDATOR") : "",
+      optionsClause(f.options, l.options),
+    ].filter(Boolean);
+    if (clauses.length > 0) out.push(`ALTER FOREIGN DATA WRAPPER ${target} ${clauses.join(" ")}`);
+  } else if (d.kind === "foreignServer") {
+    const clauses = [!same(f.version, l.version) ? `VERSION ${f.version === undefined ? "NULL" : pgString(String(f.version))}` : "", optionsClause(f.options, l.options)].filter(Boolean);
+    if (clauses.length > 0) out.push(`ALTER SERVER ${target} ${clauses.join(" ")}`);
+  } else if (d.kind === "publication") {
+    const sets: string[] = [];
+    if (!same(f.publish, l.publish)) sets.push(`publish = ${pgString(((f.publish as string[] | undefined) ?? ["insert", "update", "delete", "truncate"]).join(", "))}`);
+    if (!same(f.viaRoot, l.viaRoot)) sets.push(`publish_via_partition_root = ${f.viaRoot === true}`);
+    if (!same(f.generatedColumns, l.generatedColumns)) sets.push(`publish_generated_columns = ${String(f.generatedColumns ?? "none")}`);
+    if (sets.length > 0) out.push(`ALTER PUBLICATION ${target} SET (${sets.join(", ")})`);
+    type Member = { table: string; columns?: string[]; where?: string };
+    const want = (f.tables as Member[] | undefined) ?? [];
+    const have = (l.tables as Member[] | undefined) ?? [];
+    const kept = (m: Member) => want.some((w) => w.table === m.table && same(w, m));
+    for (const m of have) if (!kept(m)) out.push(`ALTER PUBLICATION ${target} DROP TABLE ${m.table}`);
+    for (const m of want) if (!have.some((h) => h.table === m.table && same(h, m))) out.push(`ALTER PUBLICATION ${target} ADD TABLE ${publicationTable(m)}`);
+    const wantSchemas = (f.schemas as string[] | undefined) ?? [];
+    const haveSchemas = (l.schemas as string[] | undefined) ?? [];
+    for (const s of haveSchemas) if (!wantSchemas.includes(s)) out.push(`ALTER PUBLICATION ${target} DROP TABLES IN SCHEMA ${s}`);
+    for (const s of wantSchemas) if (!haveSchemas.includes(s)) out.push(`ALTER PUBLICATION ${target} ADD TABLES IN SCHEMA ${s}`);
+  }
+  return out.map((sql) => step(sql, "metadata", "SQLPG303"));
+}
+
 /**
  * The statements for an object that exists on the server, change by change.
  * `live` is the server's definition, matched to the declaration (a renamed
@@ -704,6 +767,9 @@ export function alterSteps(
       case "SQLPG229":
         steps.push(step(`ALTER INDEX ${objectIdent(live)} RENAME TO ${quoteIdent(d.name)}`, c.class, c.rule));
         break;
+      case "SQLPG303":
+        if (!steps.some((s) => s.rule === "SQLPG303")) steps.push(...alteredSteps(d, live, target));
+        break;
       case "SQLPG250":
       case "SQLPG280":
       case "SQLPG302":
@@ -882,6 +948,9 @@ const DROP_ORDER: Record<CanonicalKind, number> = {
   defaultPrivileges: 0,
   policy: 0,
   trigger: 0,
+  // A publication reads tables, extended statistics are on one: both go before it.
+  publication: 0,
+  statistics: 0,
   materializedView: 1,
   view: 2,
   index: 3,
@@ -891,6 +960,10 @@ const DROP_ORDER: Record<CanonicalKind, number> = {
   eventTrigger: 5.5,
   cast: 5.5,
   aggregate: 5.5,
+  operator: 5.5,
+  // A server before its wrapper, a wrapper before the handler function it calls.
+  foreignServer: 5.5,
+  foreignDataWrapper: 5.6,
   // A routine after what calls it (a view, a trigger, a default), before the types its parameters use.
   function: 6,
   procedure: 6,

package/src/postgres/constraint-names.ts

@@ -0,0 +1,71 @@
+/**
+ * The names Postgres gives a constraint or an index that the DDL leaves
+ * unnamed, so a reader of the declarations can spell them without a server.
+ *
+ * `makeObjectName` and the `Choose*Name` functions are from the Postgres
+ * source (`src/backend/commands/indexcmds.c`, `src/backend/catalog/heap.c`,
+ * `src/backend/commands/tablecmds.c`): the table name, then the column
+ * names joined with `_`, then a label (`pkey`, `key`, `fkey`, `check`),
+ * cut to 63 bytes by shortening the longer of the first two parts one
+ * character at a time. A name already taken gets a number after the label
+ * (`orders_pkey1`).
+ *
+ * A name the author writes always wins; these are for the rest. Drizzle's
+ * own derived names (`orders_user_id_users_id_fk`) differ from them, which is
+ * why the Drizzle export names every constraint it writes.
+ */
+
+const NAMEDATALEN = 64;
+
+/** `makeObjectName(name1, name2, label)`: ASCII names only. */
+export function makeObjectName(name1: string, name2: string | undefined, label: string | undefined): string {
+  let overhead = 0;
+  let n2 = 0;
+  if (name2 !== undefined) {
+    n2 = name2.length;
+    overhead++;
+  }
+  if (label !== undefined) overhead += label.length + 1;
+  const avail = NAMEDATALEN - 1 - overhead;
+  let n1 = name1.length;
+  while (n1 + n2 > avail) {
+    if (n1 > n2) n1--;
+    else n2--;
+  }
+  let name = name1.slice(0, n1);
+  if (name2 !== undefined) name += `_${name2.slice(0, n2)}`;
+  if (label !== undefined) name += `_${label}`;
+  return name;
+}
+
+/** The first of `label`, `label1`, `label2`, ... that gives a name not in `taken`. */
+export function chooseName(name1: string, name2: string | undefined, label: string, taken: ReadonlySet<string>): string {
+  let pass = 0;
+  let candidate = makeObjectName(name1, name2, label);
+  while (taken.has(candidate)) candidate = makeObjectName(name1, name2, `${label}${++pass}`);
+  return candidate;
+}
+
+/** The column names of a key or foreign key, joined as Postgres joins them. */
+export const columnsAddition = (columns: readonly string[]): string => columns.join("_");
+
+/**
+ * The identifiers `expr` reads as column names: words outside quotes and
+ * string literals that are not followed by `(`, and are in `columns`.
+ */
+export function referencedColumns(expr: string, columns: readonly string[]): string[] {
+  const known = new Set(columns);
+  const found = new Set<string>();
+  const re = /'(?:[^']|'')*'|"((?:[^"]|"")+)"|([A-Za-z_][\w$]*)(?!\s*\()(?!\s*\.)/g;
+  for (let m = re.exec(expr); m; m = re.exec(expr)) {
+    const name = m[1] !== undefined ? m[1].replace(/""/g, '"') : m[2];
+    if (name !== undefined && known.has(m[1] !== undefined ? name : name.toLowerCase())) found.add(m[1] !== undefined ? name : name.toLowerCase());
+  }
+  return [...found];
+}
+
+/** A check constraint's default name: the column when the expression reads one, else just the table. */
+export function checkName(table: string, expr: string, columns: readonly string[], taken: ReadonlySet<string>): string {
+  const refs = referencedColumns(expr, columns);
+  return chooseName(table, refs.length === 1 ? refs[0] : undefined, "check", taken);
+}

package/src/postgres/database-kinds.test.ts

@@ -0,0 +1,384 @@
+/**
+ * Extended statistics, foreign data wrappers, foreign servers and
+ * publications (#3911): what the tags parse and refuse, how a change to each
+ * is classified and made, how the catalog reader prints each, and the round
+ * trip: declare, build, import, plan with no change.
+ */
+
+import { describe, expect, test } from "vitest";
+import { foreignDataWrapper, foreignServer, func, operator, publication, schema, SqlTemplateError, statistics, table } from "./entities";
+import { diffObject, keyedByQualifiedName, pgSchemaFromLive, type PgSchemaObject } from "./plan/schema";
+import { diffPgSchemas, matchPgObjects } from "./plan/diff";
+import { alterSteps, dropStatement } from "./apply/statements";
+import { declaredObjects } from "./apply/apply";
+import { readLiveSchema, type LivePgObject } from "./live/catalog";
+import { readDatabaseKinds, readOperators } from "./live/catalog-kinds";
+import type { PostgresClient } from "./live/client";
+import { objectsToIR, type ImportedPgObject } from "./import/ir";
+import { PostgresGenerator, postgresTemplates } from "./import/generator";
+import { canonicalPgObject } from "./plan/normalize";
+import { liveProps } from "./plan/deep";
+import { fakeClient } from "./testing/fake-client";
+import { kindRow } from "../coverage";
+
+const app = schema`CREATE SCHEMA app`;
+const props = (o: { props: unknown }) => o.props as Record<string, unknown>;
+
+describe("the tags", () => {
+  test("operator: a symbol in a schema, identified by its operand types", () => {
+    const eq = func`CREATE FUNCTION ${app}.pair_eq(a int, b int) RETURNS boolean LANGUAGE sql AS 'SELECT a = b'`;
+    const op = operator`CREATE OPERATOR ${app}.=== (FUNCTION = ${eq}, LEFTARG = int, RIGHTARG = int, COMMUTATOR = ===, NEGATOR = OPERATOR(app.!==), RESTRICT = eqsel, JOIN = eqjoinsel, HASHES); COMMENT ON OPERATOR ${app}.===(int, int) IS 'Same pair'`;
+    expect(op.entityType).toBe("Postgres::Operator");
+    expect(op.sqlName).toBe("app.===");
+    expect(op.dependsOn).toContain(eq);
+    expect(op.props).toMatchObject({ schema: "app", name: "===", leftArg: "int", rightArg: "int", comment: "Same pair" });
+    const c = canonicalPgObject(op.entityType, props(op));
+    expect(c.signature).toBe("(integer,integer)");
+    expect(c.fields.definition).toEqual({ commutator: "app.===", function: "app.pair_eq", hashes: "true", negator: "app.!==", restrict: "eqsel", join: "eqjoinsel" });
+    const prefix = operator`CREATE OPERATOR app.@@ (PROCEDURE = app.abs_of, RIGHTARG = int)`;
+    expect(canonicalPgObject(prefix.entityType, props(prefix))).toMatchObject({ name: "@@", signature: "(NONE,integer)", fields: { definition: { function: "app.abs_of" } } });
+  });
+
+  test("statistics: a table's columns and expressions, the kinds the server gathers", () => {
+    const orders = table`CREATE TABLE ${app}.orders (id int, status text, total numeric)`;
+    const s = statistics`CREATE STATISTICS ${app}.orders_stats (dependencies, ndistinct) ON status, id, (total * 2) FROM ${orders}; COMMENT ON STATISTICS ${app}.orders_stats IS 'Correlated'`;
+    expect(s.entityType).toBe("Postgres::Statistics");
+    expect(s.dependsOn).toContain(orders);
+    expect(s.props).toMatchObject({ schema: "app", name: "orders_stats", kinds: ["dependencies", "ndistinct"], tableName: "app.orders", comment: "Correlated" });
+    // Sorted, and the kinds the server builds when none are written are no list at all.
+    const c = canonicalPgObject(s.entityType, props(s));
+    expect(c.fields).toMatchObject({ table: "app.orders", kinds: ["dependencies", "ndistinct"], targets: ["id", "status", "total * 2"] });
+    const all = statistics`CREATE STATISTICS app.s ON a, b FROM app.t`;
+    const listed = statistics`CREATE STATISTICS app.s (mcv, ndistinct, dependencies) ON b, a FROM app.t`;
+    expect(canonicalPgObject(all.entityType, props(all)).fields).toEqual(canonicalPgObject(listed.entityType, props(listed)).fields);
+    const lone = statistics`CREATE STATISTICS app.e ON (lower(email)) FROM app.t`;
+    expect(canonicalPgObject(lone.entityType, props(lone)).fields.kinds).toEqual(["none"]);
+  });
+
+  test("a foreign data wrapper and a foreign server, the database's and without a schema", () => {
+    const handler = func`CREATE FUNCTION ${app}.fdw_handler() RETURNS fdw_handler LANGUAGE c AS 'x', 'y'`;
+    const fdw = foreignDataWrapper`CREATE FOREIGN DATA WRAPPER app_fdw HANDLER ${handler} NO VALIDATOR OPTIONS (debug 'true'); COMMENT ON FOREIGN DATA WRAPPER app_fdw IS 'Remote'`;
+    expect(fdw.entityType).toBe("Postgres::ForeignDataWrapper");
+    expect(fdw.sqlName).toBe("app_fdw");
+    expect(fdw.dependsOn).toContain(handler);
+    expect(fdw.props).toMatchObject({ name: "app_fdw", handlerName: "app.fdw_handler", noValidator: true, options: { debug: "true" }, comment: "Remote" });
+    expect(canonicalPgObject(fdw.entityType, props(fdw))).toMatchObject({ schema: undefined, fields: { handler: "app.fdw_handler", options: { debug: "true" } } });
+    expect(canonicalPgObject(fdw.entityType, props(fdw)).fields).not.toHaveProperty("validator");
+
+    const server = foreignServer`CREATE SERVER IF NOT EXISTS app_remote TYPE 'pg' VERSION '16' FOREIGN DATA WRAPPER ${fdw} OPTIONS (host 'db.internal', port '5432'); COMMENT ON SERVER app_remote IS 'The replica'`;
+    expect(server.dependsOn).toContain(fdw);
+    expect(server.props).toMatchObject({ name: "app_remote", serverType: "pg", version: "16", wrapperName: "app_fdw", options: { host: "db.internal", port: "5432" }, comment: "The replica" });
+    expect(canonicalPgObject(server.entityType, props(server)).fields).toMatchObject({ serverType: "pg", version: "16", wrapper: "app_fdw", options: { host: "db.internal", port: "5432" } });
+  });
+
+  test("a publication: all tables, or tables with column lists and filters, or schemas, and its options", () => {
+    const orders = table`CREATE TABLE ${app}.orders (id int, status text)`;
+    const audit = schema`CREATE SCHEMA audit`;
+    const p = publication`CREATE PUBLICATION app_pub FOR TABLE ONLY ${orders} (status, id) WHERE (id > 0), app.users, TABLES IN SCHEMA ${audit} WITH (publish = 'update, insert', publish_via_partition_root = on)`;
+    expect(p.entityType).toBe("Postgres::Publication");
+    expect(p.dependsOn).toEqual(expect.arrayContaining([orders, audit]));
+    expect(canonicalPgObject(p.entityType, props(p)).fields).toMatchObject({
+      tables: [{ table: "app.orders", columns: ["id", "status"], where: "id > 0" }, { table: "app.users" }],
+      schemas: ["audit"],
+      publish: ["insert", "update"],
+      viaRoot: true,
+    });
+    const all = publication`CREATE PUBLICATION everything FOR ALL TABLES WITH (publish = 'insert, update, delete, truncate')`;
+    expect(canonicalPgObject(all.entityType, props(all)).fields).toEqual({ allTables: true });
+    expect(canonicalPgObject(all.entityType, props(all)).fields.publish).toBeUndefined();
+    const empty = publication`CREATE PUBLICATION nothing`;
+    expect(canonicalPgObject(empty.entityType, props(empty)).fields).not.toHaveProperty("tables");
+  });
+
+  test("what is refused", () => {
+    expect(() => operator`CREATE OPERATOR app.=== (LEFTARG = int, RIGHTARG = int)`).toThrow(/FUNCTION/);
+    expect(() => operator`CREATE OPERATOR app.=== (FUNCTION = f, LEFTARG = int, MERGE = true)`).toThrow(/an option of an operator/);
+    expect(() => operator`CREATE OPERATOR CLASS c FOR TYPE int USING btree AS OPERATOR 1 <`).toThrow(/CREATE OPERATOR CLASS and CREATE OPERATOR FAMILY/);
+    expect(() => operator`CREATE OPERATOR app.eq (FUNCTION = f)`).toThrow(/operator's symbol/);
+    expect(() => foreignServer`CREATE SERVER s FOREIGN DATA WRAPPER w OPTIONS (host 'x', password 'hunter2')`).toThrow(/holds a credential/);
+    expect(() => foreignDataWrapper`CREATE FOREIGN DATA WRAPPER w OPTIONS (api_key 'x')`).toThrow(SqlTemplateError);
+    expect(() => foreignServer`CREATE SERVER s OPTIONS (host 'x')`).toThrow(/FOREIGN DATA WRAPPER/);
+    expect(() => foreignServer`CREATE SERVER app.s FOREIGN DATA WRAPPER w`).toThrow(/without a schema/);
+    expect(() => foreignServer`CREATE SERVER s FOREIGN DATA WRAPPER w OPTIONS (host 'a', host 'b')`).toThrow(/given twice/);
+    expect(() => publication`CREATE PUBLICATION p WITH (publich = 'insert')`).toThrow(/an option of a publication/);
+    expect(() => publication`CREATE PUBLICATION p FOR`).toThrow();
+    expect(() => statistics`CREATE STATISTICS app.s (histogram) ON a, b FROM app.t`).toThrow(/statistics kind/);
+    expect(() => statistics`CREATE STATISTICS app.s ON a, b`).toThrow(/FROM/);
+    expect(() => statistics`CREATE USER MAPPING FOR u SERVER s`).toThrow(SqlTemplateError);
+    expect(() => publication`CREATE STATISTICS app.s ON a, b FROM app.t`).toThrow(/use the statistics tag/);
+  });
+});
+
+// ── Classifying and making changes ─────────────────────────────────────
+
+const live = (type: string, statement: string, extra: Partial<LivePgObject> = {}) => pgSchemaFromLive([{ type, statement, name: "", oid: "1", ...extra } as LivePgObject], "public");
+const declared = (type: string, ddl: string): PgSchemaObject[] => keyedByQualifiedName([{ key: "x", canonical: { ...diffObject(type, ddl, "public"), exportName: "x" } }]);
+const rules = (type: string, before: string, after: string, extra: Partial<LivePgObject> = {}) =>
+  diffPgSchemas(live(type, before, extra), declared(type, after)).changes.map((c) => [c.field, c.rule]);
+
+function steps(type: string, liveDdl: string, declaredDdl: string, extra: Partial<LivePgObject> = {}): string[] {
+  const [obj] = declaredObjects(JSON.stringify({ dialect: "postgres", objects: [{ export: "x", type, ddl: declaredDdl, dependsOn: [] }] }));
+  const after = keyedByQualifiedName([{ key: "x", canonical: obj!.canonical }]);
+  const before = live(type, liveDdl, extra);
+  const m = matchPgObjects(before, after).find((x) => x.kind === "matched")!;
+  return alterSteps(obj!, m.before!.canonical, diffPgSchemas(before, after).changes, { major: 18 }).steps.map((s) => s.sql);
+}
+
+const OPR = "Postgres::Operator";
+const STAT = "Postgres::Statistics";
+const FDW = "Postgres::ForeignDataWrapper";
+const SRV = "Postgres::ForeignServer";
+const PUB = "Postgres::Publication";
+
+describe("the classifier and the statements", () => {
+  test("the server's printing is the declaration's", () => {
+    expect(rules(STAT, "CREATE STATISTICS app.s ON a, b FROM app.t", "CREATE STATISTICS app.s (ndistinct, dependencies, mcv) ON b, a FROM app.t")).toEqual([]);
+    expect(rules(STAT, "CREATE STATISTICS app.s (dependencies) ON a, (b + 1) FROM app.t", "CREATE STATISTICS app.s (dependencies) ON (b + 1), a FROM app.t")).toEqual([]);
+    expect(rules(FDW, "CREATE FOREIGN DATA WRAPPER w HANDLER app.h OPTIONS (a '1', b '2')", "CREATE FOREIGN DATA WRAPPER w HANDLER app.h NO VALIDATOR OPTIONS (b '2', a '1')")).toEqual([]);
+    expect(rules(SRV, "CREATE SERVER s TYPE 'pg' FOREIGN DATA WRAPPER w OPTIONS (host 'h')", "CREATE SERVER s TYPE 'pg' FOREIGN DATA WRAPPER w OPTIONS (host 'h')")).toEqual([]);
+    expect(
+      rules(PUB, "CREATE PUBLICATION p FOR TABLE app.a (id), app.b, TABLES IN SCHEMA s WITH (publish = 'insert, update')", "CREATE PUBLICATION p FOR TABLE app.b, app.a (id), TABLES IN SCHEMA s WITH (publish = 'update,insert')"),
+    ).toEqual([]);
+    // Options at their default are no change: the publication publishes every action, to its own tables, unless told otherwise.
+    expect(rules(PUB, "CREATE PUBLICATION p FOR ALL TABLES", "CREATE PUBLICATION p FOR ALL TABLES WITH (publish = 'insert, update, delete, truncate', publish_via_partition_root = false)")).toEqual([]);
+  });
+
+  test("an operator is dropped and created: it has no ALTER for its function or operands", () => {
+    const O1 = "CREATE OPERATOR app.=== (FUNCTION = app.pair_eq, LEFTARG = integer, RIGHTARG = integer, COMMUTATOR = OPERATOR(app.===), RESTRICT = eqsel)";
+    expect(rules(OPR, O1, "CREATE OPERATOR app.=== (LEFTARG = int, RIGHTARG = int, RESTRICT = eqsel, COMMUTATOR = ===, FUNCTION = app.pair_eq)")).toEqual([]);
+    expect(rules(OPR, O1, O1.replace("eqsel", "scalarltsel"))).toEqual([["definition", "SQLPG300"]]);
+    expect(rules(OPR, O1, O1.replace("eqsel", "scalarltsel"), { dependents: ["operator class app.c for access method btree"] })).toEqual([["definition", "SQLPG301"]]);
+    const recreate = steps(OPR, O1, O1.replace("eqsel", "scalarltsel"));
+    expect(recreate[0]).toBe("DROP OPERATOR app.===(integer,integer)");
+    expect(recreate[1]).toContain("scalarltsel");
+    expect(recreate[2]).toMatch(/^COMMENT ON OPERATOR app\.===\(integer,integer\) IS /);
+    // Another operand type is another operator, not a change.
+    expect(dropStatement("operator", "app", "===", "(NONE,integer)").sql).toBe("DROP OPERATOR app.===(NONE,integer)");
+  });
+
+  test("statistics are dropped and created: they have no ALTER for their definition", () => {
+    const S1 = "CREATE STATISTICS app.s ON a, b FROM app.t";
+    const S2 = "CREATE STATISTICS app.s (dependencies) ON a, b FROM app.t";
+    expect(rules(STAT, S1, S2)).toEqual([["kinds", "SQLPG300"]]);
+    expect(rules(STAT, S1, "CREATE STATISTICS app.s ON a, c FROM app.t")).toEqual([["targets", "SQLPG300"]]);
+    expect(rules(STAT, S1, "CREATE STATISTICS app.s ON a, b FROM app.u")).toEqual([["table", "SQLPG300"]]);
+    const recreate = steps(STAT, S1, S2);
+    expect(recreate[0]).toBe("DROP STATISTICS app.s");
+    expect(recreate[1]).toBe(S2);
+    expect(recreate[2]).toMatch(/^COMMENT ON STATISTICS app\.s IS /);
+    expect(dropStatement("statistics", "app", "s").sql).toBe("DROP STATISTICS app.s");
+  });
+
+  test("a wrapper is altered in place", () => {
+    const W1 = "CREATE FOREIGN DATA WRAPPER w HANDLER app.h OPTIONS (a '1', b '2')";
+    const W2 = "CREATE FOREIGN DATA WRAPPER w NO HANDLER VALIDATOR app.v OPTIONS (a '9', c '3')";
+    expect(rules(FDW, W1, W2)).toEqual([
+      ["handler", "SQLPG303"],
+      ["validator", "SQLPG303"],
+      ["options", "SQLPG303"],
+    ]);
+    expect(steps(FDW, W1, W2)).toEqual(["ALTER FOREIGN DATA WRAPPER w NO HANDLER VALIDATOR app.v OPTIONS (ADD c '3', SET a '9', DROP b)"]);
+    expect(dropStatement("foreignDataWrapper", undefined, "w").sql).toBe("DROP FOREIGN DATA WRAPPER w");
+  });
+
+  test("a server's version and options are altered in place; its type and wrapper are not", () => {
+    const V1 = "CREATE SERVER s TYPE 'pg' VERSION '15' FOREIGN DATA WRAPPER w OPTIONS (host 'a')";
+    expect(rules(SRV, V1, V1.replace("'15'", "'16'").replace("'a'", "'b'"))).toEqual([
+      ["version", "SQLPG303"],
+      ["options", "SQLPG303"],
+    ]);
+    expect(steps(SRV, V1, V1.replace("VERSION '15' ", "").replace("'a'", "'b'"))).toEqual(["ALTER SERVER s VERSION NULL OPTIONS (SET host 'b')"]);
+    expect(rules(SRV, V1, V1.replace("w OPTIONS", "w2 OPTIONS"))).toEqual([["wrapper", "SQLPG300"]]);
+    expect(rules(SRV, V1, V1.replace("w OPTIONS", "w2 OPTIONS"), { dependents: ["foreign table app.remote_orders"] })).toEqual([["wrapper", "SQLPG301"]]);
+    const recreate = steps(SRV, V1, V1.replace("'pg'", "'mysql'"));
+    expect(recreate[0]).toBe("DROP SERVER s");
+    expect(recreate[1]).toMatch(/^CREATE SERVER s TYPE 'mysql'/);
+  });
+
+  test("a publication is altered in place: options, tables and schemas", () => {
+    const P1 = "CREATE PUBLICATION p FOR TABLE app.a (id), app.b, TABLES IN SCHEMA s1";
+    const P2 = "CREATE PUBLICATION p FOR TABLE app.a (id, name) WHERE (id > 0), app.c, TABLES IN SCHEMA s2 WITH (publish = 'insert', publish_via_partition_root = true)";
+    expect(rules(PUB, P1, P2).map(([f]) => f)).toEqual(["tables", "schemas", "publish", "viaRoot"]);
+    expect(steps(PUB, P1, P2)).toEqual([
+      "ALTER PUBLICATION p SET (publish = 'insert', publish_via_partition_root = true)",
+      "ALTER PUBLICATION p DROP TABLE app.a",
+      "ALTER PUBLICATION p DROP TABLE app.b",
+      "ALTER PUBLICATION p ADD TABLE app.a (id, name) WHERE (id > 0)",
+      "ALTER PUBLICATION p ADD TABLE app.c",
+      "ALTER PUBLICATION p DROP TABLES IN SCHEMA s1",
+      "ALTER PUBLICATION p ADD TABLES IN SCHEMA s2",
+    ]);
+    // Back to the defaults is written out: the server has no RESET for a publication's options.
+    expect(steps(PUB, "CREATE PUBLICATION p WITH (publish = 'insert', publish_via_partition_root = true)", "CREATE PUBLICATION p")).toEqual([
+      "ALTER PUBLICATION p SET (publish = 'insert, update, delete, truncate', publish_via_partition_root = false)",
+    ]);
+    // FOR ALL TABLES cannot be altered into or out of.
+    expect(rules(PUB, "CREATE PUBLICATION p FOR ALL TABLES", "CREATE PUBLICATION p FOR TABLE app.a")).toEqual([["allTables", "SQLPG300"]]);
+    expect(steps(PUB, "CREATE PUBLICATION p FOR ALL TABLES", "CREATE PUBLICATION p FOR TABLE app.a")[0]).toBe("DROP PUBLICATION p");
+  });
+
+  test("a comment changes in place", () => {
+    expect(steps(SRV, "CREATE SERVER s FOREIGN DATA WRAPPER w", "CREATE SERVER s FOREIGN DATA WRAPPER w; COMMENT ON SERVER s IS 'x'")).toEqual([expect.stringMatching(/^COMMENT ON SERVER s IS 'x/)]);
+    expect(steps(PUB, "CREATE PUBLICATION p", "CREATE PUBLICATION p; COMMENT ON PUBLICATION p IS 'x'")).toEqual([expect.stringMatching(/^COMMENT ON PUBLICATION p IS 'x/)]);
+  });
+});
+
+// ── Reading the catalog ────────────────────────────────────────────────
+
+/** Answers the database-kind reader's queries from rows, by the catalog each reads. */
+function catalogClient(rows: { stats?: unknown[]; wrappers?: unknown[]; servers?: unknown[]; pubs?: unknown[]; pubTables?: unknown[]; pubSchemas?: unknown[]; version15?: boolean }): PostgresClient {
+  return {
+    async query<T>(sql: string): Promise<T[]> {
+      const r = (x: unknown[] | undefined) => (x ?? []) as T[];
+      if (sql.includes("pg_get_statisticsobjdef")) return r(rows.stats);
+      if (sql.includes("FROM pg_catalog.pg_foreign_data_wrapper w")) return r(rows.wrappers);
+      if (sql.includes("FROM pg_catalog.pg_foreign_server v")) return r(rows.servers);
+      if (sql.includes("FROM pg_catalog.pg_publication p")) return r(rows.pubs);
+      if (sql.includes("FROM pg_catalog.pg_publication_rel r")) return r(rows.pubTables);
+      if (sql.includes("FROM pg_catalog.pg_publication_namespace pn")) return r(rows.pubSchemas);
+      // The 15 features: the column list, and schema members.
+      if (sql.includes("attname = 'prattrs'") || sql.includes("to_regclass('pg_catalog.pg_publication_namespace')")) return rows.version15 ? r([{ x: 1 }]) : [];
+      return [];
+    },
+    async end() {},
+  };
+}
+
+describe("reading the catalog", () => {
+  test("each kind is assembled from its rows, a credential left out and said so", async () => {
+    const objects = await readDatabaseKinds(
+      catalogClient({
+        version15: true,
+        stats: [{ oid: "1", schema: "app", name: "s", def: "CREATE STATISTICS app.s (dependencies) ON a, b FROM app.t", comment: "Linked" }],
+        wrappers: [{ oid: "2", name: "app_fdw", handler: "app.h", validator: null, options: ["debug=true"], comment: null, dependents: ["server app_remote"] }],
+        servers: [{ oid: "3", name: "app_remote", type: "pg", version: null, wrapper: "app_fdw", options: ["host=db", "sslpassword=x", "password=y"], comment: "It's remote", dependents: [] }],
+        pubs: [{ oid: "4", name: "app_pub", alltables: false, pubinsert: true, pubupdate: true, pubdelete: false, pubtruncate: false, def: { pubviaroot: true, pubgencols: "n" }, comment: null }],
+        pubTables: [{ schema: "app", name: "t", columns: ['"a"', '"b"'], filter: "a > 0" }, { schema: "app", name: "u", columns: [], filter: null }],
+        pubSchemas: [{ name: "audit" }],
+      }),
+      {},
+    );
+    expect(objects.map((o) => [o.type, o.name])).toEqual([
+      [STAT, "s"],
+      [FDW, "app_fdw"],
+      [SRV, "app_remote"],
+      [PUB, "app_pub"],
+    ]);
+    expect(objects[0]!.statement).toBe("CREATE STATISTICS app.s (dependencies) ON a, b FROM app.t;\nCOMMENT ON STATISTICS app.s IS 'Linked'");
+    expect(objects[1]).toMatchObject({ statement: "CREATE FOREIGN DATA WRAPPER app_fdw HANDLER app.h OPTIONS (debug 'true')", dependents: ["server app_remote"] });
+    expect(objects[2]!.statement).toBe("CREATE SERVER app_remote TYPE 'pg' FOREIGN DATA WRAPPER app_fdw OPTIONS (host 'db');\nCOMMENT ON SERVER app_remote IS 'It''s remote'");
+    expect(objects[2]!.warnings).toEqual(["the options sslpassword, password hold a credential and are left out; the environment supplies it"]);
+    expect(objects[3]!.statement).toBe(
+      "CREATE PUBLICATION app_pub FOR TABLE app.t (\"a\", \"b\") WHERE (a > 0), app.u, TABLES IN SCHEMA audit WITH (publish = 'insert, update', publish_via_partition_root = true)",
+    );
+    // Each parses back with its own tag.
+    for (const o of objects) expect(() => liveProps(o)).not.toThrow();
+  });
+
+  test("an operator: its operands, its commutator and its flags, as the catalog holds them", async () => {
+    const client: PostgresClient = {
+      async query<T>(sql: string): Promise<T[]> {
+        if (!sql.includes("FROM pg_catalog.pg_operator o")) return [];
+        return [
+          { oid: "1", schema: "app", name: "===", leftarg: "integer", rightarg: "integer", func: "app.pair_eq", commutator: "OPERATOR(app.===)", negator: null, restrict: "eqsel", join_func: null, hashes: true, merges: false, comment: "Same", dependents: ["operator class app.c"] },
+          { oid: "2", schema: "app", name: "@@", leftarg: null, rightarg: "integer", func: "app.abs_of", commutator: null, negator: null, restrict: null, join_func: null, hashes: false, merges: false, comment: null, dependents: [] },
+        ] as T[];
+      },
+      async end() {},
+    };
+    const ops = await readOperators(client, {});
+    expect(ops.map((o) => [o.schema, o.name, o.signature])).toEqual([["app", "===", "(integer,integer)"], ["app", "@@", "(NONE,integer)"]]);
+    expect(ops[0]!.statement).toBe(
+      "CREATE OPERATOR app.=== (FUNCTION = app.pair_eq, LEFTARG = integer, RIGHTARG = integer, COMMUTATOR = OPERATOR(app.===), RESTRICT = eqsel, HASHES);\nCOMMENT ON OPERATOR app.===(integer,integer) IS 'Same'",
+    );
+    expect(ops[0]!.dependents).toEqual(["operator class app.c"]);
+    expect(ops[1]!.statement).toBe("CREATE OPERATOR app.@@ (FUNCTION = app.abs_of, RIGHTARG = integer)");
+    for (const o of ops) expect(() => liveProps(o)).not.toThrow();
+  });
+
+  test("a publication of every table, on a server before 15", async () => {
+    const [p] = await readDatabaseKinds(catalogClient({ pubs: [{ oid: "4", name: "all_of_it", alltables: true, pubinsert: true, pubupdate: true, pubdelete: true, pubtruncate: true, def: { pubviaroot: false }, comment: null }] }), {});
+    expect(p!.statement).toBe("CREATE PUBLICATION all_of_it FOR ALL TABLES");
+  });
+
+  test("the schema reader includes them, after the functions they call", async () => {
+    const log: string[] = [];
+    await readLiveSchema(fakeClient({}, log), { schemas: ["app"] });
+    expect(log.some((q) => q.includes("pg_get_statisticsobjdef"))).toBe(true);
+    expect(log.some((q) => q.includes("pg_foreign_server"))).toBe(true);
+    expect(log.some((q) => q.includes("FROM pg_catalog.pg_publication p"))).toBe(true);
+  });
+});
+
+// ── The round trip ─────────────────────────────────────────────────────
+
+/** What the server prints for the objects below. */
+const SERVER_PRINTS: Array<{ type: string; schema?: string; name: string; signature?: string; statement: string }> = [
+  { type: "Postgres::Schema", name: "app", statement: "CREATE SCHEMA app" },
+  { type: "Postgres::Schema", name: "audit", statement: "CREATE SCHEMA audit" },
+  { type: "Postgres::Table", schema: "app", name: "orders", statement: "CREATE TABLE app.orders (\n    id integer,\n    status text\n)" },
+  { type: "Postgres::Function", schema: "app", name: "pair_eq", signature: "(integer,integer)", statement: "CREATE FUNCTION app.pair_eq(a integer, b integer)\n RETURNS boolean\n LANGUAGE sql\nAS $function$SELECT a = b$function$" },
+  { type: OPR, schema: "app", name: "===", signature: "(integer,integer)", statement: "CREATE OPERATOR app.=== (FUNCTION = app.pair_eq, LEFTARG = integer, RIGHTARG = integer, COMMUTATOR = OPERATOR(app.===), HASHES);\nCOMMENT ON OPERATOR app.===(integer,integer) IS 'Same pair'" },
+  { type: STAT, schema: "app", name: "orders_stats", statement: "CREATE STATISTICS app.orders_stats (dependencies) ON id, status FROM app.orders;\nCOMMENT ON STATISTICS app.orders_stats IS 'Correlated'" },
+  { type: FDW, name: "app_fdw", statement: "CREATE FOREIGN DATA WRAPPER app_fdw OPTIONS (debug 'true');\nCOMMENT ON FOREIGN DATA WRAPPER app_fdw IS 'Remote'" },
+  { type: SRV, name: "app_remote", statement: "CREATE SERVER app_remote TYPE 'pg' VERSION '16' FOREIGN DATA WRAPPER app_fdw OPTIONS (host 'db.internal', port '5432')" },
+  { type: PUB, name: "app_pub", statement: "CREATE PUBLICATION app_pub FOR TABLE app.orders (id, status) WHERE (id > 0), TABLES IN SCHEMA audit WITH (publish = 'insert, update')" },
+];
+
+describe("declare, build, import, plan with no change", () => {
+  const liveObjects = (): LivePgObject[] => SERVER_PRINTS.map((o, i) => ({ oid: String(i), ...o }) as LivePgObject);
+
+  test("a declaration the server prints back plans with no change", () => {
+    const orders = table`CREATE TABLE ${app}.orders (id int, status text)`;
+    const audit = schema`CREATE SCHEMA audit`;
+    const fdw = foreignDataWrapper`CREATE FOREIGN DATA WRAPPER app_fdw OPTIONS (debug 'true'); COMMENT ON FOREIGN DATA WRAPPER app_fdw IS 'Remote'`;
+    const pairEq = func`CREATE FUNCTION ${app}.pair_eq(a integer, b integer) RETURNS boolean LANGUAGE sql AS 'SELECT a = b'`;
+    const objects = [
+      app,
+      audit,
+      orders,
+      pairEq,
+      operator`CREATE OPERATOR ${app}.=== (LEFTARG = int, RIGHTARG = int, FUNCTION = ${pairEq}, HASHES, COMMUTATOR = ===); COMMENT ON OPERATOR ${app}.===(int, int) IS 'Same pair'`,
+      statistics`CREATE STATISTICS ${app}.orders_stats (dependencies) ON status, id FROM ${orders}; COMMENT ON STATISTICS ${app}.orders_stats IS 'Correlated'`,
+      fdw,
+      foreignServer`CREATE SERVER app_remote TYPE 'pg' VERSION '16' FOREIGN DATA WRAPPER ${fdw} OPTIONS (port '5432', host 'db.internal')`,
+      publication`CREATE PUBLICATION app_pub FOR TABLE ${orders} (status, id) WHERE (id > 0), TABLES IN SCHEMA ${audit} WITH (publish = 'update, insert')`,
+    ];
+    // The build: each entity's DDL, rendered, as the build output holds it.
+    const build = JSON.stringify({ dialect: "postgres", objects: objects.map((o, i) => ({ export: `o${i}`, type: o.entityType, ddl: (o.props as { ddl: string }).ddl, dependsOn: [] })) });
+    const declaredSchema = keyedByQualifiedName(declaredObjects(build).map((d) => ({ key: d.exportName, canonical: d.canonical })));
+    expect(diffPgSchemas(pgSchemaFromLive(liveObjects(), "public"), declaredSchema).changes).toEqual([]);
+  });
+
+  test("import writes each as a declaration, which builds to the same objects", () => {
+    const ir = objectsToIR(SERVER_PRINTS.map((o) => ({ type: o.type, ...(o.schema ? { schema: o.schema } : {}), name: o.name, ddl: o.statement }) as ImportedPgObject));
+    const [file] = new PostgresGenerator().generate(ir);
+    const content = file!.content;
+    expect(content).toContain('import { foreignDataWrapper, foreignServer, func, operator, publication, schema, statistics, table } from "@intentius/chant-lexicon-sql/postgres";');
+    expect(content).toContain("export const ordersStats = statistics`");
+    expect(content).toContain("export const pairEq = func`");
+    expect(content).toContain("CREATE OPERATOR ${appSchema}.=== (FUNCTION = ${pairEq}, LEFTARG = integer");
+    expect(content).toContain("CREATE STATISTICS ${appSchema}.orders_stats (dependencies) ON id, status FROM ${orders}");
+    expect(content).toContain("export const appFdw = foreignDataWrapper`");
+    expect(content).toContain("FOREIGN DATA WRAPPER ${appFdw} OPTIONS (host 'db.internal'");
+    expect(content).toContain("export const appPub = publication`");
+    expect(content).toContain("TABLES IN SCHEMA ${auditSchema} WITH (publish = 'insert, update')");
+    expect(content).toContain("FOR TABLE ${orders} (id, status) WHERE (id > 0)");
+
+    // The imported statements, in the generator's order, as a build: no change against the objects they came from.
+    const items = ir.resources.map((r) => ({ exportName: r.logicalId, type: r.type, ...(r.properties.schema ? { schema: String(r.properties.schema) } : {}), name: String(r.properties.name), ddl: String(r.properties.ddl) }));
+    const { order } = postgresTemplates(items);
+    expect(order.map((o) => o.exportName).indexOf("appFdw")).toBeLessThan(order.map((o) => o.exportName).indexOf("appRemote"));
+    expect(order.map((o) => o.exportName).indexOf("auditSchema")).toBeLessThan(order.map((o) => o.exportName).indexOf("appPub"));
+    const build = JSON.stringify({ dialect: "postgres", objects: order.map((it) => ({ export: it.exportName, type: it.type, ddl: it.ddl, dependsOn: [] })) });
+    const declaredSchema = keyedByQualifiedName(declaredObjects(build).map((d) => ({ key: d.exportName, canonical: d.canonical })));
+    expect(diffPgSchemas(pgSchemaFromLive(liveObjects(), "public"), declaredSchema).changes).toEqual([]);
+  });
+});
+
+describe("the kinds that stay refused", () => {
+  test("a user mapping and a subscription say why: they carry credentials", () => {
+    expect(kindRow("postgres", "user mapping")).toMatchObject({ status: "refused", reason: expect.stringContaining("password") });
+    expect(kindRow("postgres", "subscription")).toMatchObject({ status: "refused", reason: expect.stringContaining("credential") });
+  });
+});