@intentius/chant-lexicon-sql 0.116.0 → 0.117.0

package/src/postgres/plan/normalize.ts

@@ -60,6 +60,10 @@ import type {
   IndexProps,
   KeyDef,
   SchemaProps,
+  DefaultPrivilegesProps,
+  GrantProps,
+  PolicyProps,
+  RoleProps,
   RoutineProps,
   SequenceProps,
   TableProps,
@@ -67,6 +71,8 @@ import type {
   ViewProps,
 } from "../entities";
 import { stringValue } from "../entities";
+import { parseStatements } from "../parser";
+import type { RoutineNode } from "../parser";
 
 // ── Types ──────────────────────────────────────────────────────────────
 
@@ -319,7 +325,29 @@ export interface CanonicalConstraint {
   comment?: string;
 }
 
-export type CanonicalKind = "schema" | "table" | "index" | "view" | "materializedView" | "sequence" | "enum" | "domain" | "extension" | "function" | "procedure" | "trigger";
+export type CanonicalKind =
+  | "schema"
+  | "table"
+  | "index"
+  | "view"
+  | "materializedView"
+  | "sequence"
+  | "enum"
+  | "domain"
+  | "extension"
+  | "function"
+  | "procedure"
+  | "trigger"
+  | "policy"
+  | "role"
+  | "grant"
+  | "defaultPrivileges";
+
+/** The kinds whose declarations are privileges, compared as the access they add up to (`../access/`), not one by one. */
+export const ACCESS_KINDS: ReadonlySet<CanonicalKind> = new Set(["grant", "defaultPrivileges"]);
+
+/** The kinds a profile manages only when it says so (`sql.profiles.<env>.access`). */
+export const ACCESS_MANAGED_KINDS: ReadonlySet<CanonicalKind> = new Set(["policy", "role", "grant", "defaultPrivileges"]);
 
 export interface CanonicalPgObject {
   kind: CanonicalKind;
@@ -350,6 +378,10 @@ const kindOf: Record<string, CanonicalKind> = {
   "Postgres::Function": "function",
   "Postgres::Procedure": "procedure",
   "Postgres::Trigger": "trigger",
+  "Postgres::Policy": "policy",
+  "Postgres::Role": "role",
+  "Postgres::Grant": "grant",
+  "Postgres::DefaultPrivileges": "defaultPrivileges",
 };
 
 const comment = (c: string | undefined): string | undefined => {
@@ -500,6 +532,38 @@ function routineFields(kind: "function" | "procedure", p: RoutineProps, defaultS
   fields.window = p.window === true;
 }
 
+/** A routine named with its parameters as a GRANT writes it (`app.f(int, text)`), as the target the catalog names: `app.f(integer,text)`. */
+export function canonicalRoutineTarget(text: string, defaultSchema: string): string {
+  const open = text.indexOf("(");
+  const name = canonicalName(open < 0 ? text : text.slice(0, open), defaultSchema);
+  if (open < 0) return name;
+  try {
+    // The parameter list read the way a CREATE FUNCTION reads it: modes, names and types.
+    const tokens = tokenizeText(`CREATE FUNCTION x${text.slice(open)} RETURNS void LANGUAGE sql AS ''`, 0);
+    const [node] = parseStatements(tokens);
+    const args = (node as RoutineNode).args.map((a) => ({ mode: (a.mode?.toLowerCase() ?? "in") as RoutineProps["args"][number]["mode"], type: tokens.slice(a.type.from, a.type.to).map((t) => t.text).join("") }));
+    return `${name}${routineSignature({ args }, defaultSchema)}`;
+  } catch {
+    return `${name}${text.slice(open).replace(/\s+/g, "")}`;
+  }
+}
+
+/** A role's attributes that differ from `CREATE ROLE`'s defaults (NOLOGIN, INHERIT and every other NO...), sorted. */
+const ROLE_DEFAULTS: Readonly<Record<string, boolean>> = { superuser: false, createdb: false, createrole: false, inherit: true, login: false, replication: false, bypassrls: false };
+
+export function canonicalRoleAttributes(options: readonly string[]): string[] {
+  const set: Record<string, boolean> = { ...ROLE_DEFAULTS };
+  for (const o of options) {
+    const word = o.toLowerCase();
+    if (word.startsWith("no") && word.slice(2) in ROLE_DEFAULTS) set[word.slice(2)] = false;
+    else if (word in ROLE_DEFAULTS) set[word] = true;
+  }
+  return Object.entries(set)
+    .filter(([k, v]) => ROLE_DEFAULTS[k] !== v)
+    .map(([k, v]) => (v ? k : `no${k}`))
+    .sort();
+}
+
 /** The order the catalog prints a trigger's events in. */
 const EVENT_ORDER = ["insert", "delete", "update", "truncate"];
 
@@ -538,7 +602,7 @@ function triggerFields(p: TriggerProps, defaultSchema: string, fields: Record<st
 export function canonicalPgObject(entityType: string, props: Record<string, unknown>, defaultSchema = "public"): CanonicalPgObject {
   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 schemaOf = (p: { schema?: string }) => (kind === "schema" || kind === "extension" || kind === "role" || ACCESS_KINDS.has(kind) ? undefined : (p.schema ?? defaultSchema));
   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[] = [];
@@ -572,6 +636,53 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
       base.signature = ` ON ${String(fields.table)}`;
       break;
     }
+    case "policy": {
+      const p = props as unknown as PolicyProps;
+      fields.table = canonicalName(p.tableName, defaultSchema);
+      base.signature = ` ON ${String(fields.table)}`;
+      fields.restrictive = p.permissive === false;
+      fields.command = p.command && p.command !== "all" ? p.command : undefined;
+      const roles = [...new Set(p.roles.map((r) => r.toLowerCase() === "public" ? "public" : quoteIdent(r)))].sort();
+      fields.roles = roles.length === 1 && roles[0] === "public" ? undefined : roles;
+      fields.using = canonicalExpr(p.using);
+      fields.check = canonicalExpr(p.check);
+      break;
+    }
+    case "role": {
+      const p = props as unknown as RoleProps;
+      const attributes = canonicalRoleAttributes(p.options);
+      fields.attributes = attributes.length > 0 ? attributes : undefined;
+      fields.connectionLimit = p.connectionLimit !== undefined && Number(p.connectionLimit) !== -1 ? String(Number(p.connectionLimit)) : undefined;
+      break;
+    }
+    case "grant": {
+      const p = props as unknown as GrantProps;
+      const routine = p.on === "function" || p.on === "procedure" || p.on === "routine";
+      fields.grant = {
+        action: p.action,
+        on: p.on,
+        objects: p.objectNames.map((n) => (routine ? canonicalRoutineTarget(n, defaultSchema) : p.on === "schema" ? canonicalName(n) : canonicalName(n, defaultSchema))),
+        privileges: p.privileges.map((x) => ({ privilege: x.privilege.toLowerCase(), ...(x.columns ? { columns: x.columns } : {}) })),
+        grantees: p.grantees,
+        ...(p.withGrantOption ? { withGrantOption: true } : {}),
+        ...(p.grantOptionFor ? { grantOptionFor: true } : {}),
+      };
+      break;
+    }
+    case "defaultPrivileges": {
+      const p = props as unknown as DefaultPrivilegesProps;
+      fields.grant = {
+        action: p.action,
+        on: p.on,
+        privileges: p.privileges.map((x) => ({ privilege: x.toLowerCase() })),
+        grantees: p.grantees,
+        ...(p.forRoles ? { forRoles: p.forRoles } : {}),
+        ...(p.inSchemas ? { inSchemas: p.inSchemas } : {}),
+        ...(p.withGrantOption ? { withGrantOption: true } : {}),
+        ...(p.grantOptionFor ? { grantOptionFor: true } : {}),
+      };
+      break;
+    }
     case "domain": {
       const p = props as unknown as DomainProps;
       fields.dataType = canonicalType(p.dataType, defaultSchema);
@@ -681,6 +792,8 @@ export function canonicalPgObject(entityType: string, props: Record<string, unkn
       fields.using = p.using && p.using.toLowerCase() !== "heap" ? p.using.toLowerCase() : undefined;
       fields.with = canonicalOptions(p.with);
       fields.tablespace = p.tablespace;
+      fields.rowSecurity = p.rowSecurity === true;
+      fields.forceRowSecurity = p.forceRowSecurity === true;
       break;
     }
   }

package/src/postgres/plan/rules.ts

@@ -306,6 +306,50 @@ export const PG_CLASSIFIER_RULES = {
     `${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`),
+  SQLPG290: rule(
+    "SQLPG290",
+    "metadata",
+    "Create a policy on an existing table",
+    "CREATE POLICY takes ACCESS EXCLUSIVE on its table, briefly; no row is read. Where row-level security is on, the rows each role sees change when the transaction commits.",
+    `${DOCS}/sql-createpolicy.html`,
+  ),
+  SQLPG291: rule(
+    "SQLPG291",
+    "metadata",
+    "Change a policy",
+    "ALTER POLICY changes its roles, USING and WITH CHECK under ACCESS EXCLUSIVE on the table, briefly. Its command, AS RESTRICTIVE and table cannot be altered, nor an expression taken away: the policy is dropped and created in one transaction, so no session sees the table without it.",
+    `${DOCS}/sql-alterpolicy.html`,
+  ),
+  SQLPG292: rule("SQLPG292", "drop", "Drop a policy", "DROP POLICY takes ACCESS EXCLUSIVE on its table, briefly; the rows it let a role see are hidden from that role at once, or, if it was the last policy, every non-owner sees none.", `${DOCS}/sql-droppolicy.html`),
+  SQLPG293: rule(
+    "SQLPG293",
+    "metadata",
+    "Turn row-level security on or off, or force it on the owner",
+    "ALTER TABLE ... ENABLE, DISABLE, FORCE or NO FORCE ROW LEVEL SECURITY changes only the catalog, under ACCESS EXCLUSIVE, briefly. With it on and no policy that lets a role in, that role sees no rows; FORCE subjects the table's owner too.",
+    `${DOCS}/ddl-rowsecurity.html`,
+  ),
+  SQLPG294: rule("SQLPG294", "metadata", "Change a role's attributes", "ALTER ROLE changes the role in the cluster's catalog, for every database on the server, at once; sessions already open keep the attributes they started with until they reconnect.", `${DOCS}/sql-alterrole.html`),
+  SQLPG296: rule(
+    "SQLPG296",
+    "metadata",
+    "Grant a privilege",
+    "GRANT adds to the object's privileges in the catalog; no row is read and the role can use it from its next statement.",
+    `${DOCS}/sql-grant.html`,
+  ),
+  SQLPG297: rule(
+    "SQLPG297",
+    "metadata",
+    "Revoke a privilege",
+    "REVOKE removes from the object's privileges in the catalog. The role loses it at once: its next statement that needs it fails, so move every reader off it first.",
+    `${DOCS}/sql-revoke.html`,
+  ),
+  SQLPG298: rule(
+    "SQLPG298",
+    "metadata",
+    "Change default privileges",
+    "ALTER DEFAULT PRIVILEGES changes what objects created afterwards are given; objects that exist keep their privileges.",
+    `${DOCS}/sql-alterdefaultprivileges.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

@@ -100,10 +100,12 @@ export function pgSchemaFromBuildFile(path: string, defaultSchema = "public"): P
  * 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.
+ * a trigger's or a policy's name is unique on its table, and a role's in the
+ * cluster.
  */
 export function pgNamespace(kind: string): string {
-  if (kind === "schema" || kind === "extension" || kind === "trigger") return kind;
+  if (kind === "schema" || kind === "extension" || kind === "trigger" || kind === "policy" || kind === "role") return kind;
+  if (kind === "grant" || kind === "defaultPrivileges") return "grant";
   if (kind === "enum" || kind === "domain") return "type";
   if (kind === "function" || kind === "procedure") return "routine";
   return "relation";

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

@@ -8,7 +8,10 @@
  * (`CREATE TEMP VIEW`, or a `CREATE TEMP TABLE` holding the columns' types,
  * defaults and generated expressions and the checks) inside a transaction
  * that is always rolled back, with a short `lock_timeout`, and read back with
- * the same printers the catalog read uses. Nothing is left behind: Postgres
+ * the same printers the catalog read uses. A trigger's `WHEN` and a policy's
+ * `USING` and `WITH CHECK`, which the server prints with the casts it
+ * resolved, are read back from a trigger or policy on a temporary copy of the
+ * table (`CREATE TEMP TABLE ... (LIKE table)`). Nothing is left behind: Postgres
  * DDL is transactional and a temporary object lives in the session's own
  * schema. A server that refuses (no TEMP privilege, a lock not granted in
  * time, an expression it rejects) leaves the rules' answer standing.
@@ -108,6 +111,27 @@ async function triggerWhen(client: PostgresClient, o: CanonicalPgObject, default
   });
 }
 
+/** A policy's USING and WITH CHECK as the server prints them, canonical, from a policy on a temporary copy of its table. */
+async function policyExpressions(client: PostgresClient, o: CanonicalPgObject, defaultSchema: string): Promise<{ using?: string; check?: string } | undefined> {
+  const using = o.fields.using as string | undefined;
+  const check = o.fields.check as string | undefined;
+  if (using === undefined && check === undefined) return undefined;
+  return rolledBack(client, defaultSchema, async () => {
+    await client.query(`CREATE TEMP TABLE chant_normalize (LIKE ${String(o.fields.table)})`);
+    await client.query(
+      [`CREATE POLICY chant_normalize ON pg_temp.chant_normalize FOR ${String(o.fields.command ?? "all").toUpperCase()}`, using !== undefined ? `USING (${using})` : "", check !== undefined ? `WITH CHECK (${check})` : ""]
+        .filter(Boolean)
+        .join(" "),
+    );
+    await emptyPath(client);
+    const [row] = await client.query<Row>(
+      `SELECT pg_catalog.pg_get_expr(p.polqual, p.polrelid, true) AS qual, pg_catalog.pg_get_expr(p.polwithcheck, p.polrelid, true) AS withcheck
+       FROM pg_catalog.pg_policy p WHERE p.polrelid = 'pg_temp.chant_normalize'::pg_catalog.regclass`,
+    );
+    return { ...(row?.qual ? { using: canonicalExpr(String(row.qual)) } : {}), ...(row?.withcheck ? { check: canonicalExpr(String(row.withcheck)) } : {}) };
+  });
+}
+
 /**
  * The declared object with its expressions in the server's own printing,
  * when the server answers; the object unchanged otherwise. Only the
@@ -119,6 +143,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 === "policy") {
+    const e = await policyExpressions(client, o, defaultSchema);
+    return e === undefined ? o : { ...o, fields: { ...o.fields, ...e } };
+  }
   if (o.kind === "trigger") {
     const when = await triggerWhen(client, o, defaultSchema);
     return when === undefined ? o : { ...o, fields: { ...o.fields, when } };

package/src/postgres.ts

@@ -18,6 +18,9 @@ export {
   func,
   procedure,
   trigger,
+  policy,
+  role,
+  grant,
   literal,
   SqlLiteral,
   SqlTemplateError,
@@ -39,6 +42,9 @@ export {
   type PostgresFunction,
   type PostgresProcedure,
   type PostgresTrigger,
+  type PostgresPolicy,
+  type PostgresRole,
+  type PostgresGrant,
   type ColumnDef,
   type KeyDef,
   type CheckDef,
@@ -57,6 +63,11 @@ export {
   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, extensions, functions, procedures and triggers 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, extensions, functions, procedures and triggers 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
@@ -40,6 +40,9 @@ The export name (`users`) is the object's identity in chant. The name in the SQL
 | `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`.
 
@@ -140,6 +143,10 @@ export const ordersTouch = trigger`CREATE TRIGGER orders_touch BEFORE UPDATE ON
 
 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 `;`:
@@ -178,4 +185,4 @@ chant build src --lexicon sql -o dist/schema.json
 
 ## Not covered
 
-`ALTER`, `CREATE POLICY`, `GRANT`, 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.
+`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

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