@ultimat3/db 29.4.0 → 30.1.0

package/src/row-security-role.ts

@@ -0,0 +1,60 @@
+// Single responsibility: is the role this process serves as subject to row security at all.
+// Postgres exempts a superuser, a `bypassrls` role, and a table's owner unless the table FORCES it;
+// a policy over any of those refuses nothing. Read off `current_user`'s attributes, never a name.
+
+import type { DbClient } from './client';
+import { DbError } from './errors';
+import { sql } from './sql';
+
+export interface RowSecurityRole {
+  readonly role: string;
+  readonly superuser: boolean;
+  readonly bypassRls: boolean;
+  /** Tables this role owns with row security enabled and not forced: the owner sees every row. */
+  readonly ownedUnforced: number;
+}
+
+interface RoleRow {
+  readonly role: string;
+  readonly superuser: boolean;
+  readonly bypass: boolean;
+  readonly unforced: number;
+}
+
+/** The attributes, read once. `x doctor` lists them; the boot judges them. */
+export async function rowSecurityRole(client: DbClient): Promise<RowSecurityRole> {
+  const row = await client.one<RoleRow>(sql`
+    select r.rolname as role, r.rolsuper as superuser, r.rolbypassrls as bypass,
+      (select count(*) from pg_class c
+        where c.relowner = r.oid and c.relrowsecurity and not c.relforcerowsecurity)::int as unforced
+    from pg_roles r where r.rolname = current_user`);
+  return {
+    role: row?.role ?? '',
+    superuser: row?.superuser === true,
+    bypassRls: row?.bypass === true,
+    ownedUnforced: Number(row?.unforced ?? 0),
+  };
+}
+
+/** Why `role` is exempt, or `undefined` when row security binds it. */
+export function rowSecurityExemption(role: RowSecurityRole): string | undefined {
+  if (role.superuser) return 'is a superuser';
+  if (role.bypassRls) return 'has bypassrls';
+  if (role.ownedUnforced > 0) {
+    return `owns ${String(role.ownedUnforced)} table(s) with row security enabled and not forced`;
+  }
+  return undefined;
+}
+
+/** `X_DB_ROW_SECURITY_BYPASSED` when the serving role would see every tenant's rows. */
+export async function assertRowSecurityBinds(client: DbClient): Promise<void> {
+  const role = await rowSecurityRole(client);
+  const exemption = rowSecurityExemption(role);
+  if (exemption === undefined) return;
+  throw new DbError({
+    code: 'X_DB_ROW_SECURITY_BYPASSED',
+    cause: `database.rowSecurity is on and the connected role ${JSON.stringify(role.role)} ${exemption}, which Postgres exempts from every policy`,
+    fix: 'psql "$DATABASE_URL" -c \'alter role <role> nosuperuser nobypassrls\'  # and serve as a role that owns no table: the migrator owns them, ROLE=migrate',
+    meta: { role: role.role, superuser: role.superuser, bypassRls: role.bypassRls },
+  });
+}

package/src/row-security-roles.ts

@@ -0,0 +1,64 @@
+// Single responsibility: the two roles row security needs on an engine whose own user is a
+// superuser — PGlite's default role, and the test services' `ultimate`. The app role serves and is
+// subject to every policy; the migrator owns the tables and bypasses them, so a backfill or a key
+// validate still sees every row. Idempotent: run on every boot of a flag-on database.
+
+import type { DbClient } from './client';
+import { identifier, raw } from './sql';
+
+/** `nosuperuser nobypassrls`, owning nothing: the role a request runs as. */
+export const APP_ROLE = 'x_app';
+/** `bypassrls`, owning every table: the role `ROLE=migrate` runs as. */
+export const MIGRATOR_ROLE = 'x_migrator';
+
+/**
+ * The statements, in order. Created only when absent (`create role` has no `if not exists`),
+ * attributes re-asserted every time so a role an operator altered by hand is put back. The
+ * bootstrap user may switch into both. Text, so a runner with no `DbClient` (`@ultimat3/testing`'s
+ * template database) runs the same list.
+ */
+export function rowSecurityRolesSql(): readonly string[] {
+  const app = identifier(APP_ROLE).text;
+  const migrator = identifier(MIGRATOR_ROLE).text;
+  const later = (grant: string): string =>
+    `alter default privileges for role ${migrator} in schema public grant ${grant} to ${app}`;
+  return [
+    'do $roles$ begin ' +
+      `if not exists (select from pg_roles where rolname = '${APP_ROLE}') then create role ${app}; end if; ` +
+      `if not exists (select from pg_roles where rolname = '${MIGRATOR_ROLE}') then create role ${migrator}; end if; ` +
+      'end $roles$',
+    `alter role ${app} nosuperuser nobypassrls nocreaterole nocreatedb`,
+    `alter role ${migrator} nosuperuser bypassrls`,
+    `grant ${app}, ${migrator} to current_user`,
+    // What the migrator creates later, the app role can reach: the grants follow the table.
+    `grant usage on schema public to ${app}`,
+    `grant create, usage on schema public to ${migrator}`,
+    later('select, insert, update, delete on tables'),
+    later('usage, select on sequences'),
+  ];
+}
+
+/** Idempotent: run on every boot of a flag-on database. */
+export async function ensureRowSecurityRoles(client: DbClient): Promise<void> {
+  for (const statement of rowSecurityRolesSql()) await client.execute(raw(statement));
+}
+
+/** `set role` on a session — PGlite's one, or a test connection — for the rest of its life. */
+export function assumeRole(client: DbClient, role: typeof APP_ROLE | typeof MIGRATOR_ROLE) {
+  return client.execute(raw(`set role ${identifier(role).text}`));
+}
+
+/**
+ * On an engine whose roles are ours (PGlite, whose one session is a superuser): the roles, DML on
+ * every table and sequence already there — the framework's `x_*` and any table a superuser created
+ * before the flag — then the session serves as `x_app` for the rest of its life. Idempotent.
+ */
+export async function serveAsAppRole(client: DbClient): Promise<void> {
+  const app = identifier(APP_ROLE).text;
+  await ensureRowSecurityRoles(client);
+  await client.execute(
+    raw(`grant select, insert, update, delete on all tables in schema public to ${app}`),
+  );
+  await client.execute(raw(`grant usage, select on all sequences in schema public to ${app}`));
+  await assumeRole(client, APP_ROLE);
+}

package/src/row-security.ts

@@ -0,0 +1,59 @@
+// Single responsibility: the SQL of the database's own tenant guard — enable and FORCE row level
+// security on a tenant table, one policy reading the transaction-local `x.tenant` / `x.cross`, and
+// the drop. Pure text: the generator emits it, the drift repair pastes it, the live test runs it.
+
+import { identifierUnsafe } from './errors';
+import { identifier } from './sql';
+
+/** The one policy name, the same on every table: a policy name is unique per table. */
+export const ROW_SECURITY_POLICY = 'ultimate_tenant';
+/** The settings `setLocal` writes and the policy reads. Never set at session level. */
+export const TENANT_SETTING = 'x.tenant';
+export const CROSS_TENANT_SETTING = 'x.cross';
+
+/**
+ * A Postgres type name as an entity column records it (`uuid`, `text`, `bigint`, `integer`). A
+ * closed shape, re-derived rather than spliced: `create policy` takes no parameter, so a type
+ * reaching it is text, and anything but a plain (optionally spaced) word is refused upstream.
+ */
+const TYPE = /^[a-z][a-z0-9 ]*$/;
+
+/**
+ * Unset is `''` (a `set_config` local value reads back as `''` once its transaction ends) and
+ * `nullif` turns it into NULL, so an unset tenant matches NO row: fail closed, never open.
+ */
+function predicate(column: string, type: string): string {
+  if (!TYPE.test(type)) throw identifierUnsafe(type);
+  return (
+    `(${identifier(column).text} = nullif(current_setting('${TENANT_SETTING}', true), '')::${type}` +
+    ` or current_setting('${CROSS_TENANT_SETTING}', true) = 'on')`
+  );
+}
+
+/**
+ * `enable` + `force` (an owner is exempt unless forced) + the policy, `using` for what a statement
+ * may see and `with check` for what it may write: an insert naming another tenant is refused.
+ */
+export function enableRowSecuritySql(
+  table: string,
+  column: string,
+  type: string,
+): readonly string[] {
+  const name = identifier(table).text;
+  const rule = predicate(column, type);
+  return [
+    `alter table ${name} enable row level security;`,
+    `alter table ${name} force row level security;`,
+    `create policy ${identifier(ROW_SECURITY_POLICY).text} on ${name} using ${rule} with check ${rule};`,
+  ];
+}
+
+/** The revert. `if exists`: a database where the policy was already dropped by hand must not fail. */
+export function dropRowSecuritySql(table: string): readonly string[] {
+  const name = identifier(table).text;
+  return [
+    `drop policy if exists ${identifier(ROW_SECURITY_POLICY).text} on ${name};`,
+    `alter table ${name} no force row level security;`,
+    `alter table ${name} disable row level security;`,
+  ];
+}

package/src/same-tenant.ts

@@ -0,0 +1,173 @@
+// Single responsibility: what a same-tenant edge needs that its own entity cannot declare. The
+// composite key names `(tenant, id)` on the TARGET, so the unique index behind it belongs to a table
+// whose description knows nothing about who points at it. It is answered once, over the whole set.
+
+import type {
+  ColumnDescriptionLike,
+  EntityDescriptionLike,
+  IndexDescriptionLike,
+} from './entity-shape';
+import { referenceParts } from './foreign-key';
+import { findTable, type IndexDescription, type SchemaDescription } from './introspect';
+import { MAX_IDENTIFIER_BYTES } from './invariant-ddl';
+
+/** How much of a name survives beside its hash: `_` and eight hex characters. */
+const KEPT_BYTES = MAX_IDENTIFIER_BYTES - 9;
+
+/**
+ * Within the 63 bytes Postgres truncates at and says nothing. Past them two keys sharing a prefix
+ * would be one name on the server, so the end is a hash of the whole: deterministic across
+ * processes, because a name is a property of the declaration. Every name a same-tenant edge mints
+ * passes here, and a name that fits is untouched.
+ */
+const bounded = (name: string): string => {
+  if (new TextEncoder().encode(name).length <= MAX_IDENTIFIER_BYTES) return name;
+  const hash = new Bun.CryptoHasher('sha256').update(name).digest('hex').slice(0, 8);
+  return `${name.slice(0, KEPT_BYTES)}_${hash}`;
+};
+
+/** `<table>_<column>_tenant_fkey`: another name than the plain key's, so the two can coexist. */
+export function sameTenantKeyName(table: string, column: string): string {
+  return bounded(`${table}_${column}_tenant_fkey`);
+}
+
+/** Whether an index already holds `columns` unique over every row, whichever way round. */
+const answers = (index: IndexDescriptionLike, columns: ReadonlySet<string>): boolean =>
+  index.unique &&
+  index.where === null &&
+  index.columns.length === columns.size &&
+  index.columns.every((column) => columns.has(column));
+
+/** The same question of a `unique` invariant: `declaredIndexes` makes it an index of its own. */
+const invariantAnswers = (entity: EntityDescriptionLike, columns: ReadonlySet<string>): boolean =>
+  (entity.invariants ?? []).some(
+    ({ kind, where, columns: named }) =>
+      kind === 'unique' &&
+      where === null &&
+      named?.length === columns.size &&
+      named.every((column) => columns.has(column)),
+  );
+
+const primaryKeyAnswers = (entity: EntityDescriptionLike, columns: ReadonlySet<string>): boolean =>
+  entity.primaryKey.length === columns.size &&
+  entity.primaryKey.every((column) => columns.has(column));
+
+const sameTenantColumns = (
+  entity: EntityDescriptionLike,
+): readonly (ColumnDescriptionLike & { readonly references: string })[] =>
+  entity.columns.flatMap((column) =>
+    column.references !== null && column.references !== undefined && column.sameTenant != null
+      ? [{ ...column, references: column.references }]
+      : [],
+  );
+
+/** Every target's wanted column lists, keyed by target table, then by the list itself. */
+type Wanted = Map<string, Map<string, readonly string[]>>;
+
+const want = (wanted: Wanted, target: string, columns: readonly string[]): void => {
+  const forTarget = wanted.get(target) ?? new Map<string, readonly string[]>();
+  forTarget.set(columns.join('\0'), columns);
+  wanted.set(target, forTarget);
+};
+
+/**
+ * What a retired column's recorded composite key still points at. The column left the description
+ * and stays in the table, its key with it, so the unique index under that key cannot go: a drop is
+ * `2BP01`, on every run. It goes once the column does (`drop column` takes the key first).
+ */
+const wantedByRetired = (
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription | undefined,
+  wanted: Wanted,
+): void => {
+  if (current === undefined) return;
+  for (const entity of entities) {
+    const retired = entity.retired ?? [];
+    if (retired.length === 0) continue;
+    for (const key of findTable(current, entity.table)?.foreignKeys ?? []) {
+      if (key.columns.length > 1 && key.columns.some((column) => retired.includes(column))) {
+        want(wanted, key.referencedTable, key.referencedColumns);
+      }
+    }
+  }
+};
+
+/**
+ * The set with every target's `(tenant, column)` unique index on its own list. `concurrently: true`
+ * means what it means on any index: nothing on a table this migration creates, the deferred step on
+ * a live one, which is what `targetIndexDeferred` reads so the key lands after it.
+ *
+ * Skipped when the table already holds that uniqueness over every row. A PARTIAL one does not count:
+ * Postgres refuses a key over it (`42830`). Idempotent, so every entry point may pass through here.
+ * `current` is the record a retired column's key is still on; absent, only declared edges count.
+ */
+export function withSameTenantIndexes(
+  entities: readonly EntityDescriptionLike[],
+  current?: SchemaDescription,
+): readonly EntityDescriptionLike[] {
+  const wanted: Wanted = new Map();
+  for (const entity of entities) {
+    for (const column of sameTenantColumns(entity)) {
+      const [target, key] = referenceParts(column.references);
+      want(wanted, target, [column.sameTenant?.targetColumn ?? '', key]);
+    }
+  }
+  wantedByRetired(entities, current, wanted);
+  if (wanted.size === 0) return entities;
+  return entities.map((entity) => {
+    const needed = wanted.get(entity.table);
+    if (needed === undefined) return entity;
+    const extra = [...needed.values()].flatMap((columns): IndexDescriptionLike[] => {
+      const set = new Set(columns);
+      if (
+        primaryKeyAnswers(entity, set) ||
+        invariantAnswers(entity, set) ||
+        entity.indexes.some((index) => answers(index, set))
+      ) {
+        return [];
+      }
+      return [
+        {
+          name: bounded(`${entity.table}_${columns.join('_')}_tenant_key`),
+          columns,
+          unique: true,
+          where: null,
+          order: null,
+          concurrently: true,
+        },
+      ];
+    });
+    return extra.length === 0 ? entity : { ...entity, indexes: [...entity.indexes, ...extra] };
+  });
+}
+
+/**
+ * The indexes only a retired column's recorded key keeps, per table, as a snapshot records them:
+ * for `recordRetired`, which is also `checkSnapshotDrift`'s path and has no migration to read them off.
+ */
+export function retiredKeyIndexes(
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+): ReadonlyMap<string, readonly IndexDescription[]> {
+  const out = new Map<string, readonly IndexDescription[]>();
+  const without = withSameTenantIndexes(entities);
+  for (const entity of withSameTenantIndexes(entities, current)) {
+    const known = new Set(
+      without.find((each) => each.table === entity.table)?.indexes.map((index) => index.name),
+    );
+    const kept = entity.indexes.filter((index) => !known.has(index.name));
+    if (kept.length === 0) continue;
+    out.set(
+      entity.table,
+      kept.map((index) => ({
+        name: index.name,
+        columns: [...index.columns],
+        unique: index.unique,
+        primary: false,
+        where: index.where,
+        order: index.order,
+      })),
+    );
+  }
+  return out;
+}

package/src/schema-dump-policies.ts

@@ -0,0 +1,26 @@
+// Single responsibility: a table's row security as dump statements — the `enable` and `force`
+// flags, then each policy with every clause spelled. Pure; `schema-dump.ts` files them under
+// `10_policies/`, after every table, function and role-free object they could name.
+
+import type { CatalogPolicy, CatalogRowSecurity } from './catalog';
+import { quoted } from './schema-dump-table';
+
+export const rowSecurityStatements = (entry: CatalogRowSecurity): readonly string[] => [
+  ...(entry.enabled ? [`alter table ${quoted(entry.table)} enable row level security;`] : []),
+  ...(entry.forced ? [`alter table ${quoted(entry.table)} force row level security;`] : []),
+];
+
+/** `public` is a keyword here, never a quoted role: `to "public"` names a role called public. */
+const grantee = (role: string): string => (role === 'public' ? role : quoted(role));
+
+export function policyStatement(policy: CatalogPolicy): string {
+  const clauses = [
+    `create policy ${quoted(policy.name)} on ${quoted(policy.table)}`,
+    `as ${policy.permissive ? 'permissive' : 'restrictive'}`,
+    `for ${policy.command}`,
+    `to ${policy.roles.map(grantee).join(', ')}`,
+  ];
+  if (policy.using !== null) clauses.push(`using (${policy.using})`);
+  if (policy.withCheck !== null) clauses.push(`with check (${policy.withCheck})`);
+  return `${clauses.join(' ')};`;
+}

package/src/schema-dump-table.ts

@@ -48,20 +48,35 @@ function columnClause(column: CatalogColumn): string {
   return parts.join(' ');
 }
 
+/**
+ * `create table`, or for a partition `create table … partition of <parent> [(constraints)] <bound>`
+ * — a partition's columns are its parent's, so only the constraints it holds of its own are
+ * spelled. `partition by` follows either on a partitioned table, Postgres' clause order.
+ */
+function createTable(table: CatalogTable): string {
+  const name = quoted(table.name);
+  const head = table.unlogged ? 'create unlogged table' : 'create table';
+  const by = table.partitionBy === undefined ? '' : ` partition by ${table.partitionBy}`;
+  const options = table.options === null ? '' : ` with (${table.options})`;
+  const constraints = table.constraints.map((line) => `  ${constraintClause(line)}`);
+  if (table.partitionOf !== undefined) {
+    const { table: parent, bound } = table.partitionOf;
+    const body = constraints.length === 0 ? '' : ` (\n${constraints.join(',\n')}\n)`;
+    return `${head} ${name} partition of ${quoted(parent)}${body} ${bound}${by}${options};`;
+  }
+  const body = [...table.columns.map((column) => `  ${columnClause(column)}`), ...constraints];
+  return [`${head} ${name} (`, body.join(',\n'), `)${by}${options};`].join('\n');
+}
+
 /**
  * The statements of one table, in the order they must run: a `serial` column's default names its
  * sequence, so the sequence comes first and is handed to the column only once the table exists.
  */
 export function tableStatements(table: CatalogTable): readonly string[] {
   const name = quoted(table.name);
-  const body = [...table.columns.map(columnClause), ...table.constraints.map(constraintClause)].map(
-    (line) => `  ${line}`,
-  );
-  const head = table.unlogged ? 'create unlogged table' : 'create table';
-  const tail = table.options === null ? ');' : `) with (${table.options});`;
   const statements = [
     ...table.sequences.map(createSequence),
-    [`${head} ${name} (`, body.join(',\n'), tail].join('\n'),
+    createTable(table),
     ...table.sequences.map(
       (sequence) =>
         `alter sequence ${quoted(sequence.name)} owned by ${name}.${quoted(sequence.column)};`,

package/src/schema-dump.ts

@@ -5,6 +5,8 @@
 
 import type { CatalogDescription, CatalogType } from './catalog';
 import { FRAMEWORK_TABLE_PREFIX } from './drift';
+import { inLoadOrder } from './partition-order';
+import { policyStatement, rowSecurityStatements } from './schema-dump-policies';
 import { constraintClause, createSequence, quoted, tableStatements } from './schema-dump-table';
 import { literal } from './sql';
 
@@ -25,6 +27,7 @@ export const SCHEMA_DUMP_KINDS = [
   '07_views',
   '08_functions',
   '09_triggers',
+  '10_policies',
 ] as const;
 
 export type SchemaDumpKind = (typeof SCHEMA_DUMP_KINDS)[number];
@@ -108,8 +111,9 @@ function collect(catalog: CatalogDescription): Buckets {
   for (const sequence of catalog.sequences) {
     out.add('03_sequences', sequence.name, sequence.name, createSequence(sequence));
   }
-  for (const table of catalog.tables) {
-    out.add('04_tables', table.name, table.name, ...tableStatements(table));
+  // A partition rides in its root's file, after its parent (`partition-order.ts`).
+  for (const { table, file } of inLoadOrder(catalog.tables)) {
+    out.add('04_tables', file, file, ...tableStatements(table));
   }
   for (const view of catalog.views) {
     const head = view.materialized ? 'create materialized view' : 'create view';
@@ -144,6 +148,13 @@ function collect(catalog: CatalogDescription): Buckets {
       out.add('09_triggers', trigger.table, trigger.table, statement);
     }
   }
+  // Last: a policy may call any function and name any table above it. Flags before policies.
+  for (const entry of catalog.rowSecurity) {
+    out.add('10_policies', entry.table, entry.table, ...rowSecurityStatements(entry));
+  }
+  for (const policy of catalog.policies) {
+    out.add('10_policies', policy.table, policy.table, policyStatement(policy));
+  }
   return out;
 }
 

package/src/snapshot-parse.ts

@@ -10,6 +10,8 @@ import type {
   IndexDescription,
   SchemaDescription,
   TableDescription,
+  TriggerRecord,
+  ViewDescription,
 } from './introspect';
 
 type Row = Record<string, unknown>;
@@ -29,7 +31,7 @@ const order = (value: unknown): value is 'asc' | 'desc' | null =>
 
 function column(value: unknown): ColumnDescription | undefined {
   if (!isRow(value)) return undefined;
-  const { name, dataType, nullable, default: fallback, position, generated } = value;
+  const { name, dataType, nullable, default: fallback, position, generated, retired } = value;
   if (!str(name) || !str(dataType) || !bool(nullable) || !nullableStr(fallback)) return undefined;
   if (typeof position !== 'number') return undefined;
   // `generated` was recorded by `snapshotOf` and dropped HERE, silently, for as long as the field
@@ -37,6 +39,9 @@ function column(value: unknown): ColumnDescription | undefined {
   // so `retypeColumn` read every generated column as newly generated and rebuilt it on every
   // `x db gen`. Absent stays absent — an ordinary column must gain no key.
   if (!(generated === undefined || str(generated))) return undefined;
+  // Dropped here it would refuse the drop it exists to allow. `true` or nothing, `false` normalised
+  // away: a hand-edit meaning what absence means, the rule `appendOnly` states below.
+  if (!(retired === undefined || bool(retired))) return undefined;
   return {
     name,
     dataType,
@@ -44,6 +49,7 @@ function column(value: unknown): ColumnDescription | undefined {
     default: fallback,
     position,
     ...(generated === undefined ? {} : { generated }),
+    ...(retired === true ? { retired: true as const } : {}),
   };
 }
 
@@ -101,6 +107,12 @@ function all<T>(value: unknown, one: (item: unknown) => T | undefined): readonly
   return parsed;
 }
 
+function trigger(value: unknown): TriggerRecord | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, install } = value;
+  return str(name) && strings(install) ? { name, install } : undefined;
+}
+
 function tableOf(value: unknown): TableDescription | undefined {
   if (!isRow(value)) return undefined;
   const { schema, name, primaryKey } = value;
@@ -121,9 +133,21 @@ function tableOf(value: unknown): TableDescription | undefined {
   // `appendOnly` by the same rule: `true` or nothing, `false` normalised away.
   const appendOnly = value['appendOnly'];
   if (!(appendOnly === undefined || bool(appendOnly))) return undefined;
+  // `rowSecurity` by the same rule once more.
+  const rowSecurity = value['rowSecurity'];
+  if (!(rowSecurity === undefined || bool(rowSecurity))) return undefined;
+  const retain = value['retain'];
+  if (!(retain === undefined || bool(retain))) return undefined;
+  // Absent is none recorded; anything present must be a list of `{ name, install }`.
+  const rawTriggers = value['triggers'];
+  const triggers = rawTriggers === undefined ? undefined : all(rawTriggers, trigger);
+  if (rawTriggers !== undefined && triggers === undefined) return undefined;
   const flags = {
+    ...(retain === true ? { retain: true as const } : {}),
+    ...(triggers === undefined ? {} : { triggers }),
     ...(identity === true ? { replicaIdentityFull: true as const } : {}),
     ...(appendOnly === true ? { appendOnly: true as const } : {}),
+    ...(rowSecurity === true ? { rowSecurity: true as const } : {}),
   };
   const raw = value['checks'];
   if (raw === undefined) {
@@ -145,5 +169,21 @@ function tableOf(value: unknown): TableDescription | undefined {
 export function parseSnapshot(value: unknown): SchemaDescription | undefined {
   if (!isRow(value)) return undefined;
   const tables = all(value['tables'], tableOf);
-  return tables === undefined ? undefined : { tables };
+  if (tables === undefined) return undefined;
+  const recorded = value['views'];
+  if (recorded === undefined) return { tables };
+  const views = all(recorded, viewOf);
+  return views === undefined ? undefined : { tables, views };
+}
+
+/** One recorded view: a name, the flag, the statements — anything else is not a snapshot. */
+function viewOf(value: unknown): ViewDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, materialized, create } = value;
+  if (typeof name !== 'string') return undefined;
+  if (!(materialized === undefined || materialized === true)) return undefined;
+  if (!Array.isArray(create) || !create.every((each) => typeof each === 'string')) {
+    return undefined;
+  }
+  return { name, ...(materialized === true ? { materialized } : {}), create };
 }

package/src/sqlstate.ts

@@ -27,6 +27,10 @@ export const SQLSTATE = Object.freeze({
   queryCanceled: '57014',
   /** `lock_not_available` — what `lock_timeout` raises while a DDL statement queues. */
   lockNotAvailable: '55P03',
+  /** `protocol_violation` — a pooler refusing a startup parameter says it in this class. */
+  protocolViolation: '08P01',
+  /** `idle_in_transaction_session_timeout` — the server closed a transaction nobody was using. */
+  idleInTransactionTimeout: '25P03',
   tooManyConnections: '53300',
   outOfMemory: '53200',
 } as const);

package/src/statement-bound.ts

@@ -0,0 +1,82 @@
+// Single responsibility: a time bound for ONE read, tighter than the role's. `statement_timeout`
+// is per role (`libpq-options.ts`); a search that must give up at 500 ms and a report allowed 60 s
+// share it unless the read states its own, transaction-local, through the one `setLocal` seam.
+
+import type { DbClient } from './client';
+import { DbError } from './errors';
+import { setLocal } from './local-settings';
+import { withReadTransaction } from './read-transaction';
+import { sql } from './sql';
+import { currentTx } from './transaction';
+import type { DbTx } from './transaction-options';
+
+const FIX =
+  'query({ timeoutMs: 500 })  # a whole number of ms below the role bound, read with: psql "$DATABASE_URL" -c \'show statement_timeout\'';
+
+function boundInvalid(ms: number, why: string): DbError {
+  return new DbError({
+    code: 'X_DB_STATEMENT_BOUND_INVALID',
+    cause: `withStatementTimeout(${String(ms)}) — ${why}`,
+    fix: FIX,
+  });
+}
+
+export interface StatementBoundOptions {
+  /** Override the ambient pool, as `withTransaction`'s `client` does. */
+  readonly client?: DbClient | undefined;
+}
+
+interface BoundRow {
+  readonly ms: string | number | null;
+}
+
+/**
+ * The bound in force on `tx` now, in ms; `0` is none. Read from `pg_settings`, whose `setting` is
+ * already milliseconds — `current_setting` answers `10s`, a unit this would have to parse.
+ */
+async function boundOn(tx: DbTx): Promise<number> {
+  const row = await tx.one<BoundRow>(
+    sql`select setting as ms from pg_settings where name = 'statement_timeout'`,
+  );
+  return Number(row?.ms ?? 0);
+}
+
+/**
+ * `fn` inside a read-only transaction whose statements are bounded at `ms`. A transaction is pinned
+ * to the primary, so a bounded read never reaches a replica. Inside an open transaction the bound is
+ * set, `fn` runs, and the prior bound is put back — the rest of that transaction keeps its own.
+ *
+ * Refused above the bound already in force (`X_DB_STATEMENT_BOUND_INVALID`): a read cannot extend
+ * what the role was sized for. The bound firing is `57014`, which stays `X_DB_STATEMENT_TIMEOUT`.
+ */
+export function withStatementTimeout<T>(
+  ms: number,
+  fn: (tx: DbTx) => Promise<T>,
+  options: StatementBoundOptions = {},
+): Promise<T> {
+  if (!Number.isSafeInteger(ms) || ms <= 0) {
+    return Promise.reject(boundInvalid(ms, 'a bound is a whole number of milliseconds above 0'));
+  }
+  const nested = currentTx() !== undefined;
+  return withReadTransaction(async (tx) => {
+    const prior = await boundOn(tx);
+    if (prior > 0 && ms > prior) {
+      throw boundInvalid(
+        ms,
+        `the bound in force is ${String(prior)} ms, and a read may only tighten it`,
+      );
+    }
+    await setLocal(tx, { statement_timeout: String(ms) });
+    if (!nested) return fn(tx);
+    let result: T;
+    try {
+      result = await fn(tx);
+    } catch (error) {
+      // Aborted by `fn`'s own failure, the restore would fail too; the abort discards the bound.
+      await setLocal(tx, { statement_timeout: String(prior) }).catch(() => undefined);
+      throw error;
+    }
+    await setLocal(tx, { statement_timeout: String(prior) });
+    return result;
+  }, options);
+}