@crvouga/mockingbird-service-postgres 1.5.1 → 1.7.0

package/AGENTS.md

@@ -13,12 +13,11 @@ Guidance for humans and coding agents editing this repository. For install and c
 3. Single-session **engine**: no MVCC across connections, no aborted-transaction (`25P02`) state in the sync API
 4. `NOT APPLICABLE` items: roles/auth enforcement, replication, VACUUM internals, storage params, full PL/pgSQL
 
-**Non-goals:** matching `pg`/`postgres.js` **client APIs**, full PL/pgSQL, or MVCC. The optional
-wire-protocol server (`src/wire/`, a Node/Bun-only entry over the one engine) is in scope: it
-speaks frontend/backend v3 and coordinates connections by serializing transaction blocks, adding
-advisory locks, `LISTEN`/`NOTIFY`, `CancelRequest` and per-connection `25P02`. It deliberately does
-**not** add row-level lock contention (`SELECT … FOR UPDATE SKIP LOCKED` distribution) or `COPY`
-streaming.
+**Non-goals:** matching `pg`/`postgres.js` **client APIs**, full PL/pgSQL, or MVCC in the synchronous
+API. The optional wire-protocol server (`src/wire/`, a Node/Bun-only entry over the one engine) is
+in scope: it coordinates per-session `READ COMMITTED` workspaces and adds row locks (`FOR UPDATE`,
+`NOWAIT`, `SKIP LOCKED`, deadlock detection), advisory locks, `LISTEN`/`NOTIFY`, `CancelRequest`
+and per-connection `25P02`. `COPY` streaming remains an explicitly documented boundary.
 
 ## SQL pipeline
 

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog — @crvouga/mockingbird-service-postgres
 
+## 1.7.0 (2026-10-02)
+
+### Features
+
+- coordinate HTTP and protocol mocks ([3168653](https://github.com/crvouga/mockingbird/commit/31686534c55a9823fdaa92afc9cc456cf741b809))
+
+### Fixes and improvements
+
+- decouple smoke types from built packages ([a4b31c6](https://github.com/crvouga/mockingbird/commit/a4b31c6205d92aa0c6f7c9de3518d5ae44d38829))
+- protect child admin endpoints ([5410b94](https://github.com/crvouga/mockingbird/commit/5410b948a30dcedc21e9a70e44fd415c1ea25394))
+- explain discovery and controls ([dd0fed6](https://github.com/crvouga/mockingbird/commit/dd0fed6f5f94cac51ae71f2d2e7d58a6b01ccc63))
+- harden protocol startup and state ([6f5b557](https://github.com/crvouga/mockingbird/commit/6f5b557e87b48b31985949e04f3b5ef58f51d295))
+- preserve checkpoints and lifecycle ([50e8c32](https://github.com/crvouga/mockingbird/commit/50e8c322feded2f7f45afce9d8cdef43c37ab9ab))
+- clean branch state on reset ([3b714d4](https://github.com/crvouga/mockingbird/commit/3b714d4a5df8e75fee0bb31e98d7c7566e164381))
+- type signal listener cleanup ([5279852](https://github.com/crvouga/mockingbird/commit/5279852e56ea60262ccf17aa6e46b3c31091a34a))
+
+## 1.6.0 (2026-10-01)
+
+### Features
+
+- add MVCC row locks ([9e199e0](https://github.com/crvouga/mockingbird/commit/9e199e083c3d16a9a2acfd7a2e9ab00ad733ef4f))
+- stream COPY protocol ([9e7a867](https://github.com/crvouga/mockingbird/commit/9e7a8673206fd6dad1b170e1b3a31e183e5abb2f))
+- add database catalogs ([c9b2c06](https://github.com/crvouga/mockingbird/commit/c9b2c060af4919135926c805412886177b4026a0))
+- parse identity sequence names ([e7a5a03](https://github.com/crvouga/mockingbird/commit/e7a5a03f33e6d5a0dc28a34d30659bb128db7c73))
+- accept tooling session GUCs ([0464416](https://github.com/crvouga/mockingbird/commit/04644162f7bbd5071e580cfb398b3da82a2a4952))
+
 ## 1.5.1 (2026-10-01)
 
 ### Fixes and improvements
@@ -26,6 +52,7 @@
 - allow unpopulated materialized views to reference each other ([3ce1d8f](https://github.com/crvouga/mockingbird/commit/3ce1d8f555ed4008dd894aed20ebf64ab0253774))
 - support CREATE EXTENSION pg_trgm ([2296ba2](https://github.com/crvouga/mockingbird/commit/2296ba2f3d1a9ea7ce8ec9f528e979034692ebf1))
 - install pgcrypto digest() ([b5f3ccf](https://github.com/crvouga/mockingbird/commit/b5f3ccf79c6fedcabab157f1ee07af18a7871057))
+- boot Bolt over Socket Mode ([01322df](https://github.com/crvouga/mockingbird/commit/01322df315c66b1f2f5b53094cbbeeeef6d3ae6c))
 
 ## 1.3.1 (2026-09-29)
 

package/COMPATIBILITY.md

@@ -10,13 +10,21 @@ See [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md) for the latest evidence-bas
 
 Reference oracle: **PostgreSQL 18.3** via PGlite (`@electric-sql/pglite`, real Postgres compiled to WASM, in-process). Inventory: `bun run inventory`. Construct catalog: `bun run scenarios` → [`compat/scenarios.ts`](compat/scenarios.ts). Divergences: [`compat/divergences.json`](compat/divergences.json). Requirements matrix: `bun run requirements` → `compat/requirements.json` + `compat/coverage.json`.
 
+The Node `/server` entry participates in protocol fleets. Acceptance tests use `pg@8.23.0`
+for authenticated readiness, shutdown, namespace isolation, full-catalog reset/snapshot/restore and
+clock controls. This supervisor surface does not change the SQL dialect compatibility contract.
+
 ## Proof surface
 
 Differential tests compare a **tuple** per statement: rows (normalized to canonical PostgreSQL text where typed), column names and type names where requested, error SQLSTATE class + normalized message, command tag / `rowCount`, and transaction status, plus a **logical state dump** (catalog names, column definitions, row payloads, sequence values) after write sequences.
 
 A catalog ID appearing in a test file is **not** proof by itself. Trivial probes are tracked in [`compat/smoke-baseline.json`](compat/smoke-baseline.json) and ratcheted downward (currently **0 smoke stubs** across 945 catalog scenarios). Generated operator/cast matrices live under [`tests/contract/matrices/`](tests/contract/matrices/). Observed mem≠oracle diffs must bind to a `compat/divergences.json` entry or be a **FAILURE** — unexplained diffs are not allowed.
 
-Intentional differences are finite and machine-readable in `compat/divergences.json` (PGMM snapshots, seeded `random()`/`now()`, sync single-session API, no aborted-transaction state, EXPLAIN stubs, trigger-order/`UPDATE OF` edges, float8 rounding/overflow edges, …). Human-readable: [DIVERGENCES.md](DIVERGENCES.md).
+Intentional differences are finite and machine-readable in `compat/divergences.json` (PGMM snapshots, seeded `random()`/`now()`, sync single-session API, no aborted-transaction state, EXPLAIN stubs, trigger-order/`UPDATE OF` edges, float8 rounding/overflow edges, …). The wire server supports isolated database catalogs, startup selection, database lifecycle DDL, and copy-on-write template cloning. Human-readable: [DIVERGENCES.md](DIVERGENCES.md).
+
+The wire server supports protocol-v3 text and CSV `COPY FROM STDIN` / `COPY TO STDOUT`, including
+incremental `CopyData`, client aborts, and statement-atomic rollback. Binary COPY remains outside
+the compatibility surface.
 
 ## Status vocabulary
 
@@ -33,7 +41,7 @@ Anything a PostgreSQL application can invoke through SQL against the PGlite **18
 
 1. **Snapshot format** — custom binary codec (`PGMM`), not `pg_dump` / on-disk clusters (logical state still round-trips).
 2. **Deterministic `random()` / `now()`** — seeded PRNG and fixed clock by default (injectable).
-3. **Single session** — no MVCC across connections, no isolation levels beyond one session, no `25P02` aborted-transaction state (documented divergence).
+3. **Single-session sync API** — no concurrent sessions or `25P02` aborted-transaction state. The optional wire server separately provides per-session `READ COMMITTED` workspaces and row locks.
 4. **NOT APPLICABLE** rows in `compat/coverage.json` (roles, replication, VACUUM internals, LISTEN/NOTIFY, cursors, full PL/pgSQL, extensions other than `pgcrypto`'s `digest()` and `pg_trgm`'s `similarity` / `<%` / `gin_trgm_ops`).
 
 The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalog`; postgres-mem implements **302 functions** and **41 operators**, and every remaining item is an explicit entry in [`compat/unsupported-register.json`](compat/unsupported-register.json) with a reason (trigger/internal plumbing, admin/monitoring, unsupported type families, …). The gate fails closed on silence.
@@ -56,7 +64,7 @@ The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalo
 | GROUPING SETS / ROLLUP / CUBE, DISTINCT ON, LATERAL, set ops | VERIFIED | |
 | Recursive + data-modifying CTEs | VERIFIED | |
 | Constraints: PK / UNIQUE / NOT NULL / CHECK / FK actions | VERIFIED | DEFERRABLE parsed, checked at statement end |
-| Sequences / serial / identity | VERIFIED | |
+| Sequences / serial / identity | VERIFIED | Includes pg_dump identity sequence names and options |
 | Schemas + search_path + pg_catalog / information_schema | VERIFIED | Catalog columns are the commonly-queried subset |
 | Enums, domains, generated columns | VERIFIED | |
 | Triggers (row-level, LANGUAGE sql-expressible) | PARTIALLY VERIFIED | Creation-order firing, `UPDATE OF` ignored, no INSTEAD OF (documented) |
@@ -65,14 +73,15 @@ The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalo
 | `CREATE EXTENSION pgcrypto` / `digest()` | PARTIALLY VERIFIED | `digest(bytea, text)` and `digest(text, text)` for md5, sha1, sha224, sha256, sha384, sha512. `crypt`, `hmac`, `gen_salt`, and PGP functions are not installed. OpenSSL-only names (sha3, blake2, ripemd160, sm3) are not available. Extensions other than `pgcrypto` and `pg_trgm` still fail loud (`0A000`) |
 | `CREATE EXTENSION pg_trgm` | PARTIALLY VERIFIED | `similarity(text, text)`, `<%` at the default word-similarity threshold 0.6, and a single-column `gin_trgm_ops` index on `text` or `varchar`. `gist_trgm_ops`, multicolumn `gin_trgm_ops`, and non-default thresholds are not installed. |
 | COPY FROM/TO (text, csv) | VERIFIED | Via `copyFrom` API hook / rows out |
-| PREPARE / EXECUTE / DEALLOCATE, SET / SHOW / RESET | VERIFIED | GUC subset |
+| PREPARE / EXECUTE / DEALLOCATE, SET / SHOW / RESET | VERIFIED | GUC subset, including PostgreSQL dump and migration-client preambles |
 | Transactions / savepoints | VERIFIED | No `25P02` aborted state (documented divergence) |
 | Collation / ordering | PARTIALLY VERIFIED | `C` semantics pinned; locale/ICU out of scope |
 | Regex (`~`, `~*`, POSIX functions) | PARTIALLY VERIFIED | JS regex flavor mapped to POSIX ERE; documented edges |
 | EXPLAIN | PARTIALLY VERIFIED | Stub plan shapes |
 | MERGE / CALL / cursors / LISTEN / full PL/pgSQL | UNSUPPORTED | Fail loud `0A000`, registered |
 | Roles / GRANT / VACUUM / ANALYZE / LOCK | NOT APPLICABLE | Parsed no-ops where harmless |
-| Wire protocol / multi-session MVCC / on-disk format | NOT APPLICABLE | |
+| Wire protocol / multi-session concurrency | PARTIALLY VERIFIED | `READ COMMITTED` workspaces; `FOR UPDATE`, `NOWAIT`, `SKIP LOCKED`, and deadlock detection |
+| On-disk PostgreSQL format | NOT APPLICABLE | PGMM snapshots are the persistence format |
 
 ## How to verify
 

package/README.md

@@ -173,6 +173,13 @@ const fromUri = await serve("postgres://postgres:secret@127.0.0.1:0/app")
 await fromUri.close()
 ```
 
+The wire server owns a PostgreSQL-style database catalog. Start on `postgres`, then use ordinary
+`CREATE DATABASE`, `DROP DATABASE`, and `ALTER DATABASE … RENAME TO` statements; startup packets
+select an isolated engine and unknown names fail with `3D000`. `CREATE DATABASE child TEMPLATE
+seed` forks `seed` through the same copy-on-write snapshot path as `Snapshot.open()`. The live names
+are available through `pg_database` and `server.databaseNames()`, while
+`server.getDatabase(name)` and `server.snapshot(name)` provide programmatic test controls.
+
 Or from the command line (installs a `mockingbird-postgres` bin):
 
 ```bash
@@ -186,15 +193,23 @@ server from one frozen template, so a seeded stack starts from the same bytes ea
 surface as every other mock, including the table explorer (`GET /sql/tables`, `POST /sql/query`).
 The wire server does not speak that HTTP API.
 
+`mockingbird-postgres serve --config mockingbird.json` also supervises a mixed HTTP/Postgres/Redis
+fleet through the Node `/server` entry. See [fleet configuration and controls](../../../docs/FLEETS.md)
+for ephemeral discovery, namespace endpoints, aggregate health, snapshots and clocks. Each declared
+namespace has an independent cluster. Fleet checkpoints restore its entire catalog, including created
+and dropped databases, records, deterministic random state, faults and time; live client sessions
+return a conflict until closed.
+
 `server.snapshot()` freezes the live state; `server.fault({ dropConnection | delayStatementMs |
 failCommit })` arms the next statement or connection for a drop, a delay, or a `40001` commit
 failure.
 
-One engine is shared by every connection. The engine runs one statement at a time, so a connection
-inside an explicit `BEGIN` block holds it until `COMMIT`/`ROLLBACK` and other connections queue
-behind it — which keeps read-committed visibility (an uncommitted row is never seen by another
-connection) by serializing transaction blocks rather than by MVCC. Across connections the server
-adds what a single engine does not: per-session advisory locks (`pg_advisory_lock` /
+One committed engine is shared by every connection. Explicit transactions execute in per-session
+copy-on-write workspaces that rebase each statement on the latest committed state, providing
+`READ COMMITTED` visibility without holding an engine-wide transaction turn. Successful writes
+are applied atomically at commit; rollback discards the workspace. Across connections the server
+adds row locks for `SELECT … FOR UPDATE` (including blocking, `NOWAIT`, `SKIP LOCKED`, and
+deadlock SQLSTATE `40P01`) and per-session advisory locks (`pg_advisory_lock` /
 `pg_try_advisory_lock` / `_xact_` / `_unlock`) with in-order waiters and deadlock detection
 (`40P01`), `LISTEN`/`NOTIFY` delivered to idle listeners, `CancelRequest` (a blocked statement ends
 `57014` and the session stays usable), and per-connection aborted-transaction state (a failed
@@ -202,13 +217,15 @@ statement in a block is `25P02` until `ROLLBACK`, with `ReadyForQuery` reporting
 SCRAM-SHA-256 and trust auth, the extended query protocol (`Parse`/`Bind`/`Describe`/`Execute`/
 `Sync`) with text and binary parameters and results, real type OIDs in `RowDescription`, and
 `23505`/`23502` errors carrying the constraint, table and column the engine names, all work over
-the wire.
+the wire. `COPY … FROM STDIN` and `COPY … TO STDOUT` use protocol-v3 `CopyInResponse`,
+`CopyOutResponse`, `CopyData`, `CopyDone`, and `CopyFail` messages. Text and CSV streams are parsed
+incrementally across arbitrary frame and quoted-record boundaries; failed imports are atomic and
+leave the connection in PostgreSQL's transaction state.
 
-**Not modelled by the server:** row-level lock contention, so `SELECT … FOR UPDATE SKIP LOCKED`
-parses and returns rows but does not distribute disjoint rows across concurrent workers (there are
-no row locks); `COPY` streaming (`CopyInResponse`/`CopyData`) — use `copyFrom` on a shared
-`Database`; and the binary parameter formats beyond the common scalar types (a client that sends
-another binary type gets `0A000`, and can switch that parameter to text).
+**Not modelled by the server:** transaction ID and snapshot-inspection functions, predicate and
+table locks, isolation levels beyond `READ COMMITTED`, and the binary parameter formats beyond the
+common scalar types (a client that sends another binary type gets `0A000`, and can switch that
+parameter to text). Binary `COPY` is not supported.
 
 ### Method semantics
 
@@ -308,8 +325,8 @@ Goal: **SQL dialect** behavioural parity vs PostgreSQL **18.3** for the sync API
 [DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/DROP-IN-CONTRACT.md).
 
 The in-process API has no async client, no connection pooling and no `pg_dump` codec; the optional
-[wire-protocol server](#wire-protocol-server-separate-processes) adds a TCP listener and coordinates
-several connections over the one engine, but by serializing transaction blocks, not by MVCC.
+[wire-protocol server](#wire-protocol-server-separate-processes) adds a TCP listener, per-session
+`READ COMMITTED` transaction workspaces, and row-level worker locks.
 Intentional differences: custom `PGMM` snapshots; seeded `random()` / fixed `now()` by default
 (`{ random: "os" }` / `{ now: "system" }` match PostgreSQL entropy and wall clock).