@intentius/chant-lexicon-sql 0.118.1 → 0.120.0

package/src/op/apply-gate-access.e2e.test.ts

@@ -0,0 +1,207 @@
+/**
+ * An approval does not cover a privilege granted by hand after it (#3706),
+ * end to end on Postgres with a profile that manages access.
+ *
+ * A project in a temporary directory declares a schema, a table and a grant
+ * of SELECT on it to a reader role, and a gated `ApplyOp`. The first approved
+ * run creates them. The next run stops at the gate; the test approves its
+ * plan, grants INSERT on the table to another role by hand, and runs again.
+ * The gate refuses with "is approved, but not for this plan", the hand grant
+ * is still there, and the plan the run printed lists the REVOKE an apply
+ * would make. Approving that plan applies it.
+ *
+ * Before #3706 the plan digest was taken over a diff that left privileges
+ * out (a grant was unobserved there), so the third run revoked the hand
+ * grant under the earlier approval.
+ *
+ * Everything is written to the schema `chant_e2e_3706` and the roles
+ * `chant_e2e_3706_reader` and `chant_e2e_3706_writer`, all dropped afterwards.
+ *
+ * The server: `CHANT_SQL_GATE_POSTGRES_URL` (a `postgres://user@host:port/db`
+ * URL, with `CHANT_SQL_GATE_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.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../postgres/testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../postgres/live/client";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const S = "chant_e2e_3706";
+const READER = "chant_e2e_3706_reader";
+const WRITER = "chant_e2e_3706_writer";
+const OP = "schema-apply";
+
+const given = process.env.CHANT_SQL_GATE_POSTGRES_URL;
+const enabled = given ? true : await dockerAvailable();
+
+interface Run {
+  code: number;
+  output: string;
+}
+
+const strip = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, "");
+
+const SCHEMA = `import { schema, table, grant } from "@intentius/chant-lexicon-sql/postgres";
+
+export const app = schema\`CREATE SCHEMA ${S}\`;
+
+export const orders = table\`
+  CREATE TABLE \${app}.orders (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    total numeric NOT NULL
+  )\`;
+
+export const readOrders = grant\`GRANT SELECT ON TABLE \${orders} TO ${READER}\`;
+`;
+
+const OPS = `import { ApplyOp } from "@intentius/chant/op";
+const { op } = ApplyOp({ name: "${OP}", env: "admin", target: "postgres", gate: { gate: "approve-schema" } });
+export default op;
+`;
+
+const config = (url: string) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "e2e-3706", env: "admin" },
+  sql: ${JSON.stringify({ dialect: "postgres", profiles: { admin: { url, password: { env: "ADMIN_PASSWORD" }, schemas: [S], access: true } } }, null, 2)},
+} satisfies ChantConfig;
+`;
+
+/** The `--plan <digest>` the stopped run printed in its approve command. */
+function approvedPlan(run: Run): string {
+  const m = /chant approve \S+ \S+ .*?--plan (jcs1-sha256:[0-9a-f]{64})/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command with a plan:\n${run.output}`);
+  return m[1];
+}
+
+function gateOf(run: Run): string {
+  const m = /chant approve \S+ (\S+)/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command:\n${run.output}`);
+  return m[1];
+}
+
+describe.skipIf(!enabled)("a gated ApplyOp over Postgres refuses after a privilege granted by hand (#3706)", () => {
+  let server: TestPostgres | undefined;
+  let endpoint: PostgresEndpoint;
+  let admin: PostgresClient;
+  let dir: string | undefined;
+  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}`);
+  };
+
+  const chant = async (...args: string[]): Promise<Run> => {
+    try {
+      const r = await exec(join(BIN, "chant"), args, {
+        cwd: dir,
+        env: { ...process.env, ADMIN_PASSWORD: endpoint.password ?? "", PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      return { code: 0, output: strip(`${r.stdout}${r.stderr}`) };
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string };
+      return { code: typeof e.code === "number" ? e.code : 1, output: strip(`${e.stdout ?? ""}${e.stderr ?? ""}`) };
+    }
+  };
+
+  /** Run the Op, approve the plan it stopped at, run again: the apply converges. */
+  const approveAndRun = async (): Promise<Run> => {
+    const stopped = await chant("run", OP);
+    const approve = await chant("approve", OP, gateOf(stopped), "--plan", approvedPlan(stopped));
+    expect(approve.code, approve.output).toBe(0);
+    const run = await chant("run", OP);
+    expect(run.output).toMatch(/Op "schema-apply" completed/);
+    return run;
+  };
+
+  const writerPrivileges = async () =>
+    (
+      await admin.query<{ p: string }>(
+        `SELECT privilege_type AS p FROM information_schema.role_table_grants WHERE table_schema = '${S}' AND table_name = 'orders' AND grantee = '${WRITER}'`,
+      )
+    ).map((r) => r.p);
+
+  beforeAll(async () => {
+    if (given) endpoint = { url: given, password: process.env.CHANT_SQL_GATE_POSTGRES_PASSWORD };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await cleanup();
+    // The roles are the environment's: provisioned outside the declarations, only named in them.
+    for (const r of [READER, WRITER]) await admin.query(`CREATE ROLE ${r} NOLOGIN`);
+    dir = mkdtempSync(join(tmpdir(), "chant-sql-gate-access-"));
+    symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+    const files: Record<string, string> = {
+      "package.json": JSON.stringify({ name: "sql-gate-access-e2e", private: true, type: "module", scripts: { build: "chant build src --lexicon sql -o dist/schema.json" } }),
+      ".gitignore": "node_modules\ndist\n.chant\n",
+      "chant.config.ts": config(endpoint.url),
+      "ops/apply.op.ts": OPS,
+      "src/schema.ts": SCHEMA,
+    };
+    for (const [path, text] of Object.entries(files)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true });
+      writeFileSync(join(dir, path), text);
+    }
+    const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+    await git("init", "-q");
+    await git("add", "-A");
+    await git("commit", "-qm", "the schema");
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await cleanup().catch(() => undefined);
+      await admin.end();
+    }
+    await server?.stop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("approve, grant by hand, rerun: the gate refuses and the hand grant stays", async () => {
+    await approveAndRun();
+    const readers = await admin.query<{ p: string }>(
+      `SELECT privilege_type AS p FROM information_schema.role_table_grants WHERE table_schema = '${S}' AND table_name = 'orders' AND grantee = '${READER}'`,
+    );
+    expect(readers.map((r) => r.p)).toEqual(["SELECT"]);
+
+    // Nothing to change: the run stops at the gate, and its plan is approved.
+    const first = await chant("run", OP);
+    expect(first.output).not.toContain("PENDING (");
+    const gate = gateOf(first);
+    const digest = approvedPlan(first);
+    const approve = await chant("approve", OP, gate, "--plan", digest);
+    expect(approve.code, approve.output).toBe(0);
+
+    await admin.query(`GRANT INSERT ON ${S}.orders TO ${WRITER}`);
+
+    const second = await chant("run", OP);
+    expect(second.output).toContain(`Gate "${gate}" is approved, but not for this plan.`);
+    expect(second.output).toContain(`approved: ${digest}`);
+    expect(second.output).toMatch(/PENDING \(changes an apply would make that no declared property shows\):\s+~ relation chant_e2e_3706\.orders TO chant_e2e_3706_writer: REVOKE INSERT ON TABLE chant_e2e_3706\.orders FROM chant_e2e_3706_writer/);
+    expect(second.output).not.toMatch(/Op "schema-apply" completed/);
+    expect(await writerPrivileges()).toEqual(["INSERT"]);
+
+    // Approving the plan the second run produced applies the revoke.
+    const fresh = approvedPlan(second);
+    expect(fresh).not.toBe(digest);
+    const reapprove = await chant("approve", OP, gate, "--plan", fresh);
+    expect(reapprove.code, reapprove.output).toBe(0);
+    const third = await chant("run", OP);
+    expect(third.output).toMatch(/Op "schema-apply" completed/);
+    expect(await writerPrivileges()).toEqual([]);
+  }, 600_000);
+});

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

@@ -6,7 +6,7 @@
 
 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 { diffObject, keyedByQualifiedName, pgSchemaFromBuildOutput, pgSchemaFromLive, type PgSchemaObject } from "../plan/schema";
 import { diffPgSchemas, matchPgObjects } from "../plan/diff";
 import { accessScoped } from "../plan/commands";
 import { alterSteps } from "../apply/statements";
@@ -21,6 +21,31 @@ const orders = table`
   ALTER TABLE ${app}.orders ENABLE ROW LEVEL SECURITY;
   ALTER TABLE ${app}.orders FORCE ROW LEVEL SECURITY`;
 
+describe("a grant on an interpolated routine (#3707)", () => {
+  const f = func`CREATE FUNCTION ${app}.total(n int, OUT t bigint) LANGUAGE sql AS 'select 1'`;
+  const buildOf = (objects: Array<{ export: string; entity: { entityType: string; props: unknown } }>) =>
+    JSON.stringify({
+      dialect: "postgres",
+      postgresMajor: 18,
+      objects: objects.map((o) => ({ export: o.export, type: o.entity.entityType, ddl: (o.entity.props as { ddl: string }).ddl })),
+    });
+
+  test("its statement names the routine with its parameter types", () => {
+    expect(grant`GRANT EXECUTE ON FUNCTION ${f} TO ${reader}`.props).toMatchObject({ ddl: "GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader", objectNames: ["app.total(int)"] });
+    // Types written after the reference are kept, not doubled.
+    expect((grant`GRANT EXECUTE ON FUNCTION ${f}(int) TO ${reader}`.props as { ddl: string }).ddl).toBe("GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader");
+  });
+
+  test("against a build from before the grant, it plans as one naming the signature does", () => {
+    const before = pgSchemaFromBuildOutput(buildOf([{ export: "app", entity: app }, { export: "total", entity: f }]));
+    const plan = (g: { entityType: string; props: unknown }) =>
+      diffPgSchemas(before, pgSchemaFromBuildOutput(buildOf([{ export: "app", entity: app }, { export: "total", entity: f }, { export: "run", entity: g }])), { major: 18 }).changes.map((c) => [c.object, c.rule, c.after]);
+    const interpolated = plan(grant`GRANT EXECUTE ON FUNCTION ${f} TO ${reader}`);
+    expect(interpolated).toEqual(plan(grant`GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader`));
+    expect(interpolated.map(([, rule]) => rule)).toContain("SQLPG296");
+  });
+});
+
 describe("the tags", () => {
   test("a table's row-level security, a policy, a role", () => {
     expect(orders.props).toMatchObject({ rowSecurity: true, forceRowSecurity: true });

package/src/postgres/access/changes.ts

@@ -0,0 +1,39 @@
+/**
+ * The privilege changes a connected server needs (#3681): what `chant sql
+ * plan` reports, and what the deep read reports as pending so the plan digest
+ * an approval binds to moves with a privilege granted or revoked by hand
+ * (#3706).
+ */
+
+import type { PostgresClient } from "../live/client";
+import type { CanonicalPgObject } from "../plan/normalize";
+import { declaredAccess, diffAccess, predictedAccess, targetKey, type AccessChange } from "./acl";
+import { readLiveAccess } from "./live";
+
+/** The role a session runs as: the one whose own privileges owning an object gives, and whose default privileges apply. */
+async function currentRole(client: PostgresClient): Promise<{ self?: string }> {
+  const rows = await client.query<{ self: string }>("SELECT current_user AS self").catch(() => []);
+  return rows[0]?.self ? { self: rows[0].self } : {};
+}
+
+/**
+ * The changes from the access the server holds to the access the
+ * declarations (keyed by export name, in the build's order) add up to. An
+ * object the server does not hold yet is taken to have what the server gives
+ * a new one. `scope` limits the default privileges read to those schemas.
+ */
+export async function accessChangesAgainst(
+  client: PostgresClient,
+  declared: ReadonlyArray<{ key: string; canonical: CanonicalPgObject }>,
+  options: { major: number; scope?: readonly string[] },
+): Promise<AccessChange[]> {
+  const want = declaredAccess(declared, { major: options.major, ...(await currentRole(client)) });
+  const have = await readLiveAccess(client, want.targets, {
+    ...(options.scope ? { schemas: options.scope } : {}),
+    forRoles: want.forRoles,
+    declaredDefaults: want.targets.filter((t) => t.kind === "default"),
+  });
+  const missing = want.targets.filter((t) => t.kind !== "default" && t.kind !== "column" && !have.present.has(targetKey(t)));
+  const now = new Map([...have.state, ...predictedAccess(missing, have)]);
+  return diffAccess(now, want.state, want.exportsOf);
+}

package/src/postgres/apply/apply.ts

@@ -70,7 +70,7 @@ import type { OwnershipMarker } from "@intentius/chant/ownership";
 import type { ApplyRef } from "@intentius/chant/apply";
 import { SqlApplyError, dependencyFailedDetail, missingDependencies, readBuildObjects, type SqlApplyOutcome } from "../../core/apply";
 import { carriesMarker, isChantManaged } from "../../core/ownership";
-import { PostgresQueryError, type PostgresClient } from "../live/client";
+import { DEFAULT_LOCK_TIMEOUT_MS, PostgresQueryError, withCatalogLockTimeout, type PostgresClient } from "../live/client";
 import type { PostgresTarget } from "../live/bind";
 import type { LivePgObject, readLiveSchema } from "../live/catalog";
 import { liveProps } from "../plan/deep";
@@ -98,7 +98,7 @@ export interface PostgresApplyTimeouts {
   scanTimeoutMs: number;
 }
 
-export const DEFAULT_POSTGRES_APPLY_TIMEOUTS: PostgresApplyTimeouts = { lockTimeoutMs: 5_000, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
+export const DEFAULT_POSTGRES_APPLY_TIMEOUTS: PostgresApplyTimeouts = { lockTimeoutMs: DEFAULT_LOCK_TIMEOUT_MS, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
 
 /** One statement as it ran: its object, the timeouts it ran with, and the transaction it was in. */
 export interface RanStatement {
@@ -254,8 +254,10 @@ export async function applyPostgres(
   };
 
   // ── Plan: the same diff `chant sql plan` shows. ──
+  // The catalog reads wait under lockTimeoutMs, as a plan's do (#3726): one blocked behind ACCESS EXCLUSIVE fails naming the holder instead of hanging.
+  const reader = await withCatalogLockTimeout(client, timeouts.lockTimeoutMs);
   const build: PgSchemaObject[] = declared.map((o) => ({ key: o.exportName, canonical: o.canonical }));
-  const plan = await planAgainstClient(client, target, build, {
+  const plan = await planAgainstClient(reader, target, build, {
     ...(opts.major !== undefined ? { major: opts.major } : {}),
     ...(opts.readLive ? { readLive: opts.readLive } : {}),
     ...(opts.serverNormalize ? { serverNormalize: opts.serverNormalize } : {}),
@@ -281,7 +283,7 @@ export async function applyPostgres(
   for (const m of matchPgObjects(plan.live, plan.declared)) if (m.kind === "matched") matchedLive.add(m.after.key);
 
   // An extension's own comment stays under the trailer when the declaration sets none.
-  const extensionComments = await extensionDefaults(client, objects.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
+  const extensionComments = await extensionDefaults(reader, objects.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
 
   // ── Each object's statements, or its verdict when it has none to send. ──
   const statements = planPgStatements({
@@ -454,7 +456,7 @@ export async function applyPostgres(
   }
   await commit();
 
-  if (managed) await applyAccess(client, declared, onServer, exportNames, { ...opts, major: plan.major ?? opts.major ?? POSTGRES_LATEST_MAJOR, ...(plan.scope ? { schemas: plan.scope } : {}) }, timeouts, outcome, log);
+  if (managed) await applyAccess(client, reader, declared, onServer, exportNames, { ...opts, major: plan.major ?? opts.major ?? POSTGRES_LATEST_MAJOR, ...(plan.scope ? { schemas: plan.scope } : {}) }, timeouts, outcome, log);
 
   if (opts.prune) await prune(client, statements.drops, liveRawByKey, opts, timeouts, outcome, log);
   if (outcome.failed.length > 0) throw new PostgresApplyError(outcome);
@@ -470,6 +472,7 @@ export async function applyPostgres(
  */
 async function applyAccess(
   client: PostgresClient,
+  reader: PostgresClient,
   declared: readonly DeclaredPgObject[],
   onServer: ReadonlySet<string>,
   exportNames: ReadonlySet<string>,
@@ -487,12 +490,12 @@ async function applyAccess(
     else ready.push(o);
   }
   const skipped = new Set(decls.filter((o) => !ready.includes(o)).map((o) => o.exportName));
-  const [me] = await client.query<{ self: string }>("SELECT current_user AS self");
+  const [me] = await reader.query<{ self: string }>("SELECT current_user AS self");
   const want = declaredAccess(
     declared.filter((o) => !skipped.has(o.exportName)).map((o) => ({ key: o.exportName, canonical: o.canonical })),
     { major: opts.major, ...(me?.self ? { self: me.self } : {}) },
   );
-  const have = await readLiveAccess(client, want.targets, {
+  const have = await readLiveAccess(reader, want.targets, {
     ...(opts.schemas ? { schemas: opts.schemas } : {}),
     forRoles: want.forRoles,
     declaredDefaults: want.targets.filter((t) => t.kind === "default"),

package/src/postgres/entities.ts

@@ -1048,7 +1048,7 @@ function grantProps(ctx: Ctx, node: GrantNode, ddl: string, source: { strings: s
       if (o.args) sqlName += `(${req(text(ctx, o.args, "objects")) ?? ""})`;
       else if (typeof t !== "string" && (t.entityType === POSTGRES_ENTITY_TYPES.function || t.entityType === POSTGRES_ENTITY_TYPES.procedure)) {
         // An interpolated routine is named by its own parameter types.
-        sqlName += `(${(t.props as RoutineProps).args.filter((a) => a.mode !== "out").map((a) => a.type).join(", ")})`;
+        sqlName += `(${routineArgTypes(t.props as RoutineProps)})`;
       } else throw new SqlTemplateError("grant", `${sqlName}: name the parameter types (${sqlName}(...)), or interpolate the routine, since overloads share a name`, 0, 0);
     }
     objectNames.push(sqlName);
@@ -1071,6 +1071,22 @@ function grantProps(ctx: Ctx, node: GrantNode, ddl: string, source: { strings: s
   }) as GrantProps;
 }
 
+/** A routine's parameter types, as `GRANT ... ON FUNCTION f(...)` names it: the `OUT` ones left out. */
+const routineArgTypes = (props: RoutineProps): string => props.args.filter((a) => a.mode !== "out").map((a) => a.type).join(", ");
+
+/** The interpolated functions and procedures not followed by their own `(...)`: the ones a grant's statement writes with the parameter types (#3707). */
+function bareRoutineSplices(tokens: readonly Token[], values: readonly unknown[]): Set<number> {
+  const out = new Set<number>();
+  tokens.forEach((t, k) => {
+    if (t.kind !== "ref") return;
+    const v = values[t.part];
+    if (!isPostgresObject(v) || (v.entityType !== POSTGRES_ENTITY_TYPES.function && v.entityType !== POSTGRES_ENTITY_TYPES.procedure)) return;
+    const next = tokens.slice(k + 1).find((x) => !isTrivia(x));
+    if (!(next?.kind === "punct" && next.text === "(")) out.add(t.part);
+  });
+  return out;
+}
+
 function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string[], rawValues: readonly unknown[]): PostgresObject {
   const rawParts = templateParts(strings);
   const routine = tag === "func" || tag === "procedure";
@@ -1113,9 +1129,12 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
   const rowSecurity = rest.filter((n): n is RowSecurityNode => n.statement === "rowSecurity");
 
   const positions = regclassPositions(tokens, values);
+  const bareRoutines = tag === "grant" ? bareRoutineSplices(tokens, values) : new Set<number>();
   const render = (v: unknown, i?: number): string => {
     const at = i === undefined ? undefined : positions.get(i);
     if (at && isPostgresObject(v)) return at === "call" ? `${regclassText(v.sqlName)}::regclass` : regclassText(v.sqlName);
+    // #3707: a routine a grant interpolates is written with its parameter types, so the statement names it on its own.
+    if (i !== undefined && bareRoutines.has(i) && isPostgresObject(v)) return `${renderReference(v)}(${routineArgTypes(v.props as RoutineProps)})`;
     return renderReference(v);
   };
   const ctx: Ctx = { d: { ...POSTGRES_TEMPLATES, renderReference: render }, tokens, values, fed: values.map(() => new Set<string>()) };

package/src/postgres/live/bind.ts

@@ -6,7 +6,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 { connectPostgres, DEFAULT_LOCK_TIMEOUT_MS, PostgresQueryError, withCatalogLockTimeout, type PostgresClient, type PostgresEndpoint } from "./client";
 import type { PostgresProvider } from "../providers/types";
 import { credentialSource, TokenSourceError } from "../../token-source";
 
@@ -139,11 +139,23 @@ export async function resolveBoundTarget(options: BindOptions = {}): Promise<Pos
   return target;
 }
 
-/** Resolve the environment's server and connect to it. The caller ends the client. */
+/**
+ * Resolve the environment's server and connect to it. The caller ends the client.
+ *
+ * The session reads under the profile's `lockTimeoutMs` (the applier's 5000 ms
+ * otherwise): a catalog read blocked behind ACCESS EXCLUSIVE fails with the
+ * relation and the pid that holds it, instead of waiting for as long as the
+ * lock is held.
+ */
 export async function bindPostgres(options: BindOptions = {}): Promise<{ target: PostgresTarget; client: PostgresClient }> {
   const target = await resolveBoundTarget(options);
-  const client = await (options.connect ?? connectPostgres)(target.endpoint);
-  return { target, client };
+  const raw = await (options.connect ?? connectPostgres)(target.endpoint);
+  try {
+    return { target, client: await withCatalogLockTimeout(raw, target.timeouts?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS) };
+  } catch (err) {
+    await raw.end();
+    throw err;
+  }
 }
 
 /** SQLSTATEs that mean the server refused who we are: invalid_authorization_specification, invalid_password, insufficient_privilege. */

package/src/postgres/live/catalog.ts

@@ -44,26 +44,14 @@ import { quoteIdent } from "../keywords";
 import { hasChantTrailerKey, RECEIPTS_TRAILER_KEY, stripMarker } from "../../core/ownership";
 import { MIGRATION_TRAILER_KEY } from "../migrate/names";
 import { isProviderOwned, providerData } from "../providers";
+import { FOREIGN_TABLES } from "../../core/foreign-tables";
 import type { PostgresProvider } from "../providers/types";
 
 /** The server's own schemas, never part of a declared schema. */
 export const SYSTEM_SCHEMAS = ["pg_catalog", "information_schema", "pg_toast"];
 
-/** Tables another tool keeps its migration history in, by name, with the tool. */
-export const FOREIGN_TABLES: Readonly<Record<string, string>> = {
-  _prisma_migrations: "Prisma Migrate",
-  schema_migrations: "a migration runner (Rails, golang-migrate, dbmate)",
-  ar_internal_metadata: "Rails",
-  django_migrations: "Django",
-  alembic_version: "Alembic",
-  __drizzle_migrations: "drizzle-kit",
-  flyway_schema_history: "Flyway",
-  goose_db_version: "goose",
-  knex_migrations: "Knex",
-  knex_migrations_lock: "Knex",
-  SequelizeMeta: "Sequelize",
-  pgmigrations: "node-pg-migrate",
-};
+/** Tables another tool keeps its migration history in, by name, with the tool; both dialects share the list. */
+export { FOREIGN_TABLES };
 
 export interface LivePgObject {
   type: PostgresEntityType;

package/src/postgres/live/client.ts

@@ -90,3 +90,88 @@ export async function connectPostgres(endpoint: PostgresEndpoint, options: { app
     },
   };
 }
+
+/** SQLSTATE lock_not_available: `lock_timeout` passed while a statement waited for a lock. */
+export const SQLSTATE_LOCK_NOT_AVAILABLE = "55P03";
+
+/** The `lock_timeout` a statement waits under when the profile sets none (`sql.profiles.<env>.lockTimeoutMs`): the applier's and the catalog reader's. */
+export const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+
+/** A session holding ACCESS EXCLUSIVE on a relation: what a catalog read waits behind. */
+export interface LockHolder {
+  pid: number;
+  relation: string;
+  application?: string;
+  state?: string;
+  /** Seconds since the holder's transaction began. */
+  seconds?: number;
+  query?: string;
+}
+
+/**
+ * The sessions holding ACCESS EXCLUSIVE on a relation in the current database,
+ * other than this one. Only that mode conflicts with the ACCESS SHARE a
+ * catalog function (`pg_get_viewdef()`, `pg_get_indexdef()`) takes. Empty when
+ * the lookup itself fails.
+ */
+export async function accessExclusiveHolders(client: PostgresClient): Promise<LockHolder[]> {
+  try {
+    const rows = await client.query<{ pid: number; relation: string; application: string | null; state: string | null; seconds: number | null; query: string | null }>(
+      `SELECT l.pid, l.relation::pg_catalog.regclass::text AS relation, a.application_name AS application, a.state,
+              (EXTRACT(EPOCH FROM pg_catalog.now() - a.xact_start))::int AS seconds, pg_catalog.left(a.query, 120) AS query
+         FROM pg_catalog.pg_locks l LEFT JOIN pg_catalog.pg_stat_activity a ON a.pid = l.pid
+        WHERE l.locktype = 'relation' AND l.granted AND l.mode = 'AccessExclusiveLock'
+          AND l.pid <> pg_catalog.pg_backend_pid()
+          AND l.database = (SELECT oid FROM pg_catalog.pg_database WHERE datname = pg_catalog.current_database())
+        ORDER BY l.pid, 2 LIMIT 10`,
+    );
+    return rows.map((r) => ({
+      pid: Number(r.pid),
+      relation: r.relation,
+      ...(r.application ? { application: r.application } : {}),
+      ...(r.state ? { state: r.state } : {}),
+      ...(r.seconds !== null && r.seconds !== undefined ? { seconds: Number(r.seconds) } : {}),
+      ...(r.query ? { query: r.query.replace(/\s+/g, " ").trim() } : {}),
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** One line naming the lock holders, for a message. */
+export function describeLockHolders(holders: readonly LockHolder[]): string {
+  if (holders.length === 0) return "no session holds ACCESS EXCLUSIVE now; the lock was released after the wait";
+  return holders
+    .map((h) => {
+      const about = [h.application ? `application ${JSON.stringify(h.application)}` : "", h.state ?? "", h.seconds !== undefined ? `transaction open ${h.seconds}s` : "", h.query ? `last statement: ${h.query}` : ""].filter(Boolean);
+      return `${h.relation} is held in ACCESS EXCLUSIVE by pid ${h.pid}${about.length > 0 ? ` (${about.join(", ")})` : ""}`;
+    })
+    .join("; ");
+}
+
+/**
+ * A client for catalog reads: the session's `lock_timeout` is `lockTimeoutMs`
+ * (0 waits without limit, as Postgres does), so a read that needs a table
+ * another session holds in ACCESS EXCLUSIVE (a long `ALTER TABLE`, `LOCK
+ * TABLE`) fails after the wait instead of hanging. The failure names the
+ * relation and the pid holding it.
+ */
+export async function withCatalogLockTimeout(client: PostgresClient, lockTimeoutMs: number = DEFAULT_LOCK_TIMEOUT_MS): Promise<PostgresClient> {
+  await client.query("SELECT pg_catalog.set_config('lock_timeout', $1, false)", [`${lockTimeoutMs}ms`]);
+  return {
+    async query<T>(sql: string, params?: readonly unknown[]): Promise<T[]> {
+      try {
+        return await client.query<T>(sql, params);
+      } catch (err) {
+        if (!(err instanceof PostgresQueryError) || err.code !== SQLSTATE_LOCK_NOT_AVAILABLE) throw err;
+        const holders = describeLockHolders(await accessExclusiveHolders(client));
+        throw new PostgresQueryError(
+          `${err.message.split("\n")[0]}: the catalog read waited ${lockTimeoutMs}ms for a lock; ${holders}. Wait for that transaction to finish, or raise sql.profiles.<env>.lockTimeoutMs`,
+          err.code,
+          err.position,
+        );
+      }
+    },
+    end: () => client.end(),
+  };
+}

package/src/postgres/live/live.test.ts

@@ -196,3 +196,57 @@ describe("a managed provider's own objects (sql.provider)", () => {
     expect(r.resources.authUsers).toMatchObject({ ownership: "foreign", attributes: { keptBy: "Supabase" } });
   });
 });
+
+describe("catalog reads under lock_timeout (#3678)", () => {
+  /** A fake whose view read waits behind a lock and times out, and whose pg_locks names the holder. */
+  const blocked = (log: string[]) => {
+    const inner = fakeClient(CATALOG, log);
+    return {
+      async query<T>(sql: string, params?: readonly unknown[]): Promise<T[]> {
+        if (sql.includes("c.relkind IN ('v', 'm')")) {
+          log.push(sql);
+          throw new PostgresQueryError("canceling statement due to lock timeout", "55P03");
+        }
+        if (sql.includes("pg_catalog.pg_locks")) {
+          log.push(sql);
+          return [{ pid: 4242, relation: "app.orders", application: "psql", state: "idle in transaction", seconds: 12, query: "LOCK TABLE app.orders IN ACCESS EXCLUSIVE MODE" }] as T[];
+        }
+        return inner.query<T>(sql, params);
+      },
+      end: () => inner.end(),
+    };
+  };
+
+  test("the session's lock_timeout is the profile's lockTimeoutMs, else the applier's 5000 ms", async () => {
+    for (const [lockTimeoutMs, expected] of [[undefined, "5000ms"], [250, "250ms"]] as const) {
+      const log: string[] = [];
+      const params: unknown[][] = [];
+      const cfg = { sql: { profiles: { prod: { ...config.sql.profiles.prod, ...(lockTimeoutMs !== undefined ? { lockTimeoutMs } : {}) } } } };
+      await describeResources({
+        ...options({ users: DECLARED.users }),
+        config: cfg,
+        connect: async () => {
+          const c = fakeClient(CATALOG, log);
+          return { query: (sql: string, p?: readonly unknown[]) => (params.push([sql, ...(p ?? [])]), c.query(sql, p)), end: c.end } as never;
+        },
+      });
+      expect(params[0]).toEqual(["SELECT pg_catalog.set_config('lock_timeout', $1, false)", expected]);
+    }
+  });
+
+  test("a read that times out on a lock is read-failed, naming the relation and the pid holding it", async () => {
+    const log: string[] = [];
+    const r = normalizeObservation(await describeResources({ ...options({ users: DECLARED.users }), connect: async () => blocked(log) as never }));
+    const users = r.unobserved.users;
+    expect(users?.reason).toBe("read-failed");
+    expect(users?.detail).toContain("canceling statement due to lock timeout");
+    expect(users?.detail).toContain("app.orders is held in ACCESS EXCLUSIVE by pid 4242");
+    expect(users?.detail).toContain("lockTimeoutMs");
+  });
+
+  test("other failures pass through unchanged", async () => {
+    const { withCatalogLockTimeout } = await import("./client");
+    const c = await withCatalogLockTimeout({ query: async (sql: string) => { if (sql.startsWith("SELECT 1")) throw new PostgresQueryError("boom", "XX000"); return []; }, end: async () => {} }, 100);
+    await expect(c.query("SELECT 1")).rejects.toThrow(/^boom$/);
+  });
+});