@crvouga/mockingbird-service-postgres 1.0.0 → 1.2.0

package/AGENTS.md

@@ -10,10 +10,15 @@ Guidance for humans and coding agents editing this repository. For install and c
 
 1. Custom snapshot codec (`PGMM`), not `pg_dump` / on-disk clusters
 2. Deterministic `random()` / `gen_random_uuid()` and fixed `now()` by default (injectable)
-3. Single-session engine: no MVCC across connections, no wire protocol, no aborted-transaction (`25P02`) state
+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:** speaking the wire protocol, matching `pg`/`postgres.js` client APIs, full PL/pgSQL, or multi-session concurrency.
+**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.
 
 ## SQL pipeline
 
@@ -49,6 +54,7 @@ Everything is **typed values** (`TypedValue = { t: TypeId, v: Datum }` in [`src/
 | `transactions/` | BEGIN / COMMIT / SAVEPOINT (clones state + PRNG) |
 | `runtime/` | Clock, PRNG, `DatabaseOptions` |
 | `serialization/` | `PGMM` snapshot codec |
+| `wire/` | Wire-protocol (frontend/backend v3) TCP server: `serve()`, CLI, per-connection state machine, cross-connection `Cluster` (Node/Bun only) |
 | `tsearch/` | `tsvector` / `tsquery` text search |
 | `errors/` | `PostgresError` with SQLSTATE, `unsupported()` |
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @crvouga/mockingbird-service-postgres
 
+## 1.2.0 (2026-09-29)
+
+### Features
+
+- share one field-guide identity across the docs site and READMEs ([024f445](https://github.com/crvouga/mockingbird/commit/024f445c143e0d2d07a4dd0a3c063bca94c59623))
+
+### Fixes and improvements
+
+- typecheck the postgres and sqlite README signature blocks ([cd2080b](https://github.com/crvouga/mockingbird/commit/cd2080b1af98f2746de063f289382527e28acfb2))
+
+## 1.1.0 (2026-09-25)
+
+### Features
+
+- wire-protocol server so separate processes can connect over TCP ([85000c8](https://github.com/crvouga/mockingbird/commit/85000c88fe57dc28c42caa19dcf3b825d94a361b))
+
+### Fixes and improvements
+
+- expose the wire server under ./wire, not the reserved ./server export ([12734c7](https://github.com/crvouga/mockingbird/commit/12734c7ecb39585ac3c7565d6367b3611d8c38a6))
+
 ## 1.0.0 (2026-09-24)
 
 ### ⚠️ Breaking changes

package/COMPATIBILITY.md

@@ -25,7 +25,7 @@ Intentional differences are finite and machine-readable in `compat/divergences.j
 | **VERIFIED** | Differential contracts (+ fuzz where applicable) cover happy path **and** meaningful edges vs oracle |
 | **PARTIALLY VERIFIED** | Implemented; coverage thin or known edges remain |
 | **UNSUPPORTED** | Missing from SQL surface (must fail loud; gate fails if oracle-exposed and unregistered) |
-| **NOT APPLICABLE** | Outside the in-memory single-session dialect surface (roles/auth, replication, storage, wire protocol) |
+| **NOT APPLICABLE** | Outside the SQL-dialect surface (roles/auth, replication, storage). The wire protocol is provided by the optional `/server` entry, documented in the README. |
 
 ## Scope bound
 

package/README.md

@@ -1,5 +1,7 @@
 # @crvouga/mockingbird-service-postgres
 
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
 Pure TypeScript, completely in-memory PostgreSQL engine aiming for **PostgreSQL 18 SQL dialect
 parity** (same statements, same results). Use it in tests (or the browser) wherever you want real
 PostgreSQL SQL semantics without a server: schema + migrations, constraints and SQLSTATE errors,
@@ -15,7 +17,7 @@ isolation.
 - **Synchronous**, ESM-only API (no Promises, no `require`)
 - **SQL dialect verified** against real PostgreSQL 18.3 (PGlite by default; optional native server)
   via differential contracts and a fail-closed gate
-- **Not** a drop-in for the `pg` / `postgres.js` client APIs, the wire protocol, or on-disk clusters
+- In-process it is **not** a drop-in for the `pg` / `postgres.js` client APIs or on-disk clusters, but it also ships an **optional wire-protocol server** (`@crvouga/mockingbird-service-postgres/wire`, Node/Bun) that unmodified clients connect to over TCP
 - Intentional differences: deterministic `random()` / `now()` by default, and a custom snapshot
   format (not `pg_dump`)
 
@@ -79,7 +81,8 @@ console.log(db2.query(`SELECT count(*) AS n FROM users`), db3.changes) // [{ n:
 ```
 
 All methods are **synchronous**; do not `await` them. Browser and Node/Bun share the same
-in-memory surface (no filesystem, no server, no wire protocol).
+in-memory surface (no filesystem). For a real TCP listener separate processes can connect to, see
+the [wire-protocol server](#wire-protocol-server-separate-processes) (Node/Bun only).
 
 ### Per-test isolation with snapshots
 
@@ -151,6 +154,53 @@ back as PostgreSQL text (node-postgres parses timestamps to `Date` and JSON to o
 `prepare`/`query` accept one statement at a time (use `exec` for scripts); errors are
 `PostgresError` with `code` set to the SQLSTATE, like `pg`'s `DatabaseError.code`.
 
+### Wire-protocol server (separate processes)
+
+When another process must connect over TCP — `pg`, `postgres.js`, a JDBC client, `psql`, a service
+in a local multi-service stack — start the frontend/backend v3 server instead of a shim. It needs
+`node:net`, so it is a separate Node/Bun entry (`/wire`) and the main package stays browser-safe.
+
+```ts
+import { serve } from "@crvouga/mockingbird-service-postgres/wire"
+
+const server = await serve({ port: 0 }) // 0 → a free port, reported as server.port
+// postgres://postgres@127.0.0.1:${server.port}/db  — no initdb, no OS user, pure TypeScript
+await server.close()
+```
+
+Or from the command line (installs a `mockingbird-postgres` bin):
+
+```bash
+mockingbird-postgres serve --port 55432            # trust auth
+mockingbird-postgres serve --password secret --log # SCRAM-SHA-256, log each statement
+```
+
+`serve({ database })` shares an existing `Database`, and `serve({ database: snapshot })` boots every
+server from one frozen template, so a seeded stack starts from the same bytes each time.
+`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` /
+`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
+statement in a block is `25P02` until `ROLLBACK`, with `ReadyForQuery` reporting `I`/`T`/`E`).
+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.
+
+**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).
+
 ### Method semantics
 
 | Method | Behaviour |
@@ -247,20 +297,21 @@ Goal: **SQL dialect** behavioural parity vs PostgreSQL **18.3** for the sync API
 [COMPATIBILITY.md](./COMPATIBILITY.md). Contract:
 [DROP-IN-CONTRACT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/postgres/docs/DROP-IN-CONTRACT.md).
 
-There is no wire protocol, no async client, no connection pooling, no `pg_dump` codec, and no
-multi-session concurrency. Intentional differences: custom `PGMM` snapshots; seeded `random()` /
-fixed `now()` by default (`{ random: "os" }` / `{ now: "system" }` match PostgreSQL entropy and
-wall clock); single session, no MVCC across connections.
+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.
+Intentional differences: custom `PGMM` snapshots; seeded `random()` / fixed `now()` by default
+(`{ random: "os" }` / `{ now: "system" }` match PostgreSQL entropy and wall clock).
 
 **Thin or partial areas** (do not assume full oracle fidelity):
 
 - `EXPLAIN`: stub plan shapes, not real planner output
-- Failed statements inside `BEGIN` do **not** poison the transaction (`25P02` aborted-state is not implemented)
+- The in-process API does **not** poison a transaction after a failed statement (no `25P02`); the wire-protocol server does, per connection
 - Triggers fire in **creation order** (PostgreSQL: name order); `UPDATE OF` column lists are ignored; `INSTEAD OF` is unsupported
 - `COMMENT ON` parses but comments are not stored
 - `round(float8)` rounds ties away from zero (PostgreSQL: half-to-even); numeric `round()` has full parity
 - `'1e400'::float8` saturates to `Infinity` instead of raising `22003`
-- `MERGE`, `CALL`/procedures, cursors (`DECLARE`/`FETCH`), `LISTEN`/`NOTIFY`, and full PL/pgSQL (packages, NOTICE, cursors) fail loud (`0A000`)
+- In the engine `MERGE`, `CALL`/procedures, cursors (`DECLARE`/`FETCH`), `LISTEN`/`NOTIFY`, and full PL/pgSQL (packages, NOTICE, cursors) fail loud (`0A000`); the wire-protocol server implements `LISTEN`/`NOTIFY` itself
 - `VACUUM` / `ANALYZE` / `CLUSTER` / `REINDEX` / `CHECKPOINT` / `GRANT` / `REVOKE` / `LOCK` are parsed no-ops
 - Collation is `C` semantics (byte order); locale/ICU-dependent ordering is out of scope
 
@@ -301,7 +352,7 @@ Stable runtime exports of the main entry:
 Signatures (types are exported too: `DatabaseOptions`, `RegisterFunctionOptions`, `ResultSet`,
 `RunResult`, `ErrorCategory`, `BindValue`, `JsValue`, `QueryRow`):
 
-```text
+```ts
 interface DatabaseOptions {
   seed?: number | bigint                 // default 1; ignored when random is "os"
   random?: "deterministic" | "os"        // default "deterministic"; "os" is CSPRNG like PostgreSQL
@@ -309,7 +360,7 @@ interface DatabaseOptions {
   int8?: "bigint" | "number" | "string"  // default "bigint"; "number" is unsafe beyond MAX_SAFE_INTEGER
 }
 
-class Database {
+declare class Database {
   constructor(options?: DatabaseOptions)
   exec(sql: string): void
   registerFunction(spec: { name: string; args: string[]; returns: string; strict?: boolean;
@@ -328,13 +379,13 @@ class Database {
   readonly int8Mode: "bigint" | "number" | "string"
 }
 
-class Snapshot {
+declare class Snapshot {
   open(options?: DatabaseOptions): Database
   encode(): Uint8Array
   static decode(bytes: Uint8Array): Snapshot
 }
 
-class Statement {
+declare class Statement {
   readonly sql: string
   run(...params: BindValue[]): RunResult
   all<T = QueryRow>(...params: BindValue[]): T[]
@@ -348,12 +399,13 @@ interface ResultSet     { columns: string[]; columnTypes: string[]; rows: QueryR
 interface TextResultSet { columns: string[]; columnTypes: string[]; rows: (string | null)[][]; rowCount: number; command: string }
 // columnTypes are PostgreSQL internal type names, e.g. "int4", "numeric"
 
-class PostgresError extends Error {
+declare class PostgresError extends Error {
   readonly category: ErrorCategory   // "syntax", "undefined_table", "constraint_unique", "misuse", ...
   readonly sqlState: string          // five-character SQLSTATE
   readonly code: string              // === sqlState (node-postgres err.code convention)
 }
 
+type ErrorCategory = string // "syntax" | "undefined_table" | "constraint_unique" | "misuse" | ...
 type BindValue = null | undefined | boolean | number | bigint | string | Uint8Array | Date
 type JsValue   = null | boolean | number | bigint | string | Uint8Array
 type QueryRow  = Record<string, JsValue>

package/dist/wire/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};