@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/lsp/postgres-template.ts

@@ -152,6 +152,8 @@ export function postgresDeclarations(content: string, fileName = "file.ts"): Pos
         case "function":
         case "procedure":
         case "trigger":
+        case "policy":
+        case "role":
           sqlName = text(node.name.span);
           kind = node.statement;
           break;

package/src/lsp/template.ts

@@ -143,13 +143,13 @@ export function declarations(content: string, fileName = "file.ts"): Declared[]
       const tokens = tokenize(found.parts);
       const node = parseCreate(tokens);
       const columns =
-        node.statement === "database"
+        node.statement === "database" || node.statement === "function"
           ? []
-          : node.columns.map((c) => ({
+          : (node.statement === "dictionary" ? node.attributes : node.columns).map((c) => ({
               name: c.name || spanText(found, tokens, c.nameSpan, source) || "",
               ...(spanText(found, tokens, c.type, source) ? { type: spanText(found, tokens, c.type, source)! } : {}),
             }));
-      const engine = node.engine?.name || spanText(found, tokens, node.engine?.nameSpan, source);
+      const engine = node.statement === "dictionary" || node.statement === "function" ? undefined : node.engine?.name || spanText(found, tokens, node.engine?.nameSpan, source);
       out.push({
         name: decl.name.text,
         tag: found.tag,

package/src/mcp/index.ts

@@ -10,7 +10,7 @@ import type { McpResourceContribution, McpToolContribution } from "@intentius/ch
 import { createCatalogResource, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
 import { sqlSerializer } from "../serializer";
 import { catalogIndex } from "../lsp/catalog";
-import { database, table, view } from "../clickhouse/entities";
+import { database, dictionary, func, grant, policy, role, table, user, view } from "../clickhouse/entities";
 import { SqlSyntaxError } from "../clickhouse/tokens";
 import { existsSync, readFileSync } from "fs";
 import { diffSchemas } from "../clickhouse/plan/diff";
@@ -122,12 +122,12 @@ const searchTool: McpToolContribution = {
 const parseTool: McpToolContribution = {
   name: "parse-ddl",
   description:
-    "Parse one CREATE statement the way its tag does (dialect clickhouse, the default: table, view, database; dialect postgres: schema, table, index, view, sequence, type, domain, extension), and return the entity it builds (columns, engine, keys, settings, and for a view its lineage). A statement that does not parse comes back as the error with its line and column, the same one SQLCH001 (ClickHouse) or SQLPG001 (Postgres) reports. The statement is plain DDL: there are no interpolations.",
+    "Parse one CREATE statement the way its tag does (dialect clickhouse, the default: table, view, database, dictionary, func, user, role, policy, grant; dialect postgres: schema, table, index, view, sequence, type, domain, extension), and return the entity it builds (columns, engine, keys, settings, and for a view its lineage). A statement that does not parse comes back as the error with its line and column, the same one SQLCH001 (ClickHouse) or SQLPG001 (Postgres) reports. The statement is plain DDL: there are no interpolations.",
   inputSchema: {
     type: "object",
     properties: {
       dialect: dialectProp,
-      tag: { type: "string", enum: [...new Set(["table", "view", "database", ...POSTGRES_TAGS])], description: "The tag the statement belongs in (ClickHouse: table, view, database; Postgres: " + POSTGRES_TAGS.join(", ") + ")" },
+      tag: { type: "string", enum: [...new Set(["table", "view", "database", "dictionary", "func", "user", "role", "policy", "grant", ...POSTGRES_TAGS])], description: "The tag the statement belongs in (ClickHouse: table, view, database, dictionary, func, user, role, policy, grant; Postgres: " + POSTGRES_TAGS.join(", ") + ")" },
       ddl: { type: "string", description: "The CREATE statement" },
     },
     required: ["tag", "ddl"],
@@ -136,8 +136,8 @@ const parseTool: McpToolContribution = {
     const ddl = String(params.ddl ?? "");
     const tag = String(params.tag);
     if (asDialect(params.dialect) === "postgres") return postgresParse(tag, ddl, position);
-    const build = tag === "table" ? table : tag === "view" ? view : tag === "database" ? database : undefined;
-    if (!build) throw new Error("tag must be table, view or database");
+    const build = tag === "table" ? table : tag === "view" ? view : tag === "database" ? database : tag === "dictionary" ? dictionary : tag === "func" ? func : tag === "user" ? user : tag === "role" ? role : tag === "policy" ? policy : tag === "grant" ? grant : undefined;
+    if (!build) throw new Error("tag must be table, view, database, dictionary, func, user, role, policy or grant");
     const strings = Object.assign([ddl], { raw: [ddl] }) as unknown as TemplateStringsArray;
     try {
       const entity = build(strings);
@@ -276,7 +276,7 @@ export function sqlMcpResources(): McpResourceContribution[] {
     createCatalogResource(
       new URL("../plugin.ts", import.meta.url).href,
       "SQL Entity Catalog",
-      "The entity kinds the sql lexicon declares (database, table, view, materialized view)",
+      "The entity kinds the sql lexicon declares (database, table, view, materialized view, dictionary, function, user, role, row policy, grant)",
       "lexicon-sql.json",
       "sql",
     ),

package/src/mcp/postgres.ts

@@ -81,7 +81,7 @@ export function postgresSearch(params: Record<string, unknown>): unknown {
   };
 }
 
-const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, trigger: pg.trigger } as const;
+const TAGS = { schema: pg.schema, table: pg.table, index: pg.index, view: pg.view, sequence: pg.sequence, type: pg.type, domain: pg.domain, extension: pg.extension, func: pg.func, procedure: pg.procedure, trigger: pg.trigger, policy: pg.policy, role: pg.role, grant: pg.grant } as const;
 export const POSTGRES_TAGS = Object.keys(TAGS);
 
 /** Parse one statement with the Postgres tag; an error comes back as SQLPG001 with its line and column. */

package/src/migration-statements.test.ts

@@ -150,6 +150,31 @@ const PG_AFTER = build("postgres", [APP, USERS_V2, EMAIL_IDX, ORDERS_RENAMED], {
 describe("Postgres", () => {
   const doc = diffStatements(PG_BEFORE, PG_AFTER, { marker: MARKER, env: "prod" });
 
+  test("a unique index on a table that exists carries its duplicate count, one on a new table none (#3686)", () => {
+    const unique: Obj = { export: "usersNick", type: "Postgres::Index", dependsOn: ["users"], ddl: "CREATE UNIQUE INDEX CONCURRENTLY users_nick_key ON app.users (nick) WHERE nick <> ''" };
+    const d = diffStatements(build("postgres", [APP, USERS]), build("postgres", [APP, USERS, unique]));
+    const built = d.steps.find((s): s is StatementStep => s.kind === "statement" && s.sql.startsWith("CREATE UNIQUE INDEX"));
+    expect(built?.precheck).toEqual({
+      sql: "SELECT (SELECT count(*) FROM (SELECT 1 FROM app.users WHERE nick IS NOT NULL AND (nick <> '') GROUP BY nick HAVING count(*) > 1) AS duplicates) AS n",
+      detail: "values of (nick) held by more than one row, which a unique index fails on",
+    });
+    expect(renderStatements(d)).toContain(`-- pre-check, must return 0 (values of (nick) held by more than one row, which a unique index fails on): ${built!.precheck!.sql}`);
+    const fresh = diffStatements(build("postgres", [APP]), build("postgres", [APP, USERS, unique]));
+    expect(fresh.steps.some((s) => s.kind === "statement" && s.precheck !== undefined)).toBe(false);
+  });
+
+  test("SET NOT NULL renders as its four statements, the first with the NULL count (#3686)", () => {
+    const d = diffStatements(build("postgres", [APP, USERS]), build("postgres", [APP, { ...USERS, ddl: USERS.ddl.replace("nick text", "nick text NOT NULL") }]));
+    const st = d.steps.filter((s): s is StatementStep => s.kind === "statement");
+    expect(st.map((s) => [s.sql, s.rule, s.class])).toEqual([
+      ["ALTER TABLE app.users ADD CONSTRAINT nick__chant_nn CHECK (nick IS NOT NULL) NOT VALID", "SQLPG217", "metadata"],
+      ["ALTER TABLE app.users VALIDATE CONSTRAINT nick__chant_nn", "SQLPG220", "validate"],
+      ["ALTER TABLE app.users ALTER COLUMN nick SET NOT NULL", "SQLPG210", "metadata"],
+      ["ALTER TABLE app.users DROP CONSTRAINT nick__chant_nn", "SQLPG223", "metadata"],
+    ]);
+    expect(st[0]!.precheck?.sql).toBe("SELECT count(*) AS n FROM app.users WHERE nick IS NULL");
+  });
+
   test("the statements are ordered, each with its change's rule and class and whether it may run in a transaction", () => {
     expect(doc).toMatchObject({ dialect: "postgres", defaultSchema: "public", major: 18 });
     expect(doc.steps.filter((s): s is StatementStep => s.kind === "statement").map((s) => [s.object, s.sql, s.rule, s.class, s.transactional])).toEqual([

package/src/migration-statements.ts

@@ -234,9 +234,17 @@ function postgresStatements(beforeJson: string, afterJson: string, options: Diff
         class: s.class,
         transactional: s.transactional,
         ...(s.rule === "SQLPG204" || isDestructive(entry.changes, s.rule) ? { destructive: true } : {}),
+        ...(s.precheck ? { precheck: { sql: s.precheck.sql, detail: s.precheck.detail } } : {}),
       });
     }
   }
+  // Privileges (#3681), after the objects they are on: one statement each, under the declaration behind it.
+  const afterByExport = new Map(after.map((o) => [o.exportName, o]));
+  for (const c of diff.access ?? []) {
+    const decl = c.exports.map((e) => afterByExport.get(e)).find((o) => o !== undefined);
+    const where = decl ? at(decl.exportName, decl.type, decl.name) : at(c.change.object, c.target.kind === "default" ? POSTGRES_ENTITY_TYPES.defaultPrivileges : POSTGRES_ENTITY_TYPES.grant, c.change.object.slice(4));
+    for (const sql of c.sql) steps.push({ kind: "statement", ...where, sql, rule: c.change.rule, class: c.change.class, transactional: true });
+  }
   const beforeByExport = new Map(before.map((o) => [o.exportName, o]));
   for (const d of plan.drops) {
     const o = beforeByExport.get(d.key);

package/src/op/activities/clickhouse-rebuild.ts

@@ -71,6 +71,7 @@ export async function rebuildRun(args: ClickHouseRebuildArgs, signal: AbortSigna
     retainMs: parseDuration(args.retain ?? "7d"),
     ...(args.mutationTimeout ? { mutationTimeoutMs: parseDuration(args.mutationTimeout) } : {}),
     ...(args.replicaTimeout ? { replicaTimeoutMs: parseDuration(args.replicaTimeout) } : {}),
+    ...(args.cutoverTimeout ? { cutoverTimeoutMs: parseDuration(args.cutoverTimeout) } : {}),
     log: deps.log ?? ((line: string) => console.log(line)),
     ...(signal ? { signal } : {}),
     ...(runId ? { runId } : {}),

package/src/op/activities/postgres-migration.ts

@@ -17,8 +17,8 @@ import { resolveBoundTarget } from "../../postgres/live/bind";
 import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../../postgres/live/client";
 import { DEFAULT_POSTGRES_APPLY_TIMEOUTS, declaredObjects } from "../../postgres/apply/apply";
 import { PG_CLASSIFIER_RULES } from "../../postgres/plan/rules";
-import { declaredTable, migrationPlanDigest, observeMigration } from "../../postgres/migrate/observe";
-import { backfill, verifyMigration, type BackfillDeps, type BackfillResult, type VerifyResult } from "../../postgres/migrate/backfill";
+import { declaredTable, migrationPlanDigest, MigrationRefusal, observeMigration } from "../../postgres/migrate/observe";
+import { backfill, MigrationVerificationError, verifyMigration, type BackfillDeps, type BackfillResult, type VerifyResult } from "../../postgres/migrate/backfill";
 import {
   carryOver,
   compensate,
@@ -60,8 +60,33 @@ async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "sql" | "owner
   }
 }
 
+/**
+ * With `onFailure: "keep"` (#3687) no onFailure drops what the expand added,
+ * so a step that fails says what a person does instead: a refusal or a
+ * failed verification would otherwise fail every run after it the same way.
+ */
+const ON_FAILURE_DROPS = "onFailure drops what the expand added, and the next run starts again.";
+
+function noting(args: PostgresMigrationArgs, err: unknown): unknown {
+  if (args.keepOnFailure && (err instanceof MigrationRefusal || err instanceof MigrationVerificationError)) {
+    const kept =
+      `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" (the default), whose onFailure drops it when this step fails again.`;
+    err.message = err.message.includes(ON_FAILURE_DROPS) ? err.message.replace(ON_FAILURE_DROPS, kept) : `${err.message.replace(/\.?$/, ".")} ${kept}`;
+  }
+  return err;
+}
+
 /** Bind the server, connect and read the declaration, run `body` with it, then close the connection. */
 async function withRun<T>(args: PostgresMigrationArgs, signal: AbortSignal | undefined, deps: PostgresMigrationDeps, body: (run: MigrationRun) => Promise<T>): Promise<T> {
+  try {
+    return await bound(args, signal, deps, body);
+  } catch (err) {
+    throw noting(args, err);
+  }
+}
+
+async function bound<T>(args: PostgresMigrationArgs, signal: AbortSignal | undefined, deps: PostgresMigrationDeps, body: (run: MigrationRun) => Promise<T>): Promise<T> {
   const cwd = args.cwd ?? process.cwd();
   const config = deps.config ?? (await loadConfig(cwd));
   const marker = resolveOwnershipMarker(args, config, "PostgresMigrationOp");

package/src/op/activity-contracts.ts

@@ -31,6 +31,7 @@ const rebuildArgs = z.strictObject({
   retain: z.string().optional(),
   mutationTimeout: z.string().optional(),
   replicaTimeout: z.string().optional(),
+  cutoverTimeout: z.string().optional(),
   stack: z.string().optional(),
   ownershipEnv: z.string().optional(),
   cwd: z.string().optional(),
@@ -127,6 +128,7 @@ const migrationArgs = z.strictObject({
   stack: z.string().optional(),
   ownershipEnv: z.string().optional(),
   cwd: z.string().optional(),
+  keepOnFailure: z.boolean().optional(),
 });
 
 const migrationState = z.enum(["migrate", "switched", "done"]);

package/src/plugin.ts

@@ -18,7 +18,7 @@ import { completions } from "./lsp/completions";
 import { hover } from "./lsp/hover";
 import { sqlMcpResources, sqlMcpTools } from "./mcp";
 import { sqlConfigSchema } from "./config";
-import { ClickHouseSqlParser } from "./clickhouse/import/parser";
+import { SqlFileParser, dialectOption } from "./import-parser";
 import { sqlTemplateGenerator } from "./import-generator";
 import { sqlCommands } from "./clickhouse/plan/commands";
 import { sqlDeepNormalizationHooks } from "./clickhouse/plan/deep";
@@ -97,15 +97,20 @@ export const sqlPlugin: LexiconPlugin = {
         isTag: true,
         description: "A CREATE VIEW or CREATE MATERIALIZED VIEW, parsed into a view entity with its lineage",
       },
+      { name: "dictionary", isTag: true, description: "A ClickHouse CREATE DICTIONARY, parsed into a dictionary entity with its attributes, key, source and layout" },
+      { name: "user", isTag: true, description: "A ClickHouse CREATE USER, parsed into a user entity; its password is the environment's" },
       { name: "schema", isTag: true, description: "A Postgres CREATE SCHEMA, parsed into a schema entity" },
       { name: "index", isTag: true, description: "A Postgres CREATE INDEX, parsed into an index entity" },
       { name: "sequence", isTag: true, description: "A Postgres CREATE SEQUENCE, parsed into a sequence entity" },
       { name: "type", isTag: true, description: "A Postgres CREATE TYPE ... AS ENUM, parsed into an enum entity" },
       { name: "domain", isTag: true, description: "A Postgres CREATE DOMAIN, parsed into a domain entity" },
       { name: "extension", isTag: true, description: "A Postgres CREATE EXTENSION, parsed into an extension entity" },
-      { name: "func", isTag: true, description: "A Postgres CREATE FUNCTION, parsed into a function entity with its body kept verbatim" },
+      { name: "func", isTag: true, description: "A Postgres CREATE FUNCTION, parsed into a function entity with its body kept verbatim, or a ClickHouse CREATE FUNCTION (a named lambda)" },
       { name: "procedure", isTag: true, description: "A Postgres CREATE PROCEDURE, parsed into a procedure entity with its body kept verbatim" },
       { name: "trigger", isTag: true, description: "A Postgres CREATE TRIGGER, parsed into a trigger entity on its table" },
+      { name: "policy", isTag: true, description: "A Postgres CREATE POLICY, parsed into a row-level security policy on its table, or a ClickHouse CREATE ROW POLICY" },
+      { name: "role", isTag: true, description: "A Postgres CREATE ROLE without a password or memberships, parsed into a role entity, or a ClickHouse CREATE ROLE" },
+      { name: "grant", isTag: true, description: "A Postgres GRANT, REVOKE or ALTER DEFAULT PRIVILEGES, parsed into the privileges it declares, or a ClickHouse GRANT of privileges or roles" },
       {
         name: "literal",
         isTag: false,
@@ -152,9 +157,28 @@ export const sqlPlugin: LexiconPlugin = {
     return sqlMcpResources();
   },
 
-  /** `chant import schema.sql`: a file of ClickHouse CREATE statements. */
-  templateParser() {
-    return new ClickHouseSqlParser();
+  /** `chant import schema.sql`: a file of Postgres or ClickHouse DDL (`./import-parser.ts`). */
+  templateParser(options) {
+    return new SqlFileParser(dialectOption(options));
+  },
+
+  parserOptions() {
+    return [
+      {
+        name: "dialect",
+        type: "string" as const,
+        description: "the DDL's dialect, clickhouse or postgres; read off its statements when omitted",
+      },
+    ];
+  },
+
+  /**
+   * The `.sql` files in the source directory, read into declarations beside
+   * the tagged templates (`./files/build-root.ts`, #3646).
+   */
+  async buildRoots(ctx) {
+    const { sqlFilesBuildRoot } = await import("./files/build-root");
+    return sqlFilesBuildRoot(ctx);
   },
 
   /** One generator for both dialects: each IR resource's type says whose declarations it is. */

package/src/postgres/access/access.e2e.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Access against a live server (#3681): a declared role, a table with
+ * row-level security and a policy, grants on a schema, a table, a column and
+ * a function, a revoke from PUBLIC, and default privileges, applied where the
+ * profile manages access; then a grant and a revoke made by hand are drift
+ * the plan reports and an apply undoes; a profile that does not manage access
+ * plans none of it; and an import writes the access back as declarations.
+ *
+ * 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_3681` and the roles
+ * `chant_e2e_3681_reader` and `chant_e2e_3681_writer`, all 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 { dockerAvailable, startTestPostgres, type TestPostgres } from "../testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../live/client";
+import { readLiveSchema } from "../live/catalog";
+import { planPgAgainstServer } from "../plan/commands";
+import { postgresApply } from "../../op/activities/postgres-apply";
+import { objectsToIR } from "../import/ir";
+import { PostgresGenerator } from "../import/generator";
+import { importedAccess } from "./import";
+
+const S = "chant_e2e_3681";
+const READER = "chant_e2e_3681_reader";
+const WRITER = "chant_e2e_3681_writer";
+const given = process.env.CHANT_SQL_E2E_POSTGRES_URL;
+const enabled = given ? true : await dockerAvailable();
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-access-"));
+let server: TestPostgres | undefined;
+let endpoint: PostgresEndpoint;
+let admin: PostgresClient;
+
+const cleanup = async () => {
+  await admin.query(`DROP SCHEMA IF EXISTS ${S} CASCADE`);
+  for (const r of [READER, WRITER]) await admin.query(`DROP ROLE IF EXISTS ${r}`);
+};
+
+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 cleanup();
+  // The writer is the environment's: provisioned outside the declarations, only named in them.
+  await admin.query(`CREATE ROLE ${WRITER} NOLOGIN`);
+}, 600_000);
+
+afterAll(async () => {
+  if (enabled) {
+    await cleanup().catch(() => undefined);
+    await admin?.end();
+  }
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const MARKER = { stack: "e2e3681", env: "test" };
+const profile = (access: boolean) => ({
+  config: { ownership: MARKER, sql: { profiles: { e2e: { url: endpoint.url, password: { env: "PG_E2E_PASSWORD" }, schemas: [S], ...(access ? { access: true } : {}) } } } },
+  env: { PG_E2E_PASSWORD: endpoint.password ?? "" },
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+const OBJECTS: Obj[] = [
+  { export: "app", type: "Postgres::Schema", ddl: `CREATE SCHEMA ${S}` },
+  { export: "reader", type: "Postgres::Role", ddl: `CREATE ROLE ${READER} NOLOGIN` },
+  {
+    export: "orders",
+    type: "Postgres::Table",
+    dependsOn: ["app"],
+    ddl: `CREATE TABLE ${S}.orders (id bigint PRIMARY KEY, tenant text NOT NULL, note varchar(40));\nALTER TABLE ${S}.orders ENABLE ROW LEVEL SECURITY`,
+  },
+  {
+    export: "ordersTenant",
+    type: "Postgres::Policy",
+    dependsOn: ["orders", "reader"],
+    ddl: `CREATE POLICY orders_tenant ON ${S}.orders FOR SELECT TO ${READER} USING (tenant = current_setting('app.tenant', true) AND note <> 'hidden')`,
+  },
+  { export: "total", type: "Postgres::Function", dependsOn: ["app"], ddl: `CREATE FUNCTION ${S}.total() RETURNS bigint LANGUAGE sql AS 'SELECT 1::bigint'` },
+  { export: "useApp", type: "Postgres::Grant", dependsOn: ["app", "reader"], ddl: `GRANT USAGE ON SCHEMA ${S} TO ${READER}` },
+  { export: "readOrders", type: "Postgres::Grant", dependsOn: ["orders", "reader"], ddl: `GRANT SELECT ON ${S}.orders TO ${READER}` },
+  { export: "writeNote", type: "Postgres::Grant", dependsOn: ["orders"], ddl: `GRANT UPDATE (note) ON ${S}.orders TO ${WRITER}` },
+  { export: "totalPrivate", type: "Postgres::Grant", dependsOn: ["total"], ddl: `REVOKE EXECUTE ON FUNCTION ${S}.total() FROM PUBLIC` },
+  { export: "totalReader", type: "Postgres::Grant", dependsOn: ["total", "reader"], ddl: `GRANT EXECUTE ON FUNCTION ${S}.total() TO ${READER}` },
+  { export: "readNewTables", type: "Postgres::DefaultPrivileges", dependsOn: ["app", "reader"], ddl: `ALTER DEFAULT PRIVILEGES IN SCHEMA ${S} GRANT SELECT ON TABLES TO ${READER}` },
+];
+
+function writeBuild(file: string, objects: Obj[]): string {
+  const path = join(dir, file);
+  writeFileSync(path, JSON.stringify({ dialect: "postgres", postgresMajor: 18, objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return path;
+}
+
+const apply = (path: string, access = true) => postgresApply({ buildPath: path, environment: "e2e" }, undefined, { ...profile(access), log: () => undefined });
+const plan = (path: string, access = true) => planPgAgainstServer("e2e", path, profile(access));
+const rules = async (path: string) => (await plan(path)).changes.map((c) => [c.object, c.rule]);
+
+describe.skipIf(!enabled)("access on a live server", () => {
+  test("applied, then drift by hand reported and undone, unmanaged left alone, imported back", async () => {
+    const build = writeBuild("v1.json", OBJECTS);
+
+    // A profile that does not manage access: the access declarations are filtered, the table is created without row-level security.
+    const off = await apply(build, false);
+    expect(off.failed).toEqual([]);
+    expect(off.notAttempted.map((n) => n.reason)).toEqual(Array(8).fill("filtered"));
+    expect(off.notAttempted).toHaveLength(8);
+    expect((await admin.query<{ rls: boolean }>(`SELECT relrowsecurity AS rls FROM pg_class WHERE oid = '${S}.orders'::regclass`))[0]!.rls).toBe(false);
+    const unmanaged = await plan(build, false);
+    expect(unmanaged.changes).toEqual([]);
+    expect(unmanaged.hints.join(" ")).toContain("9 access declarations are not planned");
+
+    // Managed: every access declaration applied.
+    expect(await rules(build)).toEqual([
+      [`reader (${READER})`, "SQLPG200"],
+      [`orders (${S}.orders)`, "SQLPG293"],
+      [`ordersTenant (${S}.orders_tenant ON ${S}.orders)`, "SQLPG290"],
+      [`default privileges in ${S} on tables TO ${READER}`, "SQLPG298"],
+      [`relation ${S}.orders (note) TO ${WRITER}`, "SQLPG296"],
+      [`relation ${S}.orders TO ${READER}`, "SQLPG296"],
+      [`routine ${S}.total() TO PUBLIC`, "SQLPG297"],
+      [`routine ${S}.total() TO ${READER}`, "SQLPG296"],
+      [`schema ${S} TO ${READER}`, "SQLPG296"],
+    ]);
+    const on = await apply(build);
+    expect(on.failed).toEqual([]);
+    expect(on.applied.map((a) => [a.name, a.action])).toEqual([
+      [S, "unchanged"],
+      [`${S}.total()`, "unchanged"],
+      [READER, "created"],
+      [`${S}.orders`, "updated"],
+      [`orders_tenant ON ${S}.orders`, "created"],
+      [`grant usage on schema ${S} to ${READER}`, "updated"],
+      [`grant select on table ${S}.orders to ${READER}`, "updated"],
+      [`grant update(note) on table ${S}.orders to ${WRITER}`, "updated"],
+      [`revoke execute on function ${S}.total() from public`, "updated"],
+      [`grant execute on function ${S}.total() to ${READER}`, "updated"],
+      [`default privileges grant select on tables in ${S} to ${READER}`, "updated"],
+    ]);
+    expect(await rules(build)).toEqual([]);
+    const can = async (sql: string) => (await admin.query<{ ok: boolean }>(sql))[0]!.ok;
+    expect(await can(`SELECT has_table_privilege('${READER}', '${S}.orders', 'SELECT') AS ok`)).toBe(true);
+    expect(await can(`SELECT has_column_privilege('${WRITER}', '${S}.orders', 'note', 'UPDATE') AS ok`)).toBe(true);
+    expect(await can(`SELECT has_function_privilege('public', '${S}.total()', 'EXECUTE') AS ok`)).toBe(false);
+    expect(await can(`SELECT relrowsecurity AS ok FROM pg_class WHERE oid = '${S}.orders'::regclass`)).toBe(true);
+
+    // By hand: a grant nobody declared, and a declared grant revoked. The plan reports both; an apply undoes both.
+    await admin.query(`GRANT INSERT ON ${S}.orders TO ${WRITER}`);
+    await admin.query(`REVOKE SELECT ON ${S}.orders FROM ${READER}`);
+    expect(await rules(build)).toEqual([
+      [`relation ${S}.orders TO ${READER}`, "SQLPG296"],
+      [`relation ${S}.orders TO ${WRITER}`, "SQLPG297"],
+    ]);
+    const undo = await apply(build);
+    expect(undo.failed).toEqual([]);
+    expect(undo.statements.map((s) => s.sql)).toEqual(expect.arrayContaining([`GRANT SELECT ON TABLE ${S}.orders TO ${READER}`, `REVOKE INSERT ON TABLE ${S}.orders FROM ${WRITER}`]));
+    expect(await rules(build)).toEqual([]);
+
+    // A policy changed by hand is drift too.
+    await admin.query(`ALTER POLICY orders_tenant ON ${S}.orders USING (true)`);
+    expect(await rules(build)).toEqual([[`ordersTenant (${S}.orders_tenant ON ${S}.orders)`, "SQLPG291"]]);
+    await apply(build);
+    expect(await rules(build)).toEqual([]);
+
+    // Import: the policy and the row-level security with the table, the privileges as grant declarations.
+    const live = await readLiveSchema(admin, { schemas: [S], access: true });
+    const access = await importedAccess(admin, live, [S]);
+    const [file] = new PostgresGenerator().generate(objectsToIR([...live.map((o) => ({ type: o.type, schema: o.schema, name: o.name, ddl: o.statement })), ...access]));
+    expect(file!.content).toContain("export const ordersTenant = policy`");
+    expect(file!.content).toContain(`ALTER TABLE \${chantE2e3681Schema}.orders ENABLE ROW LEVEL SECURITY`);
+    expect(file!.content).toContain(`GRANT SELECT ON TABLE \${orders} TO ${READER}`);
+    expect(file!.content).toContain(`REVOKE EXECUTE ON FUNCTION \${total}() FROM PUBLIC`);
+    expect(file!.content).toContain(`ALTER DEFAULT PRIVILEGES IN SCHEMA \${chantE2e3681Schema} GRANT SELECT ON TABLES TO ${READER}`);
+    expect(file!.content).toContain(`GRANT USAGE ON SCHEMA \${chantE2e3681Schema} TO ${READER}`);
+  }, 600_000);
+});

package/src/postgres/access/access.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Row-level security, roles, grants and default privileges (#3681): what the
+ * tags parse and refuse, how the declarations add up to access, and how a
+ * change is classified and made.
+ */
+
+import { describe, expect, test } from "vitest";
+import { func, grant, policy, role, schema, table } from "../entities";
+import { diffObject, keyedByQualifiedName, pgSchemaFromLive, type PgSchemaObject } from "../plan/schema";
+import { diffPgSchemas, matchPgObjects } from "../plan/diff";
+import { accessScoped } from "../plan/commands";
+import { alterSteps } from "../apply/statements";
+import { declaredObjects } from "../apply/apply";
+import type { LivePgObject } from "../live/catalog";
+import { declaredAccess, diffAccess } from "./acl";
+
+const app = schema`CREATE SCHEMA app`;
+const reader = role`CREATE ROLE app_reader NOLOGIN`;
+const orders = table`
+  CREATE TABLE ${app}.orders (id bigint PRIMARY KEY, tenant text NOT NULL, note text);
+  ALTER TABLE ${app}.orders ENABLE ROW LEVEL SECURITY;
+  ALTER TABLE ${app}.orders FORCE ROW LEVEL SECURITY`;
+
+describe("the tags", () => {
+  test("a table's row-level security, a policy, a role", () => {
+    expect(orders.props).toMatchObject({ rowSecurity: true, forceRowSecurity: true });
+    const p = policy`CREATE POLICY tenant_rows ON ${orders} AS RESTRICTIVE FOR SELECT TO ${reader}, PUBLIC USING (${orders.columns.tenant} = current_setting('app.tenant'))`;
+    expect(p.entityType).toBe("Postgres::Policy");
+    expect(p.props).toMatchObject({ schema: "app", name: "tenant_rows", tableName: "app.orders", permissive: false, command: "select", roles: ["app_reader", "public"], using: "tenant = current_setting('app.tenant')" });
+    expect(p.dependsOn).toEqual(expect.arrayContaining([orders, reader]));
+    expect(reader.props).toMatchObject({ name: "app_reader", options: ["nologin"] });
+  });
+
+  test("grants on a schema, a table's columns and a routine, a revoke, default privileges", () => {
+    const f = func`CREATE FUNCTION ${app}.total(n int) RETURNS bigint LANGUAGE sql AS 'select 1'`;
+    expect(grant`GRANT USAGE ON SCHEMA ${app} TO ${reader}`.props).toMatchObject({ action: "grant", on: "schema", objectNames: ["app"], grantees: ["app_reader"] });
+    expect(grant`GRANT SELECT, UPDATE (note) ON ${orders} TO writer WITH GRANT OPTION`.props).toMatchObject({
+      on: "table",
+      privileges: [{ privilege: "select" }, { privilege: "update", columns: ["note"] }],
+      withGrantOption: true,
+    });
+    expect(grant`REVOKE EXECUTE ON FUNCTION ${f} FROM PUBLIC`.props).toMatchObject({ action: "revoke", objectNames: ["app.total(int)"], grantees: ["public"] });
+    const d = grant`ALTER DEFAULT PRIVILEGES IN SCHEMA ${app} GRANT SELECT ON TABLES TO ${reader}`;
+    expect(d.entityType).toBe("Postgres::DefaultPrivileges");
+    expect(d.props).toMatchObject({ inSchemas: ["app"], on: "tables", privileges: ["select"] });
+  });
+
+  test("secrets, memberships, ALL ... IN SCHEMA and an unnamed overload are refused", () => {
+    expect(() => role`CREATE ROLE r LOGIN PASSWORD 'x'`).toThrow(/environment's secret/);
+    expect(() => role`CREATE ROLE r IN ROLE admins`).toThrow(/environment's/);
+    expect(() => grant`GRANT admins TO r`).toThrow(/membership/);
+    expect(() => grant`GRANT SELECT ON ALL TABLES IN SCHEMA app TO r`).toThrow(/ALTER DEFAULT PRIVILEGES/);
+    expect(() => grant`GRANT EXECUTE ON FUNCTION app.f TO r`).toThrow(/parameter types/);
+    expect(() => table`ALTER TABLE app.t ENABLE ROW LEVEL SECURITY`).toThrow(/after the table's CREATE TABLE/);
+  });
+});
+
+// ── Access ─────────────────────────────────────────────────────────────
+
+const decl = (type: string, ddl: string, key = ddl): PgSchemaObject => ({ key, canonical: { ...diffObject(type, ddl, "public"), exportName: key } });
+const T = (ddl: string) => decl("Postgres::Table", ddl);
+const F = (ddl: string) => decl("Postgres::Function", ddl);
+const G = (ddl: string) => decl("Postgres::Grant", ddl);
+const D = (ddl: string) => decl("Postgres::DefaultPrivileges", ddl);
+
+const entries = (objects: PgSchemaObject[]) =>
+  Object.fromEntries([...declaredAccess(objects, { major: 18 }).state].map(([k, e]) => [k, [...e.privileges].map(([p, g]) => `${p}${g ? "*" : ""}`).sort().join(",")]));
+
+describe("the access declarations add up to", () => {
+  test("a routine's EXECUTE to PUBLIC unless revoked; grants added, revokes taken away, in order", () => {
+    expect(entries([F("CREATE FUNCTION app.f() RETURNS int LANGUAGE sql AS 'select 1'")])).toEqual({ "routine app.f() TO PUBLIC": "execute" });
+    expect(
+      entries([
+        F("CREATE FUNCTION app.f() RETURNS int LANGUAGE sql AS 'select 1'"),
+        T("CREATE TABLE app.t (a int, b int)"),
+        G("REVOKE EXECUTE ON FUNCTION app.f() FROM PUBLIC"),
+        G("GRANT ALL ON app.t TO r WITH GRANT OPTION"),
+        G("REVOKE GRANT OPTION FOR DELETE ON app.t FROM r"),
+        G("REVOKE TRUNCATE, MAINTAIN ON app.t FROM r"),
+        G("GRANT SELECT (b) ON app.t TO s"),
+      ]),
+    ).toEqual({ "relation app.t TO r": "delete,insert*,references*,select*,trigger*,update*", "relation app.t (b) TO s": "select" });
+  });
+
+  test("default privileges are compared themselves, and given to the objects chant creates", () => {
+    expect(
+      entries([
+        T("CREATE TABLE app.t (a int)"),
+        D("ALTER DEFAULT PRIVILEGES IN SCHEMA app GRANT SELECT ON TABLES TO r"),
+        D("ALTER DEFAULT PRIVILEGES REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC"),
+        F("CREATE FUNCTION app.f() RETURNS int LANGUAGE sql AS 'select 1'"),
+      ]),
+    ).toEqual({ "default privileges in app on tables TO r": "select", "relation app.t TO r": "select" });
+  });
+
+  test("a change is a GRANT, a REVOKE, or ALTER DEFAULT PRIVILEGES", () => {
+    const before = declaredAccess([T("CREATE TABLE app.t (a int)"), G("GRANT SELECT, INSERT ON app.t TO r")], { major: 18 });
+    const after = declaredAccess([T("CREATE TABLE app.t (a int)"), G("GRANT SELECT ON app.t TO r WITH GRANT OPTION"), G("GRANT USAGE ON SCHEMA app TO r"), D("ALTER DEFAULT PRIVILEGES FOR ROLE owner IN SCHEMA app GRANT SELECT ON TABLES TO r")], { major: 18 });
+    expect(diffAccess(before.state, after.state).map((c) => [c.change.object, c.change.rule, c.sql])).toEqual([
+      ["acl default privileges for owner in app on tables TO r", "SQLPG298", ["ALTER DEFAULT PRIVILEGES FOR ROLE owner IN SCHEMA app GRANT SELECT ON TABLES TO r"]],
+      ["acl relation app.t TO r", "SQLPG296", ["REVOKE INSERT ON TABLE app.t FROM r", "GRANT SELECT ON TABLE app.t TO r WITH GRANT OPTION"]],
+      ["acl schema app TO r", "SQLPG296", ["GRANT USAGE ON SCHEMA app TO r"]],
+    ]);
+  });
+
+  test("between two builds, a new function's EXECUTE to PUBLIC is not a change", () => {
+    const f = "CREATE FUNCTION app.f() RETURNS int LANGUAGE sql AS 'select 1'";
+    expect(diffPgSchemas([], [F(f)]).changes.map((c) => c.rule)).toEqual(["SQLPG200"]);
+    expect(diffPgSchemas([], [F(f), G("REVOKE EXECUTE ON FUNCTION app.f() FROM PUBLIC")]).changes.map((c) => [c.object, c.rule])).toEqual([
+      [f, "SQLPG200"],
+      ["acl routine app.f() TO PUBLIC", "SQLPG297"],
+    ]);
+  });
+
+  test("a profile that does not manage access leaves out the access declarations and a table's row-level security", () => {
+    const { kept, unmanaged } = accessScoped(keyedByQualifiedName([T("CREATE TABLE app.t (a int);\nALTER TABLE app.t ENABLE ROW LEVEL SECURITY"), G("GRANT SELECT ON app.t TO r")]), false);
+    expect(unmanaged).toBe(2);
+    expect(kept.map((o) => [o.canonical.kind, o.canonical.fields.rowSecurity])).toEqual([["table", undefined]]);
+  });
+});
+
+// ── Policies, row-level security, roles ────────────────────────────────
+
+const live = (type: string, statement: string) => pgSchemaFromLive([{ type, statement, name: "", oid: "1" } as LivePgObject], "public");
+function steps(type: string, liveDdl: string, declaredDdl: string): string[] {
+  const [obj] = declaredObjects(JSON.stringify({ dialect: "postgres", objects: [{ export: "x", type, ddl: declaredDdl, dependsOn: [] }] }));
+  const after = keyedByQualifiedName([{ key: "x", canonical: obj!.canonical }]);
+  const before = live(type, liveDdl);
+  const m = matchPgObjects(before, after).find((x) => x.kind === "matched")!;
+  return alterSteps(obj!, m.before!.canonical, diffPgSchemas(before, after).changes, { major: 18 }).steps.map((s) => s.sql);
+}
+
+describe("the classifier and the statements", () => {
+  const P = "Postgres::Policy";
+  test("a policy's roles and expressions are ALTER POLICY; its command is a drop and a create", () => {
+    const p1 = "CREATE POLICY p ON app.t FOR SELECT TO r USING (a > 0)";
+    expect(steps(P, p1, "CREATE POLICY p ON app.t FOR SELECT TO r, s USING (a > 1)")).toEqual(["ALTER POLICY p ON app.t TO r, s USING (a > 1)"]);
+    expect(steps(P, p1, "CREATE POLICY p ON app.t FOR UPDATE TO r USING (a > 0)").slice(0, 2)).toEqual(["DROP POLICY p ON app.t", "CREATE POLICY p ON app.t FOR UPDATE TO r USING (a > 0)"]);
+    expect(diffPgSchemas([], keyedByQualifiedName([decl(P, p1)])).changes.map((c) => c.rule)).toEqual(["SQLPG290"]);
+    expect(diffPgSchemas(live(P, p1), []).changes.map((c) => c.rule)).toEqual(["SQLPG292"]);
+  });
+
+  test("row-level security toggled, and a role's attributes changed", () => {
+    expect(steps("Postgres::Table", "CREATE TABLE app.t (a int)", "CREATE TABLE app.t (a int);\nALTER TABLE app.t ENABLE ROW LEVEL SECURITY")).toEqual(["ALTER TABLE app.t ENABLE ROW LEVEL SECURITY"]);
+    expect(steps("Postgres::Role", "CREATE ROLE r", "CREATE ROLE r LOGIN NOINHERIT CONNECTION LIMIT 5")).toEqual(["ALTER ROLE r WITH LOGIN NOINHERIT CONNECTION LIMIT 5"]);
+  });
+});