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

package/src/postgres/plan/plan.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test } from "vitest";
+import { diffPgSchemas, type PgSchemaDiff } from "./diff";
+import { diffObject, keyedByQualifiedName, renameHints, type PgSchemaObject } from "./schema";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { diffPgBuildFiles } from "./commands";
+import { renderPgDiff } from "./report";
+import { classifyPgDisruption } from "./disruption";
+import { PG_CLASSIFIER_RULES } from "./rules";
+
+const TYPES: Record<string, string> = {
+  table: "Postgres::Table",
+  index: "Postgres::Index",
+  view: "Postgres::View",
+  materialized: "Postgres::MaterializedView",
+  sequence: "Postgres::Sequence",
+  type: "Postgres::Enum",
+  domain: "Postgres::Domain",
+  schema: "Postgres::Schema",
+  extension: "Postgres::Extension",
+};
+const obj = (key: string, kind: keyof typeof TYPES, ddl: string): PgSchemaObject => ({ key, canonical: { ...diffObject(TYPES[kind]!, ddl, "public"), exportName: key } });
+const diff = (before: PgSchemaObject[], after: PgSchemaObject[]): PgSchemaDiff => diffPgSchemas(before, after);
+const rules = (d: PgSchemaDiff) => d.changes.map((c) => [c.field, c.rule, c.class]);
+
+const ORDERS = "CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20), status text)";
+const table = (ddl: string) => obj("orders", "table", ddl);
+
+describe("columns", () => {
+  test("adding a column: metadata, a rewrite for a volatile default or stored generated column, expand for NOT NULL with no default", () => {
+    const d = diff(
+      [table(ORDERS)],
+      [
+        table(`CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20), status text,
+          a int, b timestamptz NOT NULL DEFAULT now(), c uuid DEFAULT gen_random_uuid(), d numeric GENERATED ALWAYS AS (amount * 2) STORED,
+          e numeric GENERATED ALWAYS AS (amount * 3), f bigint GENERATED ALWAYS AS IDENTITY, g int NOT NULL)`),
+      ],
+    );
+    expect(rules(d)).toEqual([
+      ["columns.a", "SQLPG201", "metadata"],
+      ["columns.b", "SQLPG201", "metadata"],
+      ["columns.c", "SQLPG202", "rewrite"],
+      ["columns.d", "SQLPG202", "rewrite"],
+      ["columns.e", "SQLPG201", "metadata"],
+      ["columns.f", "SQLPG202", "rewrite"],
+      ["columns.g", "SQLPG203", "expand"],
+    ]);
+    expect(d.refused.map((c) => c.field)).toEqual(["columns.g"]);
+  });
+
+  test("a type change is metadata when binary-coercible, a rewrite within a kind, expand across kinds", () => {
+    const d = diff(
+      [table(ORDERS)],
+      [table("CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(14,2) NOT NULL, note text, status integer)")],
+    );
+    expect(rules(d)).toEqual([
+      ["columns.amount.type", "SQLPG206", "metadata"],
+      ["columns.note.type", "SQLPG206", "metadata"],
+      ["columns.status.type", "SQLPG208", "expand"],
+    ]);
+    expect(rules(diff([table("CREATE TABLE app.orders (id integer)")], [table("CREATE TABLE app.orders (id bigint)")]))).toEqual([
+      ["columns.id.type", "SQLPG207", "rewrite"],
+    ]);
+  });
+
+  test("serial is an integer column with an owned sequence: never qualified, classified by the integer types", () => {
+    const col = (t: string) => table(`CREATE TABLE app.orders (id ${t} PRIMARY KEY)`);
+    const d = diff([col("serial")], [col("bigserial")]);
+    expect(rules(d)).toEqual([["columns.id.type", "SQLPG207", "rewrite"]]);
+    expect(d.changes[0]!.before).toBe("serial");
+    expect(d.changes[0]!.after).toBe("bigserial");
+    expect(d.changes[0]!.note).toContain("sequence is widened to bigint");
+    expect(rules(diff([col("smallserial")], [col("serial")]))).toEqual([["columns.id.type", "SQLPG207", "rewrite"]]);
+    expect(rules(diff([col("serial")], [col("serial")]))).toEqual([]);
+    expect(rules(diff([col("serial")], [col("integer")]))).toEqual([["columns.id.default", "SQLPG209", "metadata"]]);
+    expect(rules(diff([col("integer")], [col("bigserial")]))).toEqual([["columns.id.type", "SQLPG207", "rewrite"]]);
+    expect(rules(diff([col("serial")], [col("text")]))).toEqual([["columns.id.type", "SQLPG208", "expand"]]);
+  });
+
+  test("NOT NULL, defaults, comments, and a rename with and without the hint", () => {
+    expect(rules(diff([table(ORDERS)], [table("CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) DEFAULT 0, note varchar(20) NOT NULL, status text)")]))).toEqual([
+      ["columns.amount.default", "SQLPG209", "metadata"],
+      ["columns.amount.notNull", "SQLPG211", "metadata"],
+      ["columns.note.notNull", "SQLPG210", "rewrite"],
+    ]);
+    const renamed = diff([table(ORDERS)], [table(`CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20),
+      state text -- previously: status
+    )`)]);
+    expect(rules(renamed)).toEqual([["columns.state", "SQLPG205", "expand"]]);
+    const unhinted = diff([table(ORDERS)], [table("CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20), state text)")]);
+    expect(rules(unhinted)).toEqual([
+      ["columns.state", "SQLPG201", "metadata"],
+      ["columns.status", "SQLPG204", "metadata"],
+    ]);
+    expect(unhinted.hints[0]).toMatch(/-- previously: status/);
+  });
+
+  test("SET NOT NULL proven by a valid check is metadata", () => {
+    const before = table("CREATE TABLE app.orders (note text, CONSTRAINT note_nn CHECK (note IS NOT NULL))");
+    const after = table("CREATE TABLE app.orders (note text NOT NULL, CONSTRAINT note_nn CHECK (note IS NOT NULL))");
+    expect(rules(diff([before], [after]))).toEqual([["columns.note.notNull", "SQLPG210", "metadata"]]);
+  });
+});
+
+describe("constraints", () => {
+  const base = "CREATE TABLE app.orders (id bigint, user_id bigint, amount numeric";
+  test("added NOT VALID is metadata; validated, a check is a rewrite and a foreign key a validate; removing NOT VALID validates", () => {
+    const before = table(`${base})`);
+    const d = diff(
+      [before],
+      [table(`${base}, CONSTRAINT a CHECK (amount > 0), CONSTRAINT b CHECK (amount < 100) NOT VALID, CONSTRAINT c FOREIGN KEY (user_id) REFERENCES app.users (id), UNIQUE (id), EXCLUDE USING gist (id WITH =))`)],
+    );
+    expect(rules(d)).toEqual([
+      ["constraints.unique", "SQLPG221", "concurrently"],
+      ["constraints.a", "SQLPG218", "rewrite"],
+      ["constraints.b", "SQLPG217", "metadata"],
+      ["constraints.c", "SQLPG219", "validate"],
+      ["constraints.exclude", "SQLPG222", "rewrite"],
+    ]);
+    const validated = diff([table(`${base}, CONSTRAINT b CHECK (amount < 100) NOT VALID)`)], [table(`${base}, CONSTRAINT b CHECK (amount < 100))`)]);
+    expect(rules(validated)).toEqual([["constraints.b", "SQLPG220", "validate"]]);
+  });
+
+  test("an unnamed constraint matches the server's named one by what it says, and a dropped one is metadata", () => {
+    const declared = table(`${base}, CHECK (amount IN (1, 2)))`);
+    const live = table(`${base}, CONSTRAINT orders_amount_check CHECK ((amount = ANY (ARRAY[1, 2]))))`);
+    expect(diff([live], [declared]).changes).toEqual([]);
+    expect(rules(diff([live], [table(`${base})`)]))).toEqual([["constraints.orders_amount_check", "SQLPG223", "metadata"]]);
+  });
+});
+
+describe("objects", () => {
+  test("an index on an existing table needs CONCURRENTLY; on a new table it is part of the create", () => {
+    const users = table(ORDERS);
+    const conc = obj("byStatus", "index", "CREATE INDEX CONCURRENTLY by_status ON app.orders (status)");
+    const plain = obj("byNote", "index", "CREATE INDEX by_note ON app.orders (note)");
+    expect(rules(diff([users], [users, conc, plain]))).toEqual([
+      ["index", "SQLPG240", "concurrently"],
+      ["index", "SQLPG241", "concurrently"],
+    ]);
+    expect(rules(diff([], [users, plain])).map((r) => r[1])).toEqual(["SQLPG200", "SQLPG200"]);
+    expect(rules(diff([users, plain], [users]))).toEqual([["index", "SQLPG242", "concurrently"]]);
+    expect(rules(diff([plain], [obj("byNote", "index", "CREATE INDEX by_note ON app.orders (note DESC)")]))).toEqual([["elements", "SQLPG243", "concurrently"]]);
+  });
+
+  test("a view that keeps its columns is replaced; one that drops a column is expand; a materialized view is rebuilt", () => {
+    const v = (q: string) => obj("v", "view", `CREATE VIEW app.v AS ${q}`);
+    expect(rules(diff([v("SELECT id, note FROM app.orders")], [v("SELECT id, note, status FROM app.orders")]))).toEqual([["query", "SQLPG250", "metadata"]]);
+    expect(rules(diff([v("SELECT id, note FROM app.orders")], [v("SELECT id FROM app.orders")]))).toEqual([["query", "SQLPG251", "expand"]]);
+    const m = (q: string) => obj("m", "materialized", `CREATE MATERIALIZED VIEW app.m AS ${q}`);
+    expect(rules(diff([m("SELECT 1 AS a")], [m("SELECT 2 AS a")]))).toEqual([["query", "SQLPG252", "rewrite"]]);
+  });
+
+  test("enum labels added are metadata; removed or reordered are expand", () => {
+    const e = (labels: string) => obj("s", "type", `CREATE TYPE app.s AS ENUM (${labels})`);
+    expect(rules(diff([e("'a', 'c'")], [e("'a', 'b', 'c'")]))).toEqual([["labels", "SQLPG260", "metadata"]]);
+    expect(rules(diff([e("'a', 'c'")], [e("'c', 'a'")]))).toEqual([["labels", "SQLPG261", "expand"]]);
+  });
+
+  test("renames: an export renamed in SQL is a rename (expand); an index rename is metadata; a dropped table destroys data", () => {
+    expect(rules(diff([table(ORDERS)], [table(ORDERS.replace("app.orders", "app.purchases"))]))).toEqual([["name", "SQLPG228", "expand"]]);
+    const i = (n: string) => obj("i", "index", `CREATE INDEX ${n} ON app.orders (note)`);
+    expect(rules(diff([i("a")], [i("b")]))).toEqual([["name", "SQLPG229", "metadata"]]);
+    const dropped = diff([table(ORDERS)], []);
+    expect(dropped.changes[0]).toMatchObject({ rule: "SQLPG270", class: "drop", destructive: true });
+  });
+
+  test("against a server, -- previously: matches a renamed object by its old qualified name", () => {
+    const live = keyedByQualifiedName([table(ORDERS)]);
+    const declared = keyedByQualifiedName([table(`-- previously: orders\n${ORDERS.replace("app.orders", "app.purchases")}`)]);
+    expect(rules(diffPgSchemas(live, declared))).toEqual([["name", "SQLPG228", "expand"]]);
+    expect(renameHints("-- previously: orders\nCREATE TABLE t (\n  a int -- previously: b\n)")).toEqual({ previously: "orders", columns: { a: "b" } });
+  });
+
+  test("another tool's table is never proposed for a drop", () => {
+    const prisma = { key: "relation public._prisma_migrations", canonical: { ...diffObject("Postgres::Table", "CREATE TABLE public._prisma_migrations (id text)", "public"), foreign: "Prisma Migrate" } };
+    const d = diffPgSchemas([prisma], []);
+    expect(d.changes).toEqual([]);
+    expect(d.hints[0]).toMatch(/kept by Prisma Migrate/);
+  });
+});
+
+describe("the major (sql.postgresMajor)", () => {
+  test("a stored generated expression is a rewrite from 17 and expand before; a table's access method is expand before 15", () => {
+    const g = (e: string) => table(`CREATE TABLE app.orders (a int, b int GENERATED ALWAYS AS (${e}) STORED)`);
+    expect(diffPgSchemas([g("a * 2")], [g("a * 3")]).changes[0]).toMatchObject({ rule: "SQLPG212", class: "rewrite" });
+    expect(diffPgSchemas([g("a * 2")], [g("a * 3")], { major: 16 }).changes[0]).toMatchObject({ rule: "SQLPG212", class: "expand" });
+    const am = (m: string) => table(`CREATE TABLE app.orders (a int) USING ${m}`);
+    expect(diffPgSchemas([am("heap")], [am("columnar")], { major: 14 }).changes[0]).toMatchObject({ rule: "SQLPG226", class: "expand" });
+  });
+});
+
+describe("the major a build records (chant sql diff)", () => {
+  const build = (expr: string, postgresMajor?: number) => {
+    const ddl = `CREATE TABLE app.orders (a int, b int GENERATED ALWAYS AS (${expr}) STORED)`;
+    const doc = { dialect: "postgres", ...(postgresMajor === undefined ? {} : { postgresMajor }), applyOrder: ["orders"], objects: [{ export: "orders", type: "Postgres::Table", name: "orders", ddl }] };
+    const file = join(mkdtempSync(join(tmpdir(), "pg-major-")), "schema.json");
+    writeFileSync(file, JSON.stringify(doc));
+    return file;
+  };
+  const cls = (before: string, after: string, config?: number) => diffPgBuildFiles(before, after, config).changes[0]!.class;
+
+  test("the recorded major decides: SET EXPRESSION is a rewrite at 18 and expand and contract at 14", () => {
+    expect(cls(build("a * 2", 18), build("a * 3", 18))).toBe("rewrite");
+    expect(cls(build("a * 2", 14), build("a * 3", 14))).toBe("expand");
+  });
+  test("the recorded major wins over the config, and the config answers for a build with none", () => {
+    expect(cls(build("a * 2", 18), build("a * 3", 18), 14)).toBe("rewrite");
+    expect(cls(build("a * 2", 14), build("a * 3", 14), 18)).toBe("expand");
+    expect(cls(build("a * 2"), build("a * 3"), 14)).toBe("expand");
+    expect(cls(build("a * 2"), build("a * 3"))).toBe("rewrite");
+  });
+  test("the newer build's major wins over the older one's", () => {
+    expect(cls(build("a * 2", 14), build("a * 3", 18))).toBe("rewrite");
+  });
+});
+
+describe("the report, disruption and the rule table", () => {
+  test("the report names the class, the rule, the lock and the citation, and the refusal", () => {
+    const text = renderPgDiff(diff([table(ORDERS)], [table("CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20), status integer)")]));
+    expect(text).toContain("[EXPAND AND CONTRACT] columns.status.type: text -> integer");
+    expect(text).toContain("https://www.postgresql.org/docs/18/sql-altertable.html");
+    expect(text).toMatch(/Refused: 1 change/);
+  });
+
+  test("classifyDisruption maps paths onto rules, unknown where a path alone cannot say", () => {
+    const v = classifyPgDisruption({
+      environment: "prod",
+      changes: [
+        { name: "t", type: "Postgres::Table", deltas: [{ path: "comment" } as never] },
+        { name: "u", type: "Postgres::Table", deltas: [{ path: "columns[1].type" } as never] },
+        { name: "c", type: "ClickHouse::Table", deltas: [{ path: "comment" } as never] },
+      ],
+    });
+    expect(v.t).toMatchObject({ disruption: "in-place" });
+    expect(v.u).toMatchObject({ disruption: "unknown" });
+    expect(v.c).toBeUndefined();
+  });
+
+  test("every rule cites the Postgres 18 documentation", () => {
+    for (const r of Object.values(PG_CLASSIFIER_RULES)) expect(r.cite).toMatch(/^https:\/\/www\.postgresql\.org\/docs\/18\//);
+  });
+});

package/src/postgres/plan/report.ts

@@ -0,0 +1,24 @@
+/** A Postgres schema diff as text (the shared core's report, with the refusal of expand-and-contract changes). */
+
+import { renderChangeSet } from "../../core/classifier";
+import { PG_CHANGE_CLASSES, PG_CLASSIFIER_RULES } from "./rules";
+import type { PgSchemaDiff } from "./diff";
+import { renderMigrationOpSuggestions } from "../migrate/handoff";
+
+export function renderPgDiff(diff: PgSchemaDiff, opts: { title?: string } = {}): string {
+  const rewrites = diff.changes.filter((c) => c.class === "rewrite").length;
+  const trailer = [
+    ...(rewrites > 0
+      ? ["", `Warning: ${rewrites} change(s) rewrite or read a table under ACCESS EXCLUSIVE, which blocks its reads and writes until done; the rule names the form that does not.`]
+      : []),
+    ...(diff.refused.length > 0
+      ? [
+          "",
+          `Refused: ${diff.refused.length} change(s) keep no old reader working when made in place. Each runs as expand and contract ` +
+            "(add the new, write both, backfill, move readers, drop the old), as a migration Op, not as one statement.",
+          ...renderMigrationOpSuggestions(diff.migrationOps ?? []),
+        ]
+      : []),
+  ];
+  return renderChangeSet(diff, { ...(opts.title ? { title: opts.title } : {}), rules: PG_CLASSIFIER_RULES, classes: PG_CHANGE_CLASSES, trailer });
+}

package/src/postgres/plan/rules.ts

@@ -0,0 +1,276 @@
+/**
+ * The Postgres change classifier's rules (#3279, #3275 question 3): every way
+ * a declared Postgres object can change, the class of change it is on the
+ * server, and the restriction behind the class, cited from the Postgres 18
+ * documentation (the pinned major), with the differences across the
+ * supported majors 14 to 18 stated where there are any.
+ *
+ * The classes are by the lock a change takes and whether it reads or
+ * rewrites the table ("Explicit Locking", `ALTER TABLE`'s Notes):
+ *
+ * - `metadata`: a catalog change under a brief lock; no row is read or
+ *   written. Most `ALTER TABLE` forms take `ACCESS EXCLUSIVE` even so, which
+ *   queues behind every running query, so the applier (#3280) sets a
+ *   `lock_timeout`.
+ * - `validate`: every row is read to check a constraint, under a lock weaker
+ *   than `ACCESS EXCLUSIVE` (`SHARE UPDATE EXCLUSIVE` for `VALIDATE
+ *   CONSTRAINT`, so reads and writes go on).
+ * - `concurrently`: an index build, which blocks writes for its whole run
+ *   unless it is `CONCURRENTLY`, and `CONCURRENTLY` cannot run inside a
+ *   transaction block.
+ * - `rewrite`: the table is rewritten, or read in full, under `ACCESS
+ *   EXCLUSIVE`, blocking reads and writes for the duration.
+ * - `expand`: no in-place change keeps old readers working (a rename, a type
+ *   change with no cast in place, a change of partitioning): it is made as
+ *   expand and contract, by the migration Op (#3281). A plan refuses it.
+ *
+ * Creating and dropping whole objects are classed `create` and `drop`.
+ */
+
+import { classifierRule, type ChangeClasses, type ClassifierRule as SqlClassifierRule } from "../../core/classifier";
+
+export type PgChangeClass = "metadata" | "validate" | "concurrently" | "rewrite" | "expand" | "create" | "drop";
+
+export type PgClassifierRule = SqlClassifierRule<PgChangeClass>;
+
+export const PG_CHANGE_CLASSES: ChangeClasses<PgChangeClass> = {
+  order: ["create", "metadata", "validate", "concurrently", "rewrite", "expand", "drop"],
+  label: {
+    create: "create",
+    metadata: "metadata only",
+    validate: "validates under a weaker lock",
+    concurrently: "needs CONCURRENTLY",
+    rewrite: "ACCESS EXCLUSIVE rewrite or scan",
+    expand: "EXPAND AND CONTRACT",
+    drop: "drop",
+  },
+  disruption: { create: "in-place", metadata: "in-place", validate: "rolling", concurrently: "rolling", rewrite: "rolling", expand: "replace", drop: "destroy" },
+};
+
+const DOCS = "https://www.postgresql.org/docs/18";
+const ALTER_TABLE = `${DOCS}/sql-altertable.html`;
+const LOCKING = `${DOCS}/explicit-locking.html`;
+const CREATE_INDEX = `${DOCS}/sql-createindex.html#SQL-CREATEINDEX-CONCURRENTLY`;
+
+const rule = (id: string, cls: PgChangeClass, title: string, restriction: string, cite: string): PgClassifierRule => classifierRule(id, cls, title, restriction, cite);
+
+export const PG_CLASSIFIER_RULES = {
+  SQLPG200: rule("SQLPG200", "create", "Create an object", "A new object is created; nothing existing changes. A table created in the same plan as its indexes needs no CONCURRENTLY.", `${DOCS}/sql-createtable.html`),
+  SQLPG201: rule(
+    "SQLPG201",
+    "metadata",
+    "Add a column",
+    "ADD COLUMN with no default, or with a non-volatile default, changes only the catalog under ACCESS EXCLUSIVE: the default is stored once and read for existing rows (since 11, so in every supported major). A NOT NULL column needs that default.",
+    ALTER_TABLE,
+  ),
+  SQLPG202: rule(
+    "SQLPG202",
+    "rewrite",
+    "Add a column whose value has to be computed for every row",
+    "ADD COLUMN with a volatile default (clock_timestamp(), random(), gen_random_uuid(), nextval()), a STORED generated column or an identity column rewrites the whole table under ACCESS EXCLUSIVE. A VIRTUAL generated column (18) does not.",
+    ALTER_TABLE,
+  ),
+  SQLPG203: rule(
+    "SQLPG203",
+    "expand",
+    "Add a NOT NULL column with no default",
+    "ADD COLUMN ... NOT NULL with no default fails on a table that has rows. Add it nullable, backfill it, then set NOT NULL.",
+    ALTER_TABLE,
+  ),
+  SQLPG204: rule("SQLPG204", "metadata", "Drop a column", "DROP COLUMN only hides the column in the catalog under ACCESS EXCLUSIVE; its space is reclaimed as rows are rewritten. The data is gone.", ALTER_TABLE),
+  SQLPG205: rule(
+    "SQLPG205",
+    "expand",
+    "Rename a column",
+    "RENAME COLUMN is a catalog change, but every reader still using the old name fails the moment it runs: add the new column, write both, move readers, drop the old.",
+    ALTER_TABLE,
+  ),
+  SQLPG206: rule(
+    "SQLPG206",
+    "metadata",
+    "Change a column's type without a rewrite",
+    "ALTER COLUMN TYPE to a binary-coercible type (varchar(n) to a longer varchar or to text, numeric(p,s) to a wider precision or to unconstrained numeric, cidr to inet) needs no rewrite; indexes on the column may still be rebuilt. ACCESS EXCLUSIVE, briefly.",
+    ALTER_TABLE,
+  ),
+  SQLPG207: rule(
+    "SQLPG207",
+    "rewrite",
+    "Change a column's type with a rewrite",
+    "ALTER COLUMN TYPE that is not binary-coercible (integer to bigint, a shorter varchar, real to double precision) rewrites the table and rebuilds its indexes under ACCESS EXCLUSIVE.",
+    ALTER_TABLE,
+  ),
+  SQLPG208: rule(
+    "SQLPG208",
+    "expand",
+    "Change a column's type across kinds",
+    "A type change between kinds (text to integer, a type to an enum) needs a USING expression and breaks readers that expect the old type: add the new column, backfill, move readers, drop the old.",
+    ALTER_TABLE,
+  ),
+  SQLPG209: rule("SQLPG209", "metadata", "Change a column's default", "SET DEFAULT and DROP DEFAULT change only the catalog; existing rows keep their values.", ALTER_TABLE),
+  SQLPG210: rule(
+    "SQLPG210",
+    "rewrite",
+    "Set NOT NULL",
+    "SET NOT NULL reads the whole table under ACCESS EXCLUSIVE, unless a valid CHECK (column IS NOT NULL) constraint already proves it (since 12). Declare that check NOT VALID, validate it, then set NOT NULL; 18 can also add NOT NULL ... NOT VALID.",
+    ALTER_TABLE,
+  ),
+  SQLPG211: rule("SQLPG211", "metadata", "Drop NOT NULL", "DROP NOT NULL changes only the catalog.", ALTER_TABLE),
+  SQLPG212: rule(
+    "SQLPG212",
+    "rewrite",
+    "Change a generated column's expression",
+    "ALTER COLUMN SET EXPRESSION (17 and later) rewrites a STORED generated column under ACCESS EXCLUSIVE; on 14 to 16 the column has to be dropped and added. A VIRTUAL column (18) changes only the catalog.",
+    ALTER_TABLE,
+  ),
+  SQLPG213: rule("SQLPG213", "metadata", "Change a column's identity", "ADD, SET and DROP IDENTITY change the column's sequence and the catalog, not the rows.", ALTER_TABLE),
+  SQLPG214: rule("SQLPG214", "rewrite", "Change a column's collation", "A collation change is ALTER COLUMN TYPE with COLLATE: the column's indexes are rebuilt under ACCESS EXCLUSIVE.", ALTER_TABLE),
+  SQLPG215: rule("SQLPG215", "metadata", "Change a column's storage or compression", "SET STORAGE and SET COMPRESSION apply to values written afterwards; existing values are not rewritten.", ALTER_TABLE),
+  SQLPG216: rule("SQLPG216", "metadata", "Change a comment", "COMMENT ON changes only the catalog.", `${DOCS}/sql-comment.html`),
+  SQLPG217: rule(
+    "SQLPG217",
+    "metadata",
+    "Add a constraint NOT VALID",
+    "ADD CONSTRAINT ... NOT VALID checks new rows only and reads none of the existing ones; a foreign key takes SHARE ROW EXCLUSIVE on both tables, briefly. Validate it as a separate step.",
+    ALTER_TABLE,
+  ),
+  SQLPG218: rule(
+    "SQLPG218",
+    "rewrite",
+    "Add a CHECK constraint",
+    "ADD CONSTRAINT ... CHECK reads every row under ACCESS EXCLUSIVE. Declare it NOT VALID, then remove NOT VALID to validate it under SHARE UPDATE EXCLUSIVE (SQLPG220).",
+    ALTER_TABLE,
+  ),
+  SQLPG219: rule(
+    "SQLPG219",
+    "validate",
+    "Add a foreign key",
+    "ADD FOREIGN KEY reads every row under SHARE ROW EXCLUSIVE on both tables, which blocks writes to them for the scan. Declare it NOT VALID, then remove NOT VALID to validate it under SHARE UPDATE EXCLUSIVE (SQLPG220).",
+    ALTER_TABLE,
+  ),
+  SQLPG220: rule(
+    "SQLPG220",
+    "validate",
+    "Validate a constraint",
+    "VALIDATE CONSTRAINT reads every row under SHARE UPDATE EXCLUSIVE, so reads and writes go on (ROW SHARE on a foreign key's referenced table).",
+    LOCKING,
+  ),
+  SQLPG221: rule(
+    "SQLPG221",
+    "concurrently",
+    "Add a primary key or unique constraint",
+    "ADD PRIMARY KEY or UNIQUE builds its index under ACCESS EXCLUSIVE. Build the unique index CONCURRENTLY first, then ADD CONSTRAINT ... USING INDEX, which changes only the catalog.",
+    ALTER_TABLE,
+  ),
+  SQLPG222: rule("SQLPG222", "rewrite", "Add an exclusion constraint", "ADD CONSTRAINT ... EXCLUDE builds its index under ACCESS EXCLUSIVE; there is no concurrent form.", ALTER_TABLE),
+  SQLPG223: rule("SQLPG223", "metadata", "Drop a constraint", "DROP CONSTRAINT changes the catalog under ACCESS EXCLUSIVE, briefly; a primary key's or unique constraint's index goes with it.", ALTER_TABLE),
+  SQLPG224: rule(
+    "SQLPG224",
+    "metadata",
+    "Change storage parameters",
+    "SET and RESET of storage parameters change the catalog; fillfactor and the autovacuum parameters take only SHARE UPDATE EXCLUSIVE. Rows are not rewritten; a new fillfactor applies to pages written afterwards.",
+    ALTER_TABLE,
+  ),
+  SQLPG225: rule("SQLPG225", "rewrite", "Make a table LOGGED or UNLOGGED", "SET LOGGED and SET UNLOGGED rewrite the table under ACCESS EXCLUSIVE.", ALTER_TABLE),
+  SQLPG226: rule("SQLPG226", "rewrite", "Change a table's access method or tablespace", "SET ACCESS METHOD (15 and later) and SET TABLESPACE rewrite the table under ACCESS EXCLUSIVE.", ALTER_TABLE),
+  SQLPG227: rule(
+    "SQLPG227",
+    "expand",
+    "Change partitioning or inheritance",
+    "A table's partition key, its parent or bound, INHERITS and OF type cannot be altered in place: a new table is filled and swapped in. DETACH PARTITION CONCURRENTLY (14 and later) and ATTACH PARTITION, which takes SHARE UPDATE EXCLUSIVE on the parent, are the steps.",
+    `${DOCS}/ddl-partitioning.html`,
+  ),
+  SQLPG228: rule(
+    "SQLPG228",
+    "expand",
+    "Rename an object or move it to another schema",
+    "RENAME and SET SCHEMA are catalog changes, but every reader still using the old name fails at once: create the new name (a view over the old object works), move readers, drop the old.",
+    ALTER_TABLE,
+  ),
+  SQLPG229: rule("SQLPG229", "metadata", "Rename an index", "ALTER INDEX ... RENAME changes only the catalog; nothing reads an index by name.", `${DOCS}/sql-alterindex.html`),
+  SQLPG240: rule(
+    "SQLPG240",
+    "concurrently",
+    "Create an index CONCURRENTLY",
+    "CREATE INDEX CONCURRENTLY builds the index without blocking writes (SHARE UPDATE EXCLUSIVE), in two scans, and cannot run inside a transaction block; a failed build leaves an INVALID index to drop.",
+    CREATE_INDEX,
+  ),
+  SQLPG241: rule(
+    "SQLPG241",
+    "concurrently",
+    "Create an index without CONCURRENTLY",
+    "CREATE INDEX on an existing table takes SHARE, which blocks every write to the table until the build ends. Declare it CONCURRENTLY.",
+    CREATE_INDEX,
+  ),
+  SQLPG242: rule(
+    "SQLPG242",
+    "concurrently",
+    "Drop an index",
+    "DROP INDEX takes ACCESS EXCLUSIVE on the table; DROP INDEX CONCURRENTLY waits for running queries instead, and cannot run inside a transaction block.",
+    `${DOCS}/sql-dropindex.html`,
+  ),
+  SQLPG243: rule(
+    "SQLPG243",
+    "concurrently",
+    "Change an index",
+    "An index's definition cannot be altered: it is dropped and created, both CONCURRENTLY to keep writes going (SQLPG240, SQLPG242).",
+    CREATE_INDEX,
+  ),
+  SQLPG250: rule(
+    "SQLPG250",
+    "metadata",
+    "Change a view's query, keeping its columns",
+    "CREATE OR REPLACE VIEW replaces the query under ACCESS EXCLUSIVE on the view when the new query keeps the old columns, by name, in order, and only appends new ones.",
+    `${DOCS}/sql-createview.html`,
+  ),
+  SQLPG251: rule(
+    "SQLPG251",
+    "expand",
+    "Change a view's columns",
+    "A view whose columns are removed, renamed or reordered cannot be replaced: it is dropped and created, and every view and reader on top of it with it.",
+    `${DOCS}/sql-createview.html`,
+  ),
+  SQLPG252: rule(
+    "SQLPG252",
+    "rewrite",
+    "Change a materialized view's query",
+    "A materialized view's query cannot be altered: it is dropped and created, and its rows are computed again, with every view on top of it dropped too.",
+    `${DOCS}/sql-creatematerializedview.html`,
+  ),
+  SQLPG253: rule("SQLPG253", "metadata", "Change a view's options", "ALTER VIEW ... SET (check_option, security_barrier, security_invoker) changes only the catalog.", `${DOCS}/sql-alterview.html`),
+  SQLPG260: rule(
+    "SQLPG260",
+    "metadata",
+    "Add an enum label",
+    "ALTER TYPE ... ADD VALUE changes only the catalog; since 12 it can run in a transaction block, but the new label cannot be used in that transaction.",
+    `${DOCS}/sql-altertype.html`,
+  ),
+  SQLPG261: rule(
+    "SQLPG261",
+    "expand",
+    "Remove or reorder enum labels",
+    "An enum label cannot be removed and labels cannot be reordered in place: a new type is created, columns are moved to it, and the old one is dropped.",
+    `${DOCS}/sql-altertype.html`,
+  ),
+  SQLPG262: rule(
+    "SQLPG262",
+    "validate",
+    "Add a domain constraint",
+    "ALTER DOMAIN ADD CONSTRAINT (and SET NOT NULL) checks every column of the domain's type in every table; ADD CONSTRAINT ... NOT VALID skips existing rows and VALIDATE CONSTRAINT checks them later.",
+    `${DOCS}/sql-alterdomain.html`,
+  ),
+  SQLPG263: rule("SQLPG263", "metadata", "Change a domain's default or drop its constraint", "ALTER DOMAIN SET DEFAULT, DROP NOT NULL and DROP CONSTRAINT change only the catalog.", `${DOCS}/sql-alterdomain.html`),
+  SQLPG264: rule("SQLPG264", "expand", "Change a domain's data type", "A domain's underlying type cannot be altered: a new domain is created and columns are moved to it.", `${DOCS}/sql-alterdomain.html`),
+  SQLPG265: rule("SQLPG265", "metadata", "Change a sequence's options", "ALTER SEQUENCE changes the sequence's own row; tables are not touched. A sequence's AS type bounds its values.", `${DOCS}/sql-altersequence.html`),
+  SQLPG266: rule(
+    "SQLPG266",
+    "metadata",
+    "Change an extension's version or schema",
+    "ALTER EXTENSION UPDATE runs the extension's update script, which may itself alter objects; SET SCHEMA moves its objects.",
+    `${DOCS}/sql-alterextension.html`,
+  ),
+  SQLPG267: rule("SQLPG267", "metadata", "Change a schema's owner", "ALTER SCHEMA ... OWNER TO changes only the catalog.", `${DOCS}/sql-alterschema.html`),
+  SQLPG268: rule("SQLPG268", "expand", "Change an object's kind", "A view and a materialized view, or a table and either, are different kinds of object: the old one is dropped and the new one created.", `${DOCS}/sql-createview.html`),
+  SQLPG270: rule("SQLPG270", "drop", "Drop an object", "The object and, for a table, a materialized view or a sequence, its data are gone.", `${DOCS}/sql-droptable.html`),
+} as const satisfies Record<string, PgClassifierRule>;
+
+export type PgClassifierRuleId = keyof typeof PG_CLASSIFIER_RULES;