@intentius/chant-lexicon-sql 0.116.0 → 0.117.0

package/src/postgres/parser.ts

@@ -2,8 +2,10 @@
  * A hand-written, lossless parser for the Postgres statements the dialect
  * declares (chant #3278, #3279): `CREATE SCHEMA`, `TABLE`, `INDEX`, `VIEW`,
  * `MATERIALIZED VIEW`, `SEQUENCE`, `TYPE ... AS ENUM`, `DOMAIN`, `EXTENSION`,
- * `FUNCTION`, `PROCEDURE` and `TRIGGER` (#3680), and `COMMENT ON` for those
- * objects.
+ * `FUNCTION`, `PROCEDURE` and `TRIGGER` (#3680), `POLICY` and `ROLE`, `GRANT`,
+ * `REVOKE` and `ALTER DEFAULT PRIVILEGES` on schemas, tables, columns,
+ * sequences and routines, `ALTER TABLE ... ROW LEVEL SECURITY` (#3681), and
+ * `COMMENT ON` for those objects.
  *
  * A function's or procedure's body is a string (`AS $$ ... $$`), kept
  * verbatim: Postgres stores it as written and prints it back unchanged. A
@@ -260,6 +262,58 @@ export interface TriggerNode {
   args: Span[];
 }
 
+export interface PolicyNode {
+  statement: "policy";
+  name: NameNode;
+  table: NameNode;
+  /** `AS PERMISSIVE` (true, the default) or `AS RESTRICTIVE` (false). */
+  permissive?: boolean;
+  command?: "ALL" | "SELECT" | "INSERT" | "UPDATE" | "DELETE";
+  /** `TO role, ...`: role names, `public` for PUBLIC. */
+  roles: Array<{ name: string; span: Span }>;
+  /** `USING (...)`, parentheses excluded. */
+  using?: Span;
+  /** `WITH CHECK (...)`, parentheses excluded. */
+  check?: Span;
+}
+
+export interface RoleNode {
+  statement: "role";
+  name: NameNode;
+  /** The options, each by its key word (`LOGIN`, `NOINHERIT`, `CONNECTION LIMIT`, `VALID UNTIL`), with a value where it takes one. */
+  options: Array<{ option: string; value?: Span }>;
+}
+
+/** What a GRANT or REVOKE is on: an object kind, or (for default privileges) a kind of object created later. */
+export type GrantTarget = "TABLE" | "SEQUENCE" | "SCHEMA" | "FUNCTION" | "PROCEDURE" | "ROUTINE" | "TABLES" | "SEQUENCES" | "FUNCTIONS" | "ROUTINES" | "TYPES" | "SCHEMAS";
+
+export interface GrantNode {
+  statement: "grant";
+  revoke: boolean;
+  /** `REVOKE GRANT OPTION FOR ...`. */
+  grantOptionFor: boolean;
+  /** Each privilege, upper case (`ALL` for ALL [PRIVILEGES]), with the columns it is limited to. */
+  privileges: Array<{ privilege: string; columns: Array<{ name: string; span: Span }> }>;
+  on: GrantTarget;
+  /** The objects, each with a routine's parameter list as written (parentheses excluded). Empty for default privileges. */
+  objects: Array<{ name: NameNode; args?: Span }>;
+  /** Role names, `public` for PUBLIC. */
+  grantees: Array<{ name: string; span: Span }>;
+  withGrantOption: boolean;
+  /** `ALTER DEFAULT PRIVILEGES FOR ROLE ...`. */
+  forRoles?: Array<{ name: string; span: Span }>;
+  /** `ALTER DEFAULT PRIVILEGES IN SCHEMA ...`. */
+  inSchemas?: Array<{ name: string; span: Span }>;
+  /** True for `ALTER DEFAULT PRIVILEGES`. */
+  defaults: boolean;
+}
+
+export interface RowSecurityNode {
+  statement: "rowSecurity";
+  table: NameNode;
+  action: "ENABLE" | "DISABLE" | "FORCE" | "NO FORCE";
+}
+
 export interface CommentNode {
   statement: "comment";
   /** TABLE, COLUMN, INDEX, VIEW, MATERIALIZED VIEW, SEQUENCE, TYPE, DOMAIN, SCHEMA, EXTENSION, FUNCTION, PROCEDURE, TRIGGER, CONSTRAINT, DOMAIN CONSTRAINT. */
@@ -284,6 +338,10 @@ export type StatementNode =
   | ExtensionNode
   | RoutineNode
   | TriggerNode
+  | PolicyNode
+  | RoleNode
+  | GrantNode
+  | RowSecurityNode
   | CommentNode;
 
 const isNameToken = (t: Token | undefined): boolean =>
@@ -805,8 +863,15 @@ class PgParser extends SqlCursor {
 
   parse(): StatementNode {
     if (this.accept("COMMENT")) return this.comment();
+    if (this.accept("GRANT")) return this.grant(false, false);
+    if (this.accept("REVOKE")) return this.grant(true, false);
+    if (this.acceptSeq("ALTER", "DEFAULT", "PRIVILEGES")) return this.defaultPrivileges();
+    if (this.acceptSeq("ALTER", "TABLE")) return this.rowSecurity();
     this.expect("CREATE");
     const orReplace = this.acceptSeq("OR", "REPLACE");
+    if (!orReplace && this.accept("POLICY")) return this.policy();
+    if (!orReplace && this.accept("ROLE")) return this.role();
+    if (!orReplace && kw(this.peek(), "USER", "GROUP")) this.fail("expected ROLE (declare a role with CREATE ROLE; LOGIN is an option of it)");
     if (this.accept("FUNCTION")) return this.routine("function", orReplace);
     if (this.accept("PROCEDURE")) return this.routine("procedure", orReplace);
     if (this.accept("TRIGGER")) return this.trigger(orReplace, false);
@@ -825,7 +890,7 @@ class PgParser extends SqlCursor {
     const recursive = this.accept("RECURSIVE");
     if (!orReplace && !recursive && persistence === undefined && this.acceptSeq("MATERIALIZED", "VIEW")) return this.view(true, false, false, false);
     if (this.accept("VIEW")) return this.view(false, orReplace, persistence === "temporary", recursive);
-    return this.fail("expected SCHEMA, TABLE, INDEX, VIEW, MATERIALIZED VIEW, SEQUENCE, TYPE, DOMAIN, EXTENSION, FUNCTION, PROCEDURE or TRIGGER");
+    return this.fail("expected SCHEMA, TABLE, INDEX, VIEW, MATERIALIZED VIEW, SEQUENCE, TYPE, DOMAIN, EXTENSION, FUNCTION, PROCEDURE, TRIGGER, POLICY or ROLE");
   }
 
   private schema(): SchemaNode {
@@ -1306,6 +1371,165 @@ class PgParser extends SqlCursor {
     return node;
   }
 
+  /** A role name where one is granted to or named: an identifier, an interpolation, or PUBLIC (`public`). */
+  private roleSpec(what = "a role name"): { name: string; span: Span } {
+    const t = this.peek();
+    if (kw(t, "CURRENT_USER", "CURRENT_ROLE", "SESSION_USER")) this.fail(`expected ${what} (name the role: ${t!.text.toUpperCase()} is whichever role runs the statement)`);
+    if (kw(t, "PUBLIC")) {
+      const i = this.idx();
+      this.p++;
+      return { name: "public", span: { from: i, to: i + 1, refs: [] } };
+    }
+    const n = this.next();
+    if (!isNameToken(n)) this.fail(`expected ${what}`, n);
+    const i = this.idx(-1);
+    return { name: n.kind === "ref" ? "" : identValue(n), span: { from: i, to: i + 1, refs: n.kind === "ref" ? [n.part] : [] } };
+  }
+
+  private roleList(what?: string): Array<{ name: string; span: Span }> {
+    const out = [this.roleSpec(what)];
+    while (this.acceptPunct(",")) out.push(this.roleSpec(what));
+    return out;
+  }
+
+  private policy(): PolicyNode {
+    const { text, span } = this.nameTok("a policy name");
+    this.expect("ON");
+    const node: PolicyNode = { statement: "policy", name: { pieces: [text], span }, table: this.qualifiedName("a table name"), roles: [] };
+    if (this.accept("AS")) {
+      if (this.accept("PERMISSIVE")) node.permissive = true;
+      else {
+        this.expect("RESTRICTIVE");
+        node.permissive = false;
+      }
+    }
+    if (this.accept("FOR")) {
+      if (!this.accept("ALL", "SELECT", "INSERT", "UPDATE", "DELETE")) this.fail("expected ALL, SELECT, INSERT, UPDATE or DELETE");
+      node.command = this.lastSeen()!.text.toUpperCase() as PolicyNode["command"];
+    }
+    if (this.accept("TO")) node.roles = this.roleList();
+    if (this.accept("USING")) {
+      if (!this.isPunct("(")) this.fail("expected '('");
+      node.using = this.parenthesized();
+    }
+    if (this.acceptSeq("WITH", "CHECK")) {
+      if (!this.isPunct("(")) this.fail("expected '('");
+      node.check = this.parenthesized();
+    }
+    return node;
+  }
+
+  private role(): RoleNode {
+    const { text, span } = this.nameTok("a role name");
+    const node: RoleNode = { statement: "role", name: { pieces: [text], span }, options: [] };
+    this.accept("WITH");
+    const FLAGS = ["SUPERUSER", "NOSUPERUSER", "CREATEDB", "NOCREATEDB", "CREATEROLE", "NOCREATEROLE", "INHERIT", "NOINHERIT", "LOGIN", "NOLOGIN", "REPLICATION", "NOREPLICATION", "BYPASSRLS", "NOBYPASSRLS"];
+    for (;;) {
+      if (this.atEnd()) return node;
+      if (kw(this.peek(), ...FLAGS)) node.options.push({ option: this.next().text.toUpperCase() });
+      else if (this.acceptSeq("CONNECTION", "LIMIT")) {
+        const from = this.idx();
+        if (this.isOp("-")) this.p++;
+        const t = this.next();
+        if (t.kind !== "number" && t.kind !== "ref") this.fail("expected a number", t);
+        node.options.push({ option: "CONNECTION LIMIT", value: this.span(from, t.kind === "ref" ? [t.part] : []) });
+      } else if (kw(this.peek(), "PASSWORD", "ENCRYPTED", "UNENCRYPTED") || this.is("VALID", "UNTIL")) {
+        this.fail("expected a role option (a password is the environment's secret, never a declaration's: set it where the environment's credentials are kept)");
+      } else if (kw(this.peek(), "IN", "ROLE", "ADMIN", "USER", "SYSID")) {
+        this.fail("expected a role option (who is a member of which role is the environment's: grant memberships where the roles are provisioned)");
+      } else return this.fail("expected a role option");
+    }
+  }
+
+  /** `GRANT|REVOKE privileges ON target TO|FROM roles`, after GRANT or REVOKE; for default privileges, `on` is a plural kind and there are no objects. */
+  private grant(revoke: boolean, defaults: boolean): GrantNode {
+    const grantOptionFor = revoke && this.acceptSeq("GRANT", "OPTION", "FOR");
+    const privileges: GrantNode["privileges"] = [];
+    if (this.accept("ALL")) {
+      this.accept("PRIVILEGES");
+      const columns = this.isPunct("(") ? this.nameList() : [];
+      privileges.push({ privilege: "ALL", columns });
+    } else {
+      const KNOWN = ["SELECT", "INSERT", "UPDATE", "DELETE", "TRUNCATE", "REFERENCES", "TRIGGER", "MAINTAIN", "USAGE", "CREATE", "EXECUTE"];
+      do {
+        const t = this.next();
+        if (!kw(t, ...KNOWN)) {
+          if (t.kind === "ident" || t.kind === "qident" || t.kind === "ref") {
+            this.fail("expected a privilege (a role granted to a role is membership, which is the environment's: grant it where the roles are provisioned)", t);
+          }
+          this.fail("expected a privilege", t);
+        }
+        privileges.push({ privilege: t.text.toUpperCase(), columns: this.isPunct("(") ? this.nameList() : [] });
+      } while (this.acceptPunct(","));
+    }
+    this.expect("ON");
+    const node: GrantNode = { statement: "grant", revoke, grantOptionFor, privileges, on: "TABLE", objects: [], grantees: [], withGrantOption: false, defaults };
+    if (defaults) {
+      if (!this.accept("TABLES", "SEQUENCES", "FUNCTIONS", "ROUTINES", "TYPES", "SCHEMAS")) this.fail("expected TABLES, SEQUENCES, FUNCTIONS, ROUTINES, TYPES or SCHEMAS");
+      node.on = this.lastSeen()!.text.toUpperCase() as GrantTarget;
+    } else {
+      if (this.accept("ALL")) {
+        this.fail("expected an object (ALL ... IN SCHEMA grants on what exists when it runs; grant on each declared object, and use ALTER DEFAULT PRIVILEGES for what is created later)", this.lastSeen());
+      }
+      if (kw(this.peek(), "DATABASE", "DOMAIN", "TYPE", "LANGUAGE", "LARGE", "TABLESPACE", "FOREIGN", "PARAMETER")) {
+        this.fail("expected TABLE, SEQUENCE, SCHEMA, FUNCTION, PROCEDURE or ROUTINE (privileges on this kind of object are not declared)");
+      }
+      if (this.accept("TABLE", "SEQUENCE", "SCHEMA", "FUNCTION", "PROCEDURE", "ROUTINE")) node.on = this.lastSeen()!.text.toUpperCase() as GrantTarget;
+      const routine = node.on === "FUNCTION" || node.on === "PROCEDURE" || node.on === "ROUTINE";
+      do {
+        const name = this.qualifiedName(node.on === "SCHEMA" ? "a schema name" : "an object name");
+        node.objects.push(routine && this.isPunct("(") ? { name, args: this.parenthesized() } : { name });
+      } while (this.acceptPunct(","));
+    }
+    if (revoke) this.expect("FROM");
+    else this.expect("TO");
+    this.accept("GROUP");
+    node.grantees = this.roleList();
+    if (!revoke && this.acceptSeq("WITH", "GRANT", "OPTION")) node.withGrantOption = true;
+    if (this.acceptSeq("GRANTED", "BY")) this.fail("expected the end of the statement (GRANTED BY names another grantor; chant grants as the role it runs as)", this.lastSeen());
+    if (revoke && this.accept("CASCADE", "RESTRICT")) {
+      if (this.lastSeen()!.text.toUpperCase() === "CASCADE") this.fail("expected the end of the statement (CASCADE revokes what others granted from it; revoke each grant)", this.lastSeen());
+    }
+    return node;
+  }
+
+  private defaultPrivileges(): GrantNode {
+    let forRoles: GrantNode["forRoles"];
+    let inSchemas: GrantNode["inSchemas"];
+    for (;;) {
+      if (this.accept("FOR")) {
+        this.expect("ROLE", "USER");
+        forRoles = this.roleList();
+      } else if (this.acceptSeq("IN", "SCHEMA")) {
+        inSchemas = [];
+        do inSchemas.push((({ text, span }) => ({ name: text, span }))(this.nameTok("a schema name")));
+        while (this.acceptPunct(","));
+      } else break;
+    }
+    let node: GrantNode;
+    if (this.accept("GRANT")) node = this.grant(false, true);
+    else {
+      this.expect("REVOKE");
+      node = this.grant(true, true);
+    }
+    return { ...node, ...(forRoles ? { forRoles } : {}), ...(inSchemas ? { inSchemas } : {}) };
+  }
+
+  private rowSecurity(): RowSecurityNode {
+    this.accept("ONLY");
+    const table = this.qualifiedName("a table name");
+    let action: RowSecurityNode["action"];
+    if (this.accept("ENABLE")) action = "ENABLE";
+    else if (this.accept("DISABLE")) action = "DISABLE";
+    else if (this.accept("FORCE")) action = "FORCE";
+    else if (this.acceptSeq("NO", "FORCE")) action = "NO FORCE";
+    else return this.fail("expected ENABLE, DISABLE, FORCE or NO FORCE ROW LEVEL SECURITY (a table's other changes are its CREATE TABLE's)");
+    this.expect("ROW");
+    this.expect("LEVEL");
+    this.expect("SECURITY");
+    return { statement: "rowSecurity", table, action };
+  }
+
   private comment(): CommentNode {
     this.expect("ON");
     let objectType: string;
@@ -1318,16 +1542,19 @@ class PgParser extends SqlCursor {
       this.expect("ON");
       if (this.accept("DOMAIN")) objectType = "DOMAIN CONSTRAINT";
       on = this.qualifiedName("a table name");
-    } else if (this.accept("TRIGGER")) {
-      objectType = "TRIGGER";
-      target = this.qualifiedName("a trigger name");
+    } else if (this.accept("TRIGGER", "POLICY")) {
+      objectType = this.lastSeen()!.text.toUpperCase();
+      target = this.qualifiedName(`a ${objectType.toLowerCase()} name`);
       this.expect("ON");
       on = this.qualifiedName("a table name");
+    } else if (this.accept("ROLE")) {
+      objectType = "ROLE";
+      target = this.qualifiedName("a role name");
     } else {
       if (this.acceptSeq("MATERIALIZED", "VIEW")) objectType = "MATERIALIZED VIEW";
       else if (this.accept("TABLE", "COLUMN", "INDEX", "VIEW", "SEQUENCE", "TYPE", "DOMAIN", "SCHEMA", "EXTENSION", "FUNCTION", "PROCEDURE")) {
         objectType = this.tokens[this.idx(-1)]!.text.toUpperCase();
-      } else return this.fail("expected TABLE, COLUMN, INDEX, VIEW, MATERIALIZED VIEW, SEQUENCE, TYPE, DOMAIN, SCHEMA, EXTENSION, FUNCTION, PROCEDURE, TRIGGER or CONSTRAINT");
+      } else return this.fail("expected TABLE, COLUMN, INDEX, VIEW, MATERIALIZED VIEW, SEQUENCE, TYPE, DOMAIN, SCHEMA, EXTENSION, FUNCTION, PROCEDURE, TRIGGER, POLICY, ROLE or CONSTRAINT");
       target = this.qualifiedName("an object name");
       if ((objectType === "FUNCTION" || objectType === "PROCEDURE") && this.isPunct("(")) args = this.parenthesized();
     }
@@ -1357,7 +1584,19 @@ class PgParser extends SqlCursor {
 }
 
 const describe = (n: StatementNode): string =>
-  n.statement === "comment" ? "COMMENT ON" : n.statement === "enum" ? "type definition" : `${n.statement} definition`;
+  n.statement === "comment"
+    ? "COMMENT ON"
+    : n.statement === "enum"
+      ? "type definition"
+      : n.statement === "grant"
+        ? n.defaults
+          ? "ALTER DEFAULT PRIVILEGES"
+          : n.revoke
+            ? "REVOKE"
+            : "GRANT"
+        : n.statement === "rowSecurity"
+          ? "ALTER TABLE"
+          : `${n.statement} definition`;
 
 /**
  * Parse a template: one CREATE, optionally followed by COMMENT ON statements,

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);
 }