@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/postgres/import/generator.ts

@@ -11,7 +11,10 @@
  *   (`nextval('app.invoice_seq'::regclass)` is `nextval(${invoiceSeq})`);
  * - the schema part of the object's own name, wherever the name appears,
  *   becomes the schema's export (`CREATE TABLE ${appSchema}.users`);
- * - an extension's `WITH SCHEMA` names the schema's export.
+ * - an extension's `WITH SCHEMA`, a grant's `ON SCHEMA` and default
+ *   privileges' `IN SCHEMA` name the schema's export;
+ * - a grant's object becomes the object's export (`GRANT SELECT ON TABLE
+ *   ${orders} TO reader`), a policy's table its table's.
  *
  * Columns stay text, as they do for ClickHouse (#3236): which relation a bare
  * column belongs to is the server's to resolve. One file, because the
@@ -21,16 +24,24 @@
 import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
 import type { TemplateIR } from "@intentius/chant/import/parser";
 import { isTrivia, tokenizeText, type Token } from "../tokens";
-import { identValue } from "../parser";
+import { identValue, parseStatements, type NameNode, type StatementNode } from "../parser";
 import { POSTGRES_ENTITY_TYPES } from "../entity-types";
 
-interface Item {
+/** One object a template is written for, or (with no `ddl` read) one a template may reference. */
+export interface PgTemplateItem {
   exportName: string;
   type: string;
   schema?: string;
   name: string;
   ddl: string;
 }
+type Item = PgTemplateItem;
+
+/** A template's text: `parts` (template-literal safe) around one interpolation per entry of `refs`, an export name. */
+export interface TemplateBody {
+  parts: string[];
+  refs: string[];
+}
 
 const TAG: Record<string, string> = {
   [POSTGRES_ENTITY_TYPES.schema]: "schema",
@@ -45,39 +56,85 @@ const TAG: Record<string, string> = {
   [POSTGRES_ENTITY_TYPES.function]: "func",
   [POSTGRES_ENTITY_TYPES.procedure]: "procedure",
   [POSTGRES_ENTITY_TYPES.trigger]: "trigger",
+  [POSTGRES_ENTITY_TYPES.policy]: "policy",
+  [POSTGRES_ENTITY_TYPES.role]: "role",
+  [POSTGRES_ENTITY_TYPES.grant]: "grant",
+  [POSTGRES_ENTITY_TYPES.defaultPrivileges]: "grant",
 };
 
+/** The tag each entity type is declared with (`table`, `func`, ...). */
+export const POSTGRES_TAG_OF: Readonly<Record<string, string>> = TAG;
+
 /** Text that sits inside a template literal: a backquote and `${` escaped. */
 const templateSafe = (s: string) => s.replace(/\\(?=`|\$\{)/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
 
 const isName = (t: Token | undefined) => t !== undefined && (t.kind === "ident" || t.kind === "qident");
 
-/** `'app.invoice_seq'` as the qualified name it holds. */
+/** `'app.invoice_seq'` as the qualified name it holds, or the bare name when unqualified. */
 function regclassName(t: Token): string | undefined {
   if (t.kind !== "string" || !/^'.*'$/s.test(t.text)) return undefined;
   const inner = t.text.slice(1, -1).replace(/''/g, "'");
   const pieces = inner.match(/"(?:[^"]|"")*"|[^.]+/g)?.map((p) => identValue(p)) ?? [];
-  return pieces.length === 2 ? `${pieces[0]}.${pieces[1]}` : pieces.length === 1 ? `public.${pieces[0]}` : undefined;
+  return pieces.length === 2 ? `${pieces[0]}.${pieces[1]}` : pieces.length === 1 ? pieces[0] : undefined;
 }
 
-function templateBody(item: Item, byQualified: Map<string, Item>, schemaExport: Map<string, string>): { body: string; refs: string[] } {
+/** Words after which a bare name is a relation: `FROM t`, `JOIN t`, `REFERENCES t`. */
+const RELATION_WORDS = new Set(["FROM", "JOIN", "REFERENCES"]);
+
+/**
+ * The tokens where a bare (unqualified) name is another object's: a column's
+ * or a domain's type, the table of an index, trigger or policy, a trigger's
+ * function, a grant's objects. A `FROM`, `JOIN` or `REFERENCES` before a
+ * name is read off the tokens directly.
+ */
+function bareSpots(tokens: Token[]): Set<number> {
+  const out = new Set<number>();
+  let nodes: StatementNode[];
+  try {
+    nodes = parseStatements(tokens);
+  } catch {
+    return out;
+  }
+  const first = (from: number, to: number) => {
+    for (let i = from; i < to; i++) if (!isTrivia(tokens[i]!)) return out.add(i);
+    return out;
+  };
+  const name = (n: NameNode | undefined) => n && n.span.to - n.span.from > 0 && first(n.span.from, n.span.to);
+  for (const node of nodes) {
+    if (node.statement === "table") for (const c of node.columns) if (c.type) first(c.type.from, c.type.to);
+    if (node.statement === "domain") first(node.type.from, node.type.to);
+    if (node.statement === "index" || node.statement === "policy") name(node.table);
+    if (node.statement === "trigger") {
+      name(node.table);
+      name(node.function);
+    }
+    if (node.statement === "grant") for (const o of node.objects) name(o.name);
+  }
+  return out;
+}
+
+function templateBody(item: Item, byQualified: Map<string, Item>, schemaExport: Map<string, string>): TemplateBody {
   const tokens = tokenizeText(item.ddl, 0);
   const sig: number[] = [];
   tokens.forEach((t, i) => {
     if (!isTrivia(t)) sig.push(i);
   });
-  const replace = new Map<number, { to: number; text: string; ref: string }>();
+  const spots = bareSpots(tokens);
+  const replace = new Map<number, { to: number; ref: string }>();
+  const isSelf = (target: Item) => target === item || (target.exportName === item.exportName && target.type === item.type);
   for (let k = 0; k < sig.length; k++) {
     const a = tokens[sig[k]!]!;
     const prev = tokens[sig[k - 1] ?? -1];
     if (prev?.kind === "punct" && prev.text === ".") continue;
     // A regclass literal: nextval('app.seq'::regclass) or 'app.t'::regclass.
     if (a.kind === "string" && tokens[sig[k + 1] ?? -1]?.text === "::" && tokens[sig[k + 2] ?? -1]?.text.toLowerCase() === "regclass") {
-      const target = byQualified.get(regclassName(a) ?? "");
-      if (target && target !== item) {
+      const held = regclassName(a) ?? "";
+      // An unqualified name is the object in `public`, as the server's own printing has it, else the unqualified object of that name.
+      const target = (!held.includes(".") ? byQualified.get(`public.${held}`) : undefined) ?? byQualified.get(held);
+      if (target && !isSelf(target)) {
         const fn = tokens[sig[k - 2] ?? -1];
         const inCall = prev?.text === "(" && fn?.kind === "ident" && /^(nextval|currval|setval)$/i.test(fn.text);
-        replace.set(sig[k]!, { to: inCall ? sig[k + 2]! + 1 : sig[k]! + 1, text: `\${${target.exportName}}`, ref: target.exportName });
+        replace.set(sig[k]!, { to: inCall ? sig[k + 2]! + 1 : sig[k]! + 1, ref: target.exportName });
         k += inCall ? 2 : 0;
         continue;
       }
@@ -85,39 +142,89 @@ function templateBody(item: Item, byQualified: Map<string, Item>, schemaExport:
     const dot = tokens[sig[k + 1] ?? -1];
     const b = tokens[sig[k + 2] ?? -1];
     if (!isName(a) || dot?.kind !== "punct" || dot.text !== "." || !isName(b)) {
-      // An extension's `WITH SCHEMA app`.
-      if (item.type === POSTGRES_ENTITY_TYPES.extension && isName(a) && prev?.kind === "ident" && prev.text.toUpperCase() === "SCHEMA") {
+      // An extension's `WITH SCHEMA app`, a grant's `ON SCHEMA app`, default privileges' `IN SCHEMA app`.
+      const bySchemaWord = item.type === POSTGRES_ENTITY_TYPES.extension || item.type === POSTGRES_ENTITY_TYPES.grant || item.type === POSTGRES_ENTITY_TYPES.defaultPrivileges;
+      if (bySchemaWord && isName(a) && prev?.kind === "ident" && prev.text.toUpperCase() === "SCHEMA") {
         const s = schemaExport.get(identValue(a));
-        if (s) replace.set(sig[k]!, { to: sig[k]! + 1, text: `\${${s}}`, ref: s });
+        if (s) replace.set(sig[k]!, { to: sig[k]! + 1, ref: s });
+        continue;
       }
+      // A bare name where an object is named: `REFERENCES users`, `ON users`, a column of type `status`.
+      const bare = isName(a) && (spots.has(sig[k]!) || (prev?.kind === "ident" && RELATION_WORDS.has(prev.text.toUpperCase())));
+      const target = bare ? byQualified.get(identValue(a)) : undefined;
+      if (target && !isSelf(target)) replace.set(sig[k]!, { to: sig[k]! + 1, ref: target.exportName });
       continue;
     }
     const schema = identValue(a);
     const name = identValue(b);
     const self = schema === item.schema && name === item.name;
     const target = byQualified.get(`${schema}.${name}`);
-    if (!self && target && target !== item) {
-      replace.set(sig[k]!, { to: sig[k + 2]! + 1, text: `\${${target.exportName}}`, ref: target.exportName });
+    if (!self && target && !isSelf(target)) {
+      replace.set(sig[k]!, { to: sig[k + 2]! + 1, ref: target.exportName });
       k += 2;
     } else if (self && schemaExport.has(schema)) {
-      replace.set(sig[k]!, { to: sig[k]! + 1, text: `\${${schemaExport.get(schema)}}`, ref: schemaExport.get(schema)! });
+      replace.set(sig[k]!, { to: sig[k]! + 1, ref: schemaExport.get(schema)! });
       k += 2;
     }
   }
-  let body = "";
+  const parts: string[] = [""];
   const refs: string[] = [];
   for (let i = 0; i < tokens.length; ) {
     const r = replace.get(i);
     if (r) {
-      body += r.text;
       refs.push(r.ref);
+      parts.push("");
       i = r.to;
       continue;
     }
-    body += templateSafe(tokens[i]!.text);
+    parts[parts.length - 1] += templateSafe(tokens[i]!.text);
     i++;
   }
-  return { body, refs };
+  return { parts, refs };
+}
+
+/** A template body as the text between the backquotes. */
+export const bodyText = (body: TemplateBody): string => body.parts.map((p, i) => (i === 0 ? p : `\${${body.refs[i - 1]}}${p}`)).join("");
+
+/**
+ * The template of each object in `items`, with the references to `targets`
+ * (the items themselves, and any object declared elsewhere that they may
+ * name) interpolated, and the items in the order a file declares them: each
+ * after what it references.
+ *
+ * A name is a reference where it is qualified (`app.users`), or bare where an
+ * object is named (`REFERENCES users`, `FROM users`, an index's table, a
+ * column's type) and an unqualified object has that name.
+ */
+export function postgresTemplates(items: readonly Item[], targets: readonly Item[] = items): { order: Item[]; bodies: Map<string, TemplateBody> } {
+  const byQualified = new Map<string, Item>();
+  const schemaExport = new Map<string, string>();
+  for (const it of targets) {
+    if (it.type === POSTGRES_ENTITY_TYPES.schema) schemaExport.set(it.name, it.exportName);
+    // An index or a trigger is never referenced by name in another object's DDL.
+    else if (it.type !== POSTGRES_ENTITY_TYPES.index && it.type !== POSTGRES_ENTITY_TYPES.trigger && it.type !== POSTGRES_ENTITY_TYPES.policy && it.type !== POSTGRES_ENTITY_TYPES.grant && it.type !== POSTGRES_ENTITY_TYPES.defaultPrivileges && it.type !== POSTGRES_ENTITY_TYPES.role && it.type !== POSTGRES_ENTITY_TYPES.extension) {
+      byQualified.set(it.schema ? `${it.schema}.${it.name}` : it.name, it);
+    }
+  }
+
+  const bodies = new Map(items.map((it) => [it.exportName, templateBody(it, byQualified, schemaExport)]));
+  const order: Item[] = [];
+  const done = new Set<string>();
+  const visiting = new Set<string>();
+  const byExport = new Map(items.map((it) => [it.exportName, it]));
+  const visit = (it: Item) => {
+    if (done.has(it.exportName) || visiting.has(it.exportName)) return;
+    visiting.add(it.exportName);
+    for (const ref of bodies.get(it.exportName)!.refs) {
+      const dep = byExport.get(ref);
+      if (dep) visit(dep);
+    }
+    visiting.delete(it.exportName);
+    done.add(it.exportName);
+    order.push(it);
+  };
+  for (const it of items) visit(it);
+  return { order, bodies };
 }
 
 const indent = (body: string) =>
@@ -143,37 +250,13 @@ export class PostgresGenerator implements TypeScriptGenerator {
       }));
     if (items.length === 0) return [];
 
-    const byQualified = new Map<string, Item>();
-    const schemaExport = new Map<string, string>();
-    for (const it of items) {
-      if (it.type === POSTGRES_ENTITY_TYPES.schema) schemaExport.set(it.name, it.exportName);
-      // An index or a trigger is never referenced by name in another object's DDL.
-      else if (it.schema && it.type !== POSTGRES_ENTITY_TYPES.index && it.type !== POSTGRES_ENTITY_TYPES.trigger) byQualified.set(`${it.schema}.${it.name}`, it);
-    }
-
-    const bodies = new Map(items.map((it) => [it.exportName, templateBody(it, byQualified, schemaExport)]));
-    const order: Item[] = [];
-    const done = new Set<string>();
-    const visiting = new Set<string>();
-    const byExport = new Map(items.map((it) => [it.exportName, it]));
-    const visit = (it: Item) => {
-      if (done.has(it.exportName) || visiting.has(it.exportName)) return;
-      visiting.add(it.exportName);
-      for (const ref of bodies.get(it.exportName)!.refs) {
-        const dep = byExport.get(ref);
-        if (dep) visit(dep);
-      }
-      visiting.delete(it.exportName);
-      done.add(it.exportName);
-      order.push(it);
-    };
-    for (const it of items) visit(it);
+    const { order, bodies } = postgresTemplates(items);
 
     const tags = [...new Set(order.map((it) => TAG[it.type]!))].sort();
     const lines: string[] = [];
     if (this.header) lines.push(...this.header.split("\n").map((l) => `// ${l}`), "");
     lines.push(`import { ${tags.join(", ")} } from "@intentius/chant-lexicon-sql/postgres";`, "");
-    for (const it of order) lines.push(`export const ${it.exportName} = ${TAG[it.type]}\`\n  ${indent(bodies.get(it.exportName)!.body)}\`;`, "");
+    for (const it of order) lines.push(`export const ${it.exportName} = ${TAG[it.type]}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
     return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
   }
 }

package/src/postgres/import/live-export.ts

@@ -11,6 +11,12 @@
  *   a declaration of them would have chant fight it.
  * - `verbatim` changes nothing yet: the printers already leave out what the
  *   server would add by itself.
+ * - Where the profile manages access (`sql.profiles.<env>.access`), the
+ *   policies and each table's row-level security come with the objects, and
+ *   the privileges on them and the default privileges are written as `grant`
+ *   declarations: the GRANT and REVOKE statements that take a new object's
+ *   privileges to what the server holds. Roles are the environment's and are
+ *   not imported.
  */
 
 import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
@@ -18,6 +24,7 @@ import { bindPostgres, type BindOptions } from "../live/bind";
 import { markProviderOwned, readLiveSchema } from "../live/catalog";
 import { objectsToIR, type ImportedPgObject } from "./ir";
 import { isChantManaged } from "../../core/ownership";
+import { importedAccess } from "../access/import";
 
 export interface ExportOptions extends Omit<BindOptions, "environment"> {
   environment: string;
@@ -31,8 +38,11 @@ export interface ExportOptions extends Omit<BindOptions, "environment"> {
 export async function exportResources(options: ExportOptions): Promise<ExportedTemplate> {
   const { target, client } = await bindPostgres(options);
   let live;
+  let access: ImportedPgObject[] = [];
   try {
-    live = markProviderOwned(await readLiveSchema(client, { schemas: target.schemas }), target.provider);
+    live = markProviderOwned(await readLiveSchema(client, { schemas: target.schemas, access: target.access === true }), target.provider);
+    // Where the profile manages access, the privileges on what is imported, and the default privileges, as grant declarations.
+    if (target.access === true && !options.selector) access = await importedAccess(client, live.filter((o) => !o.foreign && !o.unsupported && (!options.owned || isChantManaged(o.comment))), target.schemas);
   } finally {
     await client.end();
   }
@@ -53,5 +63,5 @@ export async function exportResources(options: ExportOptions): Promise<ExportedT
     }
     objects.push({ type: o.type, ...(o.schema ? { schema: o.schema } : {}), name: o.name, ddl: o.statement });
   }
-  return objectsToIR(objects, warnings) as ExportedTemplate;
+  return objectsToIR([...objects, ...access], warnings) as ExportedTemplate;
 }

package/src/postgres/live/bind.ts

@@ -8,6 +8,7 @@ import type { ChantConfig } from "@intentius/chant/config";
 import type { UnobservedReason } from "@intentius/chant/observation";
 import { connectPostgres, PostgresQueryError, type PostgresClient, type PostgresEndpoint } from "./client";
 import type { PostgresProvider } from "../providers/types";
+import { credentialSource, TokenSourceError } from "../../token-source";
 
 export interface PostgresTarget {
   endpoint: PostgresEndpoint;
@@ -21,6 +22,8 @@ export interface PostgresTarget {
   provider?: PostgresProvider;
   /** The apply's timeouts the profile sets (`lockTimeoutMs`, `statementTimeoutMs`, `scanTimeoutMs`); the applier's defaults otherwise. */
   timeouts?: { lockTimeoutMs?: number; statementTimeoutMs?: number; scanTimeoutMs?: number };
+  /** Whether chant manages access here (`sql.profiles.<env>.access`): policies, row-level security, the declared roles, grants and default privileges. */
+  access?: boolean;
 }
 
 export interface UnresolvedTarget {
@@ -56,12 +59,21 @@ export function resolvePostgresTarget(input: {
   if (profile && isPostgresUrl(profile.url)) {
     const source = `sql.profiles.${input.environment}`;
     const endpoint: PostgresEndpoint = { url: profile.url };
-    for (const key of ["user", "password"] as const) {
-      const ref = profile[key];
-      if (!ref) continue;
-      const value = env[ref.env];
-      if (value === undefined) return { reason: "no-credentials", detail: `${source}.${key} names ${ref.env}, which is not set` };
-      endpoint[key] = value;
+    if (profile.user) {
+      const value = env[profile.user.env];
+      if (value === undefined) return { reason: "no-credentials", detail: `${source}.user names ${profile.user.env}, which is not set` };
+      endpoint.user = value;
+    }
+    const password = profile.password;
+    if (password && "env" in password) {
+      const value = env[password.env];
+      if (value === undefined) return { reason: "no-credentials", detail: `${source}.password names ${password.env}, which is not set` };
+      endpoint.password = value;
+    } else if (password) {
+      if (password.token === "rds-iam" && endpoint.user === undefined) {
+        return { reason: "no-credentials", detail: `${source}.password is an rds-iam token, which is minted for one user, and ${source}.user is not set` };
+      }
+      endpoint.token = credentialSource(password, { url: profile.url, ...(endpoint.user !== undefined ? { user: endpoint.user } : {}), env, source: `${source}.password` });
     }
     const timeouts = Object.fromEntries(
       (["lockTimeoutMs", "statementTimeoutMs", "scanTimeoutMs"] as const).filter((k) => profile[k] !== undefined).map((k) => [k, profile[k]]),
@@ -72,6 +84,7 @@ export function resolvePostgresTarget(input: {
       ...(profile.schemas ? { schemas: profile.schemas } : {}),
       defaultSchema: profile.defaultSchema ?? "public",
       ...(Object.keys(timeouts).length > 0 ? { timeouts } : {}),
+      ...(profile.access === true ? { access: true } : {}),
     });
   }
   const url = env.POSTGRES_URL;
@@ -139,6 +152,7 @@ const CREDENTIAL_STATES = new Set(["28000", "28P01", "42501"]);
 /** What a failed bind or read means, in the observation vocabulary. */
 export function classifyPostgresFailure(err: unknown): { reason: UnobservedReason; detail: string } {
   if (err instanceof PostgresBindingError) return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+  if (err instanceof TokenSourceError) return { reason: "no-credentials", detail: err.message };
   if (err instanceof PostgresQueryError && err.code && CREDENTIAL_STATES.has(err.code)) {
     return { reason: "no-credentials", detail: `${err.message} (the server refused the credentials, SQLSTATE ${err.code})` };
   }

package/src/postgres/live/catalog.ts

@@ -93,6 +93,15 @@ export interface LivePgObject {
 export interface SchemaScope {
   /** The schemas in scope; undefined is every schema but the server's own and `public`'s own objects included. */
   schemas?: readonly string[];
+  /**
+   * Whether access is read (`sql.profiles.<env>.access`): the policies on the
+   * tables in scope, each table's row-level security, and the roles named in
+   * `roles`. Off, none of it is read, so a project that manages access
+   * elsewhere sees none of it.
+   */
+  access?: boolean;
+  /** The roles to read, when access is: the declared ones. A role is the cluster's, never read otherwise. */
+  roles?: readonly string[];
 }
 
 type Row = Record<string, unknown>;
@@ -193,8 +202,8 @@ const seqParams = (r: Row): SequenceParams => ({
 /**
  * Every object in scope, in a stable order: schemas, extensions, enums,
  * domains, sequences, tables, views and materialized views, indexes,
- * functions and procedures, triggers; each kind by schema then name, in byte
- * order.
+ * functions and procedures, triggers, and where access is read, policies and
+ * the declared roles; each kind by schema then name, in byte order.
  */
 export async function readLiveSchema(client: PostgresClient, scope: SchemaScope = {}): Promise<LivePgObject[]> {
   const out: LivePgObject[] = [];
@@ -326,6 +335,7 @@ export async function readLiveSchema(client: PostgresClient, scope: SchemaScope
                   FROM pg_catalog.pg_inherits i JOIN pg_catalog.pg_class pc ON pc.oid = i.inhparent JOIN pg_catalog.pg_namespace pn ON pn.oid = pc.relnamespace
                   WHERE i.inhrelid = c.oid ORDER BY i.inhseqno) AS parents,
             c.reloptions AS reloptions, (SELECT a.amname FROM pg_catalog.pg_am a WHERE a.oid = c.relam) AS am,
+            c.relrowsecurity AS rowsecurity, c.relforcerowsecurity AS forcerowsecurity,
             (SELECT ts.spcname FROM pg_catalog.pg_tablespace ts WHERE ts.oid = c.reltablespace) AS tablespace,
             pg_catalog.obj_description(c.oid, 'pg_class') AS comment
      FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
@@ -492,7 +502,13 @@ export async function readLiveSchema(client: PostgresClient, scope: SchemaScope
       oid: rel,
       ...(str(t.comment) ? { comment: str(t.comment) } : {}),
       ...(FOREIGN_TABLES[String(t.name)] ? { foreign: FOREIGN_TABLES[String(t.name)] } : {}),
-      statement: [create, ...commentOn(`TABLE ${q}`, t.comment), ...commentLines].join(";\n"),
+      statement: [
+        create,
+        ...(scope.access && t.rowsecurity === true ? [`ALTER TABLE ${q} ENABLE ROW LEVEL SECURITY`] : []),
+        ...(scope.access && t.forcerowsecurity === true ? [`ALTER TABLE ${q} FORCE ROW LEVEL SECURITY`] : []),
+        ...commentOn(`TABLE ${q}`, t.comment),
+        ...commentLines,
+      ].join(";\n"),
     });
   }
 
@@ -630,6 +646,66 @@ export async function readLiveSchema(client: PostgresClient, scope: SchemaScope
     }
   }
 
+  if (scope.access) {
+    // Policies, on the tables in scope.
+    const policies = await client.query<Row>(
+      `SELECT p.oid::text AS oid, n.nspname AS schema, c.relname AS table_name, p.polname AS name, p.polpermissive AS permissive, p.polcmd AS cmd,
+              ARRAY(SELECT CASE WHEN r = 0 THEN 'PUBLIC' ELSE pg_catalog.quote_ident(pg_catalog.pg_get_userbyid(r)) END FROM pg_catalog.unnest(p.polroles) r ORDER BY 1) AS roles,
+              pg_catalog.pg_get_expr(p.polqual, p.polrelid, true) AS qual, pg_catalog.pg_get_expr(p.polwithcheck, p.polrelid, true) AS withcheck,
+              pg_catalog.obj_description(p.oid, 'pg_policy') AS comment
+       FROM pg_catalog.pg_policy p JOIN pg_catalog.pg_class c ON c.oid = p.polrelid JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+       WHERE ${s.sql} AND ${notExtensionOwned("pg_class", "c.oid")}
+       ORDER BY n.nspname ${C}, c.relname ${C}, p.polname ${C}`,
+      s.params,
+    );
+    const COMMAND: Record<string, string> = { r: "SELECT", a: "INSERT", w: "UPDATE", d: "DELETE" };
+    for (const r of policies) {
+      const table = qname(String(r.schema), String(r.table_name));
+      const roles = (r.roles as string[] | null) ?? [];
+      const parts = [`CREATE POLICY ${quoteIdent(String(r.name))} ON ${table}`];
+      if (r.permissive === false) parts.push("AS RESTRICTIVE");
+      if (COMMAND[String(r.cmd)]) parts.push(`FOR ${COMMAND[String(r.cmd)]}`);
+      if (!(roles.length === 1 && roles[0] === "PUBLIC")) parts.push(`TO ${roles.join(", ")}`);
+      if (str(r.qual)) parts.push(`USING (${r.qual})`);
+      if (str(r.withcheck)) parts.push(`WITH CHECK (${r.withcheck})`);
+      out.push({
+        type: POSTGRES_ENTITY_TYPES.policy,
+        schema: String(r.schema),
+        name: String(r.name),
+        oid: String(r.oid),
+        signature: ` ON ${table}`,
+        ...(str(r.comment) ? { comment: str(r.comment) } : {}),
+        statement: [parts.join(" "), ...commentOn(`POLICY ${quoteIdent(String(r.name))} ON ${table}`, r.comment)].join(";\n"),
+      });
+    }
+
+    // The declared roles, by name: a role is the cluster's, and the ones the declarations do not name are the environment's.
+    if (scope.roles && scope.roles.length > 0) {
+      const roles = await client.query<Row>(
+        `SELECT r.oid::text AS oid, r.rolname AS name, r.rolsuper AS superuser, r.rolinherit AS inherit, r.rolcreaterole AS createrole, r.rolcreatedb AS createdb,
+                r.rolcanlogin AS login, r.rolreplication AS replication, r.rolbypassrls AS bypassrls, r.rolconnlimit AS connlimit,
+                pg_catalog.shobj_description(r.oid, 'pg_authid') AS comment
+         FROM pg_catalog.pg_roles r WHERE r.rolname = ANY($1::text[]) ORDER BY r.rolname ${C}`,
+        [[...scope.roles]],
+      );
+      for (const r of roles) {
+        const words: string[] = [];
+        for (const [k, dflt] of [["superuser", false], ["createdb", false], ["createrole", false], ["inherit", true], ["login", false], ["replication", false], ["bypassrls", false]] as const) {
+          if ((r[k] === true) !== dflt) words.push(r[k] === true ? k.toUpperCase() : `NO${k.toUpperCase()}`);
+        }
+        if (Number(r.connlimit) !== -1) words.push(`CONNECTION LIMIT ${Number(r.connlimit)}`);
+        const name = quoteIdent(String(r.name));
+        out.push({
+          type: POSTGRES_ENTITY_TYPES.role,
+          name: String(r.name),
+          oid: String(r.oid),
+          ...(str(r.comment) ? { comment: str(r.comment) } : {}),
+          statement: [`CREATE ROLE ${name}${words.length > 0 ? ` WITH ${words.join(" ")}` : ""}`, ...commentOn(`ROLE ${name}`, r.comment)].join(";\n"),
+        });
+      }
+    }
+  }
+
   return out;
 }
 

package/src/postgres/live/client.ts

@@ -8,11 +8,15 @@
  * search path.
  */
 
+import type { CredentialSource } from "../../token-source";
+
 export interface PostgresEndpoint {
   /** A `postgres://` connection URL, without a password. */
   url: string;
   user?: string;
   password?: string;
+  /** Mints the password at each connect, in place of `password` (a profile's token source, #3685). */
+  token?: CredentialSource;
 }
 
 /** What chant reads and writes through: one connection. */
@@ -54,7 +58,8 @@ export async function connectPostgres(endpoint: PostgresEndpoint, options: { app
   // node-postgres lets the connection string's fields win over the config's, so the credentials go into the URL.
   const url = new URL(endpoint.url);
   if (endpoint.user !== undefined) url.username = encodeURIComponent(endpoint.user);
-  if (endpoint.password !== undefined) url.password = encodeURIComponent(endpoint.password);
+  const password = endpoint.token ? await endpoint.token.get() : endpoint.password;
+  if (password !== undefined) url.password = encodeURIComponent(password);
   const client = new pg.Client({ connectionString: url.toString(), application_name: options.applicationName ?? "chant" });
   // A server that goes away emits an error event; the next query fails with it instead of the process crashing.
   client.on("error", () => undefined);
@@ -63,7 +68,10 @@ export async function connectPostgres(endpoint: PostgresEndpoint, options: { app
     await client.query("SELECT pg_catalog.set_config('search_path', '', false)");
   } catch (err) {
     await client.end().catch(() => undefined);
-    throw wrap(err);
+    const wrapped = wrap(err);
+    // A refused token is not reused: the next connect mints another.
+    if (endpoint.token && (wrapped.code === "28P01" || wrapped.code === "28000")) endpoint.token.invalidate();
+    throw wrapped;
   }
   let ended = false;
   return {

package/src/postgres/live/describe-resources.ts

@@ -41,15 +41,30 @@ interface Bound {
  */
 export function declaredAddress(entity: { type: string; props: Record<string, unknown> }, defaultSchema: string): { schema?: string; name: string; signature?: string } {
   const name = String(entity.props.name ?? "");
-  if (entity.type === POSTGRES_ENTITY_TYPES.schema || entity.type === POSTGRES_ENTITY_TYPES.extension) return { name };
+  if (entity.type === POSTGRES_ENTITY_TYPES.schema || entity.type === POSTGRES_ENTITY_TYPES.extension || entity.type === POSTGRES_ENTITY_TYPES.role) return { name };
   const schema = typeof entity.props.schema === "string" ? entity.props.schema : identValue(defaultSchema);
-  if (entity.type === POSTGRES_ENTITY_TYPES.function || entity.type === POSTGRES_ENTITY_TYPES.procedure || entity.type === POSTGRES_ENTITY_TYPES.trigger) {
+  if (entity.type === POSTGRES_ENTITY_TYPES.function || entity.type === POSTGRES_ENTITY_TYPES.procedure || entity.type === POSTGRES_ENTITY_TYPES.trigger || entity.type === POSTGRES_ENTITY_TYPES.policy) {
     const signature = canonicalPgObject(entity.type, entity.props, defaultSchema).signature;
     return { schema, name, ...(signature !== undefined ? { signature } : {}) };
   }
   return { schema, name };
 }
 
+/**
+ * Why an access declaration is not observed one by one: a grant or default
+ * privileges, which `chant sql plan` compares as the access they add up to;
+ * a policy or role where the profile does not manage access.
+ */
+export function accessUnobserved(type: string, managed: boolean): { reason: "unsupported-kind" | "filtered"; detail: string } | undefined {
+  if (type === POSTGRES_ENTITY_TYPES.grant || type === POSTGRES_ENTITY_TYPES.defaultPrivileges) {
+    return { reason: "unsupported-kind", detail: "a grant is compared as the privileges the declarations add up to, by chant sql plan and the applier, not one statement at a time" };
+  }
+  if (!managed && (type === POSTGRES_ENTITY_TYPES.policy || type === POSTGRES_ENTITY_TYPES.role)) {
+    return { reason: "filtered", detail: "access is not managed in this environment (sql.profiles.<env>.access)" };
+  }
+  return undefined;
+}
+
 /** A schema scope for the catalog read: the profile's schemas, else every schema the declarations name and the default one. */
 export function scopeFor(target: PostgresTarget, entities: ReadonlyArray<{ type: string; props: Record<string, unknown> }>): string[] | undefined {
   if (target.schemas) return target.schemas;
@@ -68,7 +83,14 @@ function adapter(options: BindOptions & { owned?: boolean; declared: DeclaredEnt
     async bind() {
       const { target, client } = await bindPostgres(options);
       try {
-        const live = markProviderOwned(await readLiveSchema(client, { schemas: scopeFor(target, options.declared.filter((d) => d.type.startsWith("Postgres::"))) }), target.provider);
+        const live = markProviderOwned(
+          await readLiveSchema(client, {
+            schemas: scopeFor(target, options.declared.filter((d) => d.type.startsWith("Postgres::"))),
+            access: target.access === true,
+            roles: options.declared.filter((d) => d.type === POSTGRES_ENTITY_TYPES.role).map((d) => String(d.props.name)),
+          }),
+          target.provider,
+        );
         return { target, byKey: new Map(live.map((o) => [liveKey(o.type, o.schema, o.name, o.signature), o])) };
       } finally {
         await client.end();
@@ -77,6 +99,8 @@ function adapter(options: BindOptions & { owned?: boolean; declared: DeclaredEnt
     classifyBindFailure: (err) => classifyPostgresFailure(err),
     async read({ target, byKey }, entity): Promise<EntityObservation> {
       if (!entity.type.startsWith("Postgres::")) return { unobserved: { reason: "unsupported-kind", detail: entity.type } };
+      const why = accessUnobserved(entity.type, target.access === true);
+      if (why) return { unobserved: why };
       const { schema, name, signature } = declaredAddress(entity, target.defaultSchema);
       const queried = `${redactUrl(target.endpoint.url)} ${schema ? `${schema}.` : ""}${name}${signature ?? ""}`;
       const live = byKey.get(liveKey(entity.type, schema, name, signature));

package/src/postgres/migrate/migrate.test.ts

@@ -72,7 +72,30 @@ describe("PostgresMigrationOp", () => {
     expect(Object.keys(g.approval.context)).toEqual(["verifiedRows", "mismatched"]);
   });
 
+  test('gates: "outer" leaves out both approval gates and the Contract phase, and keeps the verification (#3687)', () => {
+    const props = propsOf({ ...BASE, gates: "outer" });
+    expect(props.phases.map((p) => p.name)).toEqual(["Build", "Plan", "Expand", "Dual write", "Backfill", "Carry over", "Verify", "Switch", "Retain"]);
+    expect(props.phases.flatMap((p) => p.steps).filter((s) => s.kind === "gate")).toEqual([]);
+    const fns = props.phases.flatMap((p) => p.steps).map((s) => (s as { fn?: string }).fn);
+    expect(fns.indexOf("postgresMigrationVerify")).toBeLessThan(fns.indexOf("postgresMigrationSwitch"));
+    expect(fns).not.toContain("postgresMigrationContract");
+    expect(props.onFailure?.map((p) => p.steps.map((s) => (s as { fn?: string }).fn))).toEqual([["postgresMigrationCompensate"]]);
+    expect(props.overview).toContain("the caller's approval");
+  });
+
+  test('onFailure: "keep" has no onFailure and tells every step so (#3687)', () => {
+    const props = propsOf({ ...BASE, onFailure: "keep" });
+    expect(props.onFailure).toBeUndefined();
+    const steps = props.phases.flatMap((p) => p.steps).filter((s) => s.kind === "activity" && (s as { fn: string }).fn.startsWith("postgresMigration")) as Array<{ args: Record<string, unknown> }>;
+    expect(steps).toHaveLength(9);
+    for (const s of steps) expect(s.args.keepOnFailure).toBe(true);
+    expect(props.phases.map((p) => p.name)).toContain("Approve");
+    expect((propsOf(BASE).phases[1]!.steps[0] as { args: Record<string, unknown> }).args).not.toHaveProperty("keepOnFailure");
+  });
+
   test("bad configuration fails when the Op is built", () => {
+    expect(() => PostgresMigrationOp({ ...BASE, gates: "none" as never })).toThrow(/gates must be/);
+    expect(() => PostgresMigrationOp({ ...BASE, onFailure: "retry" as never })).toThrow(/onFailure must be/);
     expect(() => PostgresMigrationOp({ ...BASE, table: "app.users; DROP" })).toThrow(/table must be/);
     expect(() => PostgresMigrationOp({ ...BASE, column: "" })).toThrow(/column must be/);
     expect(() => PostgresMigrationOp({ ...BASE, batchSize: 0 })).toThrow(/batchSize/);
@@ -95,7 +118,7 @@ describe("PostgresMigrationOp", () => {
       ownershipEnv: "prod",
       build: false,
     };
-    for (const config of [BASE, full, { ...BASE, replicationLag: false as const }]) {
+    for (const config of [BASE, full, { ...BASE, replicationLag: false as const }, { ...BASE, gates: "outer" as const, onFailure: "keep" as const }]) {
       const props = propsOf(config);
       expect(validateActivitySteps(props, merged)).toEqual([]);
       expect(validateStepOutputRefs(props, merged)).toEqual([]);