@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/postgres/plan/commands.ts

@@ -18,6 +18,10 @@ import { keyedByQualifiedName, pgBuildFileMajor, pgSchemaFromBuildFile, pgSchema
 import { serverNormalized } from "./server-normalize";
 import { POSTGRES_ENTITY_TYPES } from "../entity-types";
 import { migrationOpSuggestions } from "../migrate/handoff";
+import { POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin";
+import { ACCESS_MANAGED_KINDS } from "./normalize";
+import { declaredAccess, diffAccess, predictedAccess, targetKey } from "../access/acl";
+import { readLiveAccess } from "../access/live";
 
 export function emitPg(diff: PgSchemaDiff, json: boolean, title: string): number {
   console.log(json ? JSON.stringify(diff, null, 2) : renderPgDiff(diff, { title }));
@@ -69,6 +73,8 @@ export interface PgServerPlan {
   diff: PgSchemaDiff;
   /** The major the changes were classified for: the server's, else the one asked for. */
   major?: number;
+  /** The schemas the read was limited to; undefined is every schema. */
+  scope?: string[];
 }
 
 /**
@@ -83,29 +89,76 @@ export async function planAgainstClient(
   build: readonly PgSchemaObject[],
   options: { major?: number; environment?: string; readLive?: typeof readLiveSchema; serverNormalize?: typeof serverNormalized } = {},
 ): Promise<PgServerPlan> {
-  const declaredRaw = keyedByQualifiedName(build);
+  const managed = target.access === true;
+  const { kept, unmanaged } = accessScoped(keyedByQualifiedName(build), managed);
+  const declaredRaw = kept;
   const scope = scopeFor(
     target,
-    declaredRaw.map((o) => ({ type: POSTGRES_ENTITY_TYPES[o.canonical.kind], props: { name: o.canonical.name, ...(o.canonical.schema ? { schema: o.canonical.schema } : {}) } })),
+    declaredRaw.filter((o) => o.canonical.kind !== "role" && o.canonical.kind !== "grant" && o.canonical.kind !== "defaultPrivileges").map((o) => ({ type: POSTGRES_ENTITY_TYPES[o.canonical.kind], props: { name: o.canonical.name, ...(o.canonical.schema ? { schema: o.canonical.schema } : {}) } })),
   );
-  const liveObjects = markProviderOwned(await (options.readLive ?? readLiveSchema)(client, { schemas: scope }), target.provider);
+  const roles = declaredRaw.filter((o) => o.canonical.kind === "role").map((o) => o.canonical.name);
+  const liveObjects = markProviderOwned(await (options.readLive ?? readLiveSchema)(client, { schemas: scope, access: managed, roles }), target.provider);
   const live = pgSchemaFromLive(liveObjects, target.defaultSchema);
   const liveByKey = new Map(live.map((o) => [o.key, o]));
   const declared: PgSchemaObject[] = [];
   for (const o of declaredRaw) {
     const l = liveByKey.get(o.key);
-    if (l && differs(o, l) && (o.canonical.kind === "table" || o.canonical.kind === "view" || o.canonical.kind === "materializedView" || o.canonical.kind === "trigger")) {
+    if (l && differs(o, l) && (o.canonical.kind === "table" || o.canonical.kind === "view" || o.canonical.kind === "materializedView" || o.canonical.kind === "trigger" || o.canonical.kind === "policy")) {
       declared.push({ ...o, canonical: { ...o.canonical, ...(await (options.serverNormalize ?? serverNormalized)(client, o.canonical, target.defaultSchema)) } });
     } else declared.push(o);
   }
   // The build's major, else the server's own when it differs, since the server is what takes the locks.
   const running = await serverMajor(client).catch(() => undefined);
   const major = running ?? options.major;
-  const diff = diffPgSchemas(live, declared, { major });
+  const diff = diffPgSchemas(live, declared, { major, access: false });
+  if (managed) {
+    const want = declaredAccess(declared, { major: major ?? POSTGRES_LATEST_MAJOR, ...(await currentRole(client)) });
+    const have = await readLiveAccess(client, want.targets, { ...(scope ? { schemas: scope } : {}), forRoles: want.forRoles, declaredDefaults: want.targets.filter((t) => t.kind === "default") });
+    // An object this plan creates is given what the server gives a new one.
+    const missing = want.targets.filter((t) => t.kind !== "default" && t.kind !== "column" && !have.present.has(targetKey(t)));
+    const now = new Map([...have.state, ...predictedAccess(missing, have)]);
+    const access = diffAccess(now, want.state, want.exportsOf);
+    if (access.length > 0) {
+      diff.changes.push(...access.map((a) => a.change));
+      diff.access = access;
+    }
+  } else if (unmanaged > 0) {
+    diff.hints.push(`${unmanaged} access declaration${unmanaged === 1 ? " is" : "s are"} not planned: ${options.environment ?? "this environment"}'s profile does not manage access (sql.profiles.<env>.access)`);
+  }
   if (running !== undefined && options.major !== undefined && running !== options.major) {
     diff.hints.push(`the build targets Postgres ${options.major} but ${options.environment ?? "the server"} runs Postgres ${running}; changes are classified for ${running}`);
   }
-  return { declared, live, liveObjects, diff, ...(major !== undefined ? { major } : {}) };
+  return { declared, live, liveObjects, diff, ...(major !== undefined ? { major } : {}), ...(scope ? { scope } : {}) };
+}
+
+/** The role a session runs as: the one whose own privileges owning an object gives, and whose default privileges apply. */
+async function currentRole(client: PostgresClient): Promise<{ self?: string }> {
+  const rows = await client.query<{ self: string }>("SELECT current_user AS self").catch(() => []);
+  return rows[0]?.self ? { self: rows[0].self } : {};
+}
+
+/**
+ * The declarations a plan compares: all of them where the profile manages
+ * access; otherwise none of the policies, roles, grants and default
+ * privileges, and no table's row-level security, so a project that manages
+ * access elsewhere is not affected. `unmanaged` counts what was left out.
+ */
+export function accessScoped(objects: readonly PgSchemaObject[], managed: boolean): { kept: PgSchemaObject[]; unmanaged: number } {
+  if (managed) return { kept: [...objects], unmanaged: 0 };
+  let unmanaged = 0;
+  const kept: PgSchemaObject[] = [];
+  for (const o of objects) {
+    if (ACCESS_MANAGED_KINDS.has(o.canonical.kind)) {
+      unmanaged++;
+      continue;
+    }
+    if (o.canonical.kind === "table" && (o.canonical.fields.rowSecurity || o.canonical.fields.forceRowSecurity)) {
+      unmanaged++;
+      const { rowSecurity: _r, forceRowSecurity: _f, ...fields } = o.canonical.fields;
+      kept.push({ ...o, canonical: { ...o.canonical, fields } });
+    } else kept.push(o);
+  }
+  return { kept, unmanaged };
 }
 
 /** The declared objects against the server, keys by qualified name and labels with the export name. */
@@ -116,7 +169,7 @@ export async function planPgAgainstServer(environment: string, buildFile: string
     const { declared, diff } = await planAgainstClient(client, target, pgSchemaFromBuildFile(buildFile, target.defaultSchema), { ...(targeted !== undefined ? { major: targeted } : {}), environment });
     const { migrationOps } = withMigrationOps(diff, declared, environment, target.defaultSchema);
     const label = new Map(declared.map((o) => [o.key, `${o.canonical.exportName} (${o.key.slice(o.key.indexOf(" ") + 1)})`]));
-    const changes = diff.changes.map((c) => ({ ...c, object: label.get(c.object) ?? c.object }));
+    const changes = diff.changes.map((c) => ({ ...c, object: label.get(c.object) ?? (c.object.startsWith("acl ") ? c.object.slice(4) : c.object) }));
     return { changes, hints: diff.hints, refused: changes.filter((c) => c.class === "expand"), ...(migrationOps ? { migrationOps } : {}) };
   } finally {
     await client.end();

package/src/postgres/plan/deep.ts

@@ -17,7 +17,7 @@ import { deepObservation, type DeepObservationResult, type DeepResourceObservati
 import type { UnobservedEntity } from "@intentius/chant/lexicon";
 import { bindPostgres, classifyPostgresFailure, type BindOptions } from "../live/bind";
 import { liveKey, readLiveSchema, type LivePgObject } from "../live/catalog";
-import { declaredAddress, scopeFor } from "../live/describe-resources";
+import { accessUnobserved, declaredAddress, scopeFor } from "../live/describe-resources";
 import * as tags from "../entities";
 import { POSTGRES_ENTITY_TYPES } from "../entity-types";
 import { canonicalPgObject, columnShape, sameConstraint, type CanonicalPgObject } from "./normalize";
@@ -39,6 +39,10 @@ const TAG: Record<string, (s: TemplateStringsArray) => { props: object }> = {
   [POSTGRES_ENTITY_TYPES.function]: tags.func,
   [POSTGRES_ENTITY_TYPES.procedure]: tags.procedure,
   [POSTGRES_ENTITY_TYPES.trigger]: tags.trigger,
+  [POSTGRES_ENTITY_TYPES.policy]: tags.policy,
+  [POSTGRES_ENTITY_TYPES.role]: tags.role,
+  [POSTGRES_ENTITY_TYPES.grant]: tags.grant,
+  [POSTGRES_ENTITY_TYPES.defaultPrivileges]: tags.grant,
 };
 
 /** The props of what the server printed, parsed with the declaration's tag. */
@@ -105,6 +109,14 @@ const PROP_OF_FIELD: Record<string, string[]> = {
   deferrable: ["deferrable"],
   initiallyDeferred: ["initiallyDeferred"],
   referencing: ["referencing"],
+  restrictive: ["permissive"],
+  command: ["command"],
+  roles: ["roles"],
+  check: ["check"],
+  attributes: ["options"],
+  connectionLimit: ["connectionLimit"],
+  rowSecurity: ["rowSecurity"],
+  forceRowSecurity: ["forceRowSecurity"],
 };
 
 /** Props keys that hold constraints, by constraint kind. */
@@ -190,6 +202,8 @@ export async function observeResourcesDeep(
     try {
       live = await readLiveSchema(bound.client, {
         schemas: scopeFor(target, declared.filter((x) => x.entity?.entityType.startsWith("Postgres::")).map((x) => ({ type: x.entity!.entityType, props: x.entity!.props }))),
+        access: target.access === true,
+        roles: declared.filter((x) => x.entity?.entityType === POSTGRES_ENTITY_TYPES.role).map((x) => String(x.entity!.props.name)),
       });
     } catch (err) {
       await bound.client.end();
@@ -207,6 +221,11 @@ export async function observeResourcesDeep(
         unobserved[name] = { type: entity?.entityType ?? "", reason: "unsupported-kind" };
         continue;
       }
+      const why = accessUnobserved(entity.entityType, target.access === true);
+      if (why) {
+        unobserved[name] = { type: entity.entityType, ...why };
+        continue;
+      }
       const { schema, name: objectName, signature } = declaredAddress({ type: entity.entityType, props: entity.props }, target.defaultSchema);
       const o = byKey.get(liveKey(entity.entityType, schema, objectName, signature));
       if (!o) continue;
@@ -214,8 +233,10 @@ export async function observeResourcesDeep(
         const lp = liveProps(o);
         let d = canonicalPgObject(entity.entityType, entity.props, target.defaultSchema);
         const l = canonicalPgObject(o.type, lp, target.defaultSchema);
-        // A trigger's WHEN as the server would print it, when the rules leave it different.
-        if (d.kind === "trigger" && d.fields.when !== l.fields.when) d = await serverNormalized(client, d, target.defaultSchema);
+        // A trigger's WHEN and a policy's expressions as the server would print them, when the rules leave them different.
+        if ((d.kind === "trigger" && d.fields.when !== l.fields.when) || (d.kind === "policy" && (d.fields.using !== l.fields.using || d.fields.check !== l.fields.check))) {
+          d = await serverNormalized(client, d, target.defaultSchema);
+        }
         resources[name] = { type: o.type, physicalId: o.oid, properties: inDeclaredVocabulary(entity.props, lp, d, l) };
       } catch (err) {
         unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's definition does not parse: ${(err as Error).message}` };

package/src/postgres/plan/diff.ts

@@ -16,7 +16,8 @@
 import { classifiedChange, type ChangeSet, type ClassifiedChange } from "../../core/classifier";
 import { matchByIdentity } from "../../core/diff";
 import { PG_CLASSIFIER_RULES, type PgChangeClass, type PgClassifierRuleId } from "./rules";
-import { sameConstraint, serialBase, type CanonicalColumn, type CanonicalConstraint } from "./normalize";
+import { ACCESS_KINDS, sameConstraint, serialBase, type CanonicalColumn, type CanonicalConstraint } from "./normalize";
+import { builtinEntries, declaredAccess, diffAccess, entryKey, targetKey, type AccessChange } from "../access/acl";
 import { pgNamespace, type PgDiffObject, type PgSchemaObject } from "./schema";
 import { POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin";
 import type { PostgresMigrationOpSuggestion } from "../migrate/handoff";
@@ -24,6 +25,12 @@ import type { PostgresMigrationOpSuggestion } from "../migrate/handoff";
 /** What the diff needs to know beyond the two schemas: the server's major (`sql.postgresMajor`, else the newest pinned). */
 export interface PgDiffOptions {
   major?: number;
+  /**
+   * Whether to compare the access the two sides declare (grants, revokes,
+   * default privileges). On by default, for a diff between two builds; a plan
+   * against a server compares the server's access itself (`./commands.ts`).
+   */
+  access?: boolean;
 }
 
 export type PgChange = ClassifiedChange<PgClassifierRuleId, PgChangeClass>;
@@ -33,12 +40,14 @@ export interface PgSchemaDiff extends ChangeSet<PgChange> {
   refused: PgChange[];
   /** The `PostgresMigrationOp` to run for each refused column rename or type change (#3281). */
   migrationOps?: PostgresMigrationOpSuggestion[];
+  /** The access changes among `changes`, each with its GRANT, REVOKE or ALTER DEFAULT PRIVILEGES statements (#3681). */
+  access?: AccessChange[];
 }
 
 const change = (object: string, field: string, rule: PgClassifierRuleId, before?: unknown, after?: unknown, extra: Partial<PgChange> = {}): PgChange =>
   classifiedChange(PG_CLASSIFIER_RULES, object, field, rule, before, after, extra);
 
-const qualified = (o: PgDiffObject) => `${o.schema ? `${o.schema}.` : ""}${o.name}${o.kind === "trigger" ? "" : (o.signature ?? "")}`;
+const qualified = (o: PgDiffObject) => `${o.schema ? `${o.schema}.` : ""}${o.name}${o.kind === "trigger" || o.kind === "policy" ? "" : (o.signature ?? "")}`;
 
 // ── Columns ────────────────────────────────────────────────────────────
 
@@ -294,7 +303,31 @@ function diffObject(key: string, before: PgDiffObject, after: PgDiffObject, out:
       }
       break;
     }
+    case "policy": {
+      // ALTER POLICY sets the roles, USING and WITH CHECK; the command and AS RESTRICTIVE are fixed, and neither expression can be taken away.
+      const definition = ["table", "restrictive", "command", "roles", "using", "check"];
+      const changed = definition.filter((k) => !same(before.fields[k], after.fields[k]));
+      if (changed.length === 0) break;
+      const recreate =
+        !same(before.fields.table, after.fields.table) ||
+        !same(before.fields.restrictive, after.fields.restrictive) ||
+        !same(before.fields.command, after.fields.command) ||
+        (before.fields.using !== undefined && after.fields.using === undefined) ||
+        (before.fields.check !== undefined && after.fields.check === undefined);
+      out.push(
+        change(key, changed.join(", "), "SQLPG291", changed.map((k) => `${k} ${show(before.fields[k]) ?? "-"}`).join("; "), changed.map((k) => `${k} ${show(after.fields[k]) ?? "-"}`).join("; "), recreate ? { note: "dropped and created in one transaction: ALTER POLICY cannot change its command, AS RESTRICTIVE or table, or take an expression away" } : {}),
+      );
+      break;
+    }
+    case "role":
+      field("attributes", "SQLPG294");
+      field("connectionLimit", "SQLPG294");
+      break;
     case "table":
+      if (!same(before.fields.rowSecurity, after.fields.rowSecurity) || !same(before.fields.forceRowSecurity, after.fields.forceRowSecurity)) {
+        const state = (o: PgDiffObject) => (o.fields.rowSecurity ? (o.fields.forceRowSecurity ? "enabled, forced" : "enabled") : o.fields.forceRowSecurity ? "disabled, forced" : "disabled");
+        out.push(change(key, "rowSecurity", "SQLPG293", state(before), state(after), after.fields.rowSecurity && !before.fields.rowSecurity ? { note: "with row-level security on, a role the table's policies do not let in sees no rows" } : {}));
+      }
       diffColumns(key, before, after, out, hints, false, major);
       diffConstraints(key, before, after, out, false);
       field("with", "SQLPG224");
@@ -334,8 +367,11 @@ export function matchPgObjects(before: readonly PgSchemaObject[], after: readonl
   });
 }
 
-export function diffPgSchemas(before: readonly PgSchemaObject[], after: readonly PgSchemaObject[], options: PgDiffOptions = {}): PgSchemaDiff {
+export function diffPgSchemas(beforeAll: readonly PgSchemaObject[], afterAll: readonly PgSchemaObject[], options: PgDiffOptions = {}): PgSchemaDiff {
   const major = options.major ?? POSTGRES_LATEST_MAJOR;
+  // Grants and default privileges are compared as the access they add up to, below, not one declaration against another.
+  const before = beforeAll.filter((o) => !ACCESS_KINDS.has(o.canonical.kind));
+  const after = afterAll.filter((o) => !ACCESS_KINDS.has(o.canonical.kind));
   const matches = matchPgObjects(before, after);
   const newTables = createdTables(matches);
   const changes: PgChange[] = [];
@@ -347,6 +383,8 @@ export function diffPgSchemas(before: readonly PgSchemaObject[], after: readonly
         changes.push(change(m.after.key, "index", o.concurrently ? "SQLPG240" : "SQLPG241", undefined, qualified(o)));
       } else if (o.kind === "trigger" && !newTables.has(String(o.fields.table))) {
         changes.push(change(m.after.key, "trigger", "SQLPG283", undefined, `${o.name}${o.signature ?? ""}`));
+      } else if (o.kind === "policy" && !newTables.has(String(o.fields.table))) {
+        changes.push(change(m.after.key, "policy", "SQLPG290", undefined, `${o.name}${o.signature ?? ""}`));
       } else changes.push(change(m.after.key, o.kind, "SQLPG200", undefined, qualified(o)));
     } else if (m.kind === "dropped") {
       const o = m.before.canonical;
@@ -354,10 +392,37 @@ export function diffPgSchemas(before: readonly PgSchemaObject[], after: readonly
         hints.push(`${m.before.key} is kept by ${o.foreign}; it is not chant's to drop and is left alone`);
         continue;
       }
+      if (o.kind === "role") {
+        hints.push(`role ${o.name} is no longer declared; a role is the cluster's and is never dropped`);
+        continue;
+      }
       const destructive = o.kind === "table" || o.kind === "materializedView" || o.kind === "sequence";
-      const rule = o.kind === "index" ? "SQLPG242" : o.kind === "trigger" ? "SQLPG285" : "SQLPG270";
-      changes.push(change(m.before.key, o.kind, rule, o.kind === "trigger" ? `${o.name}${o.signature ?? ""}` : qualified(o), undefined, destructive ? { destructive: true } : {}));
+      const rule = o.kind === "index" ? "SQLPG242" : o.kind === "trigger" ? "SQLPG285" : o.kind === "policy" ? "SQLPG292" : "SQLPG270";
+      changes.push(change(m.before.key, o.kind, rule, o.kind === "trigger" || o.kind === "policy" ? `${o.name}${o.signature ?? ""}` : qualified(o), undefined, destructive ? { destructive: true } : {}));
     } else diffObject(m.after.key, m.before.canonical, m.after.canonical, changes, hints, major);
   }
-  return { changes, hints, refused: changes.filter((c) => c.class === "expand") };
+  const access = options.access === false ? [] : buildAccessChanges(beforeAll, afterAll, major);
+  changes.push(...access.map((a) => a.change));
+  return { changes, hints, refused: changes.filter((c) => c.class === "expand"), ...(access.length > 0 ? { access } : {}) };
+}
+
+/**
+ * The access change between two builds: on what the newer build decides. An
+ * object only it declares starts from what Postgres gives a new one; an
+ * object only the older one declared is dropped with its privileges.
+ */
+function buildAccessChanges(before: readonly PgSchemaObject[], after: readonly PgSchemaObject[], major: number): AccessChange[] {
+  const b = declaredAccess(before, { major });
+  const a = declaredAccess(after, { major });
+  const decided = new Set(a.targets.map(targetKey));
+  const known = new Set(b.targets.map(targetKey));
+  const from = new Map([...b.state].filter(([, e]) => decided.has(targetKey(e.target))));
+  for (const t of a.targets) {
+    if (known.has(targetKey(t)) || t.kind === "default" || t.kind === "column") continue;
+    for (const e of builtinEntries(t.kind)) {
+      const key = entryKey(t, e.grantee);
+      from.set(key, { target: t, grantee: e.grantee, privileges: new Map([...(from.get(key)?.privileges ?? []), [e.privilege, false]]) });
+    }
+  }
+  return diffAccess(from, a.state, a.exportsOf);
 }

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/plan.test.ts

@@ -82,7 +82,7 @@ describe("columns", () => {
     expect(rules(diff([table(ORDERS)], [table("CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) DEFAULT 0, note varchar(20) NOT NULL, status text)")]))).toEqual([
       ["columns.amount.default", "SQLPG209", "metadata"],
       ["columns.amount.notNull", "SQLPG211", "metadata"],
-      ["columns.note.notNull", "SQLPG210", "rewrite"],
+      ["columns.note.notNull", "SQLPG210", "validate"],
     ]);
     const renamed = diff([table(ORDERS)], [table(`CREATE TABLE app.orders (id bigint PRIMARY KEY, amount numeric(12,2) NOT NULL, note varchar(20),
       state text -- previously: status
@@ -113,7 +113,7 @@ describe("constraints", () => {
     );
     expect(rules(d)).toEqual([
       ["constraints.unique", "SQLPG221", "concurrently"],
-      ["constraints.a", "SQLPG218", "rewrite"],
+      ["constraints.a", "SQLPG218", "validate"],
       ["constraints.b", "SQLPG217", "metadata"],
       ["constraints.c", "SQLPG219", "validate"],
       ["constraints.exclude", "SQLPG222", "rewrite"],

package/src/postgres/plan/rules.ts

@@ -109,9 +109,9 @@ export const PG_CLASSIFIER_RULES = {
   SQLPG209: rule("SQLPG209", "metadata", "Change a column's default", "SET DEFAULT and DROP DEFAULT change only the catalog; existing rows keep their values.", ALTER_TABLE),
   SQLPG210: rule(
     "SQLPG210",
-    "rewrite",
+    "validate",
     "Set NOT NULL",
-    "SET NOT NULL reads the whole table under ACCESS EXCLUSIVE, unless a valid CHECK (column IS NOT NULL) constraint already proves it (since 12). Declare that check NOT VALID, validate it, then set NOT NULL; 18 can also add NOT NULL ... NOT VALID.",
+    "SET NOT NULL alone reads the whole table under ACCESS EXCLUSIVE, unless a valid CHECK (column IS NOT NULL) constraint already proves it (since 12). So it is made as four statements: that check added NOT VALID, validated under SHARE UPDATE EXCLUSIVE while writes go on, SET NOT NULL, which the check proves without a scan, and the check dropped. Rows where the column is NULL fail the validation; the first statement's pre-check counts them.",
     ALTER_TABLE,
   ),
   SQLPG211: rule("SQLPG211", "metadata", "Drop NOT NULL", "DROP NOT NULL changes only the catalog.", ALTER_TABLE),
@@ -135,16 +135,16 @@ export const PG_CLASSIFIER_RULES = {
   ),
   SQLPG218: rule(
     "SQLPG218",
-    "rewrite",
+    "validate",
     "Add a CHECK constraint",
-    "ADD CONSTRAINT ... CHECK reads every row under ACCESS EXCLUSIVE. Declare it NOT VALID, then remove NOT VALID to validate it under SHARE UPDATE EXCLUSIVE (SQLPG220).",
+    "ADD CONSTRAINT ... CHECK alone reads every row under ACCESS EXCLUSIVE. On a table that exists it is made as two statements: the check added NOT VALID (SQLPG217), which reads no rows, then VALIDATE CONSTRAINT (SQLPG220) in a transaction of its own, which reads them under SHARE UPDATE EXCLUSIVE while writes go on. Rows the check refuses fail the validation; the first statement's pre-check counts them.",
     ALTER_TABLE,
   ),
   SQLPG219: rule(
     "SQLPG219",
     "validate",
     "Add a foreign key",
-    "ADD FOREIGN KEY reads every row under SHARE ROW EXCLUSIVE on both tables, which blocks writes to them for the scan. Declare it NOT VALID, then remove NOT VALID to validate it under SHARE UPDATE EXCLUSIVE (SQLPG220).",
+    "ADD FOREIGN KEY alone reads every row under SHARE ROW EXCLUSIVE on both tables, which blocks writes to them for the scan. On a table that exists it is made as two statements: the key added NOT VALID (SQLPG217), which takes that lock briefly and reads no rows, then VALIDATE CONSTRAINT (SQLPG220) in a transaction of its own, which reads them under SHARE UPDATE EXCLUSIVE while writes go on. Orphan rows fail the validation; the first statement's pre-check counts them.",
     ALTER_TABLE,
   ),
   SQLPG220: rule(
@@ -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";