@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/postgres/migrate/op.ts

@@ -35,6 +35,12 @@
  * machine) is not a failure, runs no onFailure, and the next run resumes the
  * backfill from its receipts; a step that fails runs onFailure, and the next
  * run starts again from a new column.
+ *
+ * `gates: "outer"` (#3687) leaves out both approval gates and the Contract
+ * phase, for a caller that runs the Op under an approval of its own: the run
+ * goes from Plan to Retain, verification included. `onFailure: "keep"`
+ * leaves out the onFailure, so a failed run's next run resumes the backfill
+ * from its receipts instead of starting again.
  */
 
 import { Op, activity, gate, phase, stepOutput, type GateApproval } from "@intentius/chant/op";
@@ -98,6 +104,27 @@ export interface PostgresMigrationOpConfig {
   stack?: string;
   /** Ownership env. Default: `ownership.env` in `chant.config.ts`. */
   ownershipEnv?: string;
+  /**
+   * Whose approval the switch and the contract wait for. `"own"` (the
+   * default): the Op's two gates. `"outer"`: an approval the caller already
+   * holds for a larger change that runs this Op as one of its steps. The
+   * switch gate, the contract gate and the Contract phase are left out, so
+   * the Op ends at Retain with the old column kept until its retention date.
+   * Drop it after that date, or run the Op with `"own"`: its switch gate has
+   * nothing left to switch, and its contract gate binds that old column. The
+   * verification still runs, and any difference fails the run with nothing
+   * switched.
+   */
+  gates?: "own" | "outer";
+  /**
+   * What a failed run does with what the expand added. `"drop"` (the
+   * default): onFailure drops the new column, the dual-write trigger and the
+   * receipts, and the next run starts again from a new column. `"keep"`:
+   * there is no onFailure, and the next run resumes the backfill from its
+   * per-batch receipts. To start again instead, run the Op once with
+   * `"drop"`.
+   */
+  onFailure?: "drop" | "keep";
 }
 
 export interface PostgresMigrationOpResources {
@@ -119,6 +146,8 @@ export interface PostgresMigrationArgs {
   stack?: string;
   ownershipEnv?: string;
   cwd?: string;
+  /** A failed run keeps what the expand added (`onFailure: "keep"`): a refusal says how to start again. */
+  keepOnFailure?: boolean;
 }
 
 const IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$|^"(?:[^"]|"")+"$/;
@@ -134,6 +163,14 @@ export function PostgresMigrationOp(config: PostgresMigrationOpConfig): Postgres
   }
   if (config.replicationLag) for (const d of [config.replicationLag.max, config.replicationLag.wait]) if (d !== undefined) parseDuration(d);
   if (config.retain !== undefined) parseDuration(config.retain);
+  if (config.gates !== undefined && config.gates !== "own" && config.gates !== "outer") {
+    throw new Error(`PostgresMigrationOp "${config.name}": gates must be "own" or "outer"`);
+  }
+  if (config.onFailure !== undefined && config.onFailure !== "drop" && config.onFailure !== "keep") {
+    throw new Error(`PostgresMigrationOp "${config.name}": onFailure must be "drop" or "keep"`);
+  }
+  const outer = config.gates === "outer";
+  const keep = config.onFailure === "keep";
 
   const args: PostgresMigrationArgs = {
     table: config.table,
@@ -149,6 +186,7 @@ export function PostgresMigrationOp(config: PostgresMigrationOpConfig): Postgres
     ...(config.stack ? { stack: config.stack } : {}),
     ...(config.ownershipEnv ? { ownershipEnv: config.ownershipEnv } : {}),
     ...(config.path && config.path !== "." ? { cwd: config.path } : {}),
+    ...(keep ? { keepOnFailure: true } : {}),
   };
   const a = args as unknown as Record<string, unknown>;
   const switchGate = config.gate?.gate ?? `approve-${config.name}`;
@@ -159,6 +197,33 @@ export function PostgresMigrationOp(config: PostgresMigrationOpConfig): Postgres
   const step = (fn: string, extra: Partial<StepDefinition & { id: string; outcomeAttribute: unknown; profile: string; timeout: string }> = {}): StepDefinition =>
     ({ ...activity(fn, a), ...extra }) as StepDefinition;
 
+  // The switch waits for this gate, unless the caller holds the approval (`gates: "outer"`).
+  const approve = phase("Approve", [
+    gate(switchGate, {
+      ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+      plan: stepOutput("verify", "planDigest"),
+      description:
+        config.gate?.description ??
+        `Approve switching ${what} on ${config.env}: the run record's Verification line has what this approval binds; for a rename, readers move to the new name once it is switched`,
+      ...(config.gate?.approval
+        ? {
+            approval: {
+              ...config.gate.approval,
+              ...(policy
+                ? {
+                    context: {
+                      verifiedRows: stepOutput("verify", "rows"),
+                      mismatched: stepOutput("verify", "mismatched"),
+                      ...config.gate.approval.context,
+                    },
+                  }
+                : {}),
+            },
+          }
+        : {}),
+    }),
+  ]);
+
   const phases = [
     ...(config.build === false ? [] : [phase("Build", [activity("chantBuild", { path: config.path ?? "." })])]),
     phase("Plan", [step("postgresMigrationPlan", { id: "plan", outcomeAttribute: [{ name: "MigrationState", from: "state" }, { name: "Change", from: "change" }] })]),
@@ -194,49 +259,29 @@ export function PostgresMigrationOp(config: PostgresMigrationOpConfig): Postgres
         ],
       }),
     ]),
-    phase("Approve", [
-      gate(switchGate, {
-        ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
-        plan: stepOutput("verify", "planDigest"),
-        description:
-          config.gate?.description ??
-          `Approve switching ${what} on ${config.env}: the run record's Verification line has what this approval binds; for a rename, readers move to the new name once it is switched`,
-        ...(config.gate?.approval
-          ? {
-              approval: {
-                ...config.gate.approval,
-                ...(policy
-                  ? {
-                      context: {
-                        verifiedRows: stepOutput("verify", "rows"),
-                        mismatched: stepOutput("verify", "mismatched"),
-                        ...config.gate.approval.context,
-                      },
-                    }
-                  : {}),
-              },
-            }
-          : {}),
-      }),
-    ]),
+    ...(outer ? [] : [approve]),
     phase("Switch", [step("postgresMigrationSwitch", { timeout: "6h", outcomeAttribute: [{ name: "OldColumn", from: "oldColumn" }] })]),
     phase("Retain", [step("postgresMigrationRetain", { id: "retain", outcomeAttribute: { name: "RetainUntil", from: "retainUntil" } })]),
-    phase("Approve contract", [
-      gate(contractGate, {
-        ...(config.contractGate?.timeout ? { timeout: config.contractGate.timeout } : {}),
-        plan: stepOutput("retain", "contractDigest"),
-        description: config.contractGate?.description ?? `Approve dropping the old column of ${what} once its retention has passed and no reader uses it`,
-      }),
-    ]),
-    phase("Contract", [step("postgresMigrationContract", { outcomeAttribute: { name: "Dropped", from: "dropped" } })]),
+    ...(outer
+      ? []
+      : [
+          phase("Approve contract", [
+            gate(contractGate, {
+              ...(config.contractGate?.timeout ? { timeout: config.contractGate.timeout } : {}),
+              plan: stepOutput("retain", "contractDigest"),
+              description: config.contractGate?.description ?? `Approve dropping the old column of ${what} once its retention has passed and no reader uses it`,
+            }),
+          ]),
+          phase("Contract", [step("postgresMigrationContract", { outcomeAttribute: { name: "Dropped", from: "dropped" } })]),
+        ]),
   ];
 
   const op = Op({
     name: config.name,
-    overview: `Migrate ${what} on ${config.env} as expand and contract: new column, dual write, backfill, verify, gated switch, gated contract`,
+    overview: `Migrate ${what} on ${config.env} as expand and contract: new column, dual write, backfill, verify, ${outer ? "switch under the caller's approval" : "gated switch, gated contract"}`,
     labels: { Migration: "true", Env: config.env, Table: config.table, Column: config.column },
     phases,
-    onFailure: [phase("Compensate", [step("postgresMigrationCompensate")])],
+    ...(keep ? {} : { onFailure: [phase("Compensate", [step("postgresMigrationCompensate")])] }),
   });
   return { op };
 }

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

@@ -0,0 +1,163 @@
+/**
+ * `PostgresMigrationOp` under an outer approval with what the expand added
+ * kept on failure (#3687): a backfill that fails part way leaves the new
+ * column, its dual write and its receipts; the next run skips the batches
+ * already filled, verifies and switches with no gate, and keeps the old
+ * column; a later run with the Op's own gates stops at its gates. A refusal
+ * says how to start again, since nothing drops what was kept.
+ *
+ * The server: `CHANT_SQL_E2E_POSTGRES_URL` (a `postgres://user@host:port/db`
+ * URL, with `CHANT_SQL_E2E_POSTGRES_PASSWORD`) names a running one, such as
+ * the one `chant emulator up --lexicon sql` starts. Without it, a throwaway
+ * server at the pin, skipped cleanly when Docker is not available. The test
+ * writes only to the schema `chant_e2e_3687`, dropped afterwards.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { OpRunFailure } from "@intentius/chant/op";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../live/client";
+import { postgresApply } from "../../op/activities/postgres-apply";
+import * as m from "../../op/activities/postgres-migration";
+import type { PostgresMigrationArgs, PostgresMigrationOpConfig } from "./op";
+import { ApprovingLedger, runMigrationOp, runOutcome } from "../testing/migration";
+import { POSTGRES_RECEIPTS_TABLE } from "./receipts";
+
+const S = "chant_e2e_3687";
+const given = process.env.CHANT_SQL_E2E_POSTGRES_URL;
+const enabled = given ? true : await dockerAvailable();
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-outer-"));
+let server: TestPostgres | undefined;
+let endpoint: PostgresEndpoint;
+let admin: PostgresClient;
+
+beforeAll(async () => {
+  if (!enabled) return;
+  if (given) endpoint = { url: given, password: process.env.CHANT_SQL_E2E_POSTGRES_PASSWORD ?? "" };
+  else {
+    server = await startTestPostgres();
+    endpoint = server.endpoint();
+  }
+  admin = await connectPostgres(endpoint);
+  await admin.query(`DROP SCHEMA IF EXISTS ${S} CASCADE`);
+}, 600_000);
+
+afterAll(async () => {
+  if (enabled) {
+    await admin?.query(`DROP SCHEMA IF EXISTS ${S} CASCADE`).catch(() => undefined);
+    await admin?.end();
+  }
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+function writeBuild(file: string, objects: Obj[]): string {
+  writeFileSync(join(dir, file), JSON.stringify({ dialect: "postgres", postgresMajor: 18, applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return file;
+}
+
+const MARKER = { stack: "e2e3687", env: "test" };
+const profile = () => ({
+  config: { ownership: MARKER, sql: { profiles: { e2e: { url: endpoint.url, password: { env: "PG_E2E_PASSWORD" }, schemas: [S] } } } },
+  env: { PG_E2E_PASSWORD: endpoint.password ?? "" },
+});
+const deps = (extra: Partial<m.PostgresMigrationDeps> = {}): m.PostgresMigrationDeps => ({ ...profile(), log: () => undefined, ...extra });
+const apply = (file: string) => postgresApply({ buildPath: join(dir, file), environment: "e2e" }, undefined, { ...profile(), log: () => undefined });
+const one = async <T>(sql: string): Promise<T> => (await admin.query<T>(sql))[0]!;
+const columnsOf = async (table: string) =>
+  (await admin.query<{ name: string }>(`SELECT attname AS name FROM pg_attribute WHERE attrelid = '${table}'::regclass AND attnum > 0 AND NOT attisdropped ORDER BY attnum`)).map((r) => r.name);
+const receipts = async () => (await one<{ n: number }>(`SELECT count(*)::int AS n FROM ${S}.${POSTGRES_RECEIPTS_TABLE} WHERE address LIKE 'e2e3687/test/migrate/${S}.events.kind/%' AND address NOT LIKE '%/batches'`)).n;
+
+describe.skipIf(!enabled)("under an outer approval, a failed migration keeps its new column and the rerun resumes (#3687)", () => {
+  const SCHEMA: Obj = { export: "app", type: "Postgres::Schema", ddl: `CREATE SCHEMA ${S}` };
+  const V1: Obj = { export: "events", type: "Postgres::Table", dependsOn: ["app"], ddl: `CREATE TABLE ${S}.events (id bigint PRIMARY KEY, kind varchar(20) NOT NULL)` };
+  const V2: Obj = { ...V1, ddl: `CREATE TABLE ${S}.events (id bigint PRIMARY KEY, kind varchar(10) NOT NULL)` };
+  const config = (): PostgresMigrationOpConfig => ({
+    name: "migrate-events-kind",
+    env: "e2e",
+    table: `${S}.events`,
+    column: "kind",
+    build: false,
+    path: dir,
+    output: "events-v2.json",
+    retain: "0s",
+    batchSize: 100,
+    stack: MARKER.stack,
+    ownershipEnv: MARKER.env,
+    gates: "outer",
+    onFailure: "keep",
+  });
+  const args = (): PostgresMigrationArgs => ({ table: `${S}.events`, column: "kind", buildPath: "events-v2.json", environment: "e2e", batchSize: 100, stack: MARKER.stack, ownershipEnv: MARKER.env, cwd: dir });
+
+  test("the failed run keeps the new column and its receipts; the rerun skips what was filled, switches without a gate and keeps the old column", async () => {
+    await apply(writeBuild("events-v1.json", [SCHEMA, V1]));
+    await admin.query(`INSERT INTO ${S}.events SELECT g, CASE WHEN g % 2 = 0 THEN 'click' ELSE 'view' END FROM generate_series(0, 599) g`);
+    writeBuild("events-v2.json", [SCHEMA, V2]);
+
+    // A refusal says how to start again when nothing drops what was kept; without keepOnFailure it does not.
+    await expect(m.postgresMigrationBackfill({ ...args(), keepOnFailure: true }, undefined, deps())).rejects.toThrow(
+      /the Expand phase adds it\. This migration keeps what the expand added on failure \(onFailure: "keep"\), so nothing drops it: to start again from a new column, run the Op once with onFailure: "drop"/,
+    );
+    await expect(m.postgresMigrationBackfill(args(), undefined, deps())).rejects.not.toThrow(/onFailure: "keep"/);
+
+    // Every attempt of the backfill step fails after its batch: three attempts, three batches filled, then the run fails.
+    let filled = 0;
+    const ledger = new ApprovingLedger();
+    const failure = await runMigrationOp(config(), ledger.port, () =>
+      deps({
+        backfill: {
+          afterBatch: () => {
+            filled++;
+            throw new Error(`the backfill failed after ${filled} batch(es)`);
+          },
+        },
+      }),
+    ).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    const records = (failure as OpRunFailure).result.records;
+    expect(records.find((x) => x.fn === "postgresMigrationBackfill")?.error).toMatch(/the backfill failed after 3 batch/);
+    // No onFailure ran: the new column, the dual write and the receipts are there.
+    expect(records.find((x) => x.fn === "postgresMigrationCompensate")).toBeUndefined();
+    expect(await columnsOf(`${S}.events`)).toEqual(["id", "kind", "kind__chant_new"]);
+    expect(await one(`SELECT count(*)::int AS n FROM pg_trigger WHERE tgrelid = '${S}.events'::regclass AND tgname = 'kind__chant_sync'`)).toEqual({ n: 1 });
+    expect(await one(`SELECT count(*)::int AS n FROM ${S}.events WHERE kind__chant_new IS NOT NULL`)).toEqual({ n: 300 });
+    expect(await receipts()).toBe(3);
+
+    // The rerun resumes: three batches skipped by receipt, three filled, verified and switched, with no gate.
+    const r = await runMigrationOp(config(), ledger.port, () => deps());
+    expect(r.status).toBe("ok");
+    expect(ledger.port.appended).toEqual([]);
+    expect(runOutcome(r, "Skipped")).toBe(3);
+    expect(runOutcome(r, "Filled")).toBe(3);
+    expect(runOutcome(r, "VerifiedRows")).toBe(600);
+    expect(r.records.map((x) => x.fn)).not.toContain("postgresMigrationContract");
+    expect(await one(`SELECT format_type(atttypid, atttypmod) AS t FROM pg_attribute WHERE attrelid = '${S}.events'::regclass AND attname = 'kind'`)).toEqual({ t: "character varying(10)" });
+    // The old column is kept: dropping it is a run with the Op's own gates.
+    expect(await columnsOf(`${S}.events`)).toEqual(["id", "kind__chant_old", "kind"]);
+
+    // Run with its own gates, the Op has nothing left to switch, and its contract gate binds that old column.
+    const own = new ApprovingLedger();
+    const first = await runMigrationOp({ ...config(), gates: "own" }, own.port, () => deps());
+    expect(first.status).toBe("gated");
+    expect(first.gate).toMatchObject({ gate: "approve-migrate-events-kind" });
+    expect(runOutcome(first, "MigrationState")).toBe("switched");
+    own.approveLast();
+    const second = await runMigrationOp({ ...config(), gates: "own" }, own.port, () => deps());
+    expect(second.status).toBe("gated");
+    expect(second.gate).toMatchObject({ gate: "approve-migrate-events-kind-contract" });
+    expect(await columnsOf(`${S}.events`)).toEqual(["id", "kind__chant_old", "kind"]);
+  }, 300_000);
+});

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,