@intentius/chant-lexicon-sql 0.124.48 → 0.124.50

package/src/postgres/plan/normalize.ts

@@ -52,6 +52,11 @@ import { sequenceDefaults } from "../live/catalog";
 import type {
   AggregateArgDef,
   OperatorProps,
+  OperatorClassProps,
+  OperatorFamilyProps,
+  ForeignTableProps,
+  TextSearchConfigurationProps,
+  TextSearchDictionaryProps,
   AggregateProps,
   CastProps,
   CheckDef,
@@ -323,6 +328,8 @@ export interface CanonicalColumn {
   collate?: string;
   compression?: string;
   storage?: string;
+  /** A foreign table column's `OPTIONS`, sorted by name. */
+  options?: Record<string, string>;
   comment?: string;
 }
 
@@ -354,6 +361,11 @@ export type CanonicalKind =
   | "cast"
   | "eventTrigger"
   | "operator"
+  | "operatorClass"
+  | "operatorFamily"
+  | "foreignTable"
+  | "textSearchConfiguration"
+  | "textSearchDictionary"
   | "statistics"
   | "foreignDataWrapper"
   | "foreignServer"
@@ -404,6 +416,11 @@ const kindOf: Record<string, CanonicalKind> = {
   "Postgres::Cast": "cast",
   "Postgres::EventTrigger": "eventTrigger",
   "Postgres::Operator": "operator",
+  "Postgres::OperatorClass": "operatorClass",
+  "Postgres::OperatorFamily": "operatorFamily",
+  "Postgres::ForeignTable": "foreignTable",
+  "Postgres::TextSearchConfiguration": "textSearchConfiguration",
+  "Postgres::TextSearchDictionary": "textSearchDictionary",
   "Postgres::Statistics": "statistics",
   "Postgres::ForeignDataWrapper": "foreignDataWrapper",
   "Postgres::ForeignServer": "foreignServer",
@@ -745,6 +762,105 @@ function operatorOptions(p: OperatorProps, ownSchema: string, defaultSchema: str
   return Object.fromEntries(Object.entries(out).sort(([a], [b]) => (a < b ? -1 : 1)));
 }
 
+/**
+ * A name where an object is named (a text search parser, template or
+ * dictionary, an operator family): the schema left off when it is
+ * `pg_catalog` or the default schema, since a bare name is looked for in both.
+ * The catalog prints every schema, so both sides are brought to this form.
+ */
+export function canonicalRef(text: string, defaultSchema: string): string {
+  const pieces = canonicalName(text).split(/\.(?=(?:[^"]*"[^"]*")*[^"]*$)/);
+  if (pieces.length >= 2) {
+    const schema = identValue(pieces[0]!);
+    return schema === "pg_catalog" || schema === defaultSchema ? pieces.slice(1).join(".") : pieces.join(".");
+  }
+  return pieces[0]!;
+}
+
+/** An operator named in an operator class: `OPERATOR(app.<<)`, `app.<<` or a bare symbol, by `canonicalRef`'s rule for the schema. */
+export function canonicalOperatorName(text: string, defaultSchema: string): string {
+  const inner = text.trim().replace(/^OPERATOR\s*\(\s*(.*?)\s*\)$/is, "$1").trim();
+  const m = /^("(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)\s*\.\s*(\S.*)$/s.exec(inner);
+  if (!m) return inner;
+  const schema = identValue(m[1]!);
+  return schema === "pg_catalog" || schema === defaultSchema ? m[2]!.trim() : `${quoteIdent(schema)}.${m[2]!.trim()}`;
+}
+
+/** A comma list split at its top level: `numeric(12,2), text` is two items. */
+function splitTopLevel(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if (ch === "(" || ch === "[") depth++;
+    else if (ch === ")" || ch === "]") depth--;
+    if (ch === "," && depth === 0) {
+      out.push(current.trim());
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim() !== "") out.push(current.trim());
+  return out;
+}
+
+/**
+ * The operand types a support function of an operator class is registered
+ * for when `FUNCTION n (left, right)` does not say (sql-createopclass): a
+ * B-tree comparison function's (1) and a hash function's (1, 2) are the
+ * function's own input types, a B-tree `in_range` function's (3) its first
+ * and third, and every other support function's the class's type. The catalog
+ * always stores both, so a declaration is brought to them.
+ */
+function supportTypes(method: string, number: number, classType: string, args: readonly string[]): [string, string] {
+  if (method === "btree" && number === 1) return [args[0] ?? classType, args[1] ?? args[0] ?? classType];
+  if (method === "btree" && number === 3) return [args[0] ?? classType, args[2] ?? classType];
+  if (method === "hash" && (number === 1 || number === 2)) return [args[0] ?? classType, args[0] ?? classType];
+  return [classType, classType];
+}
+
+/** An operator class as compared: its type, family, default flag and members, each member canonical and the list sorted. */
+function operatorClassFields(p: OperatorClassProps, schema: string, defaultSchema: string, fields: Record<string, unknown>): void {
+  const type = canonicalType(p.dataType, defaultSchema)!;
+  fields.default = p.default === true;
+  fields.dataType = type;
+  // A class with no FAMILY is in a family of its own name; so is one that names that family.
+  const own = canonicalRef(`${quoteIdent(schema)}.${quoteIdent(p.name)}`, defaultSchema);
+  const named = p.family === undefined ? own : /^\s*("(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)\s*$/.test(p.family) && identValue(p.family.trim()) === p.name ? own : canonicalRef(p.family, defaultSchema);
+  fields.family = named === own ? undefined : named;
+  const side = (t: string) => (t.trim().toUpperCase() === "NONE" ? "NONE" : canonicalArgType(t, defaultSchema));
+  const members = p.items.map((i): { rank: number; number: number; text: string } => {
+    if (i.kind === "storage") return { rank: 2, number: 0, text: `storage ${canonicalType(i.type, defaultSchema)}` };
+    const n = Number(i.number);
+    if (i.kind === "operator") {
+      const [l, r] = i.types !== undefined ? splitTopLevel(i.types) : [type, type];
+      const sorted = i.orderBy !== undefined ? ` for order by ${canonicalRef(i.orderBy, defaultSchema)}` : "";
+      return { rank: 0, number: n, text: `operator ${n} ${canonicalOperatorName(i.operator, defaultSchema)} (${side(l ?? type)},${side(r ?? l ?? type)})${sorted}` };
+    }
+    const args = splitTopLevel(i.args).map((a) => canonicalArgType(a, defaultSchema));
+    const given = i.types !== undefined ? splitTopLevel(i.types).map(side) : undefined;
+    const [l, r] = given ? [given[0]!, given[1] ?? given[0]!] : supportTypes(p.method, n, type, args);
+    return { rank: 1, number: n, text: `function ${n} (${l},${r}) ${canonicalFunctionName(i.function, defaultSchema)}(${args.join(",")})` };
+  });
+  members.sort((a, b) => a.rank - b.rank || a.number - b.number || (a.text < b.text ? -1 : 1));
+  fields.items = members.map((m) => m.text);
+}
+
+/** A dictionary option's value as compared: a string constant's value, a quoted name's, a bare word folded, a number as written. */
+function dictionaryValue(v: string): string {
+  const t = v.trim();
+  if (/^([Ee]?'|\$)/.test(t)) return stringValue(t) ?? t;
+  if (/^"/.test(t)) return identValue(t);
+  return t.toLowerCase();
+}
+
+/** A text search configuration's mappings as compared: each token type to its dictionaries in order, sorted by token type. */
+function mappingFields(p: TextSearchConfigurationProps, defaultSchema: string): Record<string, string[]> | undefined {
+  const out: Record<string, string[]> = {};
+  for (const m of p.mappings) for (const t of m.tokens) out[t.toLowerCase()] = m.dictionaries.map((d) => canonicalRef(d, defaultSchema));
+  const entries = Object.entries(out).sort(([a], [b]) => (a < b ? -1 : 1));
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
 /** An `OPTIONS (...)` list as compared: by name, none as nothing. */
 function sortedOptions(options: Record<string, string> | undefined): Record<string, string> | undefined {
   const entries = Object.entries(options ?? {}).sort(([a], [b]) => (a < b ? -1 : 1));
@@ -869,6 +985,45 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
       fields.definition = operatorOptions(p, base.schema!, defaultSchema);
       break;
     }
+    case "operatorClass":
+      operatorClassFields(props as unknown as OperatorClassProps, base.schema!, defaultSchema, fields);
+      base.signature = ` USING ${(props as unknown as OperatorClassProps).method}`;
+      break;
+    case "operatorFamily":
+      base.signature = ` USING ${(props as unknown as OperatorFamilyProps).method}`;
+      break;
+    case "textSearchDictionary": {
+      const p = props as unknown as TextSearchDictionaryProps;
+      fields.template = canonicalRef(p.template, defaultSchema);
+      fields.options = sortedOptions(Object.fromEntries(Object.entries(p.options).map(([k, v]) => [k.toLowerCase(), dictionaryValue(v)])));
+      break;
+    }
+    case "textSearchConfiguration": {
+      const p = props as unknown as TextSearchConfigurationProps;
+      fields.parser = canonicalRef(p.parser, defaultSchema);
+      fields.mappings = mappingFields(p, defaultSchema);
+      break;
+    }
+    case "foreignTable": {
+      const p = props as unknown as ForeignTableProps;
+      p.columns.forEach((c: ColumnDef, position) => {
+        const options = sortedOptions(c.options);
+        columns.push({
+          name: c.name,
+          position,
+          type: canonicalType(c.type, defaultSchema),
+          notNull: c.notNull === true,
+          default: canonicalExpr(c.default),
+          collate: c.collate ? canonicalName(c.collate) : undefined,
+          comment: comment(c.comment),
+          ...(options ? { options } : {}),
+        });
+      });
+      for (const c of p.checks) constraints.push({ kind: "CHECK", name: c.name, body: ["check", canonicalExpr(c.expr), c.noInherit ? "no inherit" : ""].filter(Boolean).join(" "), ...(c.notValid ? { notValid: true } : {}), comment: comment(c.comment) });
+      fields.server = quoteIdent(p.serverName);
+      fields.options = sortedOptions(p.options);
+      break;
+    }
     case "statistics": {
       const p = props as unknown as StatisticsProps;
       fields.table = canonicalName(p.tableName, defaultSchema);

package/src/postgres/plan/rules.ts

@@ -360,15 +360,15 @@ export const PG_CLASSIFIER_RULES = {
   SQLPG300: rule(
     "SQLPG300",
     "metadata",
-    "Drop and create a type, aggregate, collation, cast, event trigger, operator, statistics object, foreign server or publication",
-    "A composite or range type's definition, a collation's, a cast's, an event trigger's, an operator's function and operands and extended statistics' have no ALTER, an aggregate's argument types, state type and final function cannot be replaced, and neither can a foreign server's type or wrapper or a publication's FOR ALL TABLES: the object is dropped and created in one transaction. Nothing on the server depends on it (a column, a view, a function or a cast would make the DROP fail); the locks are on its catalog rows only. Dropped statistics are empty until the next ANALYZE, and a publication that is dropped stops its subscribers until it is created again.",
+    "Drop and create a type, aggregate, collation, cast, event trigger, operator, operator class or family, foreign table's server, text search object, statistics object, foreign server or publication",
+    "A composite or range type's definition, a collation's, a cast's, an event trigger's, an operator's function and operands, and any attribute of it that SQLPG304 does not alter, an operator class's members, type, family and default flag, an operator family's index method, and extended statistics' have no ALTER (ALTER OPERATOR CLASS and ALTER OPERATOR FAMILY change a name, an owner or a schema only), an aggregate's argument types, state type and final function cannot be replaced, and neither can a foreign server's type or wrapper, a foreign table's server, a text search configuration's parser, a text search dictionary's template or a publication's FOR ALL TABLES: the object is dropped and created in one transaction. Nothing on the server depends on it (a column, a view, an index, a function or a cast would make the DROP fail); the locks are on its catalog rows only. Dropped statistics are empty until the next ANALYZE, and a publication that is dropped stops its subscribers until it is created again.",
     `${DOCS}/sql-createtype.html`,
   ),
   SQLPG301: rule(
     "SQLPG301",
     "expand",
-    "Change a type, aggregate, collation, cast, foreign server or publication that other objects depend on",
-    "No ALTER makes the change, and DROP refuses while a column, a view, a function or another object depends on the object. Create the new definition under another name, move what depends on it, then drop the old.",
+    "Change a type, aggregate, collation, cast, operator, operator class, text search object, foreign table's server, foreign server or publication that other objects depend on",
+    "No ALTER makes the change, and DROP refuses while a column, a view, an index, a function or another object depends on the object. Create the new definition under another name, move what depends on it, then drop the old.",
     `${DOCS}/sql-droptype.html`,
   ),
   SQLPG302: rule(
@@ -385,6 +385,27 @@ export const PG_CLASSIFIER_RULES = {
     "ALTER FOREIGN DATA WRAPPER (handler, validator, options), ALTER SERVER (version, options) and ALTER PUBLICATION (SET options, ADD and DROP TABLE and TABLES IN SCHEMA) change the object's catalog rows under a brief lock; no table is rewritten. A publication's change reaches its subscribers as the walsender next reads it: a table added is not copied to a subscription until the subscriber runs REFRESH PUBLICATION.",
     `${DOCS}/sql-alterpublication.html`,
   ),
+  SQLPG304: rule(
+    "SQLPG304",
+    "metadata",
+    "Alter an operator in place",
+    "ALTER OPERATOR ... SET changes the operator's catalog row under a brief lock; no index or table is read. RESTRICT and JOIN can be set or removed (NONE) on every supported major. From 17, COMMUTATOR and NEGATOR can be set when the operator has none, and HASHES and MERGES turned on, never off (the Postgres 18 page: \"Can only be changed if the operator does not have an existing commutator\", \"Can only be enabled and not disabled\"); setting a commutator or negator also sets the other operator's. On 14 to 16 only RESTRICT and JOIN are alterable, so any other change drops and creates the operator (SQLPG300), as does a change of function or operands on any major.",
+    `${DOCS}/sql-alteroperator.html`,
+  ),
+  SQLPG305: rule(
+    "SQLPG305",
+    "metadata",
+    "Alter a text search configuration's mappings or a dictionary's options in place",
+    "ALTER TEXT SEARCH CONFIGURATION ADD MAPPING, ALTER MAPPING and DROP MAPPING change the token types mapped to dictionaries; ALTER TEXT SEARCH DICTIONARY sets a template's options, and an option named with no value is removed. Both change catalog rows under a brief lock and leave the parser or template as it is, so a parser or template change is dropped and created (SQLPG300). A tsvector already stored keeps the tokens it was built with: rebuild the columns and indexes that hold one when the mappings or options change what a word becomes. The same applies on 14 to 18.",
+    `${DOCS}/sql-altertsconfig.html`,
+  ),
+  SQLPG306: rule(
+    "SQLPG306",
+    "metadata",
+    "Alter a foreign table in place",
+    "ALTER FOREIGN TABLE adds and drops columns, changes a column's type, default, NOT NULL and OPTIONS, adds and drops CHECK and NOT NULL constraints, and sets the table's OPTIONS, all in the catalog. Nothing is checked against the remote side and no row is rewritten or scanned (\"It is the user's responsibility to ensure that the table definition matches the remote side\"), so a CHECK is added with no validation pass. A foreign table's server cannot be altered, so a change of server is dropped and created (SQLPG300).",
+    `${DOCS}/sql-alterforeigntable.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>;
 

package/src/postgres/plan/schema.ts

@@ -106,7 +106,7 @@ export function pgSchemaFromBuildFile(path: string, defaultSchema = "public"): P
  */
 export function pgNamespace(kind: string): string {
   if (kind === "schema" || kind === "extension" || kind === "trigger" || kind === "policy" || kind === "role") return kind;
-  if (kind === "collation" || kind === "cast" || kind === "eventTrigger" || kind === "operator" || kind === "statistics" || kind === "foreignDataWrapper" || kind === "foreignServer" || kind === "publication") return kind;
+  if (kind === "collation" || kind === "cast" || kind === "eventTrigger" || kind === "operator" || kind === "operatorClass" || kind === "operatorFamily" || kind === "textSearchConfiguration" || kind === "textSearchDictionary" || kind === "statistics" || kind === "foreignDataWrapper" || kind === "foreignServer" || kind === "publication") return kind;
   if (kind === "grant" || kind === "defaultPrivileges") return "grant";
   if (kind === "enum" || kind === "domain" || kind === "composite" || kind === "range") return "type";
   if (kind === "function" || kind === "procedure" || kind === "aggregate") return "routine";

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

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+import { classifyPgStatements } from "./statements";
+
+const one = (sql: string) => classifyPgStatements([sql])[0]!;
+const rules = (sql: string) => one(sql).changes.map((c) => c.rule);
+
+describe("Postgres statements", () => {
+  test("CREATE INDEX without CONCURRENTLY is SQLPG241 with its SHARE lock", () => {
+    const v = one("CREATE INDEX orders_status_idx ON app.orders (status)");
+    expect(v.outcome).toBe("classified");
+    expect(v.changes).toMatchObject([{ rule: "SQLPG241", class: "concurrently", lock: "SHARE" }]);
+  });
+
+  test("CREATE INDEX CONCURRENTLY is SQLPG240", () => {
+    expect(one("CREATE UNIQUE INDEX CONCURRENTLY i ON t (a)").changes).toMatchObject([{ rule: "SQLPG240", lock: "SHARE UPDATE EXCLUSIVE" }]);
+  });
+
+  test("an index on a table the file creates needs no CONCURRENTLY", () => {
+    const [t, i] = classifyPgStatements(["CREATE TABLE t (id bigint PRIMARY KEY, a int)", "CREATE INDEX i ON t (a)"]);
+    expect(t!.changes[0]!.rule).toBe("SQLPG200");
+    expect(i!.changes[0]!.rule).toBe("SQLPG200");
+  });
+
+  test("ADD COLUMN splits by what the table must compute", () => {
+    expect(rules("ALTER TABLE t ADD COLUMN a int")).toEqual(["SQLPG201"]);
+    expect(rules("ALTER TABLE t ADD COLUMN a int NOT NULL DEFAULT 0")).toEqual(["SQLPG201"]);
+    expect(rules("ALTER TABLE t ADD COLUMN a int NOT NULL")).toEqual(["SQLPG203"]);
+    expect(rules("ALTER TABLE t ADD COLUMN a uuid DEFAULT gen_random_uuid()")).toEqual(["SQLPG202"]);
+    expect(rules("ALTER TABLE t ADD COLUMN a int GENERATED ALWAYS AS (b + 1) STORED")).toEqual(["SQLPG202"]);
+  });
+
+  test("a column type change is undecided between SQLPG206 and SQLPG207", () => {
+    const v = one("ALTER TABLE t ALTER COLUMN a TYPE bigint");
+    expect(v.outcome).toBe("undecided");
+    expect(v.candidates!.map((c) => c.rule)).toEqual(["SQLPG206", "SQLPG207"]);
+    expect(one("ALTER TABLE t ALTER COLUMN a TYPE int USING a::int").candidates!.map((c) => c.rule)).toEqual(["SQLPG206", "SQLPG207", "SQLPG208"]);
+  });
+
+  test("several actions in one ALTER TABLE are each classified", () => {
+    expect(rules("ALTER TABLE t ADD COLUMN a int, DROP COLUMN b, ALTER COLUMN c SET NOT NULL")).toEqual(["SQLPG201", "SQLPG204", "SQLPG210"]);
+    expect(one("ALTER TABLE t DROP COLUMN b").changes[0]!.destructive).toBe(true);
+  });
+
+  test("constraints", () => {
+    expect(rules("ALTER TABLE t ADD CONSTRAINT fk FOREIGN KEY (a) REFERENCES u (id) NOT VALID")).toEqual(["SQLPG217"]);
+    expect(rules("ALTER TABLE t ADD CONSTRAINT fk FOREIGN KEY (a) REFERENCES u (id)")).toEqual(["SQLPG219"]);
+    expect(rules("ALTER TABLE t ADD CONSTRAINT c CHECK (a > 0)")).toEqual(["SQLPG218"]);
+    expect(rules("ALTER TABLE t ADD PRIMARY KEY (id)")).toEqual(["SQLPG221"]);
+    expect(rules("ALTER TABLE t VALIDATE CONSTRAINT fk")).toEqual(["SQLPG220"]);
+    expect(rules("ALTER TABLE t DROP CONSTRAINT fk")).toEqual(["SQLPG223"]);
+  });
+
+  test("renames", () => {
+    expect(rules("ALTER TABLE t RENAME COLUMN a TO b")).toEqual(["SQLPG205"]);
+    expect(rules("ALTER TABLE t RENAME TO u")).toEqual(["SQLPG228"]);
+    expect(rules("ALTER INDEX i RENAME TO j")).toEqual(["SQLPG229"]);
+  });
+
+  test("DROP, GRANT, COMMENT and row security go through the parser or the verb", () => {
+    expect(rules("DROP INDEX CONCURRENTLY i")).toEqual(["SQLPG242"]);
+    expect(rules("DROP TABLE t")).toEqual(["SQLPG270"]);
+    expect(rules("GRANT SELECT ON TABLE t TO reader")).toEqual(["SQLPG296"]);
+    expect(rules("REVOKE SELECT ON TABLE t FROM reader")).toEqual(["SQLPG297"]);
+    expect(rules("COMMENT ON TABLE t IS 'x'")).toEqual(["SQLPG216"]);
+    expect(rules("ALTER TABLE t ENABLE ROW LEVEL SECURITY")).toEqual(["SQLPG293"]);
+  });
+
+  test("functions and views", () => {
+    expect(rules("CREATE OR REPLACE FUNCTION f() RETURNS int LANGUAGE sql AS $$ select 1; $$")).toEqual(["SQLPG280"]);
+    expect(one("CREATE OR REPLACE VIEW v AS SELECT 1 AS a").candidates!.map((c) => c.rule)).toEqual(["SQLPG250", "SQLPG251"]);
+    expect(rules("CREATE VIEW v AS SELECT 1 AS a")).toEqual(["SQLPG200"]);
+  });
+
+  test("data statements and unknown ALTERs", () => {
+    expect(one("UPDATE t SET a = 1").outcome).toBe("data");
+    expect(one("ALTER TABLE t OWNER TO app").outcome).toBe("unclassified");
+  });
+});

package/src/postgres/plan/statements.ts

@@ -0,0 +1,299 @@
+/**
+ * The Postgres statement classifier (#4407): a migration file's statements,
+ * each given the class and rule the schema-diff classifier (`./rules.ts`)
+ * gives the same change, with the lock the rule's restriction names. It reads
+ * text and contacts no server.
+ *
+ * `CREATE`, `GRANT`, `REVOKE`, `COMMENT ON` and `ALTER TABLE ... ROW LEVEL
+ * SECURITY` go through the declaration parser (`../parser.ts`). The parser
+ * has no `ALTER` grammar, so the other `ALTER` and `DROP` statements are read
+ * word by word from the same tokens.
+ *
+ * A statement alone cannot decide some changes. `ALTER COLUMN ... TYPE` is a
+ * catalog change or a table rewrite by the column's old type, which the file
+ * does not state: it is `undecided`, naming SQLPG206 and SQLPG207 (and
+ * SQLPG208 with a `USING` expression). `CREATE OR REPLACE VIEW` is SQLPG250
+ * or SQLPG251 by whether the columns stay. A statement no rule covers is
+ * `unclassified` with a note.
+ */
+
+import { isTrivia, tokenizeText, type Token } from "../tokens";
+import { parseStatements, type StatementNode } from "../parser";
+import { classifiedOf, lockOf, splitTopLevel, sqlHead, type StatementClassified, type StatementVerdict } from "../../core/statement-class";
+import { PG_CHANGE_CLASSES, PG_CLASSIFIER_RULES, type PgClassifierRuleId } from "./rules";
+
+const classified = (id: PgClassifierRuleId, extra: Partial<StatementClassified> = {}): StatementClassified => {
+  const lock = lockOf(PG_CLASSIFIER_RULES[id].restriction);
+  return classifiedOf(PG_CLASSIFIER_RULES, PG_CHANGE_CLASSES.label, id, { ...(lock ? { lock } : {}), ...extra });
+};
+
+/** What one clause of a statement comes to. */
+type Reading = { rules: Array<{ id: PgClassifierRuleId; extra?: Partial<StatementClassified> }> } | { undecided: PgClassifierRuleId[]; note: string } | { none: string } | { data: string };
+
+const rule = (id: PgClassifierRuleId, extra?: Partial<StatementClassified>): Reading => ({ rules: [{ id, ...(extra ? { extra } : {}) }] });
+
+const VOLATILE = /\b(?:clock_timestamp|random|gen_random_uuid|uuid_generate_v\d\w*|nextval|timeofday|txid_current|setseed)\s*\(/i;
+
+/** The words from `i` that are one possibly qualified name, and the index after it. */
+function nameAt(words: readonly string[], i: number): { name: string; next: number } {
+  let name = words[i] ?? "";
+  let j = i + 1;
+  while (words[j] === "." && words[j + 1] !== undefined) {
+    name += `.${words[j + 1]}`;
+    j += 2;
+  }
+  return { name, next: j };
+}
+
+const bare = (name: string): string => (name.split(".").pop() ?? name).replace(/^"|"$/g, "").toLowerCase();
+
+const has = (u: readonly string[], ...seq: string[]): boolean => u.some((_, i) => seq.every((w, k) => u[i + k] === w));
+
+/** One `ALTER TABLE` action (the words between top-level commas). */
+function tableAction(a: readonly string[]): Reading {
+  const u = a.map((w) => w.toUpperCase());
+  const first = u[0];
+  if (first === "ADD") {
+    let i = 1;
+    if (u[i] === "COLUMN") i++;
+    if (u[i] === "CONSTRAINT" || ["PRIMARY", "UNIQUE", "CHECK", "FOREIGN", "EXCLUDE"].includes(u[i] ?? "")) {
+      let k = i;
+      if (u[k] === "CONSTRAINT") k += 2;
+      const kind = u[k];
+      const notValid = has(u, "NOT", "VALID");
+      if (kind === "NOT" && u[k + 1] === "NULL") return rule("SQLPG210");
+      if (notValid) return rule("SQLPG217", { note: `${kind ?? "constraint"} added NOT VALID; VALIDATE CONSTRAINT is SQLPG220` });
+      if (kind === "PRIMARY" || kind === "UNIQUE") return rule("SQLPG221", has(u, "USING", "INDEX") ? { note: "from an existing unique index, so no build under this lock" } : {});
+      if (kind === "CHECK") return rule("SQLPG218");
+      if (kind === "FOREIGN") return rule("SQLPG219");
+      if (kind === "EXCLUDE") return rule("SQLPG222");
+      return { none: "an ADD CONSTRAINT of a kind no rule names" };
+    }
+    if (u[i] === "IF" && u[i + 1] === "NOT" && u[i + 2] === "EXISTS") i += 3;
+    const hasDefault = u.includes("DEFAULT");
+    const defaultText = hasDefault ? a.slice(u.indexOf("DEFAULT") + 1).join(" ") : "";
+    const generated = has(u, "GENERATED");
+    const stored = u.includes("STORED") && generated;
+    const identity = u.includes("IDENTITY");
+    const notNull = has(u, "NOT", "NULL");
+    if (stored || identity) return rule("SQLPG202", { note: stored ? "a STORED generated column" : "an identity column" });
+    if (VOLATILE.test(defaultText)) return rule("SQLPG202", { note: "a volatile default" });
+    if (notNull && !hasDefault && !generated) return rule("SQLPG203");
+    return rule("SQLPG201");
+  }
+  if (first === "DROP") {
+    if (u[1] === "CONSTRAINT") return rule("SQLPG223");
+    return rule("SQLPG204", { destructive: true });
+  }
+  if (first === "RENAME") {
+    if (u[1] === "COLUMN" || (u[1] !== "CONSTRAINT" && u[1] !== "TO")) return rule("SQLPG205");
+    return rule("SQLPG228");
+  }
+  if (first === "ALTER") {
+    let i = 1;
+    if (u[i] === "COLUMN") i++;
+    if (u[i] === "CONSTRAINT") return { none: "ALTER CONSTRAINT (deferrability)" };
+    const rest = u.slice(i + 1);
+    const col = a[i] ?? "column";
+    if (rest[0] === "TYPE" || (rest[0] === "SET" && rest[1] === "DATA" && rest[2] === "TYPE")) {
+      const using = rest.includes("USING");
+      return {
+        undecided: using ? ["SQLPG206", "SQLPG207", "SQLPG208"] : ["SQLPG206", "SQLPG207"],
+        note: `the new type of ${col} is a catalog change or a table rewrite by its old type${using ? ", or a change across kinds with this USING expression," : ""}, which the file does not state`,
+      };
+    }
+    if (rest[0] === "SET" && rest[1] === "DEFAULT") return rule("SQLPG209");
+    if (rest[0] === "DROP" && rest[1] === "DEFAULT") return rule("SQLPG209");
+    if (rest[0] === "SET" && rest[1] === "NOT" && rest[2] === "NULL") return rule("SQLPG210");
+    if (rest[0] === "DROP" && rest[1] === "NOT" && rest[2] === "NULL") return rule("SQLPG211");
+    if (rest[0] === "SET" && rest[1] === "EXPRESSION") return rule("SQLPG212");
+    if ((rest[0] === "ADD" && rest[1] === "GENERATED") || (rest[0] === "SET" && (rest[1] === "GENERATED" || rest[1] === "INCREMENT" || rest[1] === "START" || rest[1] === "RESTART")) || rest[0] === "RESTART" || (rest[0] === "DROP" && rest[1] === "IDENTITY")) {
+      return rule("SQLPG213");
+    }
+    if (rest[0] === "SET" && (rest[1] === "STORAGE" || rest[1] === "COMPRESSION")) return rule("SQLPG215");
+    return { none: `ALTER COLUMN ${rest.slice(0, 2).join(" ")}` };
+  }
+  if (first === "VALIDATE" && u[1] === "CONSTRAINT") return rule("SQLPG220");
+  if (first === "SET" || first === "RESET") {
+    if (u[1] === "LOGGED" || u[1] === "UNLOGGED") return rule("SQLPG225");
+    if (u[1] === "ACCESS" || u[1] === "TABLESPACE") return rule("SQLPG226");
+    if (u[1] === "SCHEMA") return rule("SQLPG228");
+    if (u[1] === "(" || first === "RESET") return rule("SQLPG224");
+    return { none: `ALTER TABLE ${u.slice(0, 2).join(" ")}` };
+  }
+  if (first === "ATTACH" || first === "DETACH" || first === "INHERIT" || (first === "NO" && u[1] === "INHERIT") || first === "OF" || (first === "NOT" && u[1] === "OF")) return rule("SQLPG227");
+  if ((first === "ENABLE" || first === "DISABLE" || first === "FORCE" || (first === "NO" && u[1] === "FORCE")) && has(u, "ROW", "LEVEL", "SECURITY")) return rule("SQLPG293");
+  if ((first === "ENABLE" || first === "DISABLE") && (u[1] === "TRIGGER" || u[1] === "REPLICA" || u[1] === "ALWAYS")) return rule("SQLPG284");
+  return { none: `ALTER TABLE ${u.slice(0, 2).join(" ")}` };
+}
+
+/** `ALTER <object> ...` other than `TABLE`, by its second word. */
+function alterOther(u: readonly string[], a: readonly string[]): Reading {
+  const obj = u[1];
+  const rename = u.includes("RENAME");
+  if (obj === "INDEX") return rename ? rule("SQLPG229") : rule("SQLPG243");
+  if (obj === "TYPE") {
+    if (has(u, "ADD", "VALUE")) return rule("SQLPG260");
+    if (has(u, "RENAME", "TO")) return rule("SQLPG228");
+    return { none: "ALTER TYPE other than ADD VALUE and RENAME TO" };
+  }
+  if (obj === "SEQUENCE") return rename || has(u, "SET", "SCHEMA") ? rule("SQLPG228") : has(u, "OWNER", "TO") ? { none: "ALTER SEQUENCE OWNER TO" } : rule("SQLPG265");
+  if (obj === "VIEW") return rename || has(u, "SET", "SCHEMA") ? rule("SQLPG228") : has(u, "OWNER", "TO") ? { none: "ALTER VIEW OWNER TO" } : rule("SQLPG253");
+  if (obj === "MATERIALIZED") return rename || has(u, "SET", "SCHEMA") ? rule("SQLPG228") : { none: "ALTER MATERIALIZED VIEW other than RENAME" };
+  if (obj === "SCHEMA") return rename ? rule("SQLPG228") : has(u, "OWNER", "TO") ? rule("SQLPG267") : { none: "ALTER SCHEMA" };
+  if (obj === "EXTENSION") return has(u, "UPDATE") || has(u, "SET", "SCHEMA") ? rule("SQLPG266") : { none: "ALTER EXTENSION ADD or DROP member" };
+  if (obj === "FUNCTION" || obj === "PROCEDURE" || obj === "ROUTINE") return rename || has(u, "SET", "SCHEMA") ? rule("SQLPG228") : { none: `ALTER ${obj} other than RENAME` };
+  if (obj === "TRIGGER") return rule("SQLPG284");
+  if (obj === "POLICY") return rename ? rule("SQLPG228") : rule("SQLPG291");
+  if (obj === "ROLE" || obj === "USER" || obj === "GROUP") return rule("SQLPG294");
+  if (obj === "DOMAIN") {
+    if (rename || has(u, "SET", "SCHEMA")) return rule("SQLPG228");
+    if (has(u, "ADD", "CONSTRAINT") || (u[3] === "ADD" && ["CHECK", "NOT"].includes(u[4] ?? ""))) return rule("SQLPG262");
+    if (has(u, "OWNER", "TO")) return { none: "ALTER DOMAIN OWNER TO" };
+    return rule("SQLPG263");
+  }
+  if (obj === "SERVER" || obj === "PUBLICATION" || (obj === "FOREIGN" && u[2] === "DATA")) return rename ? rule("SQLPG228") : rule("SQLPG303");
+  void a;
+  return { none: `ALTER ${obj ?? ""}`.trim() };
+}
+
+function dropStatement(u: readonly string[]): Reading {
+  const obj = u[1] === "MATERIALIZED" || u[1] === "FOREIGN" || u[1] === "EVENT" ? `${u[1]} ${u[2]}` : u[1];
+  if (obj === "INDEX") return rule("SQLPG242", u[2] === "CONCURRENTLY" ? { note: "DROP INDEX CONCURRENTLY waits for running queries instead of blocking them" } : {});
+  if (obj === "TRIGGER") return rule("SQLPG285", { destructive: false });
+  if (obj === "POLICY") return rule("SQLPG292", { destructive: false });
+  return rule("SQLPG270", { destructive: true });
+}
+
+/** How a `CREATE` that the parser could not read starts: its kind by key words. */
+function createByWords(u: readonly string[]): Reading {
+  let i = 1;
+  const orReplace = u[i] === "OR" && u[i + 1] === "REPLACE";
+  if (orReplace) i += 2;
+  while (["GLOBAL", "LOCAL", "TEMPORARY", "TEMP", "UNLOGGED", "RECURSIVE", "UNIQUE", "CONSTRAINT"].includes(u[i] ?? "") && u[i + 1] !== "INDEX" && u[i] !== "UNIQUE") i++;
+  if (u[i] === "UNIQUE") i++;
+  if (u[i] === "INDEX") {
+    const concurrently = u[i + 1] === "CONCURRENTLY";
+    return concurrently ? rule("SQLPG240") : rule("SQLPG241");
+  }
+  if (orReplace && (u[i] === "FUNCTION" || u[i] === "PROCEDURE")) return rule("SQLPG280");
+  if (orReplace && u[i] === "VIEW") return { undecided: ["SQLPG250", "SQLPG251"], note: "whether the view keeps its columns depends on the view it replaces" };
+  if (orReplace && u[i] === "AGGREGATE") return rule("SQLPG302");
+  if (u[i] === "TRIGGER") return rule("SQLPG283");
+  if (u[i] === "POLICY") return rule("SQLPG290");
+  return rule("SQLPG200");
+}
+
+/** A statement the parser read: its rule, given the tables this file created earlier. */
+function fromNode(n: StatementNode, created: Set<string>): Reading {
+  switch (n.statement) {
+    case "table":
+      created.add(bare(n.name.pieces.join(".")));
+      return rule("SQLPG200");
+    case "index":
+      if (n.concurrently) return rule("SQLPG240");
+      if (created.has(bare(n.table.pieces.join(".")))) return rule("SQLPG200", { note: "an index on a table this file creates, which has no rows to block" });
+      return rule("SQLPG241");
+    case "view":
+      if (n.orReplace && !n.materialized) return { undecided: ["SQLPG250", "SQLPG251"], note: "whether the view keeps its columns depends on the view it replaces" };
+      return rule("SQLPG200");
+    case "function":
+    case "procedure":
+      return n.orReplace ? rule("SQLPG280") : rule("SQLPG200");
+    case "aggregate":
+      return n.orReplace ? rule("SQLPG302") : rule("SQLPG200");
+    case "trigger":
+      return created.has(bare(n.table.pieces.join("."))) ? rule("SQLPG200", { note: "a trigger on a table this file creates" }) : rule("SQLPG283");
+    case "policy":
+      return created.has(bare(n.table.pieces.join("."))) ? rule("SQLPG200", { note: "a policy on a table this file creates" }) : rule("SQLPG290");
+    case "grant":
+      return n.defaults ? rule("SQLPG298") : n.revoke ? rule("SQLPG297") : rule("SQLPG296");
+    case "rowSecurity":
+      return rule("SQLPG293");
+    case "comment":
+      return rule("SQLPG216");
+    case "role":
+      return rule("SQLPG200");
+    default:
+      return rule("SQLPG200");
+  }
+}
+
+const DATA_WORDS = new Set(["INSERT", "UPDATE", "DELETE", "SELECT", "WITH", "COPY", "CALL", "DO", "SET", "BEGIN", "START", "COMMIT", "END", "ROLLBACK", "SAVEPOINT", "RELEASE", "ANALYZE", "ANALYSE", "VACUUM", "REINDEX", "LOCK", "NOTIFY", "LISTEN", "RESET", "SHOW", "EXPLAIN", "VALUES", "MERGE", "REFRESH", "CLUSTER", "CHECKPOINT", "DISCARD", "PREPARE", "EXECUTE", "DEALLOCATE"]);
+
+/** Classify one statement. `created` is the tables the file's earlier statements created. */
+function read(sql: string, created: Set<string>): Reading[] {
+  let tokens: Token[];
+  try {
+    tokens = tokenizeText(sql, 0);
+  } catch {
+    return [{ none: "text the tokenizer could not read" }];
+  }
+  const words = tokens.filter((t) => !isTrivia(t) && t.text !== ";").map((t) => t.text);
+  const u = words.map((w) => w.toUpperCase());
+  const head = u[0];
+  if (head === undefined) return [{ data: "an empty statement" }];
+
+  if (head === "CREATE" || head === "GRANT" || head === "REVOKE" || head === "COMMENT" || (head === "ALTER" && (u[1] === "DEFAULT" || (u[1] === "TABLE" && has(u, "ROW", "LEVEL", "SECURITY"))))) {
+    try {
+      const nodes = parseStatements(tokens);
+      return nodes.map((n) => fromNode(n, created));
+    } catch {
+      if (head === "CREATE") return [createByWords(u)];
+      if (head === "GRANT") return [rule("SQLPG296")];
+      if (head === "REVOKE") return [rule("SQLPG297")];
+      if (head === "COMMENT") return [rule("SQLPG216")];
+      if (head === "ALTER" && u[1] === "DEFAULT") return [rule("SQLPG298")];
+      return [rule("SQLPG293")];
+    }
+  }
+  if (head === "ALTER" && u[1] === "TABLE") {
+    let i = 2;
+    if (u[i] === "IF" && u[i + 1] === "EXISTS") i += 2;
+    if (u[i] === "ONLY") i++;
+    const { name, next } = nameAt(words, i);
+    if (u[next] === "*") i = next + 1;
+    else i = next;
+    const actions = splitTopLevel(words.slice(i));
+    if (actions.length === 0) return [{ none: `ALTER TABLE ${name} with no action` }];
+    void name;
+    return actions.map(tableAction);
+  }
+  if (head === "ALTER") return [alterOther(u, words)];
+  if (head === "DROP") return [dropStatement(u)];
+  if (head === "TRUNCATE") return [{ data: "TRUNCATE removes every row of the table" }];
+  if (DATA_WORDS.has(head)) return [{ data: `${head} reads or writes rows or the session, not the schema` }];
+  return [{ none: `${head} is not a statement the classifier reads` }];
+}
+
+/**
+ * Classify a migration's up statements, in order. The statements are the
+ * file's own text, one per entry (a Flyway file after placeholder
+ * substitution).
+ */
+export function classifyPgStatements(statements: readonly string[]): StatementVerdict[] {
+  const created = new Set<string>();
+  return statements.map((sql, k) => {
+    const readings = read(sql, created);
+    const out: StatementVerdict = { index: k + 1, sql: sqlHead(sql), outcome: "classified", changes: [] };
+    const none: string[] = [];
+    for (const r of readings) {
+      if ("rules" in r) out.changes.push(...r.rules.map((x) => classified(x.id, x.extra)));
+      else if ("undecided" in r) {
+        out.candidates = r.undecided.map((id) => classified(id));
+        out.note = r.note;
+      } else if ("none" in r) none.push(r.none);
+      else out.note = r.data;
+    }
+    if (out.candidates && out.changes.length === 0) out.outcome = "undecided";
+    else if (out.candidates) {
+      // A statement with some decided clauses and one undecided: report undecided, and keep the decided ones.
+      out.outcome = "undecided";
+    } else if (out.changes.length === 0 && none.length === 0) out.outcome = "data";
+    else if (none.length > 0) {
+      out.outcome = out.changes.length > 0 ? "classified" : "unclassified";
+      out.note = [out.note, `no rule covers ${none.join("; ")}`].filter(Boolean).join("; ");
+    }
+    return out;
+  });
+}