@ultimat3/db 29.4.0 → 30.1.0

package/README.md

@@ -3,6 +3,8 @@
 Postgres access for Ultimate: parameterised SQL, transactions, migrations, drift detection,
 branch databases, and a read-only client for anything an LLM drives.
 
+`bun add @ultimat3/db` · guide: [Entities And Migrations](https://github.com/developerz-ai/ultimate/wiki/Entities-And-Migrations)
+
 Tier 1. Imports `@ultimat3/core` only. No runtime dependencies; `@electric-sql/pglite` is an
 **optional peer**, loaded at first query and only by the embedded driver. **No ORM backs any of
 this** — `@ultimat3/entity`'s hand-written `postgresDriver()` compiles every statement out of the
@@ -26,16 +28,20 @@ await withTransaction(async (tx) => {
 | Export | |
 |---|---|
 | `sql` / `raw` / `identifier` / `literal` / `join` | fragment builders |
+| `keyset({ scope, keys, after, limit })` | keyset paging for a raw join: `{ select, where, orderBy, limit, page(rows) }`, [below](#paging-a-raw-join-keyset) |
 | `shellInertIdentifier()` | `As of 2026-08-26`: a quoted identifier that is also inert wherever a human PASTES it — or `null`. The one screen a catalog name goes through before it reaches a `fix:`. `identifier()` answers about SQL and **accepts** a backtick and a `$`, which are exactly what a shell substitutes inside double quotes, so a column called `$(id)` inside `x db gen "add $(id)"` runs `id` on paste |
 | `db()` / `baseClient()` / `setDbClient()` | the ambient client; `db()` returns the open tx if any |
+| `dbClientInstalled()` | `As of 30.0`: whether `setDbClient` installed a client that is still in place. Never builds the lazy default. `@ultimat3/entity`'s `testDriver()` asks it on every repository call |
 | `dbExecutor(client = db)` | the client as `@ultimat3/core`'s `PgExecutor` (`query(text, values)`) — what a jobs, idempotency, notify or MCP confirmation store takes. The client is resolved per statement: the default reaches the boot's client even when declared at module scope, and joins an open `withTransaction`; `() => pool` pins one pool whatever transaction is open |
 | `DbTx.origin` | `As of 2026-08`: the client the transaction was **opened on** — `options.client` or `baseClient()`, never the reservation it runs statements through. `@ultimat3/entity` compares a pinned repository's client against it, so a pinned repo joins its own shard's transaction instead of being refused |
 | `withTransaction()` / `currentTx()` | transaction scope; `currentTx()` is the outbox seam. `{ retry: n }` (`As of 2026-08`) re-runs `fn` from the top on a `40001`/`40P01` and on nothing else — default 0, so `fn` must be idempotent before you ask for it. Each re-run **waits first**, `As of 2026-08-23`: exponential from 10ms, capped at 500ms, full jitter (`@ultimat3/core`'s `backoffDelay`). A budget of 0 waits not at all. **A transaction the server aborted is reported as one**, `As of 2026-10-02` → [Transactions that end badly](#transactions-that-end-badly) |
+| `completeTransaction()` / `refuseAbandoned()` | `As of 2026-11-02`: the mark that takes the open root's statements and COMMIT past an abandoned scope (a keyed action's), and the check for a write that goes through no `DbTx` (`@ultimat3/entity`'s `writing()`, the enqueue facade) → [Transactions that end badly](#transactions-that-end-badly) |
 | `liveTxConnection()` | the connection of the transaction still **open** on this async context, or `undefined`. `currentTx()` keeps answering a finished scope's handle to a promise chain the body forgot to await; this is the one that says whether a statement sent now is really inside a transaction. `@ultimat3/action` reads it before binding an idempotency settlement to a commit |
 | `sqlState()` / `sqlStateCode()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both |
 | `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
 | `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data |
 | `withReplicaReads()` / `replicaScope()` | `As of 2026-08-24`: the scope inside which a plain read may be served by a replica — until it writes, after which every read in it is the primary's. No scope open, nothing routes |
+| `poolerFromEnv()` / `POOLER_ENV` / `PoolerMode` / `POOLER_WAIT_MS` / `statementBound()` / `lostStatementBound()` / `StatementBound` / `poolerSessionRequired()` | `As of 2026-11-03`: a connection pooler in the path (`pooler.ts`), and the two bounds as the session reads them. [Pool sizing by role](#pool-sizing-by-role) |
 | `replicatedClient()` / `ReplicaStats` / `REPLICA_URL_ENV` | `As of 2026-08-24`: one `DbClient` over a primary and a standby. `baseClient()` builds one when `DATABASE_REPLICA_URL` is set and the single-pool client when it is not |
 | `INDEX_METHODS` / `IndexMethod` / `indexMethodOf()` / `indexMethodSql()` / `declaredMethod()` / `isIndexMethod()` | `As of 2026-08-24`: an index's access method — `btree` or `gin`, closed. Absent is `btree`, the live side is read open (whatever `pg_am` said), and the DDL literal is re-derived from the set rather than spliced from the input |
 | `isPlainRead()` | `As of 2026-08-24`: whether a statement may leave the primary. An allow-list — everything it cannot vouch for is the primary's |
@@ -45,15 +51,18 @@ await withTransaction(async (tx) => {
 | `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
 | `isLedgerMissing()` | `As of 2026-08`: whether an error is Postgres' `undefined_table` for `x_migrations` — the one condition a caller may read as "nothing applied" |
 | `appTables()` / `FRAMEWORK_TABLE_PREFIX` | `As of 2026-08`: the live schema minus the `x_` namespace — no migration declares the ledger, the queue, the outbox or an auth table, so none of them is drift |
+| `sameTenantKeyName()` | the name of a same-tenant composite key, `<table>_<column>_tenant_fkey`, within 63 bytes. `ColumnDescriptionLike.sameTenant` is what makes a key composite; `@ultimat3/entity`'s memory driver reads this so its refusal names the constraint Postgres would |
 | `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all. `As of 2026-08-25` a **retype** drops the partial indexes and CHECK constraints written against that column first and restores them in `down`: Postgres compiles both predicates against the old type and cannot recompile either, so `alter column … type text using …::text` was `42883 operator does not exist: text = post_status` and the migration aborted mid-run. A plain btree over the column is left alone — measured, Postgres rebuilds that one itself. `As of 2026-08-26` `replicaIdentityFull` names the tables a live query subscribes to and emits one `alter table … replica identity full` each, last in `up`, recorded on the snapshot so the next generation emits none — a parameter and never an entity field, because the live-query set is a tier-3 fact (`replica-identity.ts`) |
 | `declaredIndexes()` / `invariantChecks()` / `constraintNameFor()` | `As of 2026-08-25`: the DDL an entity **invariant** becomes — a `check` as a named `CONSTRAINT`, a `unique` as a partial-capable unique INDEX, an `assert` as nothing. `EntityDescriptionLike` had no `invariants` field for three majors, so a regenerated migration silently held **none** of them, including the composite UNIQUE `upsertAll`'s `on conflict` is inferred against |
 | `declaredChecks()` / `checkClauses()` / `checkPlan()` / `columnChecks()` / `columnCheckName()` / `columnNamesConstraint()` | `As of 2026-08-25`: **every** CHECK a table declares — a column's own (`enumerated()`'s value set, `tz()`'s IANA whitelist, `locale()`'s tags, money's currency pattern and scale bound) and an invariant's — on ONE list, so `createTable`, `diffTable` and `snapshotOf` agree about what exists. A column's check reached `create table` **inline and anonymous** and nothing else: the snapshot recorded none and the diff had no arm, so a value added to `enumerated()` generated no migration and a regenerated ENUM column came back as bare `text`. The name is `<table>_<column>_check` because that is the name **Postgres itself mints** for the old anonymous form — measured — so the repair lands on the constraint an already-generated database is holding; `checkPlan` emits `drop constraint if exists` before the `add` for exactly that column, because a bare add is `42710` there and a no-op everywhere else |
 | `defaultExpression()` / `ColumnDefaultLike` | `As of 2026-08-25`: a column's `default` as SQL. A DECLARED default (`{ kind: 'value', value }`) wins; `gen_random_uuid()` and `now()` stay as the inference for a description that carries only `hasDefault` |
 | `unrenderedOf()` / `unrenderedComment()` / `UnrenderedDeclaration` | `As of 2026-08-25`: what the generator could **not** write, on `GeneratedMigration.unrendered` and as a `-- UNRENDERED` block at the top of a non-empty `up`. A generator that emits less than the declaration in silence is the defect the whole file exists against, and `x verify`'s `drift` step reads a source hash — it never reads the SQL, so the loss was green. **`unrenderedOf(entities, current)` takes the recorded schema**, required and nullable: a rule declared as an `assert` reaches no SQL by design and is no loss on its own, but one whose CHECK a previous migration RECORDED is dropped by this run and reported by nothing — five in `examples/dummy`, and `@ultimat3/cli`'s `repairFix` then offered `x db gen "drop <name>"` as the repair for the loss that command performs |
 | `isNonTransactional()` / `NO_TRANSACTION_MARKER` / `isConcurrentIndexStatement()` / `concurrentIndexTarget()` | `As of 2026-10-31`: the `-- transaction: false` marker a migration carries to run outside a transaction, and the concurrent index statements that need it → [Indexes built concurrently](#indexes-built-concurrently-and-every-index-drop) |
+| `rollingUnsafeStatements()` / `hasRollingUnsafeMarker()` / `ROLLING_UNSAFE_MARKER` / `retiredColumnsIn()` / `retireAndContractPending()` / `migrationRollingUnsafe()` | `As of 2026-11-02`: the rolling-deploy rail — would the previous release trip over this `up`? A closed list (`drop column` with no earlier `-- retires`, `rename column`, `rename table`), read by the `drift` step past `rollingSince`, and the pair `migrate()` refuses pending together in production |
+| `recordRetired()` | `As of 2026-11-02`: `snapshotOf` one step on, keeping a retired column and what hangs off it on the record. `x db gen` and the `drift` step both read through it, so they cannot disagree about one |
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructiveMigration()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
-| `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
+| `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back. **A partition is not app schema either** (`relispartition`, `As of 2026-11-06`): its parent is judged — keys, indexes, checks, triggers — and carries `partitioned: true`; a key Postgres clones per partition (`conparentid <> 0`) is not read |
 | `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspectSchema()` stays the entity-vocabulary reading a snapshot is diffed in |
 | `renderSchemaDump()` / `SchemaDumpFile` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: a catalog → the schema dump's files. Pure and byte-deterministic. [The schema dump](#the-schema-dump) |
 | `loadSchemaDump()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: build a schema from those files, in one transaction, retrying a file that names something not created yet |
@@ -65,7 +74,9 @@ await withTransaction(async (tx) => {
 | `pgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
 | `readOnlyQuery()` / `READONLY_TIMEOUT_MS` | one statement inside `BEGIN READ ONLY` with a statement timeout — layer 2 |
+| `dbDiagnostics()` / `DIAGNOSTICS_LIMIT` / `DIAGNOSTICS_TIMEOUT_MS` (from `@ultimat3/db/diagnostics`) | `As of 2026-11`: what the database is doing now, as seven sections (`blockers`, `activity`, `slowQueries`, `unusedIndexes`, `invalidIndexes`, `notValidConstraints`, `deadTuples`), each `{ available: true, rows }` or `{ available: false, code, reason, fix }` → [Diagnostics](#diagnostics). `x db diagnostics` prints it |
 | `setStatementObserver()` / `statementObserver()` | `As of 2026-08`: one event **and one `db.<verb>` span** per settled statement, both drivers; uninstalled is one branch |
+| `expectedSeqScan()` / `expectedSeqScanReason()` | `As of 2026-11`: the one way a hand-written statement says it reads its table whole — `x exercise`'s plan sweep lists it exempt with the reason instead of `X_QUERY_UNINDEXED`. Same shape as `expectedQueryLoop()`: required, non-blank, innermost wins. A small table says it once on the entity: `scan: '<why>'` |
 | `expectedQueryLoop()` / `expectedQueryLoopReason()` | `As of 2026-08`: the one way to declare a loop of queries deliberate — the reason rides on every statement it issues as `StatementEvent.expected` |
 | `withStatementAttribution()` / `statementAttribution()` | `As of 2026-08`: the `{ entity, op }` pair on `StatementEvent.attribution`, scoped exactly like `expectedQueryLoop()` — `@ultimat3/entity`'s `postgresRepo` is the one producer |
 | `STATEMENT_ATTRIBUTE` | `As of 2026-08`: `db.statement`, the OTel attribute each span carries its text under — declared here, read by `x dev`'s timeline |
@@ -87,6 +98,32 @@ trusted to remember the difference between a value and a fragment. So:
 - `raw(trusted)` is the one audited escape hatch, `identifier(name)` the safe way to interpolate
   a table or column, `literal(text)` for utility statements that reject bound parameters.
 
+## Failure bundles: `x_failures`
+
+`postgresFailureStore()` is the store `failureCapture` (`app.config.ts`) installs: every statement
+runs `outsideTransaction`, because the request that failed rolled its own transaction back.
+`find(id)` takes a bundle, request or trace id; `latest(fingerprint)` the newest of a group;
+`list({ code })` the summaries `x repro --list` prints. Retention has no default window:
+`failurePurgeTarget(store, { keepMs })` is a `purge()` target. The table is applied by the boot.
+
+## Paging a raw join: `keyset()`
+
+`As of 2026-11-06`. The handle pages with `.after()`; a join it cannot say pages with this. Four
+fragments to splice and `page(rows)`, which answers core's `Page`.
+
+| Rule | |
+|---|---|
+| A key | `{ column: SqlFragment, kind: 'timestamptz' \| 'uuid' \| 'text' \| 'integer' \| 'bigint', direction }`, last key the tiebreak |
+| Precision | selected as `col::text` under `_keyset_<n>`, bound back as `$n::<kind>`: a microsecond survives, a `Date` would floor it and drop rows |
+| The seek | uniform direction: one row comparison, Index Only Scan on a matching index. Mixed: the or-chain |
+| `order by` | the bare columns. `date_trunc('milliseconds', …)` there is a Parallel Seq Scan and a sort (100 ms against 0.2 ms, 300,000 rows); the scaffolded `repo-raw-sql` guard reports it |
+| A null key | `X_KEYSET_NULL_KEY`, on any row of a page, whatever its size |
+| The cursor | core's signed codec; scoped to `scope` plus every key's column, kind and direction. Another read's is `X_CURSOR_INVALID` |
+| `limit` | a whole number ≥ 1 (`finiteCount`), read as `limit + 1` |
+
+Proven on both engines: `keyset.live.test.ts` (Postgres) and `keyset-embedded.test.ts` (PGlite)
+walk four rows inside one millisecond across page boundaries, and assert the plan holds no sort.
+
 ## Transactions that end badly
 
 `As of 2026-10-02`. Postgres aborts the WHOLE transaction on any statement error and answers the
@@ -105,6 +142,9 @@ that, fire `onCommit`, and store nothing.
 | `COMMIT` rejects with a SQLSTATE (a deferred constraint, `40001`) | rolled back: the server's error surfaces, undos run |
 | `COMMIT` rejects with NO SQLSTATE | `X_DB_COMMIT_UNKNOWN`: neither `onCommit` nor `onRollback` runs, and it is never retried |
 | a nested scope passes `isolation`, `readOnly: true`, `deferrable: true`, or a `client` other than the root's | `X_INVARIANT` — a savepoint can honour none of them; `retry` was already refused |
+| a statement on a handle whose scope ended, committed or rolled back: an un-awaited promise, a `Promise.all` loser | `X_DB_TRANSACTION_CLOSED` `As of 2026-11-02`, where it fell through to the pool and autocommitted. `await` it, or `outsideTransaction(fn)` |
+| `ctx.signal` aborted with a coded reason (`X_TIMEOUT`, a job's cancellation), at a statement, a nested scope, a `BEGIN` or a `COMMIT` | `As of 2026-11-02`: that reason is rethrown, the same object, and the scope rolls back. An uncoded abort (a client hang-up) changes nothing. `ROLLBACK` and `ROLLBACK TO` are never refused. A statement on the pool, outside any transaction, is not refused here: `@ultimat3/entity`'s writes ask at their own funnel |
+| the same abort after `completeTransaction()` marked the root | statements and `COMMIT` go through: `withIdempotency` marks a reservation it created, because the settle rides that COMMIT |
 
 Only a failure carrying a SQLSTATE marks the scope aborted: a refusal raised before the send left
 the transaction untouched.
@@ -142,6 +182,21 @@ statement's own error. Every caller handles that failure; nothing here swallows
 `ensureReadOnlyRole()` — otherwise a table created later is not selectable by the role, and
 layer 1 covers only what existed at grant time.
 
+## Diagnostics
+
+`As of 2026-11`. `dbDiagnostics({ client?, limit? })` answers facts, never a verdict: how bloated is
+too bloated differs per app. `checkDb()` stays the readiness probe `/readyz` reads.
+
+| Rule | |
+|---|---|
+| Read-only, bounded | every section is one catalog statement through `readOnlyQuery()`: `BEGIN READ ONLY`, `DIAGNOSTICS_TIMEOUT_MS` (2 s), a cursor capped at `limit` (default 20). Sequential, so one connection |
+| One failure stays one | a section that throws is `{ available: false, code, reason, fix }`; the other six answer. The single throw is a probe (`select 1`) that cannot connect |
+| No row values | no statement reads a user table. Session SQL (`activity`, `blockers`, `slowQueries`) has every literal replaced by `?` before it leaves (`db-diagnostics-redact.ts`, over the package's one lexer); a `scheme://user:pass@` in a reason is masked |
+| `slowQueries` | reads `pg_stat_statements`; absent (always on PGlite) is `available: false` with the operator's `create extension` + `shared_preload_libraries` fix. The framework never creates an extension |
+| `unusedIndexes` | `idx_scan = 0`, unique and primary excluded; each row carries `statsAgeSeconds` (since `pg_stat_reset`, `null` = never) and `replica` — counters are per server |
+| `activity` | `queryVisible: false` (and `query: null`) for a session another role owns when this one lacks `pg_read_all_stats` |
+| Who sees what | whoever runs it sees the SQL text (redacted) of **every session on the app's database role**, and of every role when that role holds `pg_read_all_stats` or is a superuser: other users' requests, background jobs, `psql` sessions. Literals are `?`, statement shape and identifiers are not. Run it with the credentials of someone allowed to see that |
+
 ## Index access methods
 
 `btree` is the default and is never written out; `gin` is what makes `@>` / `<@` / `&&` / `?` on a
@@ -189,6 +244,30 @@ entity('runs', {
 To drop an index on a hot table: delete it from the entity's `indexes`, `x db gen "drop <name>"`,
 commit what it writes, ship. The drop is its own non-transactional migration.
 
+## Reads with their own settings
+
+| API | |
+|---|---|
+| `setLocal(tx, settings)` / `readLocal(tx, names)` | the framework's ONE `set_config` caller: `select set_config($1, $2, true)`, parameter-bound and transaction-local, so a value ends with its transaction and a pooled connection hands nothing on (`read-transaction.test.ts` greps the tree for a second one) |
+| `withReadTransaction(fn, { settings, client })` | `withTransaction(fn, { readOnly: true, client })`, then `setLocal`. Inside an open transaction it joins it, applies the settings, runs `fn` and puts the prior values back |
+| `withStatementTimeout(ms, fn, { client })` | one read's own `statement_timeout`, transaction-local. Refused above the bound already in force, and non-positive (`X_DB_STATEMENT_BOUND_INVALID`); firing is `X_DB_STATEMENT_TIMEOUT`. A transaction is the primary's, so a bounded read never reaches a replica |
+| `setTransactionSettings(provider)` | the settings every ROOT transaction sets right after `BEGIN` — row security's tenant. One provider; unset costs one comparison |
+
+## Row security (`As of 2026-11`, mechanism)
+
+| API | |
+|---|---|
+| `enableRowSecuritySql(table, column, type)` / `dropRowSecuritySql(table)` | `enable` + `force` + one `ultimate_tenant` policy: `using` and `with check` both `column = nullif(current_setting('x.tenant', true), '')::type or current_setting('x.cross', true) = 'on'`. Unset matches nothing |
+| `rowSecurityPlan(plan, input)` / `rowSecurityAfter(input)` | what `x db gen` emits per tenant table when the flag flips, both directions, grants to the app role |
+| `rowSecureClient(client)` | a statement sent outside a transaction while the provider has a tenant is wrapped: `BEGIN [READ ONLY]`, `set_config`, the statement, `COMMIT` |
+| `assertRowSecurityBinds(client)` / `rowSecurityRole(client)` | `X_DB_ROW_SECURITY_BYPASSED` for a superuser, a `bypassrls` role, or the owner of an unforced table — Postgres exempts all three |
+| `ensureRowSecurityRoles(client)` / `assumeRole(client, role)` | `x_app` (`nosuperuser nobypassrls`) and `x_migrator` (`bypassrls`, owns tables), with default privileges from one to the other. `rowSecurityRolesSql()` is the same list as text |
+| `serveAsAppRole(client)` | PGlite's superuser session: the roles, DML on every existing table and sequence to `x_app`, then `set role x_app` |
+| `generateMigration({ rowSecurity: { enabled, tenants } })` | `x db gen`: the policy per tenant table, typed off the column, recorded `rowSecurity: true` on the snapshot; off drops it |
+| `rowSecurityDifferences(entities, snapshot, option)` / `rowSecurityDrift(d)` | the flag against the migrations, `X_DB_ROW_SECURITY_DRIFT`. `checkDrift` raises the same code from `policyNames` (catalog: an enabled AND forced table's policies) |
+
+This layer catches forgetting, not hostile SQL in the app's own process: a raw `set_config('x.cross', 'on', true)` lifts it.
+
 ## Read replicas
 
 Opt in twice, and the second one is why it is safe.
@@ -219,6 +298,7 @@ await withReplicaReads(async () => {
 | read-your-writes | one write anywhere in the scope, at any depth, across any `await`, and every later read in it is the primary's |
 | a transaction | always the primary — `reserve()` is delegated there, so BEGIN, the body and COMMIT are one connection on one server. A `readOnly: true` transaction leaves the scope clean |
 | eligibility | `select` / `table` / `values` / a read-only `with`, minus locking reads, `select … into` and the functions a standby answers instead of refusing (`pg_advisory_lock`, `set_config`, `nextval`). Everything else is the primary's |
+| across requests (`As of 2026-11`) | `withReplicaReads(fn, { minPosition })`: a read goes to the standby only once its `pg_last_wal_replay_lsn()` has passed `minPosition` — sampled once per `positionCacheMs` (50 ms) per client, checked BEFORE the breaker's `admit()` so a read sent to the primary for being behind never spends the half-open probe. Unknown or `null` is the primary. `parsePosition` / `formatPosition` / `primaryPosition` (`replica-position.ts`); `ReplicatedClient.primaryPosition()` reads the primary's WAL position. The boot carries it as `__Host-x-pos` + `x-ultimate-position` |
 | a replica that fails | the statement is re-run on the primary — exactly-once, because only plain reads are sent there and a `25006` refusal never executed. Three failures in a row park it for ten seconds |
 | observability | `client.stats` (`replica`, `primary`, `fallbacks`, `parked`), and a `db.replica_fallback` warning per fallback |
 
@@ -226,9 +306,7 @@ await withReplicaReads(async () => {
 a classifier that cannot be complete; pointed at a writable node a misroute becomes a write on the
 wrong server, silently.
 
-**Nothing opens the scope for you yet.** `withReplicaReads` is tier 1 and ships first; wrapping a
-request in it is the app's call — or one line in the HTTP pipeline — so until that lands no
-production traffic is routed.
+**The boot opens the scope per request** (`@ultimat3/cli`'s `runtime-replica-position.ts`) when `DATABASE_REPLICA_URL` is set.
 
 ## The drift contract
 
@@ -302,6 +380,15 @@ the exit code — and a deploy that rolled on past a schema nobody can reconstru
 drift exists to catch. There is no `x db drift`, and `x verify`'s `drift` step is the *source*
 detector (`checkSourceDrift`), which needs no database and never calls this.
 
+## Views
+
+`EntityDescriptionLike.view` (from `entity({ view: { sql, materialized? } })`) is emitted by
+`generate-view.ts`, never by a table arm: `create [materialized] view` after every table, its
+indexes with it when materialized, recorded on the snapshot as `views: [{ name, materialized?,
+create }]`. Anything that moved — a query, an index, a retype, drop column or drop table under it —
+drops every recorded view first and recreates every declared one last. The catalog reading never
+fills `views`, so drift never reports one.
+
 ## Append-only tables
 
 `EntityDescriptionLike.appendOnly` (from `entity({ appendOnly: true })`) is a trigger, written by
@@ -354,8 +441,13 @@ object kind, numbered in the order a database is built in, one file per named ob
 - A name becomes a file name with everything outside `[A-Za-z0-9_-]` percent-encoded.
 - A file over 500 lines (`SCHEMA_DUMP_MAX_LINES`, the `filesize` ceiling) is split `<name>.1.sql`, `<name>.2.sql`;
   `loadSchemaDump()` joins the parts in numeric order.
-- What cannot be spelled — partitions, inheritance, foreign tables, composite and range types,
-  aggregates, row-security policies (and `force row level security`), rules, extended statistics,
+- A partitioned table is rendered with `partition by`, each partition `partition of … for values` in
+  its root's file, parent first (`partition-order.ts`); a partition's attached indexes, cloned keys
+  and cloned triggers are not, the parent's recreate them. `As of 2026-11-06`.
+- Row security is `10_policies/<table>.sql`: `enable`, `force`, then each policy with every clause
+  (`catalog-policies.ts`, `schema-dump-policies.ts`). `As of 2026-11-06`.
+- What cannot be spelled — inheritance children, foreign tables, composite and range types,
+  aggregates, a policy on a relation the dump does not create, rules, extended statistics,
   a column's non-default `storage`, a materialized view created `with no data`, and a trigger on
   a relation the dump does not create — is named in `unrendered.sql` as comments.
 - A generated column is spelled `stored` or `virtual` (Postgres 18), as `attgenerated` says.
@@ -437,13 +529,47 @@ one role that has to outlive it. Before this, `set` replaced the whole value and
 with a non-zero timeout, so a `search_path` survived on `migrate` and vanished on `web` — the role
 that runs the migrations and the role that serves the traffic reading different schemas.
 
+**`DATABASE_POOLER=session|transaction` names a pooler in the path** (`As of 2026-11-02`):
+`postgresClient({ env })` reads it, with `ROLE` and, absent a `url`, `DATABASE_URL`, from that one
+environment (`process.env` when absent); `client.pooler` is the answer everything after asks.
+Behind a pooler the unanswered-statement deadline grows by `poolerWaitMs` (default
+`POOLER_WAIT_MS`, 120 s, PgBouncer's `query_wait_timeout`): the server's bound starts only once
+the pooler assigns a backend, so a saturated pooler is not a dead path. Set, neither bound is sent as `options`, the operator's own
+stay and an empty one is not emitted; the bounds become `alter role`
+([`docs/ops/04-datastores.md`](../../docs/ops/04-datastores.md#pooling-and-the-trap-under-it)).
+`statementBound(client)` reads both as the session does, `{ applied, expected }` per setting, in ms.
+
+**`idleInTransactionMs`** (`As of 2026-11-02`) is sent as `idle_in_transaction_session_timeout`
+beside the statement bound: `web`, `sync` 30 s, `worker`, `scheduler` 120 s, `migrate`, `replicator`
+0. Past it the server closes the transaction, `X_DB_STATEMENT_FAILED` with `sqlState: '25P03'`.
+
 **`DATABASE_POOL_MAX` overrides `max`** (`As of 2026-08`), and it is the only pool knob an operator
 can turn without shipping an image — 400 `web` pods × the frozen `max: 20` is 8,000 backends. A
 value that is not a positive integer refuses at boot rather than falling back.
 
-**`acquireTimeoutMs` bounds `reserve()`**, because queueing turns exhaustion into a hang: `/readyz`'s
-`select 1` joins the same queue, the kubelet kills the pod, and the replacement inherits the same
-saturated database. 0 waits, which is what a run-once role wants.
+**`acquireTimeoutMs` bounds a plain statement and `reserve()` alike** (`As of 2026-11-02`, for the
+statement), because queueing turns exhaustion into a hang: `/readyz`'s `select 1` joins the same
+queue, the kubelet kills the pod, and the replacement inherits the same saturated database. 0 waits,
+which is what a run-once role wants. `max` is one count in front of `Bun.SQL`, FIFO: a statement holds
+a slot until it settles, a pin until it is released, and a statement on a pin takes none.
+
+**A statement nobody answers replaces the pool** (`As of 2026-11-02`). `statement_timeout` is the
+server's, so it cannot fire when the server or the path is gone, and the kernel's retransmit window is
+about 15 minutes. A statement unanswered past `statementTimeoutMs` + 5 s is `X_DB_UNAVAILABLE`,
+its cause naming the bound and the statement; an autocommit write may have landed. The old pool closes
+in the background (`db.pool.retired`, at error), the next statement opens a new one, a statement still
+queued moves to it unsent, and a `LISTEN` is dialled again, `onListening` firing as on any re-dial.
+`statementTimeoutMs: 0` has no deadline. **A statement on a pin — a transaction's — is bound the same
+way** (`As of 2026-11-06`), against the `statement_timeout` in force on that connection: the role's,
+until a `set_config('statement_timeout', …)` or `SET [LOCAL] statement_timeout` it answered moves it
+(`0`: no deadline), and the role's again after `COMMIT`/`ROLLBACK`. After a miss the pin sends nothing
+more: its `ROLLBACK` is refused `X_DB_UNAVAILABLE` at once rather than waiting out a second bound, and
+a missed `COMMIT` is `X_DB_COMMIT_UNKNOWN`. `X_DB_UNAVAILABLE` is unclassified for retry, so a job worker re-runs the
+attempt: a write that landed runs again, at least once, as every job. `reserve()`'s two waits share one
+`acquireTimeoutMs`. The cost is one unref'd 1 s
+timer per pool while statements are in flight, and a set insert and delete per statement: measured
+2026-11-02 on Postgres, 20,000 sends a side, `max: 4`, p50 216-268 µs against 227-258 µs before, inside
+the noise.
 
 **`lockTimeoutMs` bounds a *wait*, never the work.** `alter table … add column` takes `ACCESS
 EXCLUSIVE`; a long `SELECT` holding `ACCESS SHARE` makes it queue, and Postgres' lock queue is FIFO,
@@ -481,13 +607,16 @@ await subscription.unlisten();
 
 ## Migrations
 
+`As of 2026-11-02`: **a foreign key on a live table** is written to the deferred step (`not valid`, then `validate constraint`, an old key held until the contract phase), **a CHECK** `not valid` in the transaction with its validate deferred, **a column drop** takes two releases (`retired`, `X_MIGRATION_ROLLING_UNSAFE`), and **`migrate()` / `rollback()` send it again** (a transactional step whole, a `-- transaction: false` step per statement) when `lock_timeout` fires (`lockRetries`, default 5). The user-facing page: `wiki/Migrations-And-Backfills.md`.
+
 `migrate()` takes the advisory lock by **polling** `pg_try_advisory_lock(4919202607)` every 500ms
 until `lockWaitMs` (default 60s) and then throwing `X_MIGRATE_CONCURRENT` (`As of 2026-08`).
 `pg_advisory_lock` has no timeout, and a predecessor OOM-killed on a partition keeps its backend —
 and the lock — for hours, so a deploy hook sat inside one statement printing nothing while
 `helm upgrade --wait` blocked and `backoffLimit` never fired, because a job that never finishes
 never fails. It then ensures `x_migrations`
-(`id, name, checksum, applied_at, app_version, duration_ms`), audits, then applies each pending
+(`id, name, checksum, applied_at, app_version, duration_ms`, and `destructive` — added
+`if not exists`, written at apply from `isDestructiveMigration(up)`), audits, then applies each pending
 migration inside its own transaction — or, for one marked `-- transaction: false`, one
 autocommitted statement at a time ([Indexes built concurrently](#indexes-built-concurrently-and-every-index-drop)).
 It refuses **before applying anything** when:
@@ -500,7 +629,12 @@ It refuses **before applying anything** when:
 sorts after the newest migration this build ships, and this build has nothing left to apply, the
 ledger is an older image rolled back onto a newer build's schema. Nothing is applied, the rows are
 reported in `ahead` and logged as `ultimate migrate ledger ahead of build`; any other unknown row is
-still `X_MIGRATION_CONFLICT`.
+still `X_MIGRATION_CONFLICT`. A row ahead whose `destructive` bit is `true` refuses that rollback
+(`X_MIGRATION_ROLLBACK_DESTRUCTIVE`, `As of 2026-11`) unless `ROLLBACK_ALLOW_DESTRUCTIVE` names it
+(comma-separated ids); a `null` bit — a row applied before the ledger kept one — still warns.
+`readLedger()` reads the bit through the row's JSON, so a ledger an older release created answers
+`null` rather than `42703`. The refusal is the ROLLED-BACK build's code: it protects from the
+release after the one that ships it.
 
 Report (`--json`): `{ applied: [{ id, name, durationMs }], skipped: [id], durationMs, appVersion, ahead: [id] }`.
 
@@ -594,17 +728,21 @@ job the moment Postgres fails over.
 | `X_DB_COMMIT_UNKNOWN` | `COMMIT` was sent and the connection failed before the answer: durable or rolled back, unknowable from here |
 | `X_DB_SIBLING_SCOPE_TIMEOUT` | a nested `withTransaction` waited past `siblingWaitMs` for a sibling scope that never finished |
 | `X_DB_STATEMENT_TIMEOUT` | `57014` — the statement ran past `statement_timeout` |
-| `X_DB_LOCK_TIMEOUT` | `55P03` — it waited past `lock_timeout` for a lock it never got |
-| `X_DB_POOL_EXHAUSTED` | `53300` / `53200`, or `reserve()` past `acquireTimeoutMs` |
+| `X_DB_LOCK_TIMEOUT` | `55P03` — it waited past `lock_timeout` for a lock it never got; `migrate()` raises it only once `lockRetries` are spent |
+| `X_MIGRATION_ROLLING_UNSAFE` | a drop or rename the previous release would still read, from `x db gen`, the `drift` rail past `rollingSince`, or `migrate()` with a retire and its drop both pending in production |
+| `X_DB_POOL_EXHAUSTED` | `53300` / `53200`, or a statement or `reserve()` past `acquireTimeoutMs` |
 | `X_DB_DRIFT` | live schema differs from migrations |
-| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch — never for rows that are all newer than the build (a rollback) |
+| `X_MIGRATION_CONFLICT` | ledger app-version fence or checksum mismatch — never for rows that are all newer than the build (a rollback). A mismatch's fix restores the file: `git log -- packages/db/migrations/<id>.sql`, then `git checkout <rev> -- …` the revision whose checksum the ledger names, then `x db gen "<change>"` |
 | `X_MIGRATE_CONCURRENT` | another migrator still held the lock when the wait ran out |
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |
 | `X_BRANCH_EXISTS` | branch database already exists (or is the connected one) |
 | `X_SCHEMA_DUMP_DRIFT` | the committed schema dump is not what the migrations produce, or does not load back |
 | `X_NOT_IMPLEMENTED` | branching an in-memory PGlite — a copy needs a directory |
-| `X_ENV_MISSING` | core's — `DATABASE_POOL_MAX` is set to something that is not a positive integer |
+| `X_ENV_MISSING` | core's — `DATABASE_POOL_MAX` is set to something that is not a positive integer, or `DATABASE_POOLER` to something that is neither `session` nor `transaction` |
+| `X_DB_POOLER_OPTIONS_REFUSED` | `08P01` with `unsupported startup parameter`: a pooler refused the libpq `options`. `DATABASE_POOLER`, then `alter role` |
+| `X_DB_POOLER_SESSION_REQUIRED` | `migrate` or `replicator` under `DATABASE_POOLER=transaction`, before a socket |
+| `X_DB_STATEMENT_BOUND_LOST` | a report, never thrown by a statement: `lostStatementBound(statementBound(client), role, pooler)` |
 
 ```bash
 x db migrate --json
@@ -628,3 +766,13 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `DbError` | any `DbErrorCode` — `DB_ERROR_CODES`, including the SQLSTATE codes a driver error maps to (`DB_SQLSTATE_CODES`) | `src/errors.ts` |
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `unretiredColumnsIn(up)` | the columns this `up` takes back, as `columnKey`: a retire before it earns no later drop |
+| `RollingUnsafeKind` | `'drop-column'`, `'rename-column'` or `'rename-table'`: the closed list |
+| `RollingUnsafeStatement` | one finding of `rollingUnsafeStatements`, carrying its `kind` |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/db",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "Postgres access, transactions, migrations and drift detection",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "postgres",
+    "migrations",
+    "database",
+    "sql"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Entities-And-Migrations",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -15,6 +25,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./diagnostics": "./src/diagnostics-entry.ts",
     "./schema-dump": "./src/schema-dump-entry.ts"
   },
   "files": [
@@ -33,7 +44,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0"
+    "@ultimat3/core": "30.1.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/app-relation.ts

@@ -1,6 +1,6 @@
 // Single responsibility: name the relations in a schema that are NOT app schema, so introspection
-// never puts them in a snapshot and drift can never report one. Two disqualifications, one
-// question: an object an extension owns, and an object that is not a table at all.
+// never puts them in a snapshot and drift can never report one. Three disqualifications, one
+// question: an object an extension owns, an object that is not a table at all, and a partition.
 
 import type { DbClient } from './client';
 import { sql } from './sql';
@@ -27,6 +27,10 @@ interface NonAppRelationRow {
  * `x db gen` diff emits `create view` and no snapshot records one, so counting them as app schema
  * can only ever produce a finding an author has no way to clear.
  *
+ * **A partition is Postgres' (`relispartition`)**, a sub-partition included: the PARENT is what a
+ * migration declares, and each month's child is created by the app's own task. Counted as app
+ * schema, every partition was `unexpected-table` with `drop table` as its fix — a month of rows.
+ *
  * Excluding by NAME is safe because `pg_class` names are unique within a namespace: a name on this
  * list cannot also be an app table in the same schema.
  */
@@ -42,6 +46,7 @@ export async function nonAppRelations(
       and c.relkind in ('r', 'p', 'v', 'm', 'f')
       and (
         c.relkind in ('v', 'm', 'f')
+        or c.relispartition
         or exists (
           select 1
           from pg_depend d

package/src/catalog-fold.ts

@@ -112,5 +112,10 @@ export function tableOf(
         }),
       ),
     replicaIdentity: replicaIdentityOf(row),
+    // Absent, never `null`, on an ordinary table: its description is what it was before these.
+    ...(row.partition_key === null ? {} : { partitionBy: row.partition_key }),
+    ...(row.partition_of === null || row.partition_bound === null
+      ? {}
+      : { partitionOf: { table: row.partition_of, bound: row.partition_bound } }),
   };
 }

package/src/catalog-objects.ts

@@ -34,6 +34,8 @@ export interface ViewRow {
   readonly kind: string;
   readonly options: string | null;
   readonly definition: string;
+  /** The output columns, in order — what a view entity's `columns` must name (`X_ENTITY_VIEW_DRIFT`). */
+  readonly columns: readonly string[];
 }
 
 export interface FunctionRow {
@@ -102,7 +104,12 @@ export const viewRows = (client: DbClient, schema: string): Promise<readonly Vie
       c.relname as name,
       c.relkind as kind,
       array_to_string(c.reloptions, ', ') as options,
-      pg_get_viewdef(c.oid) as definition
+      pg_get_viewdef(c.oid) as definition,
+      array(
+        select a.attname::text from pg_attribute a
+        where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped
+        order by a.attnum
+      ) as columns
     from pg_class c
     join pg_namespace n on n.oid = c.relnamespace
     where n.nspname = ${schema}
@@ -126,6 +133,8 @@ export const functionRows = (client: DbClient, schema: string): Promise<readonly
 
 /**
  * `not tgisinternal`: a foreign key's own enforcement triggers are the constraint's, not the app's.
+ * `tgparentid = 0`: a partition's clone of its parent's trigger (Postgres 13+, `tgisinternal`
+ * false — measured on 18) is recreated by the parent's own `create trigger`.
  * A trigger on an extension-owned table is skipped with its table: the dump creates no such table,
  * so its `09_triggers/` file could never load.
  */
@@ -141,6 +150,7 @@ export const triggerRows = (client: DbClient, schema: string): Promise<readonly
     join pg_namespace n on n.oid = c.relnamespace
     where n.nspname = ${schema}
       and not t.tgisinternal
+      and t.tgparentid = 0
       and ${notExtensionOwned('pg_class', 'c.oid')}
   `);
 
@@ -149,11 +159,11 @@ export const triggerRows = (client: DbClient, schema: string): Promise<readonly
  * here is a kind the dump admits it does not carry, and a kind rendered later leaves this list in
  * the same diff.
  *
- * The last four are facts ABOUT an object the dump does render, and each was absent from both the
- * dump and this list: `create statistics`, `force row level security` (a second flag beside
- * `relrowsecurity`), a column whose `set storage` departs from its type's own, and a materialized
- * view created `with no data` — which the dump's `create materialized view` would populate. A
- * load-equals-replay check cannot see any of them, because both sides are this same reading.
+ * The last three are facts ABOUT an object the dump does render, and each was absent from both the
+ * dump and this list: `create statistics`, a column whose `set storage` departs from its type's
+ * own, and a materialized view created `with no data` — which the dump's `create materialized
+ * view` would populate. A load-equals-replay check cannot see any of them, because both sides are
+ * this same reading. Row security and its policies left this list for `catalog-policies.ts`.
  *
  * A trigger on a relation the dump does not create is the one kind NOT read here: which relations
  * are rendered is the fold's answer, so `introspectCatalog` names those itself.
@@ -166,20 +176,18 @@ export const unrenderedRows = (
     select kind, name, table_name from (
       select
         case
-          when c.relkind = 'p' then 'partitioned table'
           when c.relkind = 'f' then 'foreign table'
           when c.relkind = 'c' then 'composite type'
-          else 'partition or inheritance child'
+          else 'inheritance child'
         end as kind,
         c.relname as name,
         null::text as table_name,
         c.relnamespace as namespace
       from pg_class c
       where (
-          c.relkind in ('p', 'f', 'c')
-          or (c.relkind = 'r' and (
-            c.relispartition or exists (select 1 from pg_inherits h where h.inhrelid = c.oid)
-          ))
+          c.relkind in ('f', 'c')
+          or (c.relkind = 'r' and not c.relispartition
+            and exists (select 1 from pg_inherits h where h.inhrelid = c.oid))
         )
         and ${notExtensionOwned('pg_class', 'c.oid')}
       union all
@@ -191,14 +199,6 @@ export const unrenderedRows = (
       from pg_proc p
       where p.prokind = 'a' and ${notExtensionOwned('pg_proc', 'p.oid')}
       union all
-      select 'row security policy', pol.polname, c.relname, c.relnamespace
-      from pg_policy pol
-      join pg_class c on c.oid = pol.polrelid
-      union all
-      select 'row security', c.relname, c.relname, c.relnamespace
-      from pg_class c
-      where c.relrowsecurity
-      union all
       select 'rule', r.rulename, c.relname, c.relnamespace
       from pg_rewrite r
       join pg_class c on c.oid = r.ev_class
@@ -208,10 +208,6 @@ export const unrenderedRows = (
       from pg_statistic_ext s
       join pg_class c on c.oid = s.stxrelid
       union all
-      select 'forced row security', c.relname, c.relname, c.relnamespace
-      from pg_class c
-      where c.relforcerowsecurity
-      union all
       select 'column storage', a.attname, c.relname, c.relnamespace
       from pg_attribute a
       join pg_class c on c.oid = a.attrelid

package/src/catalog-policies.ts

@@ -0,0 +1,81 @@
+// Single responsibility: row security as the catalog holds it — which tables enable or force it,
+// and every policy on them, clause by clause — read and folded for the schema dump. A dump without
+// them loads a test database that refuses nothing, so a policy would be untested and prod-only.
+
+import type { CatalogPolicy, CatalogRowSecurity } from './catalog';
+import { by } from './catalog-fold';
+import { notExtensionOwned } from './catalog-relations';
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+export interface RowSecurityRow {
+  readonly table_name: string;
+  readonly enabled: boolean;
+  readonly forced: boolean;
+}
+
+export interface PolicyRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly permissive: boolean;
+  readonly command: string;
+  readonly roles: readonly string[];
+  readonly using: string | null;
+  readonly with_check: string | null;
+}
+
+export const rowSecurityRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly RowSecurityRow[]> =>
+  client.query<RowSecurityRow>(sql`
+    select c.relname as table_name, c.relrowsecurity as enabled, c.relforcerowsecurity as forced
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and (c.relrowsecurity or c.relforcerowsecurity)
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** `polroles` holds `0` for `public`, which no `pg_roles` row answers; each name is resolved here. */
+export const policyRows = (client: DbClient, schema: string): Promise<readonly PolicyRow[]> =>
+  client.query<PolicyRow>(sql`
+    select
+      c.relname as table_name,
+      p.polname as name,
+      p.polpermissive as permissive,
+      case p.polcmd when 'r' then 'select' when 'a' then 'insert' when 'w' then 'update'
+        when 'd' then 'delete' else 'all' end as command,
+      array(
+        select case when r.oid = 0 then 'public' else (select rolname from pg_roles where oid = r.oid) end
+        from unnest(p.polroles) as r(oid)
+      ) as roles,
+      pg_get_expr(p.polqual, p.polrelid) as using,
+      pg_get_expr(p.polwithcheck, p.polrelid) as with_check
+    from pg_policy p
+    join pg_class c on c.oid = p.polrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+export const rowSecurityOf = (rows: readonly RowSecurityRow[]): readonly CatalogRowSecurity[] =>
+  rows
+    .map((row) => ({ table: row.table_name, enabled: row.enabled, forced: row.forced }))
+    .sort(by((entry) => entry.table));
+
+export const policiesOf = (rows: readonly PolicyRow[]): readonly CatalogPolicy[] =>
+  rows
+    .map((row) => ({
+      table: row.table_name,
+      name: row.name,
+      permissive: row.permissive,
+      command: row.command,
+      roles: [...row.roles].sort(by((role) => role)),
+      using: row.using,
+      withCheck: row.with_check,
+    }))
+    .sort(
+      by(
+        (policy) => policy.table,
+        (policy) => policy.name,
+      ),
+    );