@ultimat3/db 29.4.0 → 30.1.0

package/src/introspect-rows.ts

@@ -0,0 +1,82 @@
+// Single responsibility: the catalog ROWS `introspectSchema()` reads, and the pure helpers that turn
+// one into a description field — a key's rule with its list, a table's `NOT VALID` names. Split
+// from `introspect.ts`, which issues the queries and folds the rows into tables.
+
+export interface ColumnRow {
+  readonly table_name: string;
+  readonly column_name: string;
+  readonly data_type: string;
+  readonly is_nullable: string;
+  readonly column_default: string | null;
+  readonly ordinal_position: number;
+}
+
+export interface IndexRow {
+  readonly table_name: string;
+  readonly index_name: string;
+  readonly is_unique: boolean;
+  readonly is_primary: boolean;
+  readonly columns: readonly string[];
+  readonly predicate: string | null;
+  readonly descending: boolean;
+  readonly method?: string | undefined;
+}
+
+export interface ForeignKeyRow {
+  readonly table_name: string;
+  readonly constraint_name: string;
+  readonly columns: readonly string[];
+  readonly referenced_table: string;
+  readonly referenced_columns: readonly string[];
+  readonly on_delete: string | null;
+  /** `set null (a, b)`'s list as the server prints it. Postgres 15+; `null` for any other rule. */
+  readonly set_null_columns?: string | null | undefined;
+  readonly validated?: boolean | undefined;
+}
+
+/**
+ * A key's rule in the spelling a description holds, list included. The list reads the definition
+ * text, not `confdelsetcols`, which is a column only Postgres 15+ has: this query runs against
+ * whatever an operator points it at. The server quotes a reserved word and a description never
+ * does, so each name is unquoted or `user` is a permanent `changed-foreign-key`.
+ */
+const unquotedName = (name: string): string => {
+  const trimmed = name.trim();
+  return trimmed.startsWith('"') && trimmed.endsWith('"')
+    ? trimmed.slice(1, -1).replaceAll('""', '"')
+    : trimmed;
+};
+
+export const onDeleteOf = (row: ForeignKeyRow): string | null =>
+  row.set_null_columns == null
+    ? row.on_delete
+    : `set null (${row.set_null_columns.split(',').map(unquotedName).join(', ')})`;
+
+/** A CHECK constraint's NAME. There is deliberately no column for its definition — see `checkNames`. */
+export interface CheckRow {
+  readonly table_name: string;
+  readonly constraint_name: string;
+  readonly validated?: boolean | undefined;
+}
+
+/** An enabled trigger's NAME — the half of `appendOnly` the catalog can answer. */
+export interface TriggerNameRow {
+  readonly table_name: string;
+  readonly trigger_name: string;
+}
+
+/** Absent when none: `false` only, so a row a fake client wrote without the field is not one. */
+export const notValidOf = (
+  rows: readonly {
+    readonly table_name: string;
+    readonly constraint_name: string;
+    readonly validated?: boolean | undefined;
+  }[],
+  table: string,
+): { readonly notValidNames?: readonly string[] } => {
+  const names = rows
+    .filter((row) => row.table_name === table && row.validated === false)
+    .map((row) => row.constraint_name)
+    .sort();
+  return names.length === 0 ? {} : { notValidNames: names };
+};

package/src/introspect.ts

@@ -5,6 +5,17 @@
 
 import { nonAppRelations } from './app-relation';
 import { type DbClient, db } from './client';
+import {
+  type CheckRow,
+  type ColumnRow,
+  type ForeignKeyRow,
+  type IndexRow,
+  notValidOf,
+  onDeleteOf,
+  type TriggerNameRow,
+} from './introspect-rows';
+import { partitionedTables } from './partitioned-tables';
+import { type PolicyNameRow, policyNameRows } from './row-security-catalog';
 import { sql } from './sql';
 
 export interface ColumnDescription {
@@ -23,6 +34,12 @@ export interface ColumnDescription {
    * spellings, which is the same rule `IndexDescription.where` states one field down.
    */
   readonly generated?: string | undefined;
+  /**
+   * `true` on a column an entity lists under `retired` and a migration has marked (`retired.ts`):
+   * old pods may still read it, so it stays until a later migration drops it. Absent otherwise, and
+   * always absent on a catalog read: the database has no such idea.
+   */
+  readonly retired?: true | undefined;
 }
 
 export interface IndexDescription {
@@ -109,6 +126,11 @@ export interface TableDescription {
    * read one instead of reporting every declared constraint as missing.
    */
   readonly checkNames?: readonly string[] | undefined;
+  /**
+   * The constraints the catalog holds `NOT VALID` (`convalidated`): rows that predate one are
+   * unchecked. A catalog reading, absent when there are none, and never on a sidecar.
+   */
+  readonly notValidNames?: readonly string[] | undefined;
   /**
    * That a migration set `replica identity full` on this table — what `@ultimat3/realtime` requires
    * of every table a live query subscribes to, and the only reason this generator emits it.
@@ -138,10 +160,57 @@ export interface TableDescription {
    * Written by `introspectSchema()` always, `[]` included; absent means nobody asked the catalog.
    */
   readonly triggerNames?: readonly string[] | undefined;
+  /**
+   * That the catalog holds this table as a PARTITIONED parent (`relkind = 'p'`). A catalog reading,
+   * `true` or absent, never on a sidecar: a partitioned table is declared by a hand edit to the
+   * generated `create table`, which no entity records, and drift compares what still holds on the
+   * parent — columns, keys, indexes. Absent on every ordinary table, so an unpartitioned app's
+   * descriptions are unchanged. Its partitions are Postgres' and appear in no description.
+   */
+  readonly partitioned?: true | undefined;
+  /**
+   * That a migration gave this table the tenant policy, enabled and forced (`row-security-plan.ts`).
+   * The SNAPSHOT's half, `true` or absent for `appendOnly`'s reason; the catalog's is `policyNames`.
+   */
+  readonly rowSecurity?: true | undefined;
+  /**
+   * The CATALOG's half of `rowSecurity`: the policies on the table when its row security is enabled
+   * and forced, `[]` otherwise (`row-security-catalog.ts`). Absent means nobody asked the catalog.
+   */
+  readonly policyNames?: readonly string[] | undefined;
+  /**
+   * The lifecycle triggers a migration installed on this table — history, its guard, counters
+   * (`generate-triggers.ts`). The SNAPSHOT's half, absent when none; the catalog's is `triggerNames`.
+   */
+  readonly triggers?: readonly TriggerRecord[] | undefined;
+  /**
+   * That the entity declares `retain` (`drift-triggers.ts` refuses it on a partitioned parent).
+   * SNAPSHOT-only, `true` or absent for `appendOnly`'s reason.
+   */
+  readonly retain?: true | undefined;
+}
+
+/** One installed trigger: its name, and the statements that install it — the drift repair too. */
+export interface TriggerRecord {
+  readonly name: string;
+  readonly install: readonly string[];
+}
+
+/**
+ * A view `x db gen` wrote (`generate-view.ts`): SNAPSHOT-only, as `checks` is declared-only — the
+ * catalog reading never fills it (`app-relation.ts` keeps every view out of `tables`), so drift
+ * never reports one. `create` is the statements verbatim, which is what the next diff compares.
+ */
+export interface ViewDescription {
+  readonly name: string;
+  readonly materialized?: true | undefined;
+  readonly create: readonly string[];
 }
 
 export interface SchemaDescription {
   readonly tables: readonly TableDescription[];
+  /** Absent on every snapshot written before views existed, and on every catalog reading. */
+  readonly views?: readonly ViewDescription[] | undefined;
 }
 
 export interface IntrospectOptions {
@@ -157,47 +226,6 @@ export interface IntrospectOptions {
   readonly exclude?: readonly string[] | undefined;
 }
 
-interface ColumnRow {
-  readonly table_name: string;
-  readonly column_name: string;
-  readonly data_type: string;
-  readonly is_nullable: string;
-  readonly column_default: string | null;
-  readonly ordinal_position: number;
-}
-
-interface IndexRow {
-  readonly table_name: string;
-  readonly index_name: string;
-  readonly is_unique: boolean;
-  readonly is_primary: boolean;
-  readonly columns: readonly string[];
-  readonly predicate: string | null;
-  readonly descending: boolean;
-  readonly method?: string | undefined;
-}
-
-interface ForeignKeyRow {
-  readonly table_name: string;
-  readonly constraint_name: string;
-  readonly columns: readonly string[];
-  readonly referenced_table: string;
-  readonly referenced_columns: readonly string[];
-  readonly on_delete: string | null;
-}
-
-/** A CHECK constraint's NAME. There is deliberately no column for its definition — see `checkNames`. */
-interface CheckRow {
-  readonly table_name: string;
-  readonly constraint_name: string;
-}
-
-/** An enabled trigger's NAME — the half of `appendOnly` the catalog can answer. */
-interface TriggerNameRow {
-  readonly table_name: string;
-  readonly trigger_name: string;
-}
-
 const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
 
 export async function introspectSchema(
@@ -272,7 +300,7 @@ export async function introspectSchema(
     join pg_am am on am.oid = i.relam
     cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
     left join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum and k.attnum > 0
-    where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
+    where n.nspname = ${schema} and t.relkind in ('r', 'p') and k.ord <= ix.indnkeyatts
     group by
       t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid,
       ix.indexrelid, am.amname
@@ -284,6 +312,8 @@ export async function introspectSchema(
   // two-column key came back as four source columns against four referenced ones, duplicated and
   // misaligned. Ordered by `k.ord` (the constraint's own key position), never by `attnum`, for the
   // same reason `indkey` orders the index query: `references t (y, x)` is not `references t (x, y)`.
+  // `conparentid = 0`: a key into a partitioned table makes Postgres add one clone per partition
+  // (`notes_event_fkey_1`, `_2`, …), each a fact of the partitioning and never of a migration.
   const foreignKeys = await client.query<ForeignKeyRow>(sql`
     select
       src.relname as table_name,
@@ -291,7 +321,9 @@ export async function introspectSchema(
       array_agg(sa.attname order by k.ord) as columns,
       tgt.relname as referenced_table,
       array_agg(ta.attname order by k.ord) as referenced_columns,
-      c.confdeltype as on_delete
+      c.confdeltype as on_delete,
+      substring(pg_get_constraintdef(c.oid) from 'ON DELETE SET NULL \\(([^)]*)\\)') as set_null_columns,
+      c.convalidated as validated
     from pg_constraint c
     join pg_class src on src.oid = c.conrelid
     join pg_class tgt on tgt.oid = c.confrelid
@@ -299,8 +331,8 @@ export async function introspectSchema(
     cross join lateral unnest(c.conkey, c.confkey) with ordinality as k(src_attnum, tgt_attnum, ord)
     join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = k.src_attnum
     join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = k.tgt_attnum
-    where c.contype = 'f' and n.nspname = ${schema}
-    group by src.relname, c.conname, tgt.relname, c.confdeltype
+    where c.contype = 'f' and n.nspname = ${schema} and c.conparentid = 0
+    group by c.oid, src.relname, c.conname, tgt.relname, c.confdeltype, c.convalidated
     order by src.relname, c.conname
   `);
 
@@ -310,11 +342,11 @@ export async function introspectSchema(
   // a correct database as wrong. `contype = 'c'` is the CHECK constraints alone — Postgres 17
   // onwards records a NOT NULL as `'n'`, and a domain's as `'c'` on the domain rather than here.
   const checks = await client.query<CheckRow>(sql`
-    select src.relname as table_name, c.conname as constraint_name
+    select src.relname as table_name, c.conname as constraint_name, c.convalidated as validated
     from pg_constraint c
     join pg_class src on src.oid = c.conrelid
     join pg_namespace n on n.oid = src.relnamespace
-    where c.contype = 'c' and n.nspname = ${schema} and src.relkind = 'r'
+    where c.contype = 'c' and n.nspname = ${schema} and src.relkind in ('r', 'p')
     order by src.relname, c.conname
   `);
 
@@ -326,11 +358,24 @@ export async function introspectSchema(
     join pg_class src on src.oid = t.tgrelid
     join pg_namespace n on n.oid = src.relnamespace
     where not t.tgisinternal and t.tgenabled in ('O', 'A')
-      and n.nspname = ${schema} and src.relkind = 'r'
+      and n.nspname = ${schema} and src.relkind in ('r', 'p')
     order by src.relname, t.tgname
   `);
 
-  return buildSchema(schema, excluded, columns, indexes, foreignKeys, checks, triggers);
+  const partitioned = await partitionedTables(client, schema);
+  const policies = await policyNameRows(client, schema);
+
+  return buildSchema(
+    schema,
+    excluded,
+    columns,
+    indexes,
+    foreignKeys,
+    checks,
+    triggers,
+    partitioned,
+    policies,
+  );
 }
 
 /** Pure, so the row -> description mapping is testable without a database. */
@@ -343,6 +388,9 @@ export function buildSchema(
   checks: readonly CheckRow[] = [],
   /** Absent leaves `triggerNames` off every table: nobody asked the catalog. */
   triggers?: readonly TriggerNameRow[],
+  partitioned: readonly string[] = [],
+  /** Absent leaves `policyNames` off every table, as `triggers` does `triggerNames`. */
+  policies?: readonly PolicyNameRow[],
 ): SchemaDescription {
   const names = [...new Set(columns.map((row) => row.table_name))]
     .filter((name) => !excluded.includes(name))
@@ -385,7 +433,7 @@ export function buildSchema(
           columns: [...row.columns],
           referencedTable: row.referenced_table,
           referencedColumns: [...row.referenced_columns],
-          onDelete: row.on_delete,
+          onDelete: onDeleteOf(row),
         }))
         .sort(byName),
       // Always written, `[]` included: this reading of a table HAS asked the catalog, and absence
@@ -394,6 +442,7 @@ export function buildSchema(
         .filter((row) => row.table_name === name)
         .map((row) => row.constraint_name)
         .sort(),
+      ...notValidOf([...foreignKeys, ...checks], name),
       ...(triggers === undefined
         ? {}
         : {
@@ -402,6 +451,15 @@ export function buildSchema(
               .map((row) => row.trigger_name)
               .sort(),
           }),
+      ...(partitioned.includes(name) ? { partitioned: true as const } : {}),
+      ...(policies === undefined
+        ? {}
+        : {
+            policyNames: policies
+              .filter((row) => row.table_name === name)
+              .map((row) => row.policy_name)
+              .sort(),
+          }),
     };
   });
 

package/src/keyset.ts

@@ -0,0 +1,182 @@
+// Single responsibility: keyset paging for a raw read — a join the typed handle cannot express.
+// The handle's `.after()` keeps its own seek; this is the same position, carried as the column's
+// TEXT and bound back cast by kind, so a microsecond the JS `Date` would drop is never dropped.
+
+import type { Page } from '@ultimat3/core';
+import {
+  assert,
+  CursorInvalidError,
+  decodeCursor,
+  encodeCursor,
+  finiteCount,
+  pageOf,
+} from '@ultimat3/core';
+import { DbError } from './errors';
+import { join, raw, type SqlFragment, sql } from './sql';
+
+/** The kinds a position can be bound back as, each with its own cast. A closed list. */
+export type KeysetKind = 'timestamptz' | 'uuid' | 'text' | 'integer' | 'bigint';
+
+export interface KeysetKey {
+  /** The ordered expression as written in the statement: `raw('p.created_at')`, or a `sql` one. */
+  readonly column: SqlFragment;
+  readonly kind: KeysetKind;
+  readonly direction: 'asc' | 'desc';
+}
+
+export interface KeysetOptions {
+  /** This read and its arguments: a cursor from another scope is `X_CURSOR_INVALID`. */
+  readonly scope: string;
+  /** The order, last key the tiebreak. Every key must be not null on every row. */
+  readonly keys: readonly KeysetKey[];
+  /** The previous page's `nextCursor`; `null` for the first page. */
+  readonly after: string | null;
+  readonly limit: number;
+}
+
+/** A row as `page` answers it: the `_keyset_<n>` aliases `select` added are gone. */
+export type KeysetRow<Row> = Omit<Row, `_keyset_${number}`>;
+
+/** Four fragments to splice — `select …, ${k.select}`, `where ${k.where}`, `order by`, `limit`. */
+export interface Keyset {
+  readonly select: SqlFragment;
+  readonly where: SqlFragment;
+  readonly orderBy: SqlFragment;
+  /** `limit + 1`: the extra row is how `page` knows there is a next page. */
+  readonly limit: SqlFragment;
+  /** The rows the statement answered, cut to `limit`, the key aliases stripped. */
+  page<Row extends object>(rows: readonly Row[]): Page<KeysetRow<Row>>;
+}
+
+const CASTS: ReadonlyMap<KeysetKind, string> = new Map<KeysetKind, string>([
+  ['timestamptz', 'timestamptz'],
+  ['uuid', 'uuid'],
+  ['text', 'text'],
+  ['integer', 'integer'],
+  ['bigint', 'bigint'],
+]);
+
+const NULL_KEY_FIX =
+  "keyset({ keys: [{ column: sql`coalesce(p.published_at, p.created_at)`, kind: 'timestamptz', direction: 'desc' }, …] })  # or order by a not-null column";
+
+const aliasOf = (index: number): string => `_keyset_${String(index)}`;
+
+/**
+ * The scope the cursor is signed under: the caller's, plus the order itself — so a cursor minted
+ * under `desc` cannot seek an `asc` read, nor a `uuid` key be bound back as `text`. Hashed: the
+ * key expressions are the statement's, not the client's to read.
+ */
+const scopeOf = (scope: string, keys: readonly KeysetKey[]): string => {
+  const order = keys
+    .map(
+      (key) =>
+        `${key.column.text}${JSON.stringify(key.column.values.map(String))} ${key.kind} ${key.direction}`,
+    )
+    .join(',');
+  const digest = new Bun.CryptoHasher('sha256').update(`${scope}|${order}`).digest('hex');
+  return `keyset:${digest.slice(0, 16)}`;
+};
+
+const bind = (key: KeysetKey, text: string): SqlFragment =>
+  sql`${text}::${raw(CASTS.get(key.kind) ?? 'text')}`;
+
+const past = (key: KeysetKey, value: SqlFragment): SqlFragment =>
+  sql`${key.column} ${raw(key.direction === 'desc' ? '<' : '>')} ${value}`;
+
+/**
+ * Uniform direction is ONE row comparison, the shape Postgres pushes into a multicolumn index as
+ * an Index Cond. A mixed order has none, so it is the or-chain — the same split as the entity
+ * driver's `seekSql`. No null branch in either: `page` refuses a null key before it is a cursor.
+ */
+const seek = (keys: readonly KeysetKey[], position: readonly string[]): SqlFragment => {
+  const binds = (): SqlFragment[] => keys.map((key, index) => bind(key, position[index] ?? ''));
+  const [first] = keys;
+  if (first === undefined) return sql`true`;
+  if (keys.length === 1) return past(first, bind(first, position[0] ?? ''));
+  if (keys.every((key) => key.direction === first.direction)) {
+    const op = raw(first.direction === 'desc' ? '<' : '>');
+    return sql`(${join(keys.map((key) => key.column))}) ${op} (${join(binds())})`;
+  }
+  const terms = keys.map((key, index) => {
+    const equal = keys
+      .slice(0, index)
+      .map((prior, at) => sql`${prior.column} = ${bind(prior, position[at] ?? '')}`);
+    const term = past(key, bind(key, position[index] ?? ''));
+    return equal.length === 0 ? term : sql`(${join([...equal, term], ' and ')})`;
+  });
+  return sql`(${join(terms, ' or ')})`;
+};
+
+const positionOf = (cursor: string, scope: string, keys: readonly KeysetKey[]): string[] => {
+  const { key } = decodeCursor(cursor, scope);
+  if (key.length !== keys.length || !key.every((part) => typeof part === 'string')) {
+    throw new CursorInvalidError(
+      `it carries ${key.length} key values, this order needs ${keys.length}`,
+    );
+  }
+  return key as string[];
+};
+
+/** Every key of `row`, as the text the server answered — refused when one is null. */
+const keyText = (row: object, keys: readonly KeysetKey[], index: number): string[] =>
+  keys.map((key, at) => {
+    const value: unknown = Reflect.get(row, aliasOf(at));
+    if (typeof value === 'string') return value;
+    if (value === null) {
+      throw new DbError({
+        code: 'X_KEYSET_NULL_KEY',
+        cause: `row ${String(index)} holds null in keyset key ${String(at)} (${key.column.text}): a row comparison has no null order, so that row and every one like it would fall off the next page`,
+        fix: NULL_KEY_FIX,
+        meta: { key: at, row: index },
+      });
+    }
+    throw new DbError({
+      code: 'X_INVARIANT',
+      cause: `row ${String(index)} carries no ${aliasOf(at)}: the statement did not select keyset()'s keys`,
+      fix: "db().query(sql`select p.*, <k.select> from … where <k.where> order by <k.orderBy> limit <k.limit>`)  # each <…> an interpolation of keyset()'s answer",
+      meta: { key: at, row: index },
+    });
+  });
+
+const stripped = <Row extends object>(row: Row, aliases: ReadonlySet<string>): KeysetRow<Row> =>
+  Object.fromEntries(Object.entries(row).filter(([name]) => !aliases.has(name))) as KeysetRow<Row>;
+
+/**
+ * A keyset page over any statement. The key is selected as `col::text` and bound back as
+ * `$n::<kind>`: exact, no arithmetic, and the `order by` stays on the bare column, so an index on
+ * `(created_at desc, id desc)` answers it as an Index Only Scan.
+ */
+export function keyset(options: KeysetOptions): Keyset {
+  const { keys } = options;
+  assert(
+    keys.length > 0,
+    'keyset() was given no keys, so it has no order to page by',
+    "keyset({ keys: [{ column: raw('p.created_at'), kind: 'timestamptz', direction: 'desc' }, { column: raw('p.id'), kind: 'uuid', direction: 'desc' }], … })",
+  );
+  assert(
+    options.scope.length > 0,
+    'keyset() was given an empty scope, so a cursor from any other raw read would page this one',
+    "keyset({ scope: 'posts.feed', … })   # one name per read, plus its filter arguments",
+  );
+  const limit = finiteCount('keyset', 'limit', options.limit, 1);
+  const scope = scopeOf(options.scope, keys);
+  const where =
+    options.after === null ? sql`true` : seek(keys, positionOf(options.after, scope, keys));
+  return {
+    select: join(keys.map((key, at) => sql`${key.column}::text as ${raw(`"${aliasOf(at)}"`)}`)),
+    where,
+    orderBy: join(keys.map((key) => sql`${key.column} ${raw(key.direction)}`)),
+    limit: sql`${limit + 1}`,
+    page<Row extends object>(rows: readonly Row[]): Page<KeysetRow<Row>> {
+      const positions = rows.map((row, index) => keyText(row, keys, index));
+      const aliases = new Set(keys.map((_key, at) => aliasOf(at)));
+      const kept = rows.slice(0, limit).map((row) => stripped(row, aliases));
+      const last = positions[limit - 1];
+      const next =
+        rows.length > limit && last !== undefined
+          ? encodeCursor({ scope, key: last, id: '' })
+          : null;
+      return pageOf(kept, next);
+    },
+  };
+}

package/src/lifecycle-errors.ts

@@ -0,0 +1,15 @@
+// Single responsibility: the refusal `entity({ retain })` raises at declaration. Here because the
+// code is this package's — the drift step raises it too, for a partitioned table — and
+// `@ultimat3/entity` (tier 2) reaches down for it rather than registering the same code twice.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/** `retain` with no window, beside `appendOnly`, or otherwise unsweepable. */
+export const retainInvalid = (entity: string, reason: string): DbError =>
+  new DbError({
+    code: 'X_ENTITY_RETAIN_INVALID',
+    cause: `entity "${entity}" declares retain, and ${reason}`,
+    fix: `x db gen "retention"   # after entity('${renderFixShellArg(entity, '<entity>')}', { retain: { after: '90d', on: 'createdAt' } }) names a window and appendOnly is gone`,
+    meta: { entity },
+  });

package/src/local-settings.ts

@@ -0,0 +1,38 @@
+// Single responsibility: the framework's one writer of a transaction-local setting. Every
+// `set_config` the framework sends is this file's: parameter-bound and always local, so a value
+// ends with the transaction that set it and a pooled connection hands the next caller nothing.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+/** A setting's name and its value, both text — what `set_config` takes. */
+export type LocalSettings = Readonly<Record<string, string>>;
+
+/**
+ * `select set_config($1, $2, true)` per setting, on `tx`. `true` is "local": the value lives until
+ * the transaction ends, which is the only lifetime safe behind a transaction-mode pooler. Never
+ * `set`/`set local` text: those take no parameters, so a value would have to be spliced in.
+ */
+export async function setLocal(tx: DbClient, settings: LocalSettings): Promise<void> {
+  for (const [name, value] of Object.entries(settings)) {
+    await tx.execute(sql`select set_config(${name}, ${value}, true)`);
+  }
+}
+
+interface SettingRow {
+  readonly value: string | null;
+}
+
+/**
+ * What each named setting reads as now, on `tx`, for a caller that must put it back. An unset custom
+ * setting (`x.tenant` before anything set it) reads `''`, which `set_config` restores to the same
+ * "unset" every policy reads through `nullif(…, '')`.
+ */
+export async function readLocal(tx: DbClient, names: readonly string[]): Promise<LocalSettings> {
+  const prior = new Map<string, string>();
+  for (const name of names) {
+    const row = await tx.one<SettingRow>(sql`select current_setting(${name}, true) as value`);
+    prior.set(name, row?.value ?? '');
+  }
+  return Object.fromEntries(prior);
+}

package/src/marker-line.ts

@@ -1,6 +1,6 @@
 // Single responsibility: whether a migration DECLARES something with a marker line — a top-level
-// `--` comment of its own, and nothing that merely looks like one. Two markers ask this question
-// (`-- destructive: true`, `-- transaction: false`), so the scan is written once.
+// `--` comment of its own, and nothing that merely looks like one. Several markers ask this question
+// (`-- destructive: true`, `-- transaction: false`, `rolling.ts`'s), so the scan is written once.
 
 import { noiseAt } from './sql-scan';
 
@@ -24,6 +24,12 @@ function startsLine(sql: string, index: number): boolean {
  * substring.
  */
 export function hasMarkerLine(sql: string, marker: RegExp): boolean {
+  return markerLines(sql, marker).length > 0;
+}
+
+/** Every such line's text, in source order: a marker that names something is read off these. */
+export function markerLines(sql: string, marker: RegExp): readonly string[] {
+  const found: string[] = [];
   let index = 0;
   while (index < sql.length) {
     const noise = noiseAt(sql, index);
@@ -32,8 +38,10 @@ export function hasMarkerLine(sql: string, marker: RegExp): boolean {
       continue;
     }
     const text = sql.slice(index, noise.end);
-    if (noise.kind === 'line-comment' && startsLine(sql, index) && marker.test(text)) return true;
+    if (noise.kind === 'line-comment' && startsLine(sql, index) && marker.test(text)) {
+      found.push(text);
+    }
     index = noise.end;
   }
-  return false;
+  return found;
 }

package/src/migrate-lock-retry.ts

@@ -0,0 +1,60 @@
+// Single responsibility: send one unit of a migration again when `lock_timeout` fires. A deploy that
+// dies because one reader held a table for 5 s is a wedged rollout for a thing that heals by itself.
+// `migration-step.ts` picks the unit: a transactional step whole, since it rolled back whole, and a
+// non-transactional step one statement at a time, since what already ran stays run.
+
+import { isUltimateError, jitterStatedDelay, logger, type Random } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/** Retries after the first attempt, so six tries: at 3 s each, near half a minute of patience. */
+export const MIGRATION_LOCK_RETRIES = 5;
+
+export interface LockRetryPolicy {
+  readonly retries: number;
+  readonly lockTimeoutMs: number;
+  /** Seams; a test asserts the schedule rather than sleeping through it. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  readonly random?: Random | undefined;
+}
+
+/**
+ * At least one `lockTimeoutMs` between attempts. While the ALTER queued, every query on that table
+ * queued behind it, and going straight back in would stack the same queue on a table that has had
+ * no time to serve it. Jitter upward only, so that floor is a floor.
+ */
+export async function withLockRetry(
+  id: string,
+  policy: LockRetryPolicy,
+  attempt: () => Promise<void>,
+): Promise<void> {
+  const sleep = policy.sleep ?? Bun.sleep;
+  const random = policy.random ?? Math.random;
+  for (let done = 1; ; done += 1) {
+    try {
+      await attempt();
+      return;
+    } catch (error) {
+      if (!isUltimateError(error) || error.code !== 'X_DB_LOCK_TIMEOUT') throw error;
+      const { cause, fix } = error;
+      if (done > policy.retries) {
+        throw new DbError({
+          code: 'X_DB_LOCK_TIMEOUT',
+          cause: `migration "${id}" gave up after ${done} attempts, ${policy.lockTimeoutMs} ms of lock wait each: ${cause}`,
+          fix,
+          meta: { id, attempts: done },
+          sourceError: error,
+        });
+      }
+      const waitMs = jitterStatedDelay(policy.lockTimeoutMs, policy.lockTimeoutMs, random);
+      logger.warn('ultimate migrate lock wait timed out, trying again', {
+        id,
+        attempt: done,
+        of: policy.retries + 1,
+        waitMs,
+        cause,
+        fix,
+      });
+      await sleep(waitMs);
+    }
+  }
+}