@ultimat3/db 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -35,47 +35,48 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   only while its turn is held. `pglite-embedded.test.ts`, `pglite.test.ts`,
   `pglite-two-clients.test.ts`, `pglite-observer.test.ts`.
 - **The third rule is both drivers'**: `client.ts`'s pinned handle also runs direct only while held.
-  `release()` is idempotent on both; `DbConnection` and `Turn` are `Disposable` (`[Symbol.dispose]` is
-  `release()`).
+  `release()` is idempotent on both; `DbConnection` and `Turn` are `Disposable`.
 - **A pin is held by `using`, never a hand-rolled `try/finally`** (`withTransaction`,
   `readOnlyQuery`); `BEGIN` lives inside the guarded scope.
-- **`sqlstate.ts`**: `errno` first, `code` second, both shape-tested (`^[0-9A-Z]{5}$`).
-  `DB_SQLSTATE_CODES` is closed; `driverError()` is its one consumer, `sendOn` its one caller.
+- **`sqlstate.ts`**: `errno` first, `code` second, shape AND provenance (`isState`: `severity` =
+  server; `syscall`/numeric `errno` = socket; else needs a digit). `DB_SQLSTATE_CODES` is closed; `driverError()` is its one consumer, `sendOn` its one caller.
 - **`DbTx.origin` is the client the scope was opened on**, never the pin (entity's pinned-repository
   check reads it); a nested scope reports the root's.
 - **`withTransaction(fn, { retry })` re-runs `fn` only on `40001`/`40P01`**, default 0; each attempt
   its own pin, `BEGIN` and undo list (`runRoot`); a nested `retry` is `X_INVARIANT`. A re-run waits
-  (`transaction-backoff.ts`: core's `backoffDelay`, 10 ms → 500 ms, full jitter; `{ sleep, random }`
-  are injection seams); nothing waits at retry 0 or after the last attempt.
-- **Four codes are classified `retryable`** (`DB_ERROR_RETRY`: `X_DB_SERIALIZATION_FAILURE`,
-  `X_DB_LOCK_TIMEOUT`, `X_DB_POOL_EXHAUSTED`, `X_MIGRATE_CONCURRENT`); terminal ones are deliberately
-  unclassified (`errors-retry.test.ts` asserts the absence). Core's `retry()` executor is NOT adopted.
-- **`BEGIN` re-derives its isolation level from the closed set** (`isolationMode` switch with a `never`
-  default; anything else `X_SQL_UNSAFE`).
-- Transaction control: `ROLLBACK` / `ROLLBACK TO SAVEPOINT` are best-effort; `SAVEPOINT` and
-  `RELEASE SAVEPOINT` are deliberately uncaught.
-- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`drainTimeoutMs / 1000`);
-  `drainTimeoutMs: 0` sends no option; the verdict is elapsed time on `performance.now()`
-  (`X_DB_DRAIN_TIMEOUT`). `pool-drain.test.ts`, `pool-drain.live.test.ts`. `close()` clears the cached
-  driver before awaiting the teardown.
+  (`transaction-backoff.ts`: 10 ms → 500 ms, full jitter; `{ sleep, random }` are seams).
+- **Four codes are `retryable`** (`DB_ERROR_RETRY`); terminal ones stay unclassified
+  (`errors-retry.test.ts`). Core's `retry()` executor is NOT adopted.
+- **`BEGIN` re-derives its isolation level from the closed set** (`isolationMode`; else `X_SQL_UNSAFE`).
+- **An aborted transaction is reported** (`X_DB_TRANSACTION_ABORTED`; README "Transactions that end
+  badly"): a failure carrying a SQLSTATE marks the root's `abort`, only a successful `ROLLBACK TO`
+  clears it (a failed one sets it), and `COMMIT` is then refused unsent. `commit-tag.ts` reads the
+  COMMIT tag in BOTH funnels. `COMMIT` rejecting with no SQLSTATE is `X_DB_COMMIT_UNKNOWN`: neither
+  list runs. `transaction-errors.ts`; `transaction-options.ts` holds `DbTx`, options, `BEGIN` text.
+- **Sibling nested scopes take turns** (`TxState.children`; savepoints are a stack) under a deadline
+  (`sibling-turn.ts`, `siblingWaitMs`, `X_DB_SIBLING_SCOPE_TIMEOUT`). A nested
+  `isolation`/`readOnly`/`deferrable`/foreign `client` is `X_INVARIANT`.
+- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`drainTimeoutMs / 1000`; `0`
+  sends none); the verdict is elapsed `performance.now()` (`X_DB_DRAIN_TIMEOUT`). It clears the
+  cached driver before awaiting the teardown. `pool-drain{,.live}.test.ts`.
 - **`client.listen` is ONE session beside the pool** (`listen.ts`; `Bun.SQL.listen`, PGlite's
   `listen` under a turn), never a reserved pin. `onListening` fires on every re-dial; a channel is
   refused unless it is a plain identifier. `listen.test.ts`, `listen.live.test.ts`.
 - `execute()` trusts the command tag only when `> 0`, in both drivers (`rowsOf`, `affectedBy`).
-- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND** —
-  `Bun.SQL` publishes no occupancy. `client.ts` is the one counter: `run()` from send to settle, a
-  pin from the ask to its (idempotent) release; a statement ON a pin is not counted again. Declared
-  on the first tracked pool, never at import. `pool-gauge.test.ts`.
+- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND**
+  (`Bun.SQL` publishes no occupancy). `client.ts` is the one counter: `run()` from send to settle, a
+  pin from ask to release; a statement ON a pin is not counted again. Declared on the first pool.
 - **`client.ts` connects, holds the client and the ambient `db()`**, and opens no socket at import;
   `pool-profile.ts`, `connection-url.ts`, `bun-sql.ts`, `pool-reserve.ts`, `db-health.ts` (`checkDb`)
   and `statement-funnel.ts` (`sendOn`/`runOn`) hold the rest.
-- **`libpq-options.ts` merges the framework's `options` into the operator's**: the framework wins on
-  the names it sets, the operator keeps every other flag; the bound is emitted for all six roles.
+- **`libpq-options.ts` merges the framework's `options` into the operator's**: the framework wins
+  on the names it sets, the operator keeps the rest; emitted for all six roles.
 - **`DATABASE_URL`'s scheme is screened at boot** (`POSTGRES_SCHEMES`: `postgres:`, `postgresql:`); the
-  received scheme is never echoed (it may be a host or a credential). `connection-url.test.ts`.
+  received scheme is never echoed (it may be a credential).
 - **A JS array bound as a parameter is rendered here** (`array-parameter.ts`, `bound-parameters.ts`,
   called only by `sendOn`) — `Bun.SQL` joins elements with commas. `NULL` bare vs `"NULL"`; quoting by
-  content; a `Uint8Array` is BYTEA; a ragged nest is refused. `array-parameter.live.test.ts`;
+  content; a `Uint8Array` is BYTEA, in an array too; a ragged nest and an Invalid Date are refused
+  (`X_INVARIANT`), ABOVE the driver's `try` in both funnels. `array-parameter.live.test.ts`;
   `packages/cli/src/pg-array.live.test.ts` is the composition test.
 - **Every numeric option is screened** through core's `finiteCount` (`replicaClient`'s breaker,
   `migrate`'s `lockWaitMs`, `readonlyQuery`'s `timeoutMs` — only an explicit `0` disables it — the pool
@@ -83,11 +84,10 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 
 ## Observation
 
-- **`observe.ts`: one process-wide `StatementObserver`** (`setStatementObserver()` /
-  `statementObserver()`). Guard at the call site; one observer, not a list; the seam swallows nothing;
-  `onStatement` is synchronous and must not issue SQL. Only `runOn` (`statement-funnel.ts`) and
-  `statement()` (`pglite.ts`) invoke it; both observe success and failure, and notify outside the
-  statement's own `try`.
+- **`observe.ts`: one process-wide `StatementObserver`** (`setStatementObserver()`). Guard at the
+  call site; one observer, not a list; the seam swallows nothing; `onStatement` is synchronous and
+  must not issue SQL. Only `runOn` (`statement-funnel.ts`) and `statement()` (`pglite.ts`) invoke
+  it; both observe success and failure, and notify outside the statement's own `try`.
 - **`attribution.ts`**: `withStatementAttribution(entity, op, fn)` — guard first (two strings, no
   allocation), a scope not a parameter, innermost pair wins; the funnels stamp it on both settle paths.
   `@ultimat3/entity`'s `postgresRepo` is the one producer.
@@ -95,12 +95,11 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   text) and `statementKind(text)` off `statementVerb(text)`. Read by `x dev`'s ledger and
   `@ultimat3/testing`'s `statements` fixture. It counts nothing.
 - **`statement-span.ts`**: `withStatementSpan` wraps the send alone — `db.<verb>`, attribute
-  `STATEMENT_ATTRIBUTE` (exported; `@ultimat3/cli`'s `dev-traces.ts` imports it), OTel kind `client`,
-  opened only when an observer is installed.
+  `STATEMENT_ATTRIBUTE` (`@ultimat3/cli`'s `dev-traces.ts` imports it), OTel kind `client`, opened
+  only when an observer is installed.
 - **`expected-loop.ts` is the ONLY suppression**: `expectedQueryLoop(reason, fn)`, innermost reason,
-  blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement. The
-  framework's own loops declare themselves (`migrate()`, `rollback()`, `@ultimat3/admin`'s
-  `search.ts`).
+  blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement.
+  The framework's own loops declare themselves (`migrate()`, `rollback()`, admin's `search.ts`).
 - `@ultimat3/jobs` never imports this package; its statements pass the observer only because
   `packages/cli/src/dev-queue.ts` wraps a real client for its `PgExecutor`, unattributed.
 
@@ -130,8 +129,8 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   (`rollbackStepsInvalid`, `X_INVARIANT`).
 - **`refuseDependentViews(tx, script)`** (`dependent-view.ts`) runs before each migration's first
   statement: a word scan over `sql-scan.ts` finds retyped columns, one catalog round trip, the pair
-  filtered in JS, and `X_MIGRATION_VIEW_DEPENDS` carries the `drop view` / `create view` from
-  `pg_get_viewdef` (built through `identifier()` inside a `try`).
+  filtered in JS (visible tables only), and `X_MIGRATION_VIEW_DEPENDS` carries the `drop view` /
+  `create view` from `pg_get_viewdef` (built through `identifier()` inside a `try`).
 - `runningAppVersion()` delegates to core's `appVersion()`.
 
 ## Generation (`x db gen`)
@@ -175,11 +174,10 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   NULL add is one statement; generated → plain is `drop expression`; plain → generated rebuilds the
   column (`regenerate` answers `rebuilt`) and moves its dependents aside; a generated column's own type
   change deliberately does not. `introspect` never reads `generation_expression` back.
-  `generate-generated-column.live.test.ts`, `generate-generated-rebuild.live.test.ts`.
-- **`REPLICA IDENTITY FULL` is emitted by a PARAMETER** (`GenerateOptions.replicaIdentityFull`, passed
-  by `@ultimat3/cli`'s `db-generate.ts` from `describeQueries()`' `subscribes:`), in
-  `replica-identity.ts`: recorded as `replicaIdentityFull: true` or absent; the snapshot records the
-  union; dead last in `up`; never destructive; a name no entity declares is skipped; never reverted;
+  `generate-generated-{column,rebuild}.live.test.ts`.
+- **`REPLICA IDENTITY FULL` is emitted by a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from
+  `@ultimat3/cli`'s `db-generate.ts`), in `replica-identity.ts`: recorded `true` or absent; the
+  snapshot records the union; dead last in `up`; never destructive; an undeclared name is skipped;
   `down` is `replica identity default` except on a table this migration creates.
 - **A foreign key is `alter table … add constraint`**, collected into a bucket merged after every table
   statement (`foreign-key-plan.ts`); **dropping a table has its own bucket emitted BEFORE the table
@@ -191,20 +189,19 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`snapshot-json.ts` writes bytes that are a fixed point of Biome** (arrays collapse when they fit at
   `<= 100` counting the trailing comma); `snapshot-json.test.ts` runs the repo's own `biome format`.
 - **`declaredSchema()` answers the NEWEST migration's snapshot or `undefined`**; `checkDrift` turns
-  that into `unknown-schema`, and `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING`. Both lead with
-  the same two remedies in the same order: restore the sidecar (`git checkout --`), or delete the
-  migration's files FIRST and only then run `x db gen`. `snapshotSiblings` / `migrationNameOf` build
-  the second command from the caller's path; both commands are screened (`unknownSchema` through
-  `shellInertIdentifier`, `migrationSnapshotMissing` through `renderFixShellArg`), degrading the whole
-  line to prose.
+  that into `unknown-schema`, and `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING`. Both lead
+  with the same two remedies in order: restore the sidecar (`git checkout --`), or delete the
+  migration's files FIRST and then run `x db gen`. Both commands are screened (`shellInertIdentifier`
+  / `renderFixShellArg`), degrading the whole line to prose.
 
 ## Drift and introspection
 
 - **`checkDrift()` is the post-migrate verification** (live catalog vs the ledger just written, asked
   by `@ultimat3/cli`'s `runMigrations`), returned never thrown. The OTHER `X_DB_DRIFT` is the CLI's
   `checkSourceDrift`. Neither grows the other's half.
-- `compareTable` compares existence and **nullability** (primary-key columns excluded by the union of
-  both sides' keys); the type is not compared. The `fix:` is the `alter table … set not null` itself.
+- `compareTable` compares existence, **nullability** (the DECLARED key's columns excluded) and the
+  **primary key** in column order (`changed-primary-key`, fix = one `psql -c` of the pair; `primary-key.ts`
+  holds `x db gen`'s arm, its `drop not null`s, its two refusals). The type is not compared.
 - **A missing CHECK is drift, compared by NAME**: `TableDescription.checks` (declared: name and
   expression) vs `TableDescription.checkNames` (catalog: `conname` for `contype = 'c'`, always written
   by `introspect()`, `[]` included). Only the declared side is judged; no `changed-check`, ever.
@@ -212,18 +209,18 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - `compareTable` judges declared indexes (`missing-index`, `changed-index` over method, column list,
   uniqueness, predicate presence and direction; `asc` normalises to `null`); never the predicate text.
 - `compareForeignKeys` matches on where a key points (`foreignKeyTarget`, the one copy) and compares
-  `onDelete` through `onDeleteRule` (`changed-foreign-key`, fix = drop/add pair).
+  `onDelete` through `onDeleteRule` (`changed-foreign-key`; its fix, `changed-column`'s and
+  `missing-check`'s are one `psql -c` too — `repair()`, schema-scoped off `public`).
 - `introspect()` reads index columns in key order (`indkey`) and a foreign key's two column lists
   together (`unnest(a, b) with ordinality`), pinned by `introspect-embedded.test.ts`.
 - **`appTables()`** excludes the whole `x_` namespace for drift; `introspect()` alone excludes
   `x_migrations` by default. **`app-relation.ts`**: `nonAppRelations(client, schema)` — extension
   ownership from `pg_depend` (`deptype = 'e'`) plus views, materialised views and foreign tables —
   merged into `excluded` unconditionally.
-- **`unexpectedTable`'s `fix:` never names `x db gen`**: a `create table if not exists` in a migration
-  (accepted by `@ultimat3/cli`'s `acceptCreatedTables`) or dropping a table nothing owns.
-- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`); the `X_DB_DRIFT`
-  rendering and title are duplicated in `@ultimat3/entity`, held equal by
-  `packages/entity/src/errors.test.ts`. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
+- **`unexpectedTable`'s `fix:` never names `x db gen`**: `psql -c '\d "T"'`, commented with the two
+  repairs (claim it with `create table if not exists`, or drop it).
+- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`) and is the only one —
+  `@ultimat3/entity`'s copy is deleted. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
 - `drift-findings.ts` holds every `DriftDifference` constructor and `DriftKind`; `drift.ts` keeps the
   comparisons.
 
@@ -239,8 +236,9 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`renderSchemaDump()` is pure**; `schema-dump-table.ts` spells one table. `quoted()` escapes any
   catalog name — `identifier()` refuses whitespace and `"`, which a migration may have created.
 - **`x_` owner → `framework/` twin** (`FRAMEWORK_TABLE_PREFIX`). No list is handed in.
-- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`). A kind
-  rendered later leaves that list in the same diff. Never render a partition as a plain table.
+- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`; a trigger
+  on an unrendered relation is named by the fold). A kind rendered later leaves that list in the
+  same diff. Never render a partition as a plain table. `generated` carries `stored`/`virtual`.
 - **`loadSchemaDump()`**: one transaction, `check_function_bodies` off, a savepoint per file, and
   only `42P01`/`42883`/`42704` are retried. Its refusal is `X_SCHEMA_DUMP_DRIFT` (`dump-drift.ts`).
 - **`object-drift.ts`**: `unexpectedObjects(live, expected)` compares IDENTITY (kind, table, name,
@@ -253,16 +251,15 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   by `pgliteExtensionExport` before it reaches a specifier; `plpgsql` is built in, never missing.
   Only a not-found import is `missing`; a bundle that throws is `X_DB_UNAVAILABLE`.
 - **`pglite-snapshot.ts`**: `snapshotDir` makes a `memory://` boot a restore. Key = PGlite version
-  (read off its `package.json`; unreadable = no cache), never the extension set. One file, checksum in its
-  header; unsound or unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed by
-  measurement: gzip taxes the boot that writes, and a CI checkout always writes.
-- **One embedded boot** serves every database-backed dump test: `schema-dump.test.ts`.
+  (unreadable = no cache), never the extension set. One file, checksum in its header; unsound or
+  unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed.
+- **Embedded boots for dump tests**: `schema-dump.test.ts` and `schema-dump-fidelity.test.ts`.
 
 ## Branches, replicas, read-only
 
-- **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`
-  (`BranchInfo.base`), split on the ISO tail; an older one-segment marker is skipped, never dropped; an
-  unparseable `createdAt` is skipped. `@ultimat3/cli`'s `ls`/`drop` scope by name prefix.
+- **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`,
+  split on the ISO tail; an older one-segment marker or an unparseable `createdAt` is skipped, never
+  dropped. `@ultimat3/cli`'s `ls`/`drop` scope by name prefix.
 - **Read replicas are opt-in twice**: a pool when `DATABASE_REPLICA_URL` names one
   (`default-client.ts`), and a read offered only inside `withReplicaReads(fn)` (`replica-scope.ts`);
   read-your-writes is `ReplicaScope.wrote`, never a request-id map. **`withTransaction` is on the

package/README.md

@@ -29,7 +29,8 @@ await withTransaction(async (tx) => {
 | `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 |
 | `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 |
+| `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) |
+| `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 |
@@ -55,7 +56,7 @@ await withTransaction(async (tx) => {
 | `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 |
 | `compareSchemaDump()` / `reloadDifferences()` / `schemaDumpDrift()` / `schemaDumpDifferenceOf()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: `X_SCHEMA_DUMP_DRIFT` — committed files against rendered ones in both directions, and load-equals-replay as a comparison |
-| `unexpectedObjects()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the triggers, functions, views, types and sequences a live catalog holds and an expected one does not, as `unexpected-object` drift. Identity, never definition text |
+| `unexpectedObjects()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the triggers, functions, views, types and sequences a live catalog holds and an expected one does not, as `unexpected-object` drift. Identity, never definition text. Its `fix:` is one `psql -c` command that prints the object's definition, qualified by the catalog's schema — `\d+` a view, `\dT+` an enum, `\dD+` a domain, `\d` a sequence or a trigger's table, `pg_get_functiondef` by namespace for a function — with the repair as its comment |
 | `PgliteOptions.extensions` / `linkPgliteExtensions()` | `As of 2026-10`: Postgres extensions to link at boot, by name — a list, or a function for a caller whose list is read from disk. `linkPgliteExtensions(names)` answers `{ linked, missing }` without booting anything: `missing` is what the installed PGlite ships no bundle for, which is how `@ultimat3/cli` decides a replay needs a real Postgres. A missing name is skipped at boot and refused by `create extension` itself |
 | `PgliteOptions.snapshotDir` | `As of 2026-10`: a directory for the post-`initdb` snapshot, so an in-memory boot is a restore (~0.4 s against ~2.7 s). Keyed on the PGlite version alone — `initdb` never sees a linked extension, so one snapshot serves every set; checksummed, never trusted, written by temp-name-then-rename. Ignored for a data directory on disk |
 | `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 |
@@ -75,13 +76,37 @@ String interpolation is how every SQL injection ships, and an agent writing SQL
 trusted to remember the difference between a value and a fragment. So:
 
 - scalars (`string`, `number`, `boolean`, `bigint`, `Date`, `Uint8Array`, arrays, `null`) become
-  `$1..$n` and never touch `.text`;
+  `$1..$n` and never touch `.text`. A value that cannot be SENT — an Invalid Date, a ragged array —
+  is `X_INVARIANT` before the driver is called, never `X_DB_UNAVAILABLE`; a `Uint8Array` inside an
+  array is one `bytea` element. Both drivers refuse alike;
 - a nested fragment is spliced and its parameters are renumbered;
 - **anything else throws `X_SQL_UNSAFE`** — including an object shaped like a `SqlFragment` that
   `sql`/`raw` did not produce;
 - `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.
 
+## Transactions that end badly
+
+`As of 2026-10-02`. Postgres aborts the WHOLE transaction on any statement error and answers the
+`COMMIT` that follows with the tag `ROLLBACK` and no error. `withTransaction` used to resolve on
+that, fire `onCommit`, and store nothing.
+
+| Situation | What happens |
+|---|---|
+| the body catches a failed statement and returns | `X_DB_TRANSACTION_ABORTED`, cause = the first failing statement; `ROLLBACK`, `onRollback` undos run, `onCommit` never fires |
+| the fallible statement sits in a nested `withTransaction` and THAT is caught | only the savepoint rolls back; the outer scope commits. This is the fix the error names |
+| a nested body swallows a failed statement | the nested call rejects with `X_DB_TRANSACTION_ABORTED`; its savepoint is rolled back and the outer scope is usable again |
+| `ROLLBACK TO SAVEPOINT` itself fails | the nested call still rejects with the body's error; the root is marked aborted and its `COMMIT` is refused, never sent |
+| two nested scopes under `Promise.all` | run one after the other, per parent scope — savepoints are a stack, and interleaved ones destroyed each other |
+| a nested scope waits past `siblingWaitMs` (default `SIBLING_SCOPE_WAIT_MS`, 30 s; `0` = no deadline) for its sibling | `X_DB_SIBLING_SCOPE_TIMEOUT`, naming the parent and the savepoint holding the turn. The shape it exists for: a body awaiting a sibling started after it, which waits for itself — a permanent hang before the deadline. The waiter never opened and its place is handed on |
+| any `COMMIT` answered `ROLLBACK`, on either driver | `X_DB_TRANSACTION_ABORTED` from the statement funnel (`commit-tag.ts`) — covers an abort the scope never saw and a hand-written `COMMIT` |
+| `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 |
+
+Only a failure carrying a SQLSTATE marks the scope aborted: a refusal raised before the send left
+the transaction untouched.
+
 ## Read-only access for anything an LLM drives
 
 `As of 2026-07`: a bug in one defence must not become a write, so `db.query` on the MCP dev
@@ -199,8 +224,9 @@ back as `CHECK ((status = ANY (ARRAY['draft'::text, 'published'::text])))`), so
 read as `conname` alone and lands on `TableDescription.checkNames`, a **separate field** from the
 declaration's `checks`. Only the declared side is judged, so a NOT NULL, an `enumerated()` column's
 old anonymous form and an extension's own constraint are all silent; a declared one the catalog
-does not hold is `missing-check`, whose `fix:` is the `add constraint` statement itself, because the
-migration that declares it is already in the ledger and `x db migrate` would apply nothing. There is
+does not hold is `missing-check`, whose `fix:` is the `add constraint` statement as one
+`psql "$DATABASE_URL" -c '…'` command against that database, because the migration that declares
+it is already in the ledger and `x db migrate` would apply nothing. There is
 no `changed-check`: presence is a boolean, a predicate is text, and normalising the text is an
 expression parser competing with the server's.
 
@@ -226,10 +252,12 @@ X_DB_DRIFT: schema differs from migrations
 |---|---|---|
 | live column, no migration | `table "T" has column "C" not present in any migration` | `x db gen "add C"` — the name goes through `shellInertIdentifier()`, and one it refuses is left OUT of the command rather than escaped into it (`x db gen "add the undeclared column"`, the name in the cause) |
 | migrated column, not live | `table "T" is missing column "C" that migrations declare` | `x db migrate` |
-| live table, no migration | `table "T" is not present in any migration` | a `create table if not exists` in a migration, then `x db migrate` — or `drop table` in `psql` where nothing owns it. Never `x db gen`, which diffs a table nothing declares against nothing and writes no file (issue #345). The name goes through `shellInertIdentifier()`, and one it refuses leaves the fix as prose |
+| live table, no migration | `table "T" is not present in any migration` | `psql "$DATABASE_URL" -c '\d "T"'` — one harmless command that shows the table — with the two repairs as its comment: a `create table if not exists` in a migration, then `x db migrate`, or `drop table` where nothing owns it. Never `x db gen`, which diffs a table nothing declares against nothing and writes no file (issue #345). The name goes through `shellInertIdentifier()`, and one it refuses leaves `psql "$DATABASE_URL"   # <the steps>` |
 | migrated table, not live | `table "T" is declared by migrations but does not exist` | `x db migrate` |
 | index rebuilt differently | `index "I" on "T" covers (…)` / `is unique` / `is descending` / `is partial`, `not what migrations declare` | `x db migrate` |
-| foreign key, rule moved | `foreign key on "T" (C) to "R" is on delete cascade, not what migrations declare` | the `drop constraint` + `add constraint` pair, in a new migration |
+| foreign key, rule moved | `foreign key "K" on "T" (C) to "R" is on delete cascade, not what migrations declare` — `K` is the constraint the database holds | `psql "$DATABASE_URL" -c '<the drop constraint + add constraint pair>'` — one command, against the drifted database — then `x db migrate` |
+| column nullability differs (`changed-column`) | `table "T" allows NULL in column "C" that migrations declare not null` / `forbids NULL in column "C" that migrations declare nullable` | `psql "$DATABASE_URL" -c 'alter table "T" alter column "C" set not null;'` (or `drop not null`) — one command, then `x db migrate`. A table read from a schema other than `public` gets `set search_path = "<schema>";` ahead of the statement, in the same `psql -c` word, so it and every table it references resolve there. A name `shellInertIdentifier()` refuses degrades every one of these three to `psql "$DATABASE_URL"   # <the steps>`: still a command that runs, with no name in it |
+| primary key differs (`changed-primary-key`, `As of 2026-10-02`) | `table "T" has primary key (id) as constraint "T_pkey", and migrations declare (slug)` — the constraint named is the one the DATABASE holds — compared in column ORDER; `has no primary key` when the database holds none | `psql "$DATABASE_URL" -c '<drop constraint "<the live key>"; add constraint "T_pkey" primary key (…)>'` — one command, against the drifted database — then `x db migrate`. Nullability is skipped for the DECLARED key's columns only |
 
 `checkDrift()` returns every difference; `assertNoDrift()` throws the first. `x db migrate` renders
 them all as findings and exits non-zero; a `ROLE=migrate` container throws the first one
@@ -271,7 +299,10 @@ object kind, numbered in the order a database is built in, one file per named ob
 - 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, rules — is named in `unrendered.sql` as comments.
+  aggregates, row-security policies (and `force row level security`), 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.
 
 `loadSchemaDump()` runs kind by kind, the framework twin first, each file in a savepoint. A file
 refused with `42P01`, `42883` or `42704` — "not created yet" — is retried after the rest; a pass
@@ -495,6 +526,9 @@ job the moment Postgres fails over.
 | `X_DB_UNIQUE_VIOLATION` | `23505` — `fix:` names `upsertAll(rows, { onConflict: [...] })` and the constraint the server named |
 | `X_DB_FOREIGN_KEY_VIOLATION` | `23503` |
 | `X_DB_SERIALIZATION_FAILURE` | `40001` / `40P01`, and an exhausted `withTransaction(fn, { retry: n })` budget |
+| `X_DB_TRANSACTION_ABORTED` | a statement failed inside a transaction and its error was caught; the server rolled the unit of work back. Also any `COMMIT` answered with the tag `ROLLBACK` |
+| `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` |

package/package.json

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

package/src/array-parameter.ts

@@ -28,18 +28,45 @@ import { assert } from '@ultimat3/core';
  * backslash, or leading/trailing whitespace the parser would strip — plus the empty string, which
  * unquoted is not an element at all.
  */
+const hexOf = (bytes: Uint8Array): string =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/**
+ * A `Date` as the instant Postgres reads, or `X_INVARIANT` for one that holds no instant.
+ * `toISOString()` on an Invalid Date is a bare `RangeError`, and inside the funnel that became
+ * "cannot reach the database". `position` names the parameter when the caller knows it.
+ */
+export function instantText(value: Date, position?: number): string {
+  assert(
+    !Number.isNaN(value.getTime()),
+    `${position === undefined ? 'an array element' : `parameter $${position}`} is an Invalid Date, which names no instant Postgres could store`,
+    'new Date(input) answers Invalid Date for text it cannot parse — parse it with t.date first, or bind null: Number.isNaN(value.getTime()) ? null : value',
+  );
+  return value.toISOString();
+}
+
 function element(value: unknown): string {
   if (value === null || value === undefined) return 'NULL';
   // A Date is ALWAYS quoted, even though an ISO-8601 instant carries no character the grammar
   // reads as structure. A timestamp element is conventionally quoted, and the alternative is a
   // rule that holds only while nothing ever renders a timestamp with a space in it.
-  if (value instanceof Date) return `"${value.toISOString()}"`;
+  if (value instanceof Date) return `"${instantText(value)}"`;
+  // BYTEA's hex form, never `String(bytes)` — that is `1,2,3`, three elements where one was bound,
+  // and no error anywhere. The backslash is doubled because a quoted element reads `\\` as one.
+  if (value instanceof Uint8Array) return `"\\\\x${hexOf(value)}"`;
   const text = String(value);
   const structural = /[{},"\\\s]/.test(text) || text.length === 0 || text.toUpperCase() === 'NULL';
   if (!structural) return text;
   return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
 
+/** The extents along a value's FIRST path, `2x3` for two rows of three — `''` for a scalar. */
+function extentsOf(value: unknown): string {
+  if (!Array.isArray(value)) return '';
+  const inner = extentsOf(value[0]);
+  return inner === '' ? String(value.length) : `${value.length}x${inner}`;
+}
+
 /**
  * The array literal for one parameter: `{a,b,c}`, elements escaped.
  *
@@ -71,5 +98,15 @@ export function pgArrayLiteral(values: readonly unknown[]): string {
     `a nested array parameter is ragged — its rows are ${nested.map((row) => row.length).join(', ')} long, and Postgres has no jagged array`,
     'give every row the same length, or bind one array per row',
   );
+  // Every extent, not only this level's: `[[['a']], [['b', 'c']]]` is two rows of one element each,
+  // each rectangular on its own, and `{{{a}},{{b,c}}}` is the same 22P02 — measured on 17. Each
+  // row is checked against itself by the recursion below, so comparing one path's extents per row
+  // is comparing all of them.
+  const depth = extentsOf(nested[0]);
+  assert(
+    nested.every((row) => extentsOf(row) === depth),
+    `a nested array parameter is ragged below its first level — its rows have the extents ${nested.map((row) => extentsOf(row)).join(' | ')}, and Postgres has no jagged array`,
+    'give every branch the same length at every depth, or bind one array per row',
+  );
   return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`;
 }

package/src/bound-parameters.ts

@@ -4,7 +4,7 @@
 // described type to go by the driver sent `Date.prototype.toString()`, a local-zone string
 // Postgres refuses (`22007`), so every entity write carrying a timestamp failed.
 
-import { pgArrayLiteral } from './array-parameter';
+import { instantText, pgArrayLiteral } from './array-parameter';
 
 const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value instanceof Date;
 
@@ -12,12 +12,31 @@ const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value
  * A NEW ARRAY ONLY WHEN SOMETHING CHANGED — every statement in the process passes through here, so
  * the common path is one `some` and the caller's own array, byte for byte (axiom 6). A
  * `Uint8Array` is BYTEA, never an array: `Array.isArray` answers `false` for a typed array.
+ *
+ * It REFUSES what cannot be sent — a ragged array, an Invalid Date — with `X_INVARIANT`, so the
+ * funnel calls it BEFORE the driver's `try`: inside it, a refusal was re-wrapped as a driver
+ * failure and read "cannot reach the database".
  */
+/**
+ * The refusals alone, for a driver that does its own encoding. PGlite renders an array and a
+ * `Date` correctly, so `pglite.ts` sends the caller's values untouched — but what cannot be sent
+ * must be refused alike on both funnels: an Invalid Date (its serializer answers a bare
+ * `RangeError`) and a ragged or mixed-depth array, which the pooled path refuses in
+ * `pgArrayLiteral`. That function IS the shape rule, so it is asked and its literal discarded
+ * rather than restated here; only a statement that binds an array pays for it.
+ */
+export function refuseUnsendable(values: readonly unknown[]): void {
+  for (const [index, value] of values.entries()) {
+    if (value instanceof Date) instantText(value, index + 1);
+    else if (Array.isArray(value)) pgArrayLiteral(value);
+  }
+}
+
 export function encodeBoundParameters(values: readonly unknown[]): readonly unknown[] {
   if (!values.some(needsEncoding)) return values;
-  return values.map((value) => {
+  return values.map((value, index) => {
     if (Array.isArray(value)) return pgArrayLiteral(value);
-    if (value instanceof Date) return value.toISOString();
+    if (value instanceof Date) return instantText(value, index + 1);
     return value;
   });
 }

package/src/catalog-fold.ts

@@ -51,7 +51,10 @@ function columnOf(row: ColumnRow, sequences: readonly SequenceRow[]): CatalogCol
     type: row.type,
     notNull: row.not_null,
     default: generated ? null : row.expression,
-    generated: generated ? row.expression : null,
+    generated:
+      generated && row.expression !== null
+        ? { expression: row.expression, storage: row.generated === 'v' ? 'virtual' : 'stored' }
+        : null,
     identity:
       identity === undefined
         ? null

package/src/catalog-objects.ts

@@ -148,6 +148,15 @@ export const triggerRows = (client: DbClient, schema: string): Promise<readonly
  * What exists in the schema and the dump cannot spell. One query, one closed list — a kind added
  * 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.
+ *
+ * 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.
  */
 export const unrenderedRows = (
   client: DbClient,
@@ -194,6 +203,26 @@ export const unrenderedRows = (
       from pg_rewrite r
       join pg_class c on c.oid = r.ev_class
       where r.rulename <> '_RETURN'
+      union all
+      select 'extended statistics', s.stxname, c.relname, s.stxnamespace
+      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
+      join pg_type t on t.oid = a.atttypid
+      where c.relkind = 'r' and a.attnum > 0 and not a.attisdropped
+        and a.attstorage <> t.typstorage
+        and ${notExtensionOwned('pg_class', 'c.oid')}
+      union all
+      select 'unpopulated materialized view', c.relname, null::text, c.relnamespace
+      from pg_class c
+      where c.relkind = 'm' and not c.relispopulated
     ) objects
     join pg_namespace n on n.oid = objects.namespace
     where n.nspname = ${schema}

package/src/catalog.ts

@@ -56,8 +56,16 @@ export interface CatalogColumn {
   readonly notNull: boolean;
   /** `pg_get_expr` of the default; `null` when there is none or the column is generated. */
   readonly default: string | null;
-  /** The stored generation expression, when `attgenerated` says the column has one. */
-  readonly generated: string | null;
+  /**
+   * The generation expression and HOW it is kept, when `attgenerated` says the column has one:
+   * `s` is `stored`, `v` (Postgres 18) is `virtual` — computed on read, nothing on disk. Both
+   * halves, because a dump that spelled every one `stored` loaded a virtual column as a stored
+   * one and round-tripped "equal": both sides of that comparison were this reading.
+   */
+  readonly generated: {
+    readonly expression: string;
+    readonly storage: 'stored' | 'virtual';
+  } | null;
   /** `always` / `by default`, with the identity sequence's own options. */
   readonly identity: {
     readonly mode: 'always' | 'by default';

package/src/commit-tag.ts

@@ -0,0 +1,21 @@
+// Single responsibility: the server's answer to `COMMIT`, read. Postgres answers a COMMIT on an
+// aborted transaction with the command tag `ROLLBACK` and NO error, so a driver that reports only
+// rejections calls a rolled-back unit of work committed. Both funnels (`statement-funnel.ts`,
+// `pglite.ts`) ask here, so every COMMIT in the process is covered and not only `withTransaction`'s.
+
+import { stringField } from '@ultimat3/core';
+import { transactionAborted } from './transaction-errors';
+
+/** `COMMIT` and its alias `END`, as the first word. Only consulted once the tag already disagrees. */
+const COMMIT_STATEMENT = /^\s*(?:commit|end)\b/i;
+
+/**
+ * Throws `X_DB_TRANSACTION_ABORTED` when `text` asked for a commit and the tag says `ROLLBACK`.
+ * The tag is read first: one property read per statement on the path every statement takes, and
+ * the regular expression runs only for a statement that really was answered `ROLLBACK`. Both
+ * drivers carry the tag on `command` — measured on Bun.SQL against Postgres 17 and on PGlite.
+ */
+export function refuseRolledBackCommit(text: string, result: unknown): void {
+  if (stringField(result, 'command') !== 'ROLLBACK') return;
+  if (COMMIT_STATEMENT.test(text)) throw transactionAborted();
+}

package/src/dependent-view.ts

@@ -139,6 +139,7 @@ async function dependentViews(
       join pg_attribute a on a.attrelid = c.oid and a.attnum = d.refobjsubid
      where v.relkind in ('v', 'm') and v.oid <> c.oid
        and c.relname in (${tables}) and a.attname in (${columns})
+       and pg_table_is_visible(c.oid)
      order by v.relname
   `);
 }
@@ -155,7 +156,8 @@ async function dependentViews(
 const shellArg = (statement: string): string => `'${statement.replaceAll("'", `'\\''`)}'`;
 
 /** The invocation `migrationConflict` already writes, with the statement as its own argv word. */
-const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
+export const psqlCommand = (statement: string): string =>
+  `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
 
 /**
  * The two statements that unblock the deploy, as one line an operator pastes.
@@ -166,7 +168,7 @@ const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(
  * a shell read `drop` as a program that does not exist. Neither reader could run it (axiom 4).
  *
  * `identifier()` REFUSES a name holding a quote, a space or a backslash — all three legal inside a
- * quoted Postgres name — and a `fix:` may not throw: the rule `rebuildForeignKey` already states,
+ * quoted Postgres name — and a `fix:` may not throw: the rule `changedForeignKey` (`drift-findings.ts`) states,
  * with the same shape. A refusal that raised `X_SQL_UNSAFE` in place of the finding would hand the
  * operator an exception where a verdict was asked for, over a view name that is perfectly legal.
  * The fallback still leads with a command that runs — a psql session — because quoting that name
@@ -192,8 +194,8 @@ function restoreView(view: string, definition: string, relkind: string): string
   try {
     const name = identifier(view).text;
     return (
-      `${psql(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
-      `${psql(`create ${kind} ${name} as ${body}`)}${note}`
+      `${psqlCommand(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
+      `${psqlCommand(`create ${kind} ${name} as ${body}`)}${note}`
     );
   } catch {
     return (