@intentius/chant-lexicon-sql 0.115.0 → 0.117.0

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,12 @@ export {
   type,
   domain,
   extension,
+  func,
+  procedure,
+  trigger,
+  policy,
+  role,
+  grant,
   literal,
   SqlLiteral,
   SqlTemplateError,
@@ -33,6 +39,12 @@ export {
   type PostgresEnum,
   type PostgresDomain,
   type PostgresExtension,
+  type PostgresFunction,
+  type PostgresProcedure,
+  type PostgresTrigger,
+  type PostgresPolicy,
+  type PostgresRole,
+  type PostgresGrant,
   type ColumnDef,
   type KeyDef,
   type CheckDef,
@@ -46,6 +58,16 @@ export {
   type EnumProps,
   type DomainProps,
   type ExtensionProps,
+  type RoutineProps,
+  type RoutineArgDef,
+  type FunctionProps,
+  type ProcedureProps,
+  type TriggerProps,
+  type PolicyProps,
+  type RoleProps,
+  type GrantProps,
+  type DefaultPrivilegesProps,
+  type PrivilegeDef,
   type LineageEdge,
 } from "./postgres/entities";
 

package/src/skill-defs.ts

@@ -54,7 +54,7 @@ export const sqlSkills = createSkillsLoader(import.meta.url, [
     file: "chant-sql-postgres.md",
     name: "chant-sql-postgres",
     description:
-      "Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types and extensions as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules",
+      "Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures, triggers, policies, roles and grants as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules",
     triggers: [
       { type: "context" as const, value: "postgres" },
       { type: "context" as const, value: "postgres schema" },

package/src/skills/chant-sql-postgres-migration.md

@@ -40,6 +40,8 @@ Options besides `name`, `env`, `table`, `column`, `using`:
 - `gate` and `contractGate`: the two approvals, each with `gate` (name), `timeout` and `description`; `gate` also takes `approval` for quorum, roles and a policy, and a policy gets `verifiedRows` and `mismatched` as context;
 - `backfillTimeout` (default `6h`), `output` (default `dist/schema.json`), `path`, `build` (default true runs `chant build` first), `stack`, `ownershipEnv`.
 
+Run as one step of a change approved elsewhere: `gates: "outer"` leaves out the switch gate, the contract gate and the Contract phase (verification still runs; the old column is kept until its retention date), and `onFailure: "keep"` leaves out onFailure, so a failed run's next run resumes the backfill from its receipts. Set them rather than editing the Op's phases.
+
 ## What it does
 
 | Phase | Step |
@@ -103,7 +105,7 @@ or set `replicationLag: false` to run without the check.
 
 ## When something goes wrong
 
-- A failed step (a value the `using` expression cannot convert, a verification mismatch, a refused declaration, an index that cannot be built) runs onFailure: the trigger, its function, the check, the carried indexes and constraints, the new column and the receipts table are dropped, and the plan shows the original change again. The old column was never touched. Fix the declaration or the data and run again. A failed gate or an aborted run does not run onFailure.
+- A failed step (a value the `using` expression cannot convert, a verification mismatch, a refused declaration, an index that cannot be built) runs onFailure, unless the Op sets `onFailure: "keep"`: the trigger, its function, the check, the carried indexes and constraints, the new column and the receipts table are dropped, and the plan shows the original change again. The old column was never touched. Fix the declaration or the data and run again. A failed gate or an aborted run does not run onFailure.
 - A lock timeout means another session holds a lock the step needs (SQLSTATE 55P03). The step retries a few times, then fails. Run again when the blocker has finished.
 - The working objects (new column, trigger, function, check, receipts table) carry chant's comment marker with a `migration=` key, and plans, imports and prunes leave them out, so an `ApplyOp` for the rest of the schema can run beside a migration. An object under one of the working names that is not this migration's stops the run; rename or drop it by hand.
 

package/src/skills/chant-sql-postgres.md

@@ -1,6 +1,6 @@
 ---
 skill: chant-sql-postgres
-description: Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types and extensions as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules
+description: Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures, triggers, policies, roles and grants as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules
 user-invocable: true
 ---
 # Declaring a Postgres schema with chant
@@ -37,6 +37,12 @@ The export name (`users`) is the object's identity in chant. The name in the SQL
 | `type` | `CREATE TYPE ... AS ENUM` | `Postgres::Enum` |
 | `domain` | `CREATE DOMAIN` | `Postgres::Domain` |
 | `extension` | `CREATE EXTENSION` | `Postgres::Extension` |
+| `func` | `CREATE FUNCTION` | `Postgres::Function` |
+| `procedure` | `CREATE PROCEDURE` | `Postgres::Procedure` |
+| `trigger` | `CREATE TRIGGER` | `Postgres::Trigger` |
+| `policy` | `CREATE POLICY` | `Postgres::Policy` |
+| `role` | `CREATE ROLE` (no password, no memberships) | `Postgres::Role` |
+| `grant` | `GRANT`, `REVOKE`, `ALTER DEFAULT PRIVILEGES` | `Postgres::Grant`, `Postgres::DefaultPrivileges` |
 
 `table` and `view` imported from the package root are ClickHouse's. Import every tag from `@intentius/chant-lexicon-sql/postgres`.
 
@@ -124,6 +130,23 @@ export const citext = extension`CREATE EXTENSION IF NOT EXISTS citext WITH SCHEM
 
 Use the entity as a column type: `status ${status} NOT NULL DEFAULT 'placed'`. The table then depends on the type. Enum labels are values of the type, so a label cannot be removed or reordered later without a rebuild; add labels at the end. An extension is an object of its own with no references to it from a column type, so a table using a type it provides does not wait for it; keep extensions in a project the database already has, or apply them first.
 
+## Functions, procedures and triggers
+
+```ts
+import { func, trigger } from "@intentius/chant-lexicon-sql/postgres";
+
+export const touch = func`CREATE FUNCTION ${app}.touch() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN NEW.updated_at := now(); RETURN NEW; END
+$$`;
+export const ordersTouch = trigger`CREATE TRIGGER orders_touch BEFORE UPDATE ON ${orders} FOR EACH ROW EXECUTE FUNCTION ${touch}()`;
+```
+
+The tag is `func` (`function` is a JavaScript key word). Write the body as a string, `AS $$ ... $$`: it is kept and compared verbatim. `${users}` inside the body renders as `app.users` and makes the routine depend on the table. A SQL-standard body (`RETURN ...`, `BEGIN ATOMIC`) and `SET ... FROM CURRENT` are SQLPG001 errors. Overloads are separate objects, identified by their input parameter types. A trigger's name is unqualified; it lives on its table.
+
+## Access
+
+A table's template may end with `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`. `policy`, `role` and `grant` declare policies, the roles the schema needs (never a password or a membership: those are the environment's), privileges on schemas, tables, columns, sequences and routines, and default privileges. They are planned and applied only where `sql.profiles.<env>.access` is true; there, the declared privileges are the whole of them, and one granted by hand is revoked. A role the environment provisions is named as text (`TO support`), never declared. `GRANT ... ON ALL TABLES IN SCHEMA` is refused: grant per table and declare default privileges.
+
 ## Comments
 
 Postgres has no inline comment clause. Follow the `CREATE` with `COMMENT ON` for the object, its columns and its named constraints, separated by `;`:
@@ -162,4 +185,4 @@ chant build src --lexicon sql -o dist/schema.json
 
 ## Not covered
 
-`ALTER`, `CREATE POLICY`, `GRANT`, functions, triggers, rules and the composite and range forms of `CREATE TYPE` are not declared with the tags. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.
+`ALTER` (other than a table's row-level security), role memberships, rules, aggregates, event triggers and the composite and range forms of `CREATE TYPE` are not declared with the tags. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.

package/src/validate.ts

@@ -34,6 +34,13 @@ const REQUIRED_ENTITIES = [
   "PostgresEnum",
   "PostgresDomain",
   "PostgresExtension",
+  "PostgresFunction",
+  "PostgresProcedure",
+  "PostgresTrigger",
+  "PostgresPolicy",
+  "PostgresRole",
+  "PostgresGrant",
+  "PostgresDefaultPrivileges",
 ];
 
 /** Engines a ClickHouse schema declares most: the MergeTree family and the engines beside it. */