@intentius/chant-lexicon-sql 0.114.1 → 0.116.0

package/src/postgres/plan/normalize.ts

@@ -27,7 +27,15 @@
  *   column's columns are `NOT NULL` whether or not that is written;
  * - an identity column's or a sequence's options at their defaults are left
  *   out; storage parameters compare as a map;
- * - an index's access method defaults to `btree`.
+ * - an index's access method defaults to `btree`;
+ * - a function's or procedure's parameter types drop their modifiers (the
+ *   catalog keeps none: `varchar(20)` is `character varying`), a parameter's
+ *   mode is `in` unless written, its attributes at their defaults (VOLATILE,
+ *   CALLED ON NULL INPUT, SECURITY INVOKER, PARALLEL UNSAFE, COST 100 or 1,
+ *   ROWS 1000 or 0) are left out, and its body is compared as written, since
+ *   the server keeps it verbatim;
+ * - a trigger's events compare as a set, `UPDATE OF` columns sorted, and its
+ *   arguments as the strings the catalog stores.
  *
  * What the rules cannot see (a view's `SELECT *`, which the server expands, or
  * an expression it parenthesizes) is asked of the live server itself when a
@@ -52,10 +60,13 @@ import type {
   IndexProps,
   KeyDef,
   SchemaProps,
+  RoutineProps,
   SequenceProps,
   TableProps,
+  TriggerProps,
   ViewProps,
 } from "../entities";
+import { stringValue } from "../entities";
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -178,7 +189,7 @@ function castEnd(sig: readonly Token[], i: number): { end: number; type: string
   return { end: j, type: words.join("").toLowerCase() };
 }
 
-const isLiteral = (t: Token | undefined): boolean => t !== undefined && (t.kind === "string" || t.kind === "number");
+const isLiteral = (t: Token | undefined): boolean => t !== undefined && (t.kind === "string" || t.kind === "number" || (t.kind === "ident" && t.text.toUpperCase() === "NULL"));
 
 /** One token's canonical text. */
 function tokenText(t: Token): string {
@@ -308,12 +319,18 @@ export interface CanonicalConstraint {
   comment?: string;
 }
 
-export type CanonicalKind = "schema" | "table" | "index" | "view" | "materializedView" | "sequence" | "enum" | "domain" | "extension";
+export type CanonicalKind = "schema" | "table" | "index" | "view" | "materializedView" | "sequence" | "enum" | "domain" | "extension" | "function" | "procedure" | "trigger";
 
 export interface CanonicalPgObject {
   kind: CanonicalKind;
   schema?: string;
   name: string;
+  /**
+   * What tells the object from another of the same name: a routine's input
+   * parameter types, `(integer,text)`; a trigger's table, ` ON app.users`.
+   * Written as SQL names the object after its name.
+   */
+  signature?: string;
   /** Everything else that is compared, by field, each field canonical. */
   fields: Record<string, unknown>;
   columns: CanonicalColumn[];
@@ -330,6 +347,9 @@ const kindOf: Record<string, CanonicalKind> = {
   "Postgres::Enum": "enum",
   "Postgres::Domain": "domain",
   "Postgres::Extension": "extension",
+  "Postgres::Function": "function",
+  "Postgres::Procedure": "procedure",
+  "Postgres::Trigger": "trigger",
 };
 
 const comment = (c: string | undefined): string | undefined => {
@@ -390,6 +410,127 @@ const keyBody = (kind: string, k: KeyDef) =>
     .filter(Boolean)
     .join(" ");
 
+/** The pseudo-types (`pg_type.typtype = 'p'`), in `pg_catalog`: a routine's parameter or result, never a column's. */
+const PSEUDO_TYPES = new Set([
+  "any", "anyarray", "anycompatible", "anycompatiblearray", "anycompatiblemultirange", "anycompatiblenonarray", "anycompatiblerange",
+  "anyelement", "anyenum", "anymultirange", "anynonarray", "anyrange", "cstring", "event_trigger", "fdw_handler", "index_am_handler",
+  "internal", "language_handler", "pg_ddl_command", "record", "table_am_handler", "trigger", "tsm_handler", "unknown", "void",
+]);
+
+/** A parameter's or result's type as the catalog keeps it: canonical, its modifiers dropped (`varchar(20)` is `character varying`). */
+export function canonicalArgType(text: string, defaultSchema: string): string {
+  const m = /^\s*(?:pg_catalog\s*\.\s*)?([A-Za-z_]+)\s*((?:\[\s*\]\s*)*)$/.exec(text);
+  if (m && PSEUDO_TYPES.has(m[1]!.toLowerCase())) return `${m[1]!.toLowerCase()}${"[]".repeat((m[2]!.match(/\[/g) ?? []).length)}`;
+  return canonicalType(text, defaultSchema)!.replace(/\([^()]*\)/g, "");
+}
+
+/** A routine's input parameters: those whose mode is `in`, `inout` or `variadic`. */
+const isInput = (a: { mode: string }) => a.mode !== "out";
+
+/** A routine's identity among its overloads: its input parameter types, `(integer,text)`. */
+export function routineSignature(p: Pick<RoutineProps, "args">, defaultSchema: string): string {
+  return `(${p.args.filter(isInput).map((a) => canonicalArgType(a.type, defaultSchema)).join(",")})`;
+}
+
+/** The result a function declares, or the one its OUT parameters give it: one OUT is its type, several are `record`. */
+function routineResult(p: RoutineProps, defaultSchema: string): string | undefined {
+  if (p.returnsTable) return `table(${p.returnsTable.map((c) => `${quoteIdent(c.name)} ${canonicalArgType(c.type, defaultSchema)}`).join(",")})`;
+  if (p.returns !== undefined) {
+    const m = /^setof\s+(.*)$/is.exec(p.returns.trim());
+    return m ? `setof ${canonicalArgType(m[1]!, defaultSchema)}` : canonicalArgType(p.returns, defaultSchema);
+  }
+  const outs = p.args.filter((a) => a.mode === "out" || a.mode === "inout");
+  if (outs.length === 1) return canonicalArgType(outs[0]!.type, defaultSchema);
+  if (outs.length > 1) return "record";
+  return undefined;
+}
+
+/** A `SET` value as compared: each item unquoted, a bare word folded, `TO` and `=` alike. */
+function canonicalSetting(value: string): string {
+  const items: string[] = [];
+  let tokens: Token[];
+  try {
+    tokens = tokenizeText(value, 0).filter((t) => !isTrivia(t));
+  } catch {
+    return value.trim();
+  }
+  let sign = "";
+  for (const t of tokens) {
+    if (t.kind === "punct" && t.text === ",") continue;
+    if (t.kind === "op" && (t.text === "-" || t.text === "+")) {
+      sign = t.text === "-" ? "-" : "";
+      continue;
+    }
+    if (t.kind === "string") items.push(stringValue(t.text) ?? t.text);
+    else if (t.kind === "qident") items.push(identValue(t));
+    else items.push(`${sign}${t.kind === "ident" ? t.text.toLowerCase() : t.text}`);
+    sign = "";
+  }
+  return items.join(", ");
+}
+
+/** The canonical fields of a function or procedure. */
+function routineFields(kind: "function" | "procedure", p: RoutineProps, defaultSchema: string, fields: Record<string, unknown>): void {
+  const lang = (p.language ?? "sql").toLowerCase();
+  fields.args = p.args.map((a) =>
+    [a.mode, a.name ? quoteIdent(a.name) : "", canonicalArgType(a.type, defaultSchema), a.default !== undefined ? `default ${canonicalExpr(a.default)}` : ""].filter(Boolean).join(" "),
+  );
+  fields.language = lang;
+  // Line endings aside, the body is what the server keeps and prints back.
+  fields.body = p.body.replace(/\r\n/g, "\n");
+  fields.link = p.link;
+  fields.securityDefiner = p.securityDefiner === true;
+  fields.set = p.set && Object.keys(p.set).length > 0
+    ? Object.fromEntries(Object.entries(p.set).map(([k, v]) => [k.toLowerCase(), canonicalSetting(v)]).sort(([a], [b]) => (a! < b! ? -1 : 1)))
+    : undefined;
+  fields.transform = p.transform ? canonicalExpr(p.transform) : undefined;
+  if (kind === "procedure") return;
+  const result = routineResult(p, defaultSchema);
+  const setReturning = result !== undefined && /^(setof |table\()/.test(result);
+  fields.returns = result;
+  fields.volatility = p.volatility && p.volatility !== "volatile" ? p.volatility : undefined;
+  fields.strict = p.strict === true;
+  fields.leakproof = p.leakproof === true;
+  fields.parallel = p.parallel && p.parallel !== "unsafe" ? p.parallel : undefined;
+  const defaultCost = lang === "c" || lang === "internal" ? 1 : 100;
+  fields.cost = p.cost !== undefined && Number(p.cost) !== defaultCost ? String(Number(p.cost)) : undefined;
+  const defaultRows = setReturning ? 1000 : 0;
+  fields.rows = p.rows !== undefined && Number(p.rows) !== defaultRows ? String(Number(p.rows)) : undefined;
+  fields.support = p.support ? canonicalName(p.support, "pg_catalog").replace(/^pg_catalog\./, "") : undefined;
+  fields.window = p.window === true;
+}
+
+/** The order the catalog prints a trigger's events in. */
+const EVENT_ORDER = ["insert", "delete", "update", "truncate"];
+
+/** A trigger argument as the catalog stores it: a string. */
+function triggerArg(a: string): string {
+  const t = a.trim();
+  if (/^'/.test(t) || /^[Ee]'/.test(t) || /^\$/.test(t)) return stringValue(t) ?? t;
+  if (/^"/.test(t)) return identValue(t);
+  if (/^-?[0-9.]/.test(t)) return t.replace(/\s+/g, "");
+  return t.toLowerCase();
+}
+
+function triggerFields(p: TriggerProps, defaultSchema: string, fields: Record<string, unknown>): void {
+  fields.table = canonicalName(p.tableName, defaultSchema);
+  fields.constraint = p.constraint === true;
+  fields.timing = p.timing;
+  fields.events = [...p.events]
+    .sort((a, b) => EVENT_ORDER.indexOf(a.event) - EVENT_ORDER.indexOf(b.event))
+    .map((e) => (e.columns && e.columns.length > 0 ? `${e.event} of ${[...e.columns].sort().map(quoteIdent).join(",")}` : e.event));
+  fields.forEach = p.forEach;
+  fields.when = canonicalExpr(p.when);
+  fields.function = canonicalName(p.functionName, defaultSchema);
+  fields.args = p.args.length > 0 ? p.args.map(triggerArg) : undefined;
+  fields.from = p.from ? canonicalName(p.from, defaultSchema) : undefined;
+  fields.deferrable = p.deferrable === true;
+  fields.initiallyDeferred = p.initiallyDeferred === true;
+  fields.referencing = p.referencing && (p.referencing.old || p.referencing.new)
+    ? [p.referencing.old ? `old table as ${quoteIdent(p.referencing.old)}` : "", p.referencing.new ? `new table as ${quoteIdent(p.referencing.new)}` : ""].filter(Boolean).join(" ")
+    : undefined;
+}
+
 /**
  * A definition in canonical form. `props` is an entity's props, declared or
  * parsed from what the server printed; `defaultSchema` qualifies a bare name.
@@ -398,7 +539,7 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
   const kind = kindOf[entityType];
   if (!kind) throw new Error(`not a Postgres entity type: ${entityType}`);
   const schemaOf = (p: { schema?: string }) => (kind === "schema" || kind === "extension" ? undefined : (p.schema ?? defaultSchema));
-  const base = { kind, schema: schemaOf(props as { schema?: string }), name: String(props.name) };
+  const base: Pick<CanonicalPgObject, "kind" | "schema" | "name" | "signature"> = { kind, schema: schemaOf(props as { schema?: string }), name: String(props.name) };
   const fields: Record<string, unknown> = { comment: comment(props.comment as string | undefined) };
   const columns: CanonicalColumn[] = [];
   const constraints: CanonicalConstraint[] = [];
@@ -418,6 +559,19 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
     case "enum":
       fields.labels = (props as unknown as EnumProps).labels;
       break;
+    case "function":
+    case "procedure": {
+      const p = props as unknown as RoutineProps;
+      base.signature = routineSignature(p, defaultSchema);
+      routineFields(kind, p, defaultSchema, fields);
+      break;
+    }
+    case "trigger": {
+      const p = props as unknown as TriggerProps;
+      triggerFields(p, defaultSchema, fields);
+      base.signature = ` ON ${String(fields.table)}`;
+      break;
+    }
     case "domain": {
       const p = props as unknown as DomainProps;
       fields.dataType = canonicalType(p.dataType, defaultSchema);

package/src/postgres/plan/rules.ts

@@ -270,6 +270,42 @@ export const PG_CLASSIFIER_RULES = {
   ),
   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`),
+  SQLPG280: rule(
+    "SQLPG280",
+    "metadata",
+    "Replace a function's or procedure's definition",
+    "CREATE OR REPLACE FUNCTION (or PROCEDURE) replaces the body and attributes in the catalog; it locks no table, and a call already running finishes with the old definition. The parameter types, the result and the input parameters' names have to stay the same.",
+    `${DOCS}/sql-createfunction.html`,
+  ),
+  SQLPG281: rule(
+    "SQLPG281",
+    "metadata",
+    "Drop and create a function or procedure",
+    "CREATE OR REPLACE refuses a change of the result type, the output parameters, an input parameter's name, a removed parameter default or the routine's kind: the routine is dropped and created in one transaction. Nothing on the server depends on it (a view, a trigger, a column default would make the DROP fail).",
+    `${DOCS}/sql-createfunction.html`,
+  ),
+  SQLPG282: rule(
+    "SQLPG282",
+    "expand",
+    "Change a function's result or parameters while other objects depend on it",
+    "DROP FUNCTION refuses while a view, a trigger, a column default or another routine depends on the function, and CREATE OR REPLACE cannot make this change. Create the new definition under a new name (or signature), move what depends on it, then drop the old.",
+    `${DOCS}/sql-dropfunction.html`,
+  ),
+  SQLPG283: rule(
+    "SQLPG283",
+    "metadata",
+    "Create a trigger on an existing table",
+    "CREATE TRIGGER takes SHARE ROW EXCLUSIVE on its table: writes and other schema changes to the table wait until the transaction commits, but no row is read. The applier's lock_timeout bounds the wait behind long-running transactions.",
+    `${DOCS}/sql-createtrigger.html`,
+  ),
+  SQLPG284: rule(
+    "SQLPG284",
+    "metadata",
+    "Change a trigger",
+    "CREATE OR REPLACE TRIGGER (14 and later) replaces the trigger under SHARE ROW EXCLUSIVE on its table. A constraint trigger has no OR REPLACE, and a trigger moved to another table is another trigger: each is dropped (ACCESS EXCLUSIVE, briefly) and created in one transaction.",
+    `${DOCS}/sql-createtrigger.html`,
+  ),
+  SQLPG285: rule("SQLPG285", "drop", "Drop a trigger", "DROP TRIGGER takes ACCESS EXCLUSIVE on its table, briefly; no row is read or lost, and the table's writes no longer fire it.", `${DOCS}/sql-droptrigger.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

@@ -28,6 +28,8 @@ export interface PgDiffObject extends CanonicalPgObject {
   foreign?: string;
   /** The export name, against a server. */
   exportName?: string;
+  /** What depends on a routine on the server (a view, a trigger, a default), which a DROP FUNCTION would refuse. */
+  dependents?: string[];
 }
 
 export type PgSchemaObject = Keyed<PgDiffObject>;
@@ -94,10 +96,22 @@ export function pgSchemaFromBuildFile(path: string, defaultSchema = "public"): P
   return pgSchemaFromBuildOutput(readFileSync(path, "utf-8"), defaultSchema);
 }
 
-/** The identity an object has on a server: its kind's namespace and its qualified name. */
-export function qualifiedKey(o: { kind: string; schema?: string; name: string }): string {
-  const space = o.kind === "schema" ? "schema" : o.kind === "extension" ? "extension" : o.kind === "enum" || o.kind === "domain" ? "type" : "relation";
-  return `${space} ${o.schema ? `${o.schema}.` : ""}${o.name}`;
+/**
+ * The namespace an object's name is unique in: relations (tables, views,
+ * sequences, indexes) share one per schema, types and domains another,
+ * functions and procedures a third (told apart by their parameter types),
+ * and a trigger's name is unique on its table.
+ */
+export function pgNamespace(kind: string): string {
+  if (kind === "schema" || kind === "extension" || kind === "trigger") return kind;
+  if (kind === "enum" || kind === "domain") return "type";
+  if (kind === "function" || kind === "procedure") return "routine";
+  return "relation";
+}
+
+/** The identity an object has on a server: its kind's namespace, its qualified name, and its signature where it has one. */
+export function qualifiedKey(o: { kind: string; schema?: string; name: string; signature?: string }): string {
+  return `${pgNamespace(o.kind)} ${o.schema ? `${o.schema}.` : ""}${o.name}${o.signature ?? ""}`;
 }
 
 /** The declared objects re-keyed by qualified name, the only identity a server has. */
@@ -107,8 +121,13 @@ export function keyedByQualifiedName(objects: readonly PgSchemaObject[]): PgSche
 
 /** What a server holds, in the diff's form, keyed by qualified name. */
 export function pgSchemaFromLive(live: readonly LivePgObject[], defaultSchema: string): PgSchemaObject[] {
-  return live.map((o) => {
-    const canonical = { ...diffObject(o.type, o.statement, defaultSchema), ...(o.foreign ? { foreign: o.foreign } : {}) };
+  // A routine with a SQL-standard body is not one a declaration can hold (`../parser.ts`): never chant's, never compared.
+  return live.filter((o) => !o.unsupported).map((o) => {
+    const canonical = {
+      ...diffObject(o.type, o.statement, defaultSchema),
+      ...(o.foreign ? { foreign: o.foreign } : {}),
+      ...(o.dependents && o.dependents.length > 0 ? { dependents: o.dependents } : {}),
+    };
     return { key: qualifiedKey(canonical), canonical };
   });
 }

package/src/postgres/plan/server-normalize.ts

@@ -88,6 +88,26 @@ async function tableExpressions(client: PostgresClient, o: CanonicalPgObject, de
   });
 }
 
+/** A trigger's WHEN condition as the server prints it, canonical. */
+async function triggerWhen(client: PostgresClient, o: CanonicalPgObject, defaultSchema: string): Promise<string | undefined> {
+  const when = o.fields.when;
+  // An INSTEAD OF trigger, on a view, takes no WHEN.
+  if (typeof when !== "string" || o.fields.timing === "instead of") return undefined;
+  const events = ((o.fields.events as string[] | undefined) ?? []).map((e) => e.replace(/^(\w+)( of )?/, (_m, ev: string, of?: string) => `${ev.toUpperCase()}${of ? " OF " : ""}`));
+  return rolledBack(client, defaultSchema, async () => {
+    await client.query(`CREATE TEMP TABLE chant_normalize (LIKE ${String(o.fields.table)})`);
+    await client.query(`CREATE FUNCTION pg_temp.chant_normalize() RETURNS trigger LANGUAGE plpgsql AS 'BEGIN RETURN NULL; END'`);
+    await client.query(
+      `CREATE TRIGGER chant_normalize ${String(o.fields.timing).toUpperCase()} ${events.join(" OR ")} ON pg_temp.chant_normalize ` +
+        `FOR EACH ${o.fields.forEach === "row" ? "ROW" : "STATEMENT"} WHEN (${when}) EXECUTE FUNCTION pg_temp.chant_normalize()`,
+    );
+    await emptyPath(client);
+    const [row] = await client.query<Row>(`SELECT pg_catalog.pg_get_triggerdef(t.oid, true) AS def FROM pg_catalog.pg_trigger t WHERE t.tgrelid = 'pg_temp.chant_normalize'::pg_catalog.regclass`);
+    const m = / WHEN \((.*)\) EXECUTE (?:FUNCTION|PROCEDURE) /s.exec(String(row?.def ?? ""));
+    return m ? canonicalExpr(m[1]!) : undefined;
+  });
+}
+
 /**
  * The declared object with its expressions in the server's own printing,
  * when the server answers; the object unchanged otherwise. Only the
@@ -99,6 +119,10 @@ export async function serverNormalized<T extends CanonicalPgObject & { outputs?:
     // A declared column list names the outputs; otherwise the server's names do (`SELECT *` expanded).
     return q === undefined ? o : { ...o, fields: { ...o.fields, query: q.query }, ...(o.fields.columns === undefined ? { outputs: q.outputs } : {}) };
   }
+  if (o.kind === "trigger") {
+    const when = await triggerWhen(client, o, defaultSchema);
+    return when === undefined ? o : { ...o, fields: { ...o.fields, when } };
+  }
   if (o.kind === "table") {
     const e = await tableExpressions(client, o, defaultSchema);
     if (!e) return o;

package/src/postgres/routines.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Functions, procedures and triggers (#3680): what the tags parse and refuse,
+ * how a change to each is classified and made, and how an import writes them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { func, procedure, schema, SqlTemplateError, table, trigger } from "./entities";
+import { diffObject, keyedByQualifiedName, pgSchemaFromLive, type PgSchemaObject } from "./plan/schema";
+import { diffPgSchemas, matchPgObjects } from "./plan/diff";
+import { alterSteps, dropStatement } from "./apply/statements";
+import { declaredObjects } from "./apply/apply";
+import type { LivePgObject } from "./live/catalog";
+import { objectsToIR } from "./import/ir";
+import { PostgresGenerator } from "./import/generator";
+
+const app = schema`CREATE SCHEMA app`;
+const users = table`CREATE TABLE ${app}.users (id bigint PRIMARY KEY, email text, updated_at timestamptz)`;
+
+describe("the tags", () => {
+  test("a function: its signature, attributes and body as written; an interpolation in the body is a reference", () => {
+    const count = func`
+      CREATE FUNCTION ${app}.user_count(min_id int = 0, OUT n bigint)
+      LANGUAGE sql STABLE STRICT PARALLEL SAFE SET search_path = ${app}
+      AS $$ SELECT count(*) FROM ${users} WHERE ${users.columns.id} >= min_id $$;
+      COMMENT ON FUNCTION ${app}.user_count(int) IS 'Users'`;
+    expect(count.entityType).toBe("Postgres::Function");
+    expect(count.sqlName).toBe("app.user_count");
+    expect(count.props).toMatchObject({
+      schema: "app",
+      name: "user_count",
+      args: [
+        { mode: "in", name: "min_id", type: "int", default: "0" },
+        { mode: "out", name: "n", type: "bigint" },
+      ],
+      language: "sql",
+      volatility: "stable",
+      strict: true,
+      parallel: "safe",
+      set: { search_path: "app" },
+      body: " SELECT count(*) FROM app.users WHERE id >= min_id ",
+      comment: "Users",
+    });
+    expect(count.dependsOn).toContain(users);
+    expect(count.props.reads).toEqual([users]);
+  });
+
+  test("a procedure and a trigger", () => {
+    const archive = procedure`CREATE PROCEDURE ${app}.archive(IN before bigint, INOUT n int DEFAULT NULL) LANGUAGE plpgsql AS 'BEGIN n := 0; END'`;
+    expect(archive.props).toMatchObject({ args: [{ mode: "in", name: "before" }, { mode: "inout", name: "n", default: "NULL" }], body: "BEGIN n := 0; END" });
+    const touch = func`CREATE FUNCTION ${app}.touch() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN NEW.updated_at := now(); RETURN NEW; END $$`;
+    const t = trigger`CREATE TRIGGER users_touch BEFORE INSERT OR UPDATE OF email ON ${users} FOR EACH ROW WHEN (NEW.email IS NOT NULL) EXECUTE FUNCTION ${touch}('x', 1)`;
+    expect(t.entityType).toBe("Postgres::Trigger");
+    expect(t.props).toMatchObject({
+      schema: "app",
+      name: "users_touch",
+      timing: "before",
+      events: [{ event: "insert" }, { event: "update", columns: ["email"] }],
+      tableName: "app.users",
+      forEach: "row",
+      when: "NEW.email IS NOT NULL",
+      functionName: "app.touch",
+      args: ["'x'", "1"],
+    });
+    expect(t.dependsOn).toEqual([users, touch]);
+  });
+
+  test("a SQL-standard body, SET FROM CURRENT and a qualified trigger name are refused", () => {
+    expect(() => func`CREATE FUNCTION app.f(a int) RETURNS int LANGUAGE sql RETURN a + 1`).toThrow(/SQL-standard body/);
+    expect(() => func`CREATE FUNCTION app.f() RETURNS int LANGUAGE sql BEGIN ATOMIC SELECT 1; END`).toThrow(/SQL-standard body/);
+    expect(() => func`CREATE FUNCTION app.f() RETURNS int LANGUAGE sql SET search_path FROM CURRENT AS 'select 1'`).toThrow(/FROM CURRENT/);
+    expect(() => procedure`CREATE PROCEDURE app.p() LANGUAGE sql STABLE AS 'select 1'`).toThrow(/not an attribute of a procedure/);
+    expect(() => trigger`CREATE TRIGGER app.t BEFORE INSERT ON app.users EXECUTE FUNCTION app.f()`).toThrow(/not schema-qualified/);
+    expect(() => func`CREATE TABLE app.t (a int)`).toThrow(SqlTemplateError);
+  });
+});
+
+// ── Classifying and making changes ─────────────────────────────────────
+
+const F = "Postgres::Function";
+const TR = "Postgres::Trigger";
+const live = (type: string, statement: string, extra: Partial<LivePgObject> = {}) => pgSchemaFromLive([{ type, statement, name: "", oid: "1", ...extra } as LivePgObject], "public");
+const declared = (type: string, ddl: string): PgSchemaObject[] => keyedByQualifiedName([{ key: "x", canonical: { ...diffObject(type, ddl, "public"), exportName: "x" } }]);
+const rules = (type: string, before: string, after: string, extra: Partial<LivePgObject> = {}) =>
+  diffPgSchemas(live(type, before, extra), declared(type, after)).changes.map((c) => [c.field, c.rule]);
+
+const FN = (body: string, returns = "integer", args = "a integer") => `CREATE FUNCTION app.f(${args}) RETURNS ${returns} LANGUAGE sql AS $$ ${body} $$`;
+const SERVER_FN = "CREATE OR REPLACE FUNCTION app.f(a integer)\n RETURNS integer\n LANGUAGE sql\nAS $function$ select a $function$\n";
+
+describe("the classifier", () => {
+  test("the server's printing of a function is the declaration's", () => {
+    expect(rules(F, SERVER_FN, FN("select a", "int", "a int"))).toEqual([]);
+  });
+
+  test("a new body or attribute is CREATE OR REPLACE; a new result is drop and create, or expand and contract when something depends on it", () => {
+    expect(rules(F, SERVER_FN, FN("select a + 1"))).toEqual([["body", "SQLPG280"]]);
+    expect(rules(F, SERVER_FN, FN("select a", "bigint"))).toEqual([["returns", "SQLPG281"]]);
+    expect(rules(F, SERVER_FN, FN("select a", "integer", "b integer"))).toEqual([["args", "SQLPG281"]]);
+    expect(rules(F, SERVER_FN, FN("select a", "bigint"), { dependents: ["view app.v"] })).toEqual([["returns", "SQLPG282"]]);
+  });
+
+  test("a trigger: created on an existing table under SHARE ROW EXCLUSIVE, changed in place, dropped", () => {
+    const T1 = "CREATE TRIGGER t BEFORE UPDATE ON app.users FOR EACH ROW EXECUTE FUNCTION app.touch()";
+    const T2 = "CREATE TRIGGER t BEFORE INSERT OR UPDATE ON app.users FOR EACH ROW EXECUTE FUNCTION app.touch()";
+    expect(diffPgSchemas([], declared(TR, T1)).changes.map((c) => c.rule)).toEqual(["SQLPG283"]);
+    expect(rules(TR, T1, T2)).toEqual([["events", "SQLPG284"]]);
+    expect(diffPgSchemas(live(TR, T1), []).changes.map((c) => [c.rule, c.class])).toEqual([["SQLPG285", "drop"]]);
+  });
+});
+
+function steps(type: string, liveDdl: string, declaredDdl: string): string[] {
+  const [obj] = declaredObjects(JSON.stringify({ dialect: "postgres", objects: [{ export: "x", type, ddl: declaredDdl, dependsOn: [] }] }));
+  const after = keyedByQualifiedName([{ key: "x", canonical: obj!.canonical }]);
+  const before = live(type, liveDdl);
+  const m = matchPgObjects(before, after).find((x) => x.kind === "matched")!;
+  return alterSteps(obj!, m.before!.canonical, diffPgSchemas(before, after).changes, { major: 18 }).steps.map((s) => s.sql);
+}
+
+describe("the statements", () => {
+  test("OR REPLACE, or a drop and a create named by the parameter types", () => {
+    expect(steps(F, SERVER_FN, FN("select a + 1"))).toEqual(["CREATE OR REPLACE FUNCTION app.f(a integer) RETURNS integer LANGUAGE sql AS $$ select a + 1 $$"]);
+    const recreate = steps(F, SERVER_FN, FN("select a", "bigint"));
+    expect(recreate[0]).toBe("DROP FUNCTION app.f(integer)");
+    expect(recreate[1]).toBe("CREATE FUNCTION app.f(a integer) RETURNS bigint LANGUAGE sql AS $$ select a $$");
+    expect(recreate[2]).toMatch(/^COMMENT ON FUNCTION app\.f\(integer\) IS /);
+    expect(dropStatement("procedure", "app", "p", "(integer,text)").sql).toBe("DROP PROCEDURE app.p(integer,text)");
+  });
+
+  test("a trigger is replaced in place; a constraint trigger is dropped and created", () => {
+    const T1 = "CREATE TRIGGER t BEFORE UPDATE ON app.users FOR EACH ROW EXECUTE FUNCTION app.touch()";
+    expect(steps(TR, T1, T1.replace("UPDATE", "INSERT"))).toEqual(["CREATE OR REPLACE TRIGGER t BEFORE INSERT ON app.users FOR EACH ROW EXECUTE FUNCTION app.touch()"]);
+    const C1 = "CREATE CONSTRAINT TRIGGER t AFTER UPDATE ON app.users DEFERRABLE FOR EACH ROW EXECUTE FUNCTION app.touch()";
+    expect(steps(TR, C1, C1.replace("UPDATE", "INSERT")).slice(0, 2)).toEqual(["DROP TRIGGER t ON app.users", C1.replace("UPDATE", "INSERT")]);
+    expect(dropStatement("trigger", "app", "t", " ON app.users").sql).toBe("DROP TRIGGER t ON app.users");
+  });
+});
+
+describe("importing", () => {
+  test("functions and triggers are written as func and trigger declarations, their references interpolated", () => {
+    const content = new PostgresGenerator().generate(
+      objectsToIR([
+        { type: "Postgres::Table", schema: "app", name: "users", ddl: "CREATE TABLE app.users (\n    id bigint\n)" },
+        { type: "Postgres::Function", schema: "app", name: "touch", ddl: "CREATE OR REPLACE FUNCTION app.touch()\n RETURNS trigger\n LANGUAGE plpgsql\nAS $function$ BEGIN RETURN NEW; END $function$" },
+        { type: "Postgres::Trigger", schema: "app", name: "users_touch", ddl: "CREATE TRIGGER users_touch BEFORE UPDATE ON app.users FOR EACH ROW EXECUTE FUNCTION app.touch()" },
+      ]),
+    )[0]!.content;
+    expect(content).toContain('import { func, table, trigger } from "@intentius/chant-lexicon-sql/postgres";');
+    expect(content).toContain("export const touch = func`");
+    expect(content).toContain("ON ${users} FOR EACH ROW EXECUTE FUNCTION ${touch}()");
+  });
+});

package/src/postgres.ts

@@ -15,6 +15,9 @@ export {
   type,
   domain,
   extension,
+  func,
+  procedure,
+  trigger,
   literal,
   SqlLiteral,
   SqlTemplateError,
@@ -33,6 +36,9 @@ export {
   type PostgresEnum,
   type PostgresDomain,
   type PostgresExtension,
+  type PostgresFunction,
+  type PostgresProcedure,
+  type PostgresTrigger,
   type ColumnDef,
   type KeyDef,
   type CheckDef,
@@ -46,6 +52,11 @@ export {
   type EnumProps,
   type DomainProps,
   type ExtensionProps,
+  type RoutineProps,
+  type RoutineArgDef,
+  type FunctionProps,
+  type ProcedureProps,
+  type TriggerProps,
   type LineageEdge,
 } from "./postgres/entities";
 

package/src/receipts.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "vitest";
+import { environmentOf, receiptDialect, sqlReceiptStore } from "./receipts";
+import type { PostgresClient } from "./postgres/live/client";
+
+const ref = (effect: string) => ({ name: effect, effect, flavor: "existence" as const, inputs: {} });
+
+/** A Postgres client that records each statement and answers the store's catalog reads. */
+function fakePostgres(state: { schema?: boolean; table?: string | null } = {}) {
+  const statements: string[] = [];
+  let schema = state.schema ?? false;
+  let table: string | null | undefined = state.table;
+  const rows = new Map<string, string>();
+  const client: PostgresClient = {
+    async query<T>(sql: string, params: readonly unknown[] = []): Promise<T[]> {
+      statements.push(sql);
+      if (sql.includes("pg_namespace WHERE nspname")) return [{ n: schema ? 1 : 0 }] as T[];
+      if (sql.startsWith("CREATE SCHEMA")) schema = true;
+      if (sql.includes("to_regclass($1) IS NOT NULL AS present")) return [{ present: table !== undefined, comment: table ?? null }] as T[];
+      if (sql.startsWith("CREATE TABLE")) table = null;
+      if (sql.startsWith("COMMENT ON TABLE")) table = sql.slice(sql.indexOf("IS '") + 4, -1);
+      if (sql.startsWith("INSERT INTO")) rows.set(String(params[0]), String(params[2]));
+      if (sql.startsWith("SELECT expectation")) {
+        const v = rows.get(String(params[0]));
+        return (v === undefined ? [] : [{ expectation: v }]) as T[];
+      }
+      return [] as T[];
+    },
+    end: async () => undefined,
+  };
+  return { client, statements, rows };
+}
+
+describe("receiptDialect (#3657)", () => {
+  test("the environment's profile decides, by its URL's scheme", () => {
+    const config = { sql: { profiles: { pg: { url: "postgres://db:5432/app" }, ch: { url: "http://ch:8123" } } } };
+    expect(receiptDialect(config, "pg", {})).toBe("postgres");
+    expect(receiptDialect(config, "ch", {})).toBe("clickhouse");
+  });
+
+  test("with no profile, sql.dialect, then whichever server variable is set", () => {
+    expect(receiptDialect({ sql: { dialect: "postgres" } }, "dev", {})).toBe("postgres");
+    expect(receiptDialect({ sql: { dialect: ["clickhouse"] } }, undefined, { POSTGRES_URL: "postgres://x/y" })).toBe("clickhouse");
+    expect(receiptDialect(undefined, undefined, { POSTGRES_URL: "postgres://x/y" })).toBe("postgres");
+    expect(receiptDialect(undefined, undefined, {})).toBe("clickhouse");
+  });
+});
+
+describe("environmentOf (#3657)", () => {
+  test("the option, then CHANT_ENV, then a literal ownership.env", () => {
+    expect(environmentOf({ environment: "a" }, { ownership: { stack: "s", env: "c" } }, { CHANT_ENV: "b" })).toBe("a");
+    expect(environmentOf({}, { ownership: { stack: "s", env: "c" } }, { CHANT_ENV: "b" })).toBe("b");
+    expect(environmentOf({}, { ownership: { stack: "s", env: "c" } }, {})).toBe("c");
+    expect(environmentOf({}, undefined, {})).toBeUndefined();
+  });
+});
+
+describe("sqlReceiptStore over Postgres (#3657)", () => {
+  test("keeps receipts in chant_receipts.receipts, a schema and table it marks as chant's", async () => {
+    const pg = fakePostgres();
+    const store = sqlReceiptStore({ environment: "prod", stack: "shop", postgres: pg.client, runId: "r1" });
+    expect(await store.read(ref("fill/b1"))).toBeUndefined();
+    await store.write(ref("fill/b1"), "present");
+    expect(await store.read(ref("fill/b1"))).toBe("present");
+
+    expect(pg.statements).toContain("CREATE SCHEMA IF NOT EXISTS chant_receipts");
+    expect(pg.statements.find((s) => s.startsWith("COMMENT ON SCHEMA chant_receipts"))).toContain("receipts=effects");
+    expect(pg.statements.find((s) => s.startsWith("CREATE TABLE"))).toContain("TABLE IF NOT EXISTS chant_receipts.receipts (");
+    expect([...pg.rows.keys()]).toEqual(["shop/prod/fill/b1"]);
+    expect(await store.location()).toEqual({ dialect: "postgres", table: "chant_receipts.receipts", source: "the caller's connection", address: "shop/prod/<effect>" });
+  });
+
+  test("a receiptsSchema keeps them in <schema>.__chant_receipts, and creates no schema", async () => {
+    const pg = fakePostgres();
+    const store = sqlReceiptStore({
+      environment: "prod",
+      postgres: pg.client,
+      config: { ownership: { stack: "shop" }, sql: { profiles: { prod: { url: "postgres://db/app", receiptsSchema: "app" } } } },
+    });
+    await store.write(ref("fill/b1"), "present");
+    expect(pg.statements.some((s) => s.includes("CREATE SCHEMA"))).toBe(false);
+    expect(pg.statements.find((s) => s.startsWith("CREATE TABLE"))).toContain("TABLE IF NOT EXISTS app.__chant_receipts (");
+    expect((await store.location()).table).toBe("app.__chant_receipts");
+  });
+
+  test("a table of the user's under the receipts name is refused, not written into", async () => {
+    const pg = fakePostgres({ schema: true, table: "the user's own receipts" });
+    const store = sqlReceiptStore({ environment: "prod", stack: "shop", postgres: pg.client });
+    await expect(store.write(ref("fill/b1"), "present")).rejects.toThrow(/chant_receipts\.receipts exists and is not chant's receipts table/);
+    expect(pg.rows.size).toBe(0);
+  });
+});