@intentius/chant-lexicon-sql 0.124.48 → 0.124.49

package/src/lint/post-synth/postgres-checks.test.ts

@@ -4,7 +4,7 @@ import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 import type { SerializerResult } from "@intentius/chant/serializer";
 import { sqlSerializer } from "../../serializer";
 import { table as chTable } from "../../clickhouse/entities";
-import { domain, extension, func, grant, index, role, schema, sequence, table, type as pgType, view } from "../../postgres/entities";
+import { domain, extension, func, grant, index, operatorClass, role, schema, sequence, table, type as pgType, view } from "../../postgres/entities";
 import { sqlAuditCatalog } from "../audit-catalog";
 import { postSynthChecks } from "./index";
 
@@ -444,6 +444,13 @@ describe("SQLPG125: access methods and operator classes", () => {
     clean("SQLPG125", { t, i, e: extension`CREATE EXTENSION pg_trgm` });
   });
   test("an operator class in an undeclared schema is left alone", () => clean("SQLPG125", { t, i: index`CREATE INDEX t_x ON ${t} (email ext.my_ops)` }));
+  test("an operator class the project declares passes for its own method only (#4406)", () => {
+    const app = schema`CREATE SCHEMA app`;
+    const ops = operatorClass`CREATE OPERATOR CLASS ${app}.shop_ops FOR TYPE text USING btree AS OPERATOR 1 <, OPERATOR 2 <=, OPERATOR 3 =, OPERATOR 4 >=, OPERATOR 5 >, FUNCTION 1 bttextcmp(text, text)`;
+    clean("SQLPG125", { app, t, ops, i: index`CREATE INDEX t_x ON ${t} (email shop_ops)` });
+    clean("SQLPG125", { app, t, ops, i: index`CREATE INDEX t_x ON ${t} (email app.shop_ops)` });
+    flagged("SQLPG125", { app, t, ops, i: index`CREATE INDEX t_x ON ${t} USING hash (email shop_ops)` }, /shop_ops, which Postgres 18 does not have for hash/);
+  });
 });
 
 describe("SQLPG126: functions", () => {

package/src/lint/post-synth/postgres-names.ts

@@ -474,6 +474,8 @@ export type OpClassResolution = { ok: true } | { ok: false; miss: Miss; otherMet
 /** An operator class for `method` at the target major. */
 export function resolveOpClass(p: PgProject, method: string, opclass: { schema?: string; name: string }): OpClassResolution {
   if (opclass.schema !== undefined && outsideProject(p, opclass.schema)) return { ok: true };
+  // A class the project declares (an `operatorClass` tag), for this method.
+  if (p.objects.some((o) => o.type === "Postgres::OperatorClass" && o.name === opclass.name && o.method === method && (opclass.schema === undefined || o.schema === opclass.schema))) return { ok: true };
   const classes = OPERATOR_CLASSES as Readonly<Record<string, Readonly<Record<string, Presence>>>>;
   if (presentAt(classes[method]?.[opclass.name], p.major)) return { ok: true };
   const ext = extensionFor(p, (e) => e.opclasses?.[method]?.includes(opclass.name) ?? false);

package/src/lint/rules/postgres-templates.ts

@@ -17,12 +17,12 @@ export const POSTGRES_TEMPLATE_SOURCES: readonly TemplateSource<PostgresTag>[] =
   {
     dialect: "postgres",
     modules: ["@intentius/chant-lexicon-sql/postgres"],
-    tags: ["schema", "table", "index", "view", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
+    tags: ["schema", "table", "index", "view", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "operatorClass", "operatorFamily", "foreignTable", "textSearchConfiguration", "textSearchDictionary", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
   },
   {
     dialect: "postgres",
     modules: ["@intentius/chant-lexicon-sql"],
-    tags: ["schema", "index", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
+    tags: ["schema", "index", "sequence", "type", "domain", "extension", "func", "procedure", "aggregate", "trigger", "eventTrigger", "operator", "operatorClass", "operatorFamily", "foreignTable", "textSearchConfiguration", "textSearchDictionary", "statistics", "foreignDataWrapper", "foreignServer", "publication", "collation", "cast", "policy", "role", "grant"],
   },
 ];
 

package/src/lsp/postgres-template.ts

@@ -156,6 +156,15 @@ export function postgresDeclarations(content: string, fileName = "file.ts"): Pos
           sqlName = text(node.name.span);
           kind = "operator";
           break;
+        case "operatorClass":
+        case "operatorFamily":
+        case "foreignTable":
+        case "textSearchConfiguration":
+        case "textSearchDictionary":
+          sqlName = text(node.name.span);
+          kind = { operatorClass: "operator class", operatorFamily: "operator family", foreignTable: "foreign table", textSearchConfiguration: "text search configuration", textSearchDictionary: "text search dictionary" }[node.statement];
+          if (node.statement === "foreignTable") columns = node.columns.map((c) => ({ name: c.name || text(c.nameSpan) || "", ...(text(c.type) ? { type: text(c.type)! } : {}) }));
+          break;
         case "statistics":
         case "foreignDataWrapper":
         case "foreignServer":

package/src/mcp/postgres.ts

@@ -81,7 +81,7 @@ export function postgresSearch(params: Record<string, unknown>): unknown {
   };
 }
 
-const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, aggregate: pg.aggregate, trigger: pg.trigger, eventTrigger: pg.eventTrigger, operator: pg.operator, statistics: pg.statistics, foreignDataWrapper: pg.foreignDataWrapper, foreignServer: pg.foreignServer, publication: pg.publication, collation: pg.collation, cast: pg.cast, policy: pg.policy, role: pg.role, grant: pg.grant } as const;
+const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, aggregate: pg.aggregate, trigger: pg.trigger, eventTrigger: pg.eventTrigger, operator: pg.operator, operatorClass: pg.operatorClass, operatorFamily: pg.operatorFamily, foreignTable: pg.foreignTable, textSearchConfiguration: pg.textSearchConfiguration, textSearchDictionary: pg.textSearchDictionary, statistics: pg.statistics, foreignDataWrapper: pg.foreignDataWrapper, foreignServer: pg.foreignServer, publication: pg.publication, collation: pg.collation, cast: pg.cast, policy: pg.policy, role: pg.role, grant: pg.grant } as const;
 export const POSTGRES_TAGS = Object.keys(TAGS);
 
 /** Parse one statement with the Postgres tag; an error comes back as SQLPG001 with its line and column. */

package/src/migration-classify.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Classifying the migration files a pull request adds (#4407), for goose,
+ * golang-migrate, clickhouse-migrations and Flyway. Each fixture directory is
+ * an in-memory tree at the base commit and another at the head, with one
+ * file added; the answer is what the plan note lists. Offline: nothing here
+ * opens a server.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test, vi } from "vitest";
+import { LINK_READERS, type KindLinkRead } from "@intentius/chant/workspace/kind-link-readers";
+import { classifyNewMigrations, newMigrationGroups } from "@intentius/chant/workspace/new-migrations";
+import { renderMigrationLines } from "@intentius/chant/pr-migrations";
+import type { WorkspaceTree } from "@intentius/chant/workspace/tree";
+import { classifyMigrationFiles } from "./migration-classify";
+
+function memoryTree(files: Record<string, string>): WorkspaceTree {
+  const dirs = new Set([""]);
+  for (const f of Object.keys(files)) {
+    const parts = f.split("/");
+    for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join("/"));
+  }
+  return {
+    label: "",
+    stat: (p) => (p in files ? "file" : dirs.has(p) ? "dir" : undefined),
+    list(p) {
+      if (!dirs.has(p)) return undefined;
+      const prefix = p === "" ? "" : `${p}/`;
+      const seen = new Map<string, "file" | "dir">();
+      for (const f of Object.keys(files)) {
+        if (!f.startsWith(prefix)) continue;
+        const rest = f.slice(prefix.length);
+        seen.set(rest.split("/")[0]!, rest.includes("/") ? "dir" : "file");
+      }
+      return [...seen].map(([name, type]) => ({ name, type }));
+    },
+    read(p) {
+      if (!(p in files)) throw new Error(`no such file ${p}`);
+      return files[p]!;
+    },
+  };
+}
+
+const sql = { name: "sql", classifyMigrations: classifyMigrationFiles };
+
+/** The files the pull request adds, classified, as the plan note lists them. */
+async function classify(reader: keyof typeof LINK_READERS, fields: Record<string, string>, base: Record<string, string>, added: Record<string, string>) {
+  const head = memoryTree({ ...base, ...added });
+  const read = new Map<string, KindLinkRead>([["m", LINK_READERS[reader]({ member: { name: "m" } as never, dir: "db", fields: fields as never, tree: head })]]);
+  const groups = newMigrationGroups([{ name: "m", dir: "db" }], read, memoryTree(base));
+  return classifyNewMigrations(groups, head, [sql]);
+}
+
+const rules = (f: Awaited<ReturnType<typeof classify>>[number]) => f.statements.flatMap((s) => s.changes.map((c) => c.rule));
+
+describe("a new file in each migration directory kind appears with classes", () => {
+  test("goose: the Up section only", async () => {
+    const [f, ...rest] = await classify(
+      "goose-dir",
+      { dialect: "postgres" },
+      { "db/00001_init.sql": "-- +goose Up\nCREATE TABLE orders (id bigint PRIMARY KEY, status text);\n-- +goose Down\nDROP TABLE orders;\n" },
+      {
+        "db/00002_idx.sql":
+          "-- +goose Up\nCREATE INDEX orders_status_idx ON orders (status);\nALTER TABLE orders ADD COLUMN note text;\n-- +goose Down\nDROP INDEX orders_status_idx;\n",
+      },
+    );
+    expect(rest).toEqual([]);
+    expect(f).toMatchObject({ member: "m", reader: "goose-dir", file: "db/00002_idx.sql", dialect: "postgres" });
+    expect(rules(f!)).toEqual(["SQLPG241", "SQLPG201"]);
+    expect(f!.statements[0]!.changes[0]).toMatchObject({ class: "concurrently", lock: "SHARE" });
+  });
+
+  test("golang-migrate: the .up file, not the .down file", async () => {
+    const out = await classify(
+      "golang-migrate-dir",
+      { dialect: "postgres" },
+      { "db/000001_init.up.sql": "CREATE TABLE t (id bigint);", "db/000001_init.down.sql": "DROP TABLE t;" },
+      { "db/000002_fk.up.sql": "ALTER TABLE t ADD CONSTRAINT fk FOREIGN KEY (id) REFERENCES u (id) NOT VALID;", "db/000002_fk.down.sql": "ALTER TABLE t DROP CONSTRAINT fk;" },
+    );
+    expect(out.map((f) => f.file)).toEqual(["db/000002_fk.up.sql"]);
+    expect(rules(out[0]!)).toEqual(["SQLPG217"]);
+  });
+
+  test("clickhouse-migrations: a sort-key change is a rebuild", async () => {
+    const [f] = await classify(
+      "clickhouse-migrations-dir",
+      {},
+      { "db/1_events.sql": "CREATE TABLE events (user_id UInt64, ts DateTime) ENGINE = MergeTree ORDER BY ts;" },
+      { "db/2_key.sql": "ALTER TABLE events MODIFY ORDER BY (user_id, ts);" },
+    );
+    expect(f).toMatchObject({ dialect: "clickhouse" });
+    expect(f!.statements[0]).toMatchObject({ outcome: "classified", changes: [{ rule: "SQLCH220", class: "rebuild", label: "REBUILD" }] });
+  });
+
+  test("flyway: placeholders are substituted before the statements are read", async () => {
+    const [f] = await classify(
+      "flyway-dir",
+      { dialect: "postgres" },
+      { "db/V1__init.sql": "CREATE TABLE ${schema}.t (id bigint);", "db/flyway.conf": "flyway.locations=filesystem:.\nflyway.placeholders.schema=app\n" },
+      { "db/V2__idx.sql": "CREATE INDEX CONCURRENTLY i ON ${schema}.t (id);" },
+    );
+    expect(f).toMatchObject({ file: "db/V2__idx.sql", type: "versioned" });
+    expect(f!.statements[0]!.sql).toBe("CREATE INDEX CONCURRENTLY i ON app.t (id)");
+    expect(rules(f!)).toEqual(["SQLPG240"]);
+  });
+
+  test("flyway: a placeholder with no value is reported on the file, not thrown", async () => {
+    const [f] = await classify("flyway-dir", { dialect: "postgres" }, { "db/V1__init.sql": "SELECT 1;" }, { "db/V2__x.sql": "CREATE TABLE ${missing}.t (id bigint);" });
+    expect(f!.statements).toEqual([]);
+    expect(f!.error).toContain("missing");
+  });
+});
+
+describe("the plan note lines", () => {
+  test("a Postgres CREATE INDEX without CONCURRENTLY is listed with its lock", async () => {
+    const files = await classify("goose-dir", { dialect: "postgres" }, { "db/1_a.sql": "-- +goose Up\nSELECT 1;\n" }, { "db/2_b.sql": "-- +goose Up\nCREATE INDEX i ON orders (status);\n" });
+    const lines = renderMigrationLines(files).join("\n");
+    expect(lines).toContain("`db/2_b.sql` (member `m`, postgres)");
+    expect(lines).toContain("`CREATE INDEX i ON orders (status)`: needs CONCURRENTLY (SQLPG241, SHARE)");
+  });
+
+  test("a ClickHouse sort-key change is listed as a rebuild", async () => {
+    const files = await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "ALTER TABLE events MODIFY ORDER BY (a, b);" });
+    expect(renderMigrationLines(files).join("\n")).toContain("REBUILD (SQLCH220)");
+  });
+
+  test("an undecided statement names both rules", async () => {
+    const files = await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "ALTER TABLE events MODIFY COLUMN user_id UInt32;" });
+    expect(renderMigrationLines(files).join("\n")).toContain("undecided between SQLCH210 background rewrite and SQLCH211 REBUILD");
+  });
+});
+
+describe("offline", () => {
+  test("classifying contacts no server and starts no process", async () => {
+    const fetched = vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("network used"));
+    await classify("goose-dir", { dialect: "postgres" }, { "db/1_a.sql": "-- +goose Up\nSELECT 1;\n" }, { "db/2_b.sql": "-- +goose Up\nDROP TABLE t;\n" });
+    await classify("clickhouse-migrations-dir", {}, { "db/1_a.sql": "SELECT 1;" }, { "db/2_b.sql": "DROP TABLE t;" });
+    expect(fetched).not.toHaveBeenCalled();
+    fetched.mockRestore();
+  });
+
+  test("the classifier modules import no live binding, client or process API", () => {
+    for (const f of ["migration-classify.ts", "postgres/plan/statements.ts", "clickhouse/plan/statements.ts", "core/statement-class.ts"]) {
+      const src = readFileSync(join(import.meta.dirname, f), "utf8");
+      const imports = [...src.matchAll(/(?:from|import\()\s*["']([^"']+)["']/g)].map((m) => m[1]!);
+      for (const spec of imports) expect(spec, `${f} imports ${spec}`).not.toMatch(/\/live\/|\/apply\/|\/http$|child_process|node:net|node:http|node:https|\/bind$/);
+    }
+  });
+});

package/src/migration-classify.ts

@@ -0,0 +1,45 @@
+/**
+ * Classify the migration files a pull request adds (#4407), the lexicon's
+ * answer to core's `classifyMigrations` hook. The "check" adoption level:
+ * each new file's up statements are read and given the class the schema-diff
+ * classifier gives the same change, and nothing else happens. No server is
+ * contacted, no migration tool runs and nothing is applied, so it needs no
+ * environment binding (compare `chant sql replay`, which does).
+ *
+ * The up statements are the ones replay would run: goose's `-- +goose Up`
+ * section, the whole file for golang-migrate and clickhouse-migrations, and a
+ * Flyway file after placeholder substitution with the configuration's values.
+ */
+
+import type { MigrationFileClassification } from "@intentius/chant/pr-migrations";
+import { findFlywayConfig, readFlywayConfig, substitute } from "@intentius/chant/workspace/flyway-layout";
+import type { WorkspaceTree } from "@intentius/chant/workspace/tree";
+import { classifyClickHouseStatements } from "./clickhouse/plan/statements";
+import { gooseUpStatements, splitStatements } from "./migration-replay";
+import { classifyPgStatements } from "./postgres/plan/statements";
+
+export const MIGRATION_DIALECTS = ["postgres", "clickhouse"] as const;
+
+/** The reader names whose files this lexicon reads. */
+const READERS = new Set(["goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"]);
+
+export function classifyMigrationFiles(options: { reader: string; dialect: string; tree: WorkspaceTree; dir: string; files: string[] }): MigrationFileClassification[] {
+  const { reader, dialect, tree, dir, files } = options;
+  if (!READERS.has(reader) || !(MIGRATION_DIALECTS as readonly string[]).includes(dialect)) return [];
+  const classify = dialect === "postgres" ? classifyPgStatements : classifyClickHouseStatements;
+  let flyway: ReturnType<typeof readFlywayConfig> | undefined;
+  return files.map((file) => {
+    try {
+      const text = tree.read(file);
+      let statements: string[];
+      if (reader === "goose-dir") statements = gooseUpStatements(text);
+      else if (reader === "flyway-dir") {
+        flyway ??= readFlywayConfig(tree, findFlywayConfig(tree, dir), dir);
+        statements = splitStatements(substitute(text, file, flyway));
+      } else statements = splitStatements(text);
+      return { file, statements: classify(statements) };
+    } catch (err) {
+      return { file, statements: [], error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+}

package/src/op/watch-pipeline.test.ts

@@ -13,7 +13,7 @@
  */
 
 import { join } from "node:path";
-import { describe, expect, test } from "vitest";
+import { beforeAll, describe, expect, test } from "vitest";
 import { generateOpsPipeline } from "@intentius/chant/op";
 import { parseYAML } from "@intentius/chant/yaml";
 import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
@@ -58,6 +58,13 @@ async function render(forge: "github" | "gitlab" | "forgejo", spec: ScheduledOpS
 const runLine = (steps: Array<Record<string, unknown>>) => steps.find((s) => s.run === "chant run schema-watch");
 
 describe("generateOpsPipeline renders the sql drift watch (#3642)", () => {
+  // The first render loads the github, gitlab and forgejo plugins and discovers the example's Ops. On a loaded CI shard
+  // that cold load took 5.7s and put the first test over the 5s unit-test budget (chant #2817). A file's beforeAll is
+  // not counted against the budget, so the load is paid here and each test below times only its own render.
+  beforeAll(async () => {
+    await generateOpsPipeline([reader(actionsSecret)], "github", { beforeScript: INSTALL.actions }, EXAMPLE);
+  }, 60_000);
+
   test("GitHub: the Op's own cron, a read-only token and the reader's credentials", async () => {
     const { file, doc } = await render("github", reader(actionsSecret));
     expect(file.name).toBe("schema-watch.yml");

package/src/plugin.ts

@@ -115,6 +115,11 @@ export const sqlPlugin: LexiconPlugin = {
       { name: "trigger", isTag: true, description: "A Postgres CREATE TRIGGER, parsed into a trigger entity on its table" },
       { name: "eventTrigger", isTag: true, description: "A Postgres CREATE EVENT TRIGGER, parsed into the database's event trigger entity" },
       { name: "operator", isTag: true, description: "A Postgres CREATE OPERATOR, parsed into an operator entity identified by its name and operand types" },
+      { name: "operatorClass", isTag: true, description: "A Postgres CREATE OPERATOR CLASS, parsed into an operator class entity identified by its name and index method" },
+      { name: "operatorFamily", isTag: true, description: "A Postgres CREATE OPERATOR FAMILY, parsed into an operator family entity identified by its name and index method" },
+      { name: "foreignTable", isTag: true, description: "A Postgres CREATE FOREIGN TABLE, parsed into a foreign table entity with its columns, server and options" },
+      { name: "textSearchConfiguration", isTag: true, description: "A Postgres CREATE TEXT SEARCH CONFIGURATION with its ADD MAPPING statements, parsed into a configuration entity" },
+      { name: "textSearchDictionary", isTag: true, description: "A Postgres CREATE TEXT SEARCH DICTIONARY, parsed into a dictionary entity with its template and options" },
       { name: "statistics", isTag: true, description: "A Postgres CREATE STATISTICS, parsed into an extended statistics entity on its table" },
       { name: "foreignDataWrapper", isTag: true, description: "A Postgres CREATE FOREIGN DATA WRAPPER, parsed into the database's wrapper entity" },
       { name: "foreignServer", isTag: true, description: "A Postgres CREATE SERVER, parsed into the database's foreign server entity (user mappings are not declared)" },
@@ -295,6 +300,15 @@ export const sqlPlugin: LexiconPlugin = {
     return { ...classifyDisruption(options), ...classifyPgDisruption(options) };
   },
 
+  /**
+   * The migration files a pull request adds (#4407): each up statement given
+   * the class the schema-diff classifier gives the same change. Offline.
+   */
+  async classifyMigrations(options) {
+    const { classifyMigrationFiles } = await import("./migration-classify");
+    return classifyMigrationFiles(options);
+  },
+
   /** `chant sql diff` and `chant sql plan`: schema changes, classified. */
   commands() {
     return sqlCommands;

package/src/postgres/access/acl.ts

@@ -188,7 +188,7 @@ export function declaredAccess(objects: ReadonlyArray<{ key: string; canonical:
   for (const { canonical: o } of objects) {
     const name = `${o.schema ? `${quoteIdent(o.schema)}.` : ""}${quoteIdent(o.name)}`;
     if (o.kind === "schema") declaredTargets.push({ kind: "schema", name: quoteIdent(o.name) });
-    else if (o.kind === "table" || o.kind === "view" || o.kind === "materializedView") {
+    else if (o.kind === "table" || o.kind === "foreignTable" || o.kind === "view" || o.kind === "materializedView") {
       relationKind.set(name, "table");
       declaredTargets.push({ kind: "table", name });
     } else if (o.kind === "sequence") {

package/src/postgres/access/import.ts

@@ -21,7 +21,7 @@ function targetsOf(objects: readonly LivePgObject[]): AclTarget[] {
   for (const o of objects) {
     const name = `${o.schema ? `${quoteIdent(o.schema)}.` : ""}${quoteIdent(o.name)}`;
     if (o.type === POSTGRES_ENTITY_TYPES.schema) out.push({ kind: "schema", name: quoteIdent(o.name) });
-    else if (o.type === POSTGRES_ENTITY_TYPES.table || o.type === POSTGRES_ENTITY_TYPES.view || o.type === POSTGRES_ENTITY_TYPES.materializedView) out.push({ kind: "table", name });
+    else if (o.type === POSTGRES_ENTITY_TYPES.table || o.type === POSTGRES_ENTITY_TYPES.foreignTable || o.type === POSTGRES_ENTITY_TYPES.view || o.type === POSTGRES_ENTITY_TYPES.materializedView) out.push({ kind: "table", name });
     else if (o.type === POSTGRES_ENTITY_TYPES.sequence) out.push({ kind: "sequence", name });
     else if (o.type === POSTGRES_ENTITY_TYPES.function || o.type === POSTGRES_ENTITY_TYPES.procedure) {
       out.push({ kind: o.type === POSTGRES_ENTITY_TYPES.function ? "function" : "procedure", name: `${name}${o.signature ?? ""}` });

package/src/postgres/apply/apply.ts

@@ -575,6 +575,11 @@ function liveCanonicalAddress(o: LivePgObject): { kind: CanonicalKind; schema?:
       "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",

package/src/postgres/apply/statements.ts

@@ -34,7 +34,7 @@ import { ACCESS_KINDS, canonicalOptions, sameConstraint, type CanonicalConstrain
 import type { PgDiffObject, PgSchemaObject } from "../plan/schema";
 import { migrationTarget } from "../migrate/handoff";
 import { pgName } from "../migrate/names";
-import type { CheckDef, ColumnDef, DomainProps, ExclusionDef, ForeignKeyDef, IndexProps, KeyDef, PolicyProps, SequenceProps, TableProps } from "../entities";
+import type { CheckDef, ColumnDef, DomainProps, ForeignTableProps, TextSearchConfigurationProps, ExclusionDef, ForeignKeyDef, IndexProps, KeyDef, PolicyProps, SequenceProps, TableProps } from "../entities";
 
 const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
 
@@ -136,6 +136,11 @@ export const KIND_WORDS: Readonly<Record<CanonicalKind, string>> = {
   cast: "CAST",
   eventTrigger: "EVENT TRIGGER",
   operator: "OPERATOR",
+  operatorClass: "OPERATOR CLASS",
+  operatorFamily: "OPERATOR FAMILY",
+  foreignTable: "FOREIGN TABLE",
+  textSearchConfiguration: "TEXT SEARCH CONFIGURATION",
+  textSearchDictionary: "TEXT SEARCH DICTIONARY",
   statistics: "STATISTICS",
   foreignDataWrapper: "FOREIGN DATA WRAPPER",
   foreignServer: "SERVER",
@@ -322,7 +327,7 @@ function identitySetClauses(options: string | undefined): string[] {
   return out;
 }
 
-const COLUMN_FIELD = /^columns\.(.+?)(?:\.(type|default|notNull|generated|identity|collate|storage|comment))?$/;
+const COLUMN_FIELD = /^columns\.(.+?)(?:\.(type|default|notNull|generated|identity|collate|storage|options|comment))?$/;
 
 // ── Constraints ────────────────────────────────────────────────────────
 
@@ -632,6 +637,125 @@ function alteredSteps(d: PgDiffObject, live: PgDiffObject, target: string): PgSt
   return out.map((sql) => step(sql, "metadata", "SQLPG303"));
 }
 
+
+// ── Operators, text search and foreign tables (#4406) ──────────────────
+
+/**
+ * The clauses of `ALTER OPERATOR ... SET (...)` for the attributes the diff
+ * found changeable in place (SQLPG304): RESTRICT and JOIN to the declared
+ * estimator or NONE, COMMUTATOR and NEGATOR to the declared operator, and
+ * HASHES and MERGES as bare words, since they can only be turned on.
+ */
+function operatorSetClauses(d: PgDiffObject, changes: readonly PgChange[]): string[] {
+  const definition = (d.fields.definition ?? {}) as Record<string, string>;
+  return changes.map((c) => {
+    const key = c.field.replace(/^definition\./, "");
+    const value = definition[key];
+    if (key === "hashes" || key === "merges") return key.toUpperCase();
+    if (key === "commutator" || key === "negator") return `${key.toUpperCase()} = OPERATOR(${value})`;
+    return `${key.toUpperCase()} = ${value ?? "NONE"}`;
+  });
+}
+
+/**
+ * A text search configuration's mappings, or a dictionary's options, taken to
+ * the declaration in place (SQLPG305). For a configuration: DROP MAPPING for
+ * the token types no longer mapped, ALTER MAPPING for those whose dictionaries
+ * changed, ADD MAPPING for the new ones, one statement for the token types
+ * that share their dictionaries; the dictionaries are named as the
+ * declaration wrote them. For a dictionary: one ALTER with each option that
+ * differs set, and each option the declaration dropped named with no value,
+ * which removes it.
+ */
+function textSearchSteps(obj: DeclaredPgObject, live: PgDiffObject, target: string): PgStep[] {
+  const d = obj.canonical;
+  if (d.kind === "textSearchDictionary") {
+    const want = (d.fields.options ?? {}) as Record<string, string>;
+    const have = (live.fields.options ?? {}) as Record<string, string>;
+    const parts = [
+      ...Object.keys(want).filter((k) => have[k] !== want[k]).map((k) => `${quoteIdent(k)} = ${pgString(want[k]!)}`),
+      ...Object.keys(have).filter((k) => !(k in want)).map((k) => quoteIdent(k)),
+    ];
+    return parts.length > 0 ? [step(`ALTER TEXT SEARCH DICTIONARY ${target} (${parts.join(", ")})`, "metadata", "SQLPG305")] : [];
+  }
+  const want = (d.fields.mappings ?? {}) as Record<string, string[]>;
+  const have = (live.fields.mappings ?? {}) as Record<string, string[]>;
+  const written = new Map<string, string[]>();
+  for (const m of (obj.props as unknown as TextSearchConfigurationProps).mappings) for (const t of m.tokens) written.set(t.toLowerCase(), m.dictionaries);
+  const group = (tokens: string[]): Map<string, string[]> => {
+    const out = new Map<string, string[]>();
+    for (const t of tokens) {
+      const key = JSON.stringify(want[t]);
+      out.set(key, [...(out.get(key) ?? []), t]);
+    }
+    return out;
+  };
+  const dropped = Object.keys(have).filter((t) => !(t in want));
+  const added = Object.keys(want).filter((t) => !(t in have));
+  const changed = Object.keys(want).filter((t) => t in have && JSON.stringify(have[t]) !== JSON.stringify(want[t]));
+  const names = (tokens: string[]) => tokens.map(quoteIdent).join(", ");
+  const out: PgStep[] = [];
+  if (dropped.length > 0) out.push(step(`ALTER TEXT SEARCH CONFIGURATION ${target} DROP MAPPING FOR ${names(dropped)}`, "metadata", "SQLPG305"));
+  for (const [verb, tokens] of [["ALTER", changed], ["ADD", added]] as const) {
+    for (const members of group(tokens).values()) out.push(step(`ALTER TEXT SEARCH CONFIGURATION ${target} ${verb} MAPPING FOR ${names(members)} WITH ${written.get(members[0]!)!.join(", ")}`, "metadata", "SQLPG305"));
+  }
+  return out;
+}
+
+/**
+ * A foreign table's changes in place (SQLPG306), as ALTER FOREIGN TABLE
+ * makes them: ADD and DROP COLUMN, a column's type, default, NOT NULL and
+ * OPTIONS, CHECK constraints added and dropped, and the table's OPTIONS.
+ * A column added with options gets them in an ALTER of its own, since ADD
+ * COLUMN has no OPTIONS clause.
+ */
+function foreignTableSteps(c: PgChange, obj: DeclaredPgObject, live: PgDiffObject, alterKind: string): PgStep[] {
+  const d = obj.canonical;
+  const props = obj.props as unknown as ForeignTableProps;
+  const make = (sql: string) => step(sql, "metadata", "SQLPG306");
+  if (c.field === "options") {
+    const clause = optionsClause(d.fields.options, live.fields.options);
+    return clause ? [make(`${alterKind} ${clause}`)] : [];
+  }
+  if (c.field.startsWith("constraints.")) {
+    const key = c.field.slice("constraints.".length);
+    // A declared CHECK the server lacks is added; one it has and the declaration dropped is dropped by the server's name.
+    if (c.before === undefined) {
+      const i = d.constraints.findIndex((a) => (a.name ?? a.kind.toLowerCase()) === key && !live.constraints.some((b) => sameConstraint(a, b)));
+      return i >= 0 && props.checks[i] ? [make(`${alterKind} ADD ${constraintSql("CHECK", props.checks[i]!)}`)] : [];
+    }
+    return [make(`${alterKind} DROP CONSTRAINT ${quoteIdent(key)}`)];
+  }
+  const m = COLUMN_FIELD.exec(c.field);
+  if (!m) return [];
+  const name = m[1]!;
+  const prop = m[2];
+  const def = props.columns.find((x) => x.name === name);
+  const column = `${alterKind} ALTER COLUMN ${quoteIdent(name)}`;
+  const liveColumn = live.columns.find((x) => x.name === name);
+  if (prop === undefined) {
+    if (!def) return [make(`${alterKind} DROP COLUMN ${quoteIdent(name)}`)];
+    const options = optionsClause(def.options, undefined);
+    return [make(`${alterKind} ADD COLUMN ${columnDefinition(def)}`), ...(options ? [make(`${column} ${options}`)] : [])];
+  }
+  if (!def) return [];
+  switch (prop) {
+    case "type":
+    case "collate":
+      return def.type ? [make(`${column} TYPE ${def.type}${def.collate ? ` COLLATE ${def.collate}` : prop === "collate" ? ' COLLATE "default"' : ""}`)] : [];
+    case "default":
+      return [make(def.default !== undefined ? `${column} SET DEFAULT ${def.default}` : `${column} DROP DEFAULT`)];
+    case "notNull":
+      return [make(`${column} ${def.notNull ? "SET" : "DROP"} NOT NULL`)];
+    case "options": {
+      const clause = optionsClause(def.options, liveColumn?.options);
+      return clause ? [make(`${column} ${clause}`)] : [];
+    }
+    default:
+      return [];
+  }
+}
+
 /**
  * The statements for an object that exists on the server, change by change.
  * `live` is the server's definition, matched to the declaration (a renamed
@@ -667,13 +791,23 @@ export function alterSteps(
       steps.push(...createSteps(obj, opts.marker, { cls: c.class, rule: c.rule }));
       continue;
     }
+    if (c.rule === "SQLPG306") {
+      steps.push(...foreignTableSteps(c, obj, live, alterKind));
+      continue;
+    }
+    if (d.kind === "foreignTable" && c.rule === "SQLPG216" && /^constraints\.[^.]+\.comment$/.test(c.field)) {
+      const name = c.field.split(".")[1]!;
+      const declared = d.constraints.find((a) => (a.name ?? a.kind.toLowerCase()) === name);
+      steps.push(step(`COMMENT ON CONSTRAINT ${quoteIdent(name)} ON ${target} IS ${declared?.comment === undefined ? "NULL" : pgString(declared.comment)}`, c.class, c.rule));
+      continue;
+    }
     if (c.field.startsWith("constraints.")) {
       if (!constraintsDone) steps.push(...constraintSteps(obj, live, notNullChecks));
       constraintsDone = true;
       continue;
     }
     const col = COLUMN_FIELD.exec(c.field);
-    if (col && (d.kind === "table")) {
+    if (col && (d.kind === "table" || d.kind === "foreignTable")) {
       const name = col[1]!;
       const prop = col[2];
       const def = columns.get(name);
@@ -770,6 +904,12 @@ export function alterSteps(
       case "SQLPG303":
         if (!steps.some((s) => s.rule === "SQLPG303")) steps.push(...alteredSteps(d, live, target));
         break;
+      case "SQLPG304":
+        if (!steps.some((s) => s.rule === "SQLPG304")) steps.push(step(`ALTER OPERATOR ${target} SET (${operatorSetClauses(d, changes.filter((x) => x.rule === "SQLPG304")).join(", ")})`, c.class, c.rule));
+        break;
+      case "SQLPG305":
+        if (!steps.some((s) => s.rule === "SQLPG305")) steps.push(...textSearchSteps(obj, live, target));
+        break;
       case "SQLPG250":
       case "SQLPG280":
       case "SQLPG302":
@@ -955,12 +1095,20 @@ const DROP_ORDER: Record<CanonicalKind, number> = {
   view: 2,
   index: 3,
   table: 4,
+  // A foreign table reads a foreign server (below) and a type; a view on it goes before.
+  foreignTable: 4,
   sequence: 5,
   // An event trigger and a cast before the function they call; an aggregate before its functions.
   eventTrigger: 5.5,
   cast: 5.5,
   aggregate: 5.5,
   operator: 5.5,
+  // A class names operators and functions; a family goes after its classes.
+  operatorClass: 5.2,
+  operatorFamily: 5.3,
+  // A configuration maps token types to dictionaries, so it goes first.
+  textSearchConfiguration: 5.7,
+  textSearchDictionary: 5.8,
   // A server before its wrapper, a wrapper before the handler function it calls.
   foreignServer: 5.5,
   foreignDataWrapper: 5.6,