@ultimat3/db 11.3.0 → 13.0.0

package/CLAUDE.md

@@ -369,6 +369,56 @@ anonymous SQL, never as a `job` statement, and will keep seeing it that way unti
 own pair through `driver-pg.ts` the way `postgresRepo` now threads entity's — that is still future
 work, not something this change reaches.
 
+**An index's ACCESS METHOD is carried end to end, `As of 2026-08-24`, and it had to land here
+before `@ultimat3/entity` could declare it.** `@>` / `<@` / `&&` / `?` on a `json()` or `arrayOf()`
+column is a sequential scan without a GIN index. `IndexInit.using` on the entity side while this
+package ignored it would emit a **btree for a declared GIN index** — a declared-and-never-wired key,
+which is the defect class this release exists to eliminate and strictly worse than the missing
+capability. So the method reaches all four places or none: `createIndex` emits it, `snapshotOf`
+records it, `indexShape` rebuilds on it, and `compareIndexes` reports it.
+
+`index-method.ts` is the vocabulary, its own file for the reason `foreign-key.ts` holds
+`onDeleteRule`: a generator and a detector that disagreed about what "the default" is would report
+drift on a database that is exactly right. Four rules.
+
+**The set is closed at two — `btree` and `gin`.** `gist`, `brin`, `hash` and `spgist` are legitimate
+and are deliberately absent: nothing declares one, and each brings a rule that would have to be
+enforced with no caller to test it (`hash` and `brin` cannot be unique, `gist` needs `btree_gist` to
+be, none of the three accepts `asc`/`desc`). Adding a member later is additive; shipping four nobody
+uses is four ways for a first caller to be silently wrong.
+
+**Declared is CLOSED, live is OPEN.** `IndexDescriptionLike.using` is `IndexMethod | undefined` —
+what an entity may ask for. `IndexDescription.using` is `string | undefined` — whatever `pg_am`
+answered, `gist` and an extension's own access method included. Folding an unknown catalog name into
+`btree` would hide exactly the difference drift exists to report, so `indexMethodOf` passes the live
+side through verbatim and `declaredMethod` is the one place the open reading is narrowed back — a
+**refusal**, never a silent fall back, because its one caller is `redefineIndex`'s `down` and a
+`gist` quietly rebuilt as a btree is a rollback leaving a state no migration describes.
+
+**Absent is `btree`, on both sides, through one function.** `indexMethodOf` is that function.
+Postgres' default is written out by nobody, every index created before this existed is one, and
+every sidecar written before the field is silent about it — so `snapshotOf` records `using` only
+when one was declared. Writing `'btree'` out for every index would rewrite every sidecar in every
+app on the next `x db gen`, a diff on every file for a fact that was already true.
+
+**The literal is re-derived from the set, never spliced from the input** — `indexMethodSql` is a
+`switch` whose `default` arm is `never` and throws `indexMethodInvalid` (`X_SQL_UNSAFE`, the code
+`isolationLevelInvalid` and `branchNameInvalid` already use for a value spliced into a statement).
+The type is not the guard: this value arrives from an entity declaration, a config or a hand-edited
+snapshot, and `using ${method}` on an operand TypeScript never saw is the **identical hole** to the
+one `columnName` carried when it was `meta.name ?? snake(property)` with only the second branch
+validated — a name that closed the parenthesis and opened a second command, measured through
+`generateMigration`. `create index "x" on "t" using gin ("c") where (...)` also refuses a unique or
+an ordered GIN through core's `assert` (`X_INVARIANT`), the discipline `createIndex` already applies
+to an index naming no columns: Postgres has neither, and a syntax error inside `ROLE=migrate` fails
+the release phase with the server's words and none of the entity's.
+
+`introspect()` reads the method from `pg_am` joined through `pg_class.relam`, and
+`introspect-embedded.test.ts` is where that is pinned — a recording client can pin the SQL text and
+nothing more, and a query that silently returned no method would read as `btree` everywhere and make
+drift blind to the one case `using` exists for. Measured on PGlite: a real `using gin` index reads
+back `gin`, the btree beside it and the primary key's own index read back `btree`.
+
 **`generate.ts` reads an index, it never re-derives one.** `EntityDescriptionLike.indexes` carries
 `columns`, `unique`, `where` and `order`, and `createIndex` writes every one of them out. It used to
 carry names alone and `parseIndexName` recovered the column list from the `<table>_<a>_<b>_idx`
@@ -502,6 +552,62 @@ override — `x_migrations.app_version` and `@ultimat3/jobs`' `x_backfills.app_v
 durable columns an operator reads side by side, and `jobs` cannot import this package for the
 answer, so the key has one reader at tier 0 rather than one per writer.
 
+**Read replicas are opt-in twice, and the second opt-in is the correctness argument, `As of
+2026-08-24`.** A replica pool exists when `DATABASE_REPLICA_URL` names one (`default-client.ts`);
+a read is *offered* to it only inside `withReplicaReads(fn)` (`replica-scope.ts`). With no scope
+open nothing routes and the client is byte-identical to the single-pool one it has always been —
+which is what makes "nobody adopted it yet" today's behaviour rather than a wrong answer.
+
+The scope is what closes **read-your-writes**, and the reason it is a scope and not a request id is
+worth writing down because the request id is the obvious answer and it does not work. `Ctx.requestId`
+IS reachable from here — `@ultimat3/http`'s pipeline opens `runWithContext` around every request
+(`packages/http/src/pipeline.ts`), `withChildContext` may not change the id, and `tryUseContext()` is
+tier 0 — but nothing tells tier 1 when a request ENDED. A `Map<requestId, wrote>` therefore only
+grows, ~100 bytes a request forever, and every eviction policy that forgets a request which WROTE
+serves it a stale row on its next read. That is a data-correctness bug strictly worse than the
+capacity problem replicas exist to solve, so the marker lives on a mutable value on an async context
+(`ReplicaScope.wrote`, the same shape as `TxState.live`) whose lifetime somebody else already owns.
+
+**`withTransaction` is on the primary structurally, not by rule.** `runRoot` pins a connection
+through `reserve()`, and `replicatedClient` delegates `reserve()` to the primary and exposes it only
+when the primary has one — so BEGIN, every statement and COMMIT are one connection on one server.
+`isReservable` therefore has to keep answering about the DATABASE and not about the wrapper: a
+wrapper that always exposed `reserve` makes `runRoot` pin a client that cannot pin, and one that
+never exposed it makes `runRoot` run BEGIN, the body and COMMIT on three different pooled
+connections. What `runRoot` adds is one line — `markScopeWrote()` unless `readOnly: true` — because
+its statements go through a reservation and never through the router, so the scope could not
+otherwise see that the request has written.
+
+**`isPlainRead` is an allow-list, and that inversion is why it is not the lexer this file forbids.**
+`readonly.ts` was deleted for defaulting to PERMISSION: a 22-word deny-list that read
+`select pg_sleep(60)` as safe. This one defaults to the primary — a statement shape nobody
+anticipated costs a replica opportunity and never an answer. **`statementKind()` is not the
+authority and must not become it**: it calls `with … update … returning` a read, which is right for
+an N+1 report and catastrophic for a routing decision, and `replica-route.test.ts` asserts the
+disagreement so the two can never be collapsed. Three refusals earn their line — a locking read
+(`for update`/`for share`; a standby cannot take the row lock), `select … into` (it creates a
+table), and the functions a word boundary cannot reach (`pg_advisory_lock`, `set_config`,
+`nextval`), which a standby ANSWERS rather than refusing, so the server cannot be the safety net for
+those the way it is for a real write.
+
+**A misroute fails loudly and repairs itself; a replica outage costs latency and never an answer.**
+A statement a standby refuses (`25006`) never executed, and only `isPlainRead` statements are ever
+sent there, so re-running one on the primary is exactly-once rather than at-least-once — which is
+what makes the blanket fallback in `replica-client.ts` safe. The breaker is what stops that from
+doubling every read during an outage: three consecutive failures park the replica for ten seconds,
+counted on `Clock.monotonic()` so an NTP step cannot un-park it. `ReplicaStats` is exposed on the
+client for a test that cannot scrape, the same reason `@ultimat3/realtime` exposes
+`droppedChannelFrames`, and each fallback logs `db.replica_fallback` with `renderThrowable(error)`.
+
+**The URL must name a read-only standby**, and nothing here can check it. The `25006` refusal is the
+whole safety net under a text classifier that cannot be complete; pointed at a writable node, a
+misroute becomes a write on the wrong server with nothing anywhere to report it.
+
+**Nothing opens `withReplicaReads` per request yet.** The scope, the client and the wiring are tier
+1 and land here first; the adopter is one call in `@ultimat3/http`'s pipeline (or an app's own
+handler), and until it exists no production traffic is routed. That is the tier rule working —
+lowest tier first, consumers after — not an omission.
+
 `checkDrift()` is the **post-migrate verification** and the only drift question that needs a
 database: the live catalog against the ledger the run just wrote. It is asked where a connection is
 open — `@ultimat3/cli`'s `runMigrations`, which is `x db migrate`, `x db reset` and `ROLE=migrate`
@@ -547,8 +653,37 @@ right database, and `x db gen`'s `retypeColumn` owns that question where both si
 The `fix:` is the `alter table … set not null` itself and deliberately not `x db gen`, which has
 never emitted one and would answer with an empty migration.
 
+**A column the DATABASE computes is a different thing at every step, and `generated-column.ts` is
+all of them** — `As of 2026-08-24`. `ColumnDescriptionLike.generated` carries the
+`generated always as (<expr>) stored` body across the tier seam (this package cannot import
+`@ultimat3/entity`, so a field that is not on the projection reaches no DDL at all), and it reached
+none until this date: `@ultimat3/entity`'s `.searchable()` emitted a `tsvector not null` column that
+`columnClause` rendered plain, so nothing computed it and **the first insert was a `23502`**. Loud,
+which was deliberate — but a feature nobody can insert into is not shipped. Four rules ride with it,
+each one measured against a real server (`generate-generated-column.live.test.ts`):
+
+| Rule | Why it is not the ordinary column's rule |
+|---|---|
+| the clause sits directly after the type | `"c" tsvector generated always as (…) stored not null check (…)` is what Postgres accepts; a column constraint may follow it |
+| **generated and defaulted is refused** at `x db gen` | Postgres has no such column (`42601`) — a generated column's value IS its expression. `X_INVARIANT`, the same refusal `createIndex` gives a unique GIN, and for the same reason: the alternative is DDL whose first reader is `ROLE=migrate` |
+| an expression that moved is **`set expression as (…)`**, never a drop and recreate | Postgres 17's statement, and it rewrites the table, recomputes every row and **keeps the column's indexes** — measured. Dropping the column takes its GIN index with it and nothing in the diff puts one back, and `alter table … drop column` is what `destructive.ts` reads as data loss: every expression change would then carry `-- destructive: true` on a migration that loses nothing, and a marker on all is none |
+| a retype on it carries **no `using`** | Postgres refuses `using` on a generated column outright, which is exactly what `retypeColumn` emits for every other column — and there is nothing to convert, because the expression produces the new type itself |
+| the NOT NULL add is **one statement**, never nullable-then-backfill | the database computes it for every existing row inside the same `add column`. The ordinary path's `-- backfill "c", then: … set not null;` names a step nobody can perform: writing to a generated column is `428C9` |
+
+Two transitions have no `set expression`. **Generated → plain is `drop expression`**, which keeps
+every value the column already computed. **Plain → generated is the whole column again** — drop,
+add, and every index over it stated a second time, which is why `regenerate` answers `rebuilt` and
+`diffTable` carries that set into its index loop: `redefineIndex` sees a definition that never moved
+and would emit nothing, so the table would come back with no index at all.
+
+**`introspect` deliberately does not read `generation_expression` back.** Postgres stores its own
+rewriting (`COALESCE(title, ''::text)` for `coalesce("title", '')`), so a catalog value could never
+compare equal to a generated one and drift would report a correct database forever. The diff that
+DOES read it is `x db gen`'s, where both sides are this generator's own spellings — the rule
+`IndexDescription.where` already states.
+
 `compareTable` judges **declared** indexes: one the migrations name and the catalog does not hold is
-`missing-index`, and one whose column list or uniqueness moved is `changed-index` — which is what
+`missing-index`, and one whose access method, column list or uniqueness moved is `changed-index` — which is what
 catches a composite index rebuilt with its columns the other way round while the column diff said
 `ok: true`. A live index no snapshot names is deliberately **not** reported: Postgres creates one for
 every primary key and every unique constraint, so counting those is eight findings against a correct
@@ -644,7 +779,8 @@ rather than spliced DDL — the discipline `createIndex` already applies to an i
 ceiling and along the seam the tier already draws: they are the structural mirror of
 `@ultimat3/entity`'s description, which is how a snapshot crosses tier 2 → tier 1 with no import.
 `ColumnDescriptionLike.onDelete` is optional for exactly that reason — a description written before
-the field existed still satisfies the shape.
+the field existed still satisfies the shape — and `ColumnDescriptionLike.generated` is optional for
+the same one.
 
 **`snapshot-json.ts` writes the sidecar's bytes, and they must be a fixed point of Biome.** A
 scaffolded app's `lint` step is `biome check .` over `"includes": ["**"]`, and `.sql`/`.hash` are
@@ -681,7 +817,39 @@ exists` at boot, declared by no migration and carried in no snapshot, so counted
 are eight `unexpected-table` findings against a correct database. The prefix is the rule, not a
 list, so a table a future package adds needs no second declaration here. `introspect()` keeps its
 narrower default (`x_migrations` alone) because the admin schema view and the MCP `schema.describe`
-tool legitimately show `x_users` — only drift wants the whole namespace gone.
+tool legitimately show `x_users` — only drift wants the whole namespace gone. That last sentence is
+a *reservation*, not a description, `As of 2026-08-24`: nothing outside this package imports
+`introspect()` today, and `schema.describe` (`@ultimat3/mcp`'s `dev-server.ts`) answers from the
+entity registry.
+
+**`app-relation.ts` is the other half, and it is ownership, never a name — issue #340,
+`As of 2026-08-24`.** `pg_stat_statements` is a view an extension owns, the CNPG/RDS/Supabase
+default puts it in `public` of every database, and the drift audit after `ROLE=migrate` reported it
+as `unexpected-table` with `x db gen "add pg_stat_statements"` as the fix — so every deploy of the
+demo app failed terminally for 16 hours, and following the fix would have written an extension's
+internal view into the app's migration set. `nonAppRelations(client, schema)` names what
+`introspect()` must not see, and `introspect()` merges it into `excluded` **unconditionally**: an
+explicit `exclude` replaces the `x_migrations` default, never this set, because an extension's
+relations are not app schema in any deployment and that is not a caller's to switch off.
+
+Two disqualifications, one question. **Extension ownership is read out of `pg_depend`**
+(`deptype = 'e'`, `refclassid = 'pg_extension'`) — Postgres' own record, and the only rule that
+generalises: a `pg_*` prefix would have covered the reported view and missed `postgis`'
+`spatial_ref_sys`, `timescaledb`'s catalog, and `pg_stat_statements`' own `pg_stat_statements_info`
+sibling, which is a real `relkind = 'r'` table. **A view, a materialised view and a foreign table
+are not tables**, whoever made them: measured on PGlite, a plain `create view` reaches
+`information_schema.columns` while the index query already fences on `relkind = 'r'`, so one arrived
+as a table with columns, no primary key and no indexes — a `TableDescription` that cannot be true,
+and a finding no author could clear because no snapshot records a view. Excluding by NAME is safe
+because `pg_class` names are unique within a namespace.
+
+Nothing else in the audit had the same hole. An extension cannot own a **column** of a table it does
+not own — `alter extension … add` has no `COLUMN` form — so `unexpected-column` is unreachable that
+way. **Types and enums** are never compared (`compareTable` reads nullability and existence, never
+the type). **Indexes and foreign keys** are judged on the declared side only, so an extension's
+index on an app table was already silent. `introspect-embedded.test.ts` proves the predicate against
+a real catalog by writing the exact `pg_depend` row `create extension` writes; a recording client
+can only pin the SQL text, which is what `app-relation.test.ts` does.
 
 The `X_DB_DRIFT` rendering in `drift.ts` and the title in `DB_ERROR_TITLES` are pinned by the
 framework contract and duplicated in `@ultimat3/entity`. Change them together or not at all.

package/README.md

@@ -13,7 +13,7 @@ boundary stays thin.
 ## Public API
 
 ```ts
-import { db, sql, raw, withTransaction, currentTx, readOnly, setDbClient } from '@ultimat3/db';
+import { db, sql, raw, withTransaction, currentTx, setDbClient } from '@ultimat3/db';
 
 const rows = await db().query<Post>(sql`select * from posts where org_id = ${orgId}`);
 
@@ -32,7 +32,11 @@ await withTransaction(async (tx) => {
 | `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 |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (columns, uniqueness, direction, and whether a predicate is there at all — never its text) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
+| `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 |
+| `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 |
+| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
 | `declaredSchema()` / `expectedSchema()` | `As of 2026-08`: the schema the migrations write down, or `undefined` when the newest one carries no snapshot — never an older snapshot standing in for it |
 | `parseSnapshot()` | `As of 2026-08`: a `<id>.snapshot.json` sidecar validated to the last nested field, or `undefined`. `{"tables":[null]}` is valid JSON and is not a schema |
 | `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 |
@@ -41,7 +45,7 @@ await withTransaction(async (tx) => {
 | `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 |
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `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 |
-| `introspect()` | live schema → `SchemaDescription` |
+| `introspect()` | 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 |
 | `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases. `As of 2026-08-19` the marker comment records the **base** as well as the instant (`ultimate:branch:<base>:<iso>`, on `BranchInfo.base`), and `reapBranches()` sweeps only branches of the database it is connected to — one Postgres hosting two Ultimate apps used to mean one app's nightly reap dropped the other's branches. A pre-3.x marker records no base and is skipped, never dropped |
 | `createPgliteClient()` / `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 |
@@ -98,6 +102,62 @@ 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.
 
+## Index access methods
+
+`btree` is the default and is never written out; `gin` is what makes `@>` / `<@` / `&&` / `?` on a
+`json()` or `arrayOf()` column an index lookup rather than a sequential scan.
+
+| | |
+|---|---|
+| declared | `IndexDescriptionLike.using` — `'btree' \| 'gin'`, closed. Anything else is `X_SQL_UNSAFE` before it reaches DDL |
+| absent | `btree`, on every side, through `indexMethodOf()` — so a snapshot written before the field existed reads as what it always was |
+| emitted | `create index "posts_tags_idx" on "posts" using gin ("tags");` — and `create index "posts_tags_idx" on "posts" ("tags");` when no method was declared, byte for byte what shipped before |
+| refused | a unique GIN and an ordered GIN (`X_INVARIANT`) — Postgres has neither, and the alternative is a syntax error inside `ROLE=migrate` |
+| recorded | only when declared, so no existing sidecar is rewritten |
+| a method that moved | drop and recreate — Postgres cannot alter one in place |
+| drift | a declared GIN against a live btree is `changed-index`, and the live method is reported by the name the catalog gave it |
+
+## Read replicas
+
+Opt in twice, and the second one is why it is safe.
+
+```ts
+// 1. the pool — an environment variable, read once by baseClient()
+//    DATABASE_REPLICA_URL=postgres://reader@replica.internal:5432/app
+
+// 2. the scope — reads inside it may be served by the replica
+import { db, sql, withReplicaReads, withTransaction } from '@ultimat3/db';
+
+declare const id: string;
+
+await withReplicaReads(async () => {
+  await db().query(sql`select id from posts limit 20`); // -> replica
+  await db().execute(sql`insert into posts (id) values (${id})`);
+  await db().query(sql`select id from posts limit 20`); // -> primary, for the rest of the scope
+  await withTransaction(async (tx) => {
+    await tx.query(sql`select 1`); // -> primary, always
+  });
+});
+```
+
+| Rule | |
+|---|---|
+| unconfigured | no `DATABASE_REPLICA_URL` → one pool, statement for statement what it always was |
+| no scope | no `withReplicaReads` → nothing routes, whatever is configured |
+| 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 |
+| 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 |
+
+**The URL must name a read-only standby.** The server's own `25006` refusal is the safety net under
+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 drift contract
 
 `checkDrift()` compares `introspect()` against the snapshot the newest applied migration carries —
@@ -119,8 +179,17 @@ subset, so a database that simply has not migrated yet is pending, not divergent
 table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox and every
 `@ultimat3/auth` table are created by `create table if not exists` at boot and appear in no
 snapshot, so `appTables()` drops them before the diff. `introspect()` keeps its own narrower
-exclusion (the ledger alone), because the admin schema view and the MCP `schema.describe` tool
-legitimately show `x_users`.
+exclusion (the ledger alone), reserving `x_users` for a schema view that wants it.
+
+**Nor is a relation an extension owns, `As of 2026-08-24`.** `create extension pg_stat_statements`
+in `public` is the CNPG, RDS, Supabase and Neon default, and its view read as `unexpected-table`
+with `x db gen "add pg_stat_statements"` as the fix — so every deploy failed terminally and the fix
+would have written an extension's internal view into the app's migration set. `introspect()` now
+excludes every relation Postgres records as extension-owned (`pg_depend`, `deptype = 'e'`), which is
+ownership rather than a name: a `pg_*` prefix rule covers that view and misses `postgis`'
+`spatial_ref_sys`. Views, materialised views and foreign tables go with them — no snapshot records
+one, so counting them could only ever produce a finding an author has no way to clear. A table
+someone created by hand carries no such dependency and is still `unexpected-table`.
 
 Rendered output is pinned byte-for-byte:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "11.3.0",
+  "version": "13.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.3.0"
+    "@ultimat3/core": "13.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/app-relation.ts

@@ -0,0 +1,57 @@
+// 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.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+interface NonAppRelationRow {
+  readonly name: string;
+}
+
+/**
+ * Relation names in `schema` that no migration could legitimately declare.
+ *
+ * **Extension ownership is the rule, never a name prefix.** Every object `create extension` builds
+ * carries a `pg_depend` row with `deptype = 'e'` pointing at `pg_extension` — that is Postgres'
+ * own record of "this belongs to an extension", and it is the only thing that generalises. A
+ * prefix rule spelled `pg_*` would have covered the `pg_stat_statements` view that made every
+ * deploy of the demo app fail terminally (issue #340) and missed `postgis`' `spatial_ref_sys`,
+ * `timescaledb`'s catalog and `pg_stat_statements`' own `pg_stat_statements_info` sibling. An
+ * extension may install a relation under any name at all, so the name is not evidence.
+ *
+ * **A view, a materialised view and a foreign table are not tables**, whoever created them. They
+ * reach `information_schema.columns` (measured on PGlite: a plain `create view` appears there),
+ * while the index query already fences on `relkind = 'r'` — so one came back as a table with
+ * columns, no primary key and no indexes, which is a `TableDescription` that cannot be true. No
+ * `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.
+ *
+ * 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.
+ */
+export async function nonAppRelations(
+  client: DbClient,
+  schema: string,
+): Promise<readonly string[]> {
+  const rows = await client.query<NonAppRelationRow>(sql`
+    select c.relname as name
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and c.relkind in ('r', 'p', 'v', 'm', 'f')
+      and (
+        c.relkind in ('v', 'm', 'f')
+        or exists (
+          select 1
+          from pg_depend d
+          where d.classid = 'pg_class'::regclass
+            and d.objid = c.oid
+            and d.refclassid = 'pg_extension'::regclass
+            and d.deptype = 'e'
+        )
+      )
+    order by c.relname
+  `);
+  return rows.map((row) => row.name);
+}

package/src/client.ts

@@ -5,6 +5,9 @@
 
 import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
+// Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
+// module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
+import { defaultClient } from './default-client';
 import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
@@ -123,7 +126,7 @@ export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
  * rather than falling back: a fleet that ignored the number it was given is the failure the
  * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
  */
-function poolMaxFromEnv(): Partial<PoolProfile> {
+export function poolMaxFromEnv(): Partial<PoolProfile> {
   const raw = process.env[POOL_MAX_ENV];
   if (raw === undefined || raw.trim() === '') return {};
   const max = Number(raw);
@@ -437,10 +440,11 @@ export function setDbClient(client: DbClient | undefined): void {
  * The role default is layered under `DATABASE_POOL_MAX`, because this is the one place the process
  * builds its own client and therefore the only place an operator's value can reach one:
  * `createPostgresClient` has always taken a `profile` override and nothing in a running app passed
- * it, so `POOL_PROFILES` was the last word in a deployed image.
+ * it, so `POOL_PROFILES` was the last word in a deployed image. `default-client.ts` owns what gets
+ * built — one pool, or a primary and a replica when `DATABASE_REPLICA_URL` names one.
  */
 export function baseClient(): DbClient {
-  if (ambient === undefined) ambient = createPostgresClient({ profile: poolMaxFromEnv() });
+  if (ambient === undefined) ambient = defaultClient();
   return ambient;
 }
 

package/src/default-client.ts

@@ -0,0 +1,35 @@
+// Single responsibility: the client `baseClient()` builds when an app installed none — the primary
+// pool, plus a read replica when one is configured. Its own file because it is the one place the
+// framework decides a process's database topology from the environment, and `client.ts` is at the
+// line ceiling.
+
+import { createPostgresClient, type DbClient, poolMaxFromEnv } from './client';
+import { replicatedClient } from './replica-client';
+
+/**
+ * A read replica's connection string. Unset — which is every app that has not asked for one — and
+ * this builds exactly the single-pool client it always did, statement for statement.
+ *
+ * It must name a READ-ONLY standby. A statement misrouted to one is refused with `25006` and
+ * re-run on the primary, and that refusal is the safety net a text classifier cannot be; a URL
+ * pointing at a writable node turns a misroute into a write on the wrong server, silently.
+ */
+export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
+
+/**
+ * Composed rather than folded into `createPostgresClient`, on purpose: `migrate`, `x db branch` and
+ * every test build a client that must be exactly one pool, and a second pool reachable through the
+ * same factory would be a second thing `reserve()`, `close()` and `ping()` each have to mean two
+ * ways.
+ *
+ * The replica inherits the role's profile, `DATABASE_POOL_MAX` included: a fleet sized against
+ * `max_connections` has two servers to size against, not one, and a replica pool that ignored the
+ * operator's number would be the exhaustion `poolMaxFromEnv` exists to prevent, on the other host.
+ */
+export function defaultClient(): DbClient {
+  const profile = poolMaxFromEnv();
+  const primary = createPostgresClient({ profile });
+  const replicaUrl = process.env[REPLICA_URL_ENV];
+  if (replicaUrl === undefined || replicaUrl.trim() === '') return primary;
+  return replicatedClient(primary, createPostgresClient({ url: replicaUrl, profile }));
+}

package/src/drift.ts

@@ -6,6 +6,7 @@
 import { baseClient, type DbClient } from './client';
 import { DbError } from './errors';
 import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { indexMethodOf } from './index-method';
 import {
   type ForeignKeyDescription,
   findTable,
@@ -219,6 +220,12 @@ function changedForeignKey(
  * a `desc` index rebuilt ascending by hand serves a feed's newest page off the wrong end. `asc` is
  * normalised to `null` first — `createIndex` writes `"col" asc`, which Postgres stores as
  * not-descending, so the raw values differ on every ascending index in a correct database.
+ *
+ * The **access method** is compared for the same reason and normalised the same way (`indexMethodOf`,
+ * absent = `btree`). Without it an emitter that can write `using gin` ships a btree for a declared
+ * GIN index and nothing anywhere says so — a declared-and-never-wired key, which is worse than the
+ * missing capability, and the reason `using` could not land in `@ultimat3/entity` before it landed
+ * here.
  */
 function compareIndexes(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
@@ -229,6 +236,17 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
       differences.push(missingIndex(live.name, index.name));
       continue;
     }
+    // The method first, and before the column list: a GIN index and a btree over the same column
+    // are not the same index with a detail different, they are two structures the planner uses for
+    // different operators — `@>` on a jsonb column is a sequential scan on the wrong one. Both
+    // sides go through `indexMethodOf`, so a snapshot that predates the field and an index the
+    // catalog reports as `btree` agree instead of reporting drift on a correct database.
+    if (indexMethodOf(counterpart) !== indexMethodOf(index)) {
+      differences.push(
+        changedIndex(live.name, index.name, `is a ${indexMethodOf(counterpart)} index`),
+      );
+      continue;
+    }
     if (counterpart.columns.join(',') !== index.columns.join(',')) {
       differences.push(
         changedIndex(live.name, index.name, `covers (${counterpart.columns.join(', ')})`),

package/src/entity-shape.ts

@@ -2,6 +2,8 @@
 // tier 1 and may never import `entity` (tier 2), so a snapshot arrives as a parameter and every
 // part of it — a column's `on delete` rule included — crosses the seam by shape or not at all.
 
+import type { IndexMethod } from './index-method';
+
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
 export interface ColumnDescriptionLike {
   readonly property: string;
@@ -19,6 +21,17 @@ export interface ColumnDescriptionLike {
    * the field travelling structurally is the *only* way the rule crosses the tier boundary.
    */
   readonly onDelete?: string | null | undefined;
+  /**
+   * The `generated always as (<expr>) stored` body, when the DATABASE computes this column rather
+   * than a writer. Absent on every ordinary column, exactly like `IndexDescriptionLike.using`: a
+   * description written before this existed emits the statement it always emitted.
+   *
+   * `@ultimat3/entity` (tier 2) is the declarer and this package cannot import it, so the
+   * expression crosses the seam structurally or it reaches no DDL at all — which is where it was
+   * until `As of 2026-08-24`: the column landed as a plain `tsvector not null` and the first insert
+   * was a `23502`, because nothing computed it.
+   */
+  readonly generated?: string | undefined;
 }
 
 /**
@@ -37,6 +50,13 @@ export interface IndexDescriptionLike {
   readonly where: string | null;
   /** `null` is Postgres' own default (`asc`), never written out. */
   readonly order: 'asc' | 'desc' | null;
+  /**
+   * The access method. Absent is `btree`, which is Postgres' own default and what every index
+   * declared before this field existed is — so a description written without it still satisfies
+   * the shape, exactly as `ColumnDescriptionLike.onDelete` does. `@ultimat3/entity` (tier 2) is
+   * the declarer; this package cannot import it, so the method crosses the seam structurally.
+   */
+  readonly using?: IndexMethod | undefined;
 }
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */

package/src/errors.ts

@@ -426,6 +426,22 @@ export const multipleStatements = (statement: string, count: number): DbError =>
     meta: { count },
   });
 
+/**
+ * An index method that is not one of the set. `X_SQL_UNSAFE` for the reason `isolationLevelInvalid`
+ * uses it: `create index … using <method>` takes no parameters, so the method is SPLICED into the
+ * statement text, and an operand TypeScript never saw is an injection rather than a typo — the
+ * identical hole a `columnName` built from an unvalidated `meta.name` carried into `create table`.
+ *
+ * `describeValue`, never the value, for the reason that one gives: this cause is folded into a
+ * problem document and a log line.
+ */
+export const indexMethodInvalid = (received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an index method must be 'btree' or 'gin'; got ${describeValue(received)}`,
+    fix: "indexes: [{ on: ['tags'], using: 'gin' }]   # or leave it out for the btree default",
+  });
+
 export const branchExists = (branch: string): DbError =>
   new DbError({
     code: 'X_BRANCH_EXISTS',