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

package/src/postgres/plan/commands.ts

@@ -0,0 +1,124 @@
+/**
+ * `chant sql diff` and `chant sql plan` for Postgres: the classified change
+ * between two builds, or between a build and a live server.
+ *
+ * `diff` is offline and needs no server. `plan` reads the server
+ * `sql.profiles.<env>` binds, and asks it about expressions the rules leave
+ * different (`./server-normalize.ts`). Both exit 2 when a change can only be
+ * made as expand and contract, which a plan refuses, and 0 otherwise.
+ */
+
+import { bindPostgres, loadSqlConfig, type BindOptions, type PostgresTarget } from "../live/bind";
+import type { PostgresClient } from "../live/client";
+import { markProviderOwned, readLiveSchema, type LivePgObject } from "../live/catalog";
+import { scopeFor } from "../live/describe-resources";
+import { diffPgSchemas, type PgSchemaDiff } from "./diff";
+import { renderPgDiff } from "./report";
+import { keyedByQualifiedName, pgBuildFileMajor, pgSchemaFromBuildFile, pgSchemaFromLive, type PgSchemaObject } from "./schema";
+import { serverNormalized } from "./server-normalize";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types";
+import { migrationOpSuggestions } from "../migrate/handoff";
+
+export function emitPg(diff: PgSchemaDiff, json: boolean, title: string): number {
+  console.log(json ? JSON.stringify(diff, null, 2) : renderPgDiff(diff, { title }));
+  return diff.refused.length > 0 ? 2 : 0;
+}
+
+/** The major the project declares (`sql.postgresMajor`); undefined is the newest pinned one. */
+export async function projectMajor(options: { config?: { sql?: { postgresMajor?: number } }; cwd?: string } = {}): Promise<number | undefined> {
+  const config = options.config ?? (await loadSqlConfig(options.cwd ?? process.cwd()));
+  return (config?.sql as { postgresMajor?: number } | undefined)?.postgresMajor;
+}
+
+/**
+ * Offline, the major is the one the builds recorded (`postgresMajor`): the
+ * newer build's, else the older's, so a diff between revisions does not
+ * depend on today's config. `configMajor` (`sql.postgresMajor`) answers for
+ * builds that recorded none.
+ */
+export function diffPgBuildFiles(before: string, after: string, configMajor?: number): PgSchemaDiff {
+  const major = pgBuildFileMajor(after) ?? pgBuildFileMajor(before) ?? configMajor;
+  const head = pgSchemaFromBuildFile(after);
+  return withMigrationOps(diffPgSchemas(pgSchemaFromBuildFile(before), head, { major }), head, "<env>");
+}
+
+/** The diff with the migration Op to run for each refused column rename or type change (`../migrate/handoff.ts`). */
+export function withMigrationOps(diff: PgSchemaDiff, declared: readonly PgSchemaObject[], env: string, defaultSchema = "public"): PgSchemaDiff {
+  const migrationOps = migrationOpSuggestions(diff.refused, new Map(declared.map((o) => [o.key, o.canonical])), env, defaultSchema);
+  return migrationOps.length > 0 ? { ...diff, migrationOps } : diff;
+}
+
+/** The live server's major, from `server_version_num` (`180006` is 18). */
+async function serverMajor(client: { query<T>(sql: string): Promise<T[]> }): Promise<number | undefined> {
+  const rows = await client.query<{ v: string }>("select current_setting('server_version_num') as v");
+  const n = Number(rows[0]?.v);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n / 10000) : undefined;
+}
+
+const differs = (a: PgSchemaObject, b: PgSchemaObject) =>
+  JSON.stringify([a.canonical.fields, a.canonical.columns, a.canonical.constraints]) !== JSON.stringify([b.canonical.fields, b.canonical.columns, b.canonical.constraints]);
+
+/** What {@link planAgainstClient} compares and finds: both sides keyed by qualified name, and the classified changes between them. */
+export interface PgServerPlan {
+  /** The declarations, keyed by qualified name, with what the server said about expressions the rules left different. */
+  declared: PgSchemaObject[];
+  /** What the server holds in scope, keyed by qualified name. */
+  live: PgSchemaObject[];
+  /** The same, as the catalog read returned it (comments with their trailers). */
+  liveObjects: LivePgObject[];
+  diff: PgSchemaDiff;
+  /** The major the changes were classified for: the server's, else the one asked for. */
+  major?: number;
+}
+
+/**
+ * The declared objects (a build's, keyed by export name) against what a
+ * connected server holds: read in the declarations' scope, the server asked
+ * about expressions the rules leave different, then diffed. The plan and the
+ * applier (`../apply/`) share it.
+ */
+export async function planAgainstClient(
+  client: PostgresClient,
+  target: PostgresTarget,
+  build: readonly PgSchemaObject[],
+  options: { major?: number; environment?: string; readLive?: typeof readLiveSchema; serverNormalize?: typeof serverNormalized } = {},
+): Promise<PgServerPlan> {
+  const declaredRaw = keyedByQualifiedName(build);
+  const scope = scopeFor(
+    target,
+    declaredRaw.map((o) => ({ type: POSTGRES_ENTITY_TYPES[o.canonical.kind], props: { name: o.canonical.name, ...(o.canonical.schema ? { schema: o.canonical.schema } : {}) } })),
+  );
+  const liveObjects = markProviderOwned(await (options.readLive ?? readLiveSchema)(client, { schemas: scope }), target.provider);
+  const live = pgSchemaFromLive(liveObjects, target.defaultSchema);
+  const liveByKey = new Map(live.map((o) => [o.key, o]));
+  const declared: PgSchemaObject[] = [];
+  for (const o of declaredRaw) {
+    const l = liveByKey.get(o.key);
+    if (l && differs(o, l) && (o.canonical.kind === "table" || o.canonical.kind === "view" || o.canonical.kind === "materializedView")) {
+      declared.push({ ...o, canonical: { ...o.canonical, ...(await (options.serverNormalize ?? serverNormalized)(client, o.canonical, target.defaultSchema)) } });
+    } else declared.push(o);
+  }
+  // The build's major, else the server's own when it differs, since the server is what takes the locks.
+  const running = await serverMajor(client).catch(() => undefined);
+  const major = running ?? options.major;
+  const diff = diffPgSchemas(live, declared, { major });
+  if (running !== undefined && options.major !== undefined && running !== options.major) {
+    diff.hints.push(`the build targets Postgres ${options.major} but ${options.environment ?? "the server"} runs Postgres ${running}; changes are classified for ${running}`);
+  }
+  return { declared, live, liveObjects, diff, ...(major !== undefined ? { major } : {}) };
+}
+
+/** The declared objects against the server, keys by qualified name and labels with the export name. */
+export async function planPgAgainstServer(environment: string, buildFile: string, options: Omit<BindOptions, "environment"> = {}): Promise<PgSchemaDiff> {
+  const { target, client } = await bindPostgres({ ...options, environment });
+  try {
+    const targeted = pgBuildFileMajor(buildFile) ?? (await projectMajor(options));
+    const { declared, diff } = await planAgainstClient(client, target, pgSchemaFromBuildFile(buildFile, target.defaultSchema), { ...(targeted !== undefined ? { major: targeted } : {}), environment });
+    const { migrationOps } = withMigrationOps(diff, declared, environment, target.defaultSchema);
+    const label = new Map(declared.map((o) => [o.key, `${o.canonical.exportName} (${o.key.split(" ")[1]})`]));
+    const changes = diff.changes.map((c) => ({ ...c, object: label.get(c.object) ?? c.object }));
+    return { changes, hints: diff.hints, refused: changes.filter((c) => c.class === "expand"), ...(migrationOps ? { migrationOps } : {}) };
+  } finally {
+    await client.end();
+  }
+}

package/src/postgres/plan/deep.ts

@@ -0,0 +1,177 @@
+/**
+ * `observeResourcesDeep()` for the Postgres dialect: each declared object's
+ * live definition as a property tree in the declaration's own shape, so
+ * `chant lifecycle diff --live` reports property drift with no false drift.
+ *
+ * The reader parses what the catalog prints for the object (`../live/catalog.ts`)
+ * with the same tag the declaration used, which gives the same props shape.
+ * A field whose canonical form (`./normalize.ts`) equals the declaration's is
+ * written with the declaration's own value, so `timestamptz` and
+ * `timestamp with time zone`, or a constraint the declaration left unnamed and
+ * the name Postgres gave it, do not read as drift; a field that differs keeps
+ * the server's value. `deepNormalizationHooks` prunes what is not a property
+ * of the object (the DDL text, the template source, lineage, reads).
+ */
+
+import { deepObservation, type DeepObservationResult, type DeepResourceObservation } from "@intentius/chant/deep-observation";
+import type { UnobservedEntity } from "@intentius/chant/lexicon";
+import { bindPostgres, classifyPostgresFailure, type BindOptions } from "../live/bind";
+import { liveKey, readLiveSchema, type LivePgObject } from "../live/catalog";
+import { declaredAddress, scopeFor } from "../live/describe-resources";
+import * as tags from "../entities";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types";
+import { canonicalPgObject, columnShape, sameConstraint, type CanonicalPgObject } from "./normalize";
+
+type Props = Record<string, unknown>;
+
+const TAG: Record<string, (s: TemplateStringsArray) => { props: object }> = {
+  [POSTGRES_ENTITY_TYPES.schema]: tags.schema,
+  [POSTGRES_ENTITY_TYPES.table]: tags.table,
+  [POSTGRES_ENTITY_TYPES.index]: tags.index,
+  [POSTGRES_ENTITY_TYPES.view]: tags.view,
+  [POSTGRES_ENTITY_TYPES.materializedView]: tags.view,
+  [POSTGRES_ENTITY_TYPES.sequence]: tags.sequence,
+  [POSTGRES_ENTITY_TYPES.enum]: tags.type,
+  [POSTGRES_ENTITY_TYPES.domain]: tags.domain,
+  [POSTGRES_ENTITY_TYPES.extension]: tags.extension,
+};
+
+/** The props of what the server printed, parsed with the declaration's tag. */
+export function liveProps(o: LivePgObject): Props {
+  const strings = Object.assign([o.statement], { raw: [o.statement] }) as unknown as TemplateStringsArray;
+  return { ...(TAG[o.type]!(strings).props as Props) };
+}
+
+const PROP_OF_FIELD: Record<string, string[]> = {
+  comment: ["comment"],
+  authorization: ["authorization"],
+  schema: ["schema"],
+  version: ["version"],
+  labels: ["labels"],
+  dataType: ["dataType"],
+  collate: ["collate"],
+  default: ["default"],
+  notNull: ["notNull"],
+  options: ["dataType", "increment", "minValue", "maxValue", "start", "cache", "cycle"],
+  unlogged: ["persistence"],
+  ownedBy: ["ownedBy"],
+  table: ["table", "tableName"],
+  unique: ["unique"],
+  method: ["method"],
+  elements: ["elements"],
+  include: ["include"],
+  nullsNotDistinct: ["nullsNotDistinct"],
+  with: ["with"],
+  where: ["where"],
+  tablespace: ["tablespace"],
+  query: ["query"],
+  columns: ["columns"],
+  checkOption: ["checkOption"],
+  withData: ["withData"],
+  columnComments: ["columnComments"],
+  partitionBy: ["partitionBy"],
+  partitionOf: ["partitionOf"],
+  partitionBound: ["partitionBound"],
+  inherits: ["inherits"],
+  using: ["using"],
+};
+
+/** Props keys that hold constraints, by constraint kind. */
+const CONSTRAINT_PROPS: Record<string, string> = {
+  "PRIMARY KEY": "primaryKey",
+  UNIQUE: "uniques",
+  CHECK: "checks",
+  "FOREIGN KEY": "foreignKeys",
+  EXCLUDE: "exclusions",
+};
+
+/** The live props, with each field the declaration means the same as written the declaration's way. */
+export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalPgObject, l: CanonicalPgObject): Props {
+  const out: Props = { ...live };
+  const adopt = (key: string) => {
+    if (declared[key] === undefined) delete out[key];
+    else out[key] = declared[key];
+  };
+  if (d.name === l.name) adopt("name");
+  if (d.schema === l.schema) adopt("schema");
+  const fieldKeys = new Set([...Object.keys(d.fields), ...Object.keys(l.fields)]);
+  for (const f of fieldKeys) {
+    if (f === "schema" && d.kind !== "extension") continue;
+    if (JSON.stringify(d.fields[f]) !== JSON.stringify(l.fields[f])) continue;
+    for (const key of PROP_OF_FIELD[f] ?? []) adopt(key);
+  }
+  // Fields neither side's canonical form carries (left at their default) are the declaration's too.
+  for (const [f, keys] of Object.entries(PROP_OF_FIELD)) {
+    if (!fieldKeys.has(f)) for (const key of keys) if (f !== "schema" || d.kind === "extension") adopt(key);
+  }
+
+  if (d.kind === "table") {
+    const declaredColumns = (declared.columns as unknown[] | undefined) ?? [];
+    const liveColumns = (live.columns as unknown[] | undefined) ?? [];
+    out.columns = liveColumns.map((c, i) => {
+      const lc = l.columns[i];
+      const dc = lc ? d.columns.find((x) => x.name === lc.name) : undefined;
+      return lc && dc && columnShape(lc) === columnShape(dc) ? declaredColumns[dc.position] : c;
+    });
+  }
+  if (d.kind === "table" || d.kind === "domain") {
+    // A constraint the declaration says the same as the server is the declaration's (its name included or left out).
+    const kinds = d.kind === "domain" ? ["CHECK"] : Object.keys(CONSTRAINT_PROPS);
+    for (const kind of kinds) {
+      const key = CONSTRAINT_PROPS[kind]!;
+      const dl = d.constraints.filter((c) => c.kind === kind);
+      const ll = l.constraints.filter((c) => c.kind === kind);
+      const all = dl.length === ll.length && dl.every((c) => ll.some((x) => sameConstraint(c, x) && c.notValid === x.notValid && c.comment === x.comment));
+      if (all) adopt(key);
+    }
+  }
+  return out;
+}
+
+export async function observeResourcesDeep(
+  options: {
+    environment: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  } & Omit<BindOptions, "environment">,
+): Promise<DeepObservationResult> {
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  let target;
+  let live: LivePgObject[];
+  const declared = options.entityNames.map((name) => ({ name, entity: options.entities.get(name) }));
+  try {
+    const bound = await bindPostgres(options);
+    target = bound.target;
+    try {
+      live = await readLiveSchema(bound.client, {
+        schemas: scopeFor(target, declared.filter((x) => x.entity?.entityType.startsWith("Postgres::")).map((x) => ({ type: x.entity!.entityType, props: x.entity!.props }))),
+      });
+    } finally {
+      await bound.client.end();
+    }
+  } catch (err) {
+    const why = classifyPostgresFailure(err);
+    for (const { name, entity } of declared) unobserved[name] = { type: entity?.entityType ?? "", reason: why.reason, detail: why.detail };
+    return deepObservation({}, unobserved);
+  }
+  const byKey = new Map(live.map((o) => [liveKey(o.type, o.schema, o.name), o]));
+  for (const { name, entity } of declared) {
+    if (!entity || !entity.entityType.startsWith("Postgres::")) {
+      unobserved[name] = { type: entity?.entityType ?? "", reason: "unsupported-kind" };
+      continue;
+    }
+    const { schema, name: objectName } = declaredAddress({ type: entity.entityType, props: entity.props }, target.defaultSchema);
+    const o = byKey.get(liveKey(entity.entityType, schema, objectName));
+    if (!o) continue;
+    try {
+      const lp = liveProps(o);
+      const d = canonicalPgObject(entity.entityType, entity.props, target.defaultSchema);
+      const l = canonicalPgObject(o.type, lp, target.defaultSchema);
+      resources[name] = { type: o.type, physicalId: o.oid, properties: inDeclaredVocabulary(entity.props, lp, d, l) };
+    } catch (err) {
+      unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's definition does not parse: ${(err as Error).message}` };
+    }
+  }
+  return deepObservation(resources, unobserved);
+}

package/src/postgres/plan/diff.ts

@@ -0,0 +1,323 @@
+/**
+ * The diff between two Postgres schemas, each change classified by the lock
+ * it takes and whether it reads or rewrites the table (`./rules.ts`).
+ *
+ * Identity, as for ClickHouse (#3237): an object is its export name between
+ * two builds, so a changed SQL name under the same export is a rename;
+ * against a server it is its qualified name, and `-- previously: <old name>`
+ * before the CREATE declares a rename. A column is its name; a column renamed
+ * in place says `-- previously: <old name>` on its line, and without the hint
+ * a drop and an add of the same type in the same place get a hint.
+ *
+ * A constraint the declaration leaves unnamed is matched by what it says, so
+ * the name Postgres gave it is not a change.
+ */
+
+import { classifiedChange, type ChangeSet, type ClassifiedChange } from "../../core/classifier";
+import { matchByIdentity } from "../../core/diff";
+import { PG_CLASSIFIER_RULES, type PgChangeClass, type PgClassifierRuleId } from "./rules";
+import { sameConstraint, serialBase, type CanonicalColumn, type CanonicalConstraint } from "./normalize";
+import type { PgDiffObject, PgSchemaObject } from "./schema";
+import { POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin";
+import type { PostgresMigrationOpSuggestion } from "../migrate/handoff";
+
+/** What the diff needs to know beyond the two schemas: the server's major (`sql.postgresMajor`, else the newest pinned). */
+export interface PgDiffOptions {
+  major?: number;
+}
+
+export type PgChange = ClassifiedChange<PgClassifierRuleId, PgChangeClass>;
+
+export interface PgSchemaDiff extends ChangeSet<PgChange> {
+  /** The changes a plan refuses to make in place: expand and contract only. */
+  refused: PgChange[];
+  /** The `PostgresMigrationOp` to run for each refused column rename or type change (#3281). */
+  migrationOps?: PostgresMigrationOpSuggestion[];
+}
+
+const change = (object: string, field: string, rule: PgClassifierRuleId, before?: unknown, after?: unknown, extra: Partial<PgChange> = {}): PgChange =>
+  classifiedChange(PG_CLASSIFIER_RULES, object, field, rule, before, after, extra);
+
+const qualified = (o: PgDiffObject) => `${o.schema ? `${o.schema}.` : ""}${o.name}`;
+
+// ── Columns ────────────────────────────────────────────────────────────
+
+/**
+ * Volatile functions a default may call, from `pg_proc.provolatile = 'v'` at
+ * 18.6: a default that calls one has to be computed per row, so ADD COLUMN
+ * with it rewrites the table. `now()` and `current_timestamp` are stable and
+ * do not.
+ */
+const VOLATILE = /\b(clock_timestamp|timeofday|random|random_normal|setseed|gen_random_uuid|uuidv4|uuidv7|uuid_generate_v1|uuid_generate_v1mc|uuid_generate_v4|nextval|txid_current|pg_current_xact_id|statement_timestamp)\s*\(/;
+
+/** Whether a type change needs no rewrite: binary-coercible, per ALTER TABLE's Notes. */
+function coercible(before: string, after: string): boolean {
+  if (before === after) return true;
+  const vc = (t: string) => /^character varying(\((\d+)\))?$/.exec(t);
+  const b = vc(before);
+  const a = vc(after);
+  if (b && (after === "text" || (a && (!a[2] || (b[2] && Number(a[2]) >= Number(b[2])))))) return true;
+  if (before === "text" && after === "character varying") return true;
+  const num = (t: string) => /^numeric(\((\d+),(\d+)\))?$/.exec(t);
+  const nb = num(before);
+  const na = num(after);
+  if (nb && na && (!na[1] || (nb[1] && na[3] === nb[3] && Number(na[2]) >= Number(nb[2])))) return true;
+  if (before === "cidr" && after === "inet") return true;
+  return false;
+}
+
+/** The kind of value a type holds, for telling a widening from a change of kind. */
+function family(t: string): string {
+  const base = t.replace(/\(.*\)/, "").replace(/\[\]$/, "");
+  if (/^(smallint|integer|bigint|numeric|real|double precision|serial|bigserial|smallserial)$/.test(base)) return "number";
+  if (/^(text|character varying|character|"char"|name|citext)$/.test(base) || base.endsWith(".citext")) return "string";
+  if (/^(timestamp|time|date|interval)/.test(base)) return "time";
+  return base;
+}
+
+function diffColumns(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[], hints: string[], tableIsNew: boolean, major: number): void {
+  const byName = new Map(before.columns.map((c) => [c.name, c]));
+  const afterNames = new Set(after.columns.map((c) => c.name));
+  const matched = new Set<string>();
+  const added: CanonicalColumn[] = [];
+  const checksProvingNotNull = new Set(
+    before.constraints.filter((c) => c.kind === "CHECK" && !c.notValid).map((c) => /^check (\S+) is not null$/.exec(c.body)?.[1]).filter((x): x is string => x !== undefined),
+  );
+
+  for (const a of after.columns) {
+    let b = byName.get(a.name);
+    const prev = after.columnPreviously[a.name];
+    if (!b && prev && byName.has(prev) && !afterNames.has(prev)) {
+      b = byName.get(prev)!;
+      out.push(change(key, `columns.${a.name}`, "SQLPG205", b.name, a.name));
+    }
+    if (!b) {
+      added.push(a);
+      if (tableIsNew) continue;
+      const identity = a.identity !== undefined;
+      const storedGenerated = a.generated?.startsWith("stored ");
+      const volatile = a.default !== undefined && VOLATILE.test(a.default);
+      const text = `${a.name} ${a.type ?? ""}`.trim();
+      if (identity || storedGenerated || volatile) {
+        out.push(change(key, `columns.${a.name}`, "SQLPG202", undefined, text, { note: identity ? "an identity column" : storedGenerated ? "a STORED generated column" : `the default ${a.default} is volatile` }));
+      } else if (a.notNull && a.default === undefined && !a.generated) out.push(change(key, `columns.${a.name}`, "SQLPG203", undefined, text));
+      else out.push(change(key, `columns.${a.name}`, "SQLPG201", undefined, text));
+      continue;
+    }
+    matched.add(b.name);
+    const at = `columns.${a.name}`;
+    if (b.type !== a.type) {
+      // A serial spelling is an integer column with an owned sequence and a nextval default:
+      // the change is classified by the integer types, and a change of the shorthand alone is a default.
+      const bt = serialBase(b.type) ?? b.type ?? "";
+      const at2 = serialBase(a.type) ?? a.type ?? "";
+      const serial = serialBase(b.type) !== undefined || serialBase(a.type) !== undefined;
+      if (bt === at2) out.push(change(key, `${at}.default`, "SQLPG209", b.type, a.type, { note: "the column gains or loses its owned sequence and nextval default" }));
+      else {
+        const rule = coercible(bt, at2) ? "SQLPG206" : family(bt) === family(at2) ? "SQLPG207" : "SQLPG208";
+        const note = serial && serialBase(b.type) !== undefined && serialBase(a.type) !== undefined ? { note: `${bt} to ${at2}; the owned sequence is widened to ${at2} (ALTER SEQUENCE ... AS ${at2}, SQLPG265)` } : {};
+        out.push(change(key, `${at}.type`, rule, b.type, a.type, note));
+      }
+    }
+    if (b.default !== a.default) out.push(change(key, `${at}.default`, "SQLPG209", b.default, a.default));
+    if (b.notNull !== a.notNull) {
+      if (a.notNull) {
+        const proven = checksProvingNotNull.has(a.name);
+        out.push(change(key, `${at}.notNull`, "SQLPG210", "NULL", "NOT NULL", proven ? { class: "metadata", note: "a valid CHECK (column IS NOT NULL) proves it, so no scan (12 and later)" } : {}));
+      } else out.push(change(key, `${at}.notNull`, "SQLPG211", "NOT NULL", "NULL"));
+    }
+    if (b.generated !== a.generated) {
+      const virtual = a.generated?.startsWith("virtual ") && b.generated?.startsWith("virtual ");
+      const extra: Partial<PgChange> = virtual
+        ? { class: "metadata", note: "a VIRTUAL column (18) changes only the catalog" }
+        : major < 17
+          ? { class: "expand", note: `Postgres ${major} has no SET EXPRESSION: the column is dropped and added` }
+          : {};
+      out.push(change(key, `${at}.generated`, "SQLPG212", b.generated, a.generated, extra));
+    }
+    if (b.identity !== a.identity) out.push(change(key, `${at}.identity`, "SQLPG213", b.identity, a.identity));
+    if (b.collate !== a.collate) out.push(change(key, `${at}.collate`, "SQLPG214", b.collate, a.collate));
+    if (b.compression !== a.compression || b.storage !== a.storage) out.push(change(key, `${at}.storage`, "SQLPG215", [b.storage, b.compression].filter(Boolean).join(" ") || undefined, [a.storage, a.compression].filter(Boolean).join(" ") || undefined));
+    if (b.comment !== a.comment) out.push(change(key, `${at}.comment`, "SQLPG216", b.comment, a.comment));
+  }
+  const dropped = before.columns.filter((c) => !matched.has(c.name));
+  for (const b of dropped) {
+    out.push(change(key, `columns.${b.name}`, "SQLPG204", `${b.name} ${b.type ?? ""}`.trim(), undefined, { destructive: true }));
+    const twin = added.find((a) => a.type === b.type && a.position === b.position);
+    if (twin) hints.push(`${key}: ${b.name} is dropped and ${twin.name} added with the same type in the same place; if it is a rename, write -- previously: ${b.name} on its line`);
+  }
+}
+
+// ── Constraints ────────────────────────────────────────────────────────
+
+/** The rule adding a constraint falls under. */
+export function addConstraintRule(c: CanonicalConstraint): PgClassifierRuleId {
+  if (c.notValid) return "SQLPG217";
+  switch (c.kind) {
+    case "CHECK":
+      return "SQLPG218";
+    case "FOREIGN KEY":
+      return "SQLPG219";
+    case "PRIMARY KEY":
+    case "UNIQUE":
+      return "SQLPG221";
+    case "EXCLUDE":
+      return "SQLPG222";
+  }
+}
+
+function diffConstraints(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[], domain: boolean): void {
+  const remaining = [...before.constraints];
+  const label = (c: CanonicalConstraint) => (c.name ? `${c.name}: ${c.body}` : c.body);
+  for (const a of after.constraints) {
+    const i = remaining.findIndex((b) => sameConstraint(a, b));
+    if (i < 0) {
+      out.push(change(key, `constraints.${a.name ?? a.kind.toLowerCase()}`, domain ? (a.notValid ? "SQLPG217" : "SQLPG262") : addConstraintRule(a), undefined, label(a)));
+      continue;
+    }
+    const b = remaining.splice(i, 1)[0]!;
+    if (b.notValid && !a.notValid) out.push(change(key, `constraints.${a.name ?? b.name ?? a.kind.toLowerCase()}`, "SQLPG220", "NOT VALID", "VALID"));
+    if (!b.notValid && a.notValid) out.push(change(key, `constraints.${a.name ?? b.name ?? a.kind.toLowerCase()}`, "SQLPG216", "VALID", "NOT VALID", { note: "a validated constraint stays validated; NOT VALID only matters when it is added" }));
+    if (b.comment !== a.comment) out.push(change(key, `constraints.${a.name ?? b.name}.comment`, "SQLPG216", b.comment, a.comment));
+  }
+  for (const b of remaining) out.push(change(key, `constraints.${b.name ?? b.kind.toLowerCase()}`, domain ? "SQLPG263" : "SQLPG223", label(b), undefined));
+}
+
+// ── Objects ────────────────────────────────────────────────────────────
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+const show = (v: unknown): string | undefined => (v === undefined ? undefined : typeof v === "string" ? v : JSON.stringify(v));
+
+function diffObject(key: string, before: PgDiffObject, after: PgDiffObject, out: PgChange[], hints: string[], major: number): void {
+  if (before.kind !== after.kind) {
+    out.push(change(key, "kind", "SQLPG268", before.kind, after.kind));
+    return;
+  }
+  const f = (name: string) => [before.fields[name], after.fields[name]] as const;
+  const field = (name: string, rule: PgClassifierRuleId, extra: Partial<PgChange> = {}) => {
+    const [b, a] = f(name);
+    if (!same(b, a)) out.push(change(key, name, rule, show(b), show(a), extra));
+  };
+  if (before.schema !== after.schema || before.name !== after.name) {
+    out.push(change(key, "name", after.kind === "index" ? "SQLPG229" : "SQLPG228", qualified(before), qualified(after)));
+  }
+  field("comment", "SQLPG216");
+  switch (after.kind) {
+    case "schema":
+      field("authorization", "SQLPG267");
+      break;
+    case "extension":
+      field("version", "SQLPG266");
+      field("schema", "SQLPG266");
+      break;
+    case "sequence":
+      field("options", "SQLPG265");
+      field("ownedBy", "SQLPG265");
+      field("unlogged", "SQLPG225", { class: "metadata", note: "a sequence's own row only" });
+      break;
+    case "enum": {
+      const b = (before.fields.labels as string[] | undefined) ?? [];
+      const a = (after.fields.labels as string[] | undefined) ?? [];
+      if (!same(b, a)) {
+        // Labels only added, wherever they go, keep every old label in order.
+        const kept = a.filter((l) => b.includes(l));
+        out.push(change(key, "labels", same(kept, b) ? "SQLPG260" : "SQLPG261", b.join(", "), a.join(", ")));
+      }
+      break;
+    }
+    case "domain":
+      field("dataType", "SQLPG264");
+      field("collate", "SQLPG264");
+      field("default", "SQLPG263");
+      if (!same(f("notNull")[0], f("notNull")[1])) out.push(change(key, "notNull", after.fields.notNull ? "SQLPG262" : "SQLPG263", show(before.fields.notNull), show(after.fields.notNull)));
+      diffConstraints(key, before, after, out, true);
+      break;
+    case "index": {
+      const definition = ["table", "unique", "method", "elements", "include", "nullsNotDistinct", "where"];
+      const changed = definition.filter((k) => !same(before.fields[k], after.fields[k]));
+      if (changed.length > 0) {
+        out.push(change(key, changed.join(", "), "SQLPG243", changed.map((k) => `${k} ${show(before.fields[k]) ?? "-"}`).join("; "), changed.map((k) => `${k} ${show(after.fields[k]) ?? "-"}`).join("; ")));
+      } else {
+        field("with", "SQLPG224");
+        field("tablespace", "SQLPG226");
+      }
+      break;
+    }
+    case "view":
+    case "materializedView": {
+      const b = before.outputs ?? [];
+      const a = after.outputs ?? [];
+      const appends = a.length >= b.length && b.every((o, i) => a[i] === o);
+      if (!same(before.fields.query, after.fields.query) || !same(b, a)) {
+        if (after.kind === "materializedView") out.push(change(key, "query", "SQLPG252", show(before.fields.query), show(after.fields.query)));
+        else out.push(change(key, "query", appends ? "SQLPG250" : "SQLPG251", show(before.fields.query), show(after.fields.query), appends ? {} : { note: `columns ${b.join(", ")} -> ${a.join(", ")}` }));
+      }
+      field("with", "SQLPG253");
+      field("checkOption", "SQLPG253");
+      field("withData", "SQLPG252");
+      field("columnComments", "SQLPG216");
+      break;
+    }
+    case "table":
+      diffColumns(key, before, after, out, hints, false, major);
+      diffConstraints(key, before, after, out, false);
+      field("with", "SQLPG224");
+      field("unlogged", "SQLPG225");
+      field("using", "SQLPG226", major < 15 ? { class: "expand", note: `Postgres ${major} has no SET ACCESS METHOD: the table is created again` } : {});
+      field("tablespace", "SQLPG226");
+      for (const k of ["partitionBy", "partitionOf", "partitionBound", "inherits"]) field(k, "SQLPG227");
+      break;
+  }
+}
+
+/** Whether an object is created by this plan in the same run (its index then needs no CONCURRENTLY). */
+function createdTables(matches: ReturnType<typeof matchByIdentity<PgDiffObject>>): Set<string> {
+  const out = new Set<string>();
+  for (const m of matches) if (m.kind === "created" && m.after.canonical.kind === "table") out.add(qualified(m.after.canonical));
+  return out;
+}
+
+/**
+ * Classify every change from `before` to `after`. Objects another tool owns
+ * (an ORM's revision table) are never proposed for a drop.
+ */
+/**
+ * Which object of `before` each object of `after` is: by key, else by a
+ * `-- previously:` hint naming the old one. The diff and the applier
+ * (`../apply/`) match the same way.
+ */
+export function matchPgObjects(before: readonly PgSchemaObject[], after: readonly PgSchemaObject[]): ReturnType<typeof matchByIdentity<PgDiffObject>> {
+  return matchByIdentity(before, after, {
+    qualified: (o) => `${o.kind === "schema" ? "schema" : o.kind === "extension" ? "extension" : o.kind === "enum" || o.kind === "domain" ? "type" : "relation"} ${qualified(o)}`,
+    previously: (o) => o.previously,
+    previousNames: (o, prev) => {
+      const space = o.kind === "schema" ? "schema" : o.kind === "extension" ? "extension" : o.kind === "enum" || o.kind === "domain" ? "type" : "relation";
+      return [`${space} ${prev}`, ...(o.schema && !prev.includes(".") ? [`${space} ${o.schema}.${prev}`] : [])];
+    },
+  });
+}
+
+export function diffPgSchemas(before: readonly PgSchemaObject[], after: readonly PgSchemaObject[], options: PgDiffOptions = {}): PgSchemaDiff {
+  const major = options.major ?? POSTGRES_LATEST_MAJOR;
+  const matches = matchPgObjects(before, after);
+  const newTables = createdTables(matches);
+  const changes: PgChange[] = [];
+  const hints: string[] = [];
+  for (const m of matches) {
+    if (m.kind === "created") {
+      const o = m.after.canonical;
+      if (o.kind === "index" && !newTables.has(String(o.fields.table))) {
+        changes.push(change(m.after.key, "index", o.concurrently ? "SQLPG240" : "SQLPG241", undefined, qualified(o)));
+      } else changes.push(change(m.after.key, o.kind, "SQLPG200", undefined, qualified(o)));
+    } else if (m.kind === "dropped") {
+      const o = m.before.canonical;
+      if (o.foreign) {
+        hints.push(`${m.before.key} is kept by ${o.foreign}; it is not chant's to drop and is left alone`);
+        continue;
+      }
+      const destructive = o.kind === "table" || o.kind === "materializedView" || o.kind === "sequence";
+      changes.push(change(m.before.key, o.kind, o.kind === "index" ? "SQLPG242" : "SQLPG270", qualified(o), undefined, destructive ? { destructive: true } : {}));
+    } else diffObject(m.after.key, m.before.canonical, m.after.canonical, changes, hints, major);
+  }
+  return { changes, hints, refused: changes.filter((c) => c.class === "expand") };
+}