@crvouga/postgres-mem 1.0.1 → 1.1.1

package/AGENTS.md

@@ -11,9 +11,9 @@ 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
-4. `NOT APPLICABLE` items: roles/auth enforcement, replication, VACUUM internals, storage params, PL/pgSQL
+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, PL/pgSQL, or multi-session concurrency.
+**Non-goals:** speaking the wire protocol, matching `pg`/`postgres.js` client APIs, full PL/pgSQL, or multi-session concurrency.
 
 ## SQL pipeline
 
@@ -39,7 +39,7 @@ Everything is **typed values** (`TypedValue = { t: TypeId, v: Datum }` in [`src/
 | `ast/` | Discriminated-union AST (`nodes.ts`) |
 | `lexer/` | Tokenizer (dollar quoting, E-strings, `::`, operators) |
 | `parser/` | Recursive-descent parser |
-| `executor/` | Statement dispatch, SELECT, DML, DDL, session (SET/SHOW/COPY/PREPARE), triggers, window functions |
+| `executor/` | Statement dispatch, SELECT, DML, DDL, session (SET/SHOW/COPY/PREPARE), triggers, plpgsql-lite UDFs, window functions |
 | `expressions/` | `evalExpr`, operators, pattern matching, `EngineCtx` |
 | `functions/` | Scalar / aggregate / window / datetime / JSON / array / SRF / tsearch registries |
 | `types/` | `TypedValue`, casts, comparison, numeric, datetime, jsonb, timezone |
@@ -101,10 +101,10 @@ Hot / large files: `parser/parser.ts`, `executor/select.ts`, `executor/dml.ts`,
 
 | Path | Role |
 | --- | --- |
-| `tests/contract/` | Differential SQL vs PGlite (**authoritative**) |
+| `tests/contract/` | Differential SQL vs oracle (**authoritative**; default PGlite, optional native via `test:postgres-native`) |
 | `tests/fuzz/` | fast-check property tests (seeded); differential, NoREC/TLP metamorphic, stateful DST |
 | `tests/harness/` | Compare/normalize/classify helpers + harness unit tests |
-| `tests/adapters/` | Wrappers for postgres-mem and PGlite (`ContractDb`) |
+| `tests/adapters/` | Wrappers for postgres-mem, PGlite, and native Postgres (`ContractDb`) |
 | `tests/corpus/` | Fuzz regression corpus |
 | `tests/meta/` | Canary definitions, skip register |
 
@@ -124,7 +124,8 @@ POSTGRES_MEM_FUZZ_SEED=12345 POSTGRES_MEM_FUZZ_PATH='0:1' bun test tests/fuzz
 
 | Command | Role |
 | --- | --- |
-| `bun run test:postgres-compat` | Requirements + fail-closed gate + construct catalog + smoke ratchet + contract/fuzz/harness |
+| `bun run test:postgres-compat` | Requirements + fail-closed gate + construct catalog + smoke ratchet + contract/fuzz/harness (PGlite oracle) |
+| `bun run test:postgres-native` | Same differential suite vs real PostgreSQL 18.3 (embedded-postgres, or `POSTGRES_MEM_ORACLE_URL`) |
 | `bun run inventory` | Oracle `pg_proc` / `pg_operator` vs engine registries (+ `--write-register`) |
 | `bun run scenarios` | Construct-level scenario catalog (`compat/scenarios.ts`) + smoke gate |
 | `bun run requirements` | Refresh PostgreSQL 18 SQL-commands docs → `compat/requirements.json` + `compat/coverage.json` |
@@ -136,6 +137,8 @@ Statuses: **VERIFIED** / **PARTIALLY VERIFIED** / **UNSUPPORTED** / **NOT APPLIC
 
 **PGlite quirk:** PGlite's WASM boot leaks `process.exitCode = 99` under Bun ([pglite#975](https://github.com/electric-sql/pglite/issues/975)); the adapter and scripts reset it — keep that workaround when touching `tests/adapters/pglite.ts`.
 
+**Native oracle:** `POSTGRES_MEM_ORACLE=server` + `POSTGRES_MEM_ORACLE_URL` selects `PostgresServerAdapter`. Prefer `bun run test:postgres-native` (starts embedded-postgres 18.3). Optional Docker: `docker-compose.oracle.yml`.
+
 Details: [COMPATIBILITY.md](COMPATIBILITY.md), audit: [COMPATIBILITY-AUDIT.md](COMPATIBILITY-AUDIT.md).
 
 ## Local gates
@@ -150,10 +153,11 @@ bun run format
 bun run lint
 bun run typecheck
 bun run test:postgres-compat
+bun run test:postgres-native # optional second oracle (real PostgreSQL 18.3)
 bun test # contract + fuzz + harness
 bun run build
 ```
 
 ## PR and commits
 
-Use [Conventional Commits](https://www.conventionalcommits.org/) for commits and PR titles (enforced in CI). Prefer squash merges with a conventional title. Releasing is automated via semantic-release — see [README.md](README.md#releasing).
+Use [Conventional Commits](https://www.conventionalcommits.org/) for commits and PR titles (enforced on PRs). Prefer squash merges with a conventional title so the npm bump is `feat` → minor / `fix` → patch. Direct pushes to `main` with any other subject still publish a patch. See [README.md](README.md#releasing).

package/COMPATIBILITY-AUDIT.md

@@ -32,8 +32,8 @@ Coverage statuses (SQL_BEHAVIOR):
 
 Oracle builtin inventory:
   pg_catalog functions exposed by oracle: 2787
-  implemented in engine registries:        301
-  registered unsupported (with reasons):  2486
+  implemented in engine registries:        302
+  registered unsupported (with reasons):  2485
   silently missing:                          0 (gate fails otherwise)
   pg_catalog operators exposed by oracle:   74
   implemented:                              41
@@ -53,7 +53,7 @@ Types / casts / NULL:
   3VL through operators/aggregates/DISTINCT
 
 Functions (oracle surface):
-  VERIFIED for the implemented 301; every other oracle builtin is an
+  VERIFIED for the implemented 302; every other oracle builtin is an
   explicit register entry (never silent)
 
 JSON / JSONB:
@@ -74,10 +74,11 @@ Schemas / search_path / catalogs:
 Sequences / serial / identity / enums / domains / generated columns:
   VERIFIED
 
-Triggers / LANGUAGE sql functions:
+Triggers / LANGUAGE sql / plpgsql-lite functions:
   PARTIALLY VERIFIED — row-level triggers fire in creation order
   (PostgreSQL: name order), UPDATE OF ignored, INSTEAD OF unsupported —
-  all pinned divergences
+  all pinned divergences. plpgsql-lite UDFs: DECLARE, EXCEPTION WHEN
+  others, CASE, FOR-IN-SELECT, RETURN NEXT.
 
 Text search:
   PARTIALLY VERIFIED — tsvector/tsquery/@@/ts_rank with simple-style

package/COMPATIBILITY.md

@@ -34,9 +34,9 @@ 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).
-4. **NOT APPLICABLE** rows in `compat/coverage.json` (roles, replication, VACUUM internals, LISTEN/NOTIFY, cursors, PL/pgSQL, extensions).
+4. **NOT APPLICABLE** rows in `compat/coverage.json` (roles, replication, VACUUM internals, LISTEN/NOTIFY, cursors, full PL/pgSQL, extensions).
 
-The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalog`; postgres-mem implements **301 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.
+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.
 
 ## Requirements coverage (PostgreSQL 18 SQL commands)
 
@@ -60,7 +60,7 @@ The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalo
 | 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) |
-| CREATE FUNCTION LANGUAGE sql | PARTIALLY VERIFIED | Scalar + set-returning; no polymorphic/variadic edges |
+| CREATE FUNCTION LANGUAGE sql / plpgsql-lite | PARTIALLY VERIFIED | Scalar + set-returning; plpgsql subset: DECLARE, EXCEPTION WHEN others, CASE, FOR-IN-SELECT, RETURN NEXT |
 | Text search (tsvector / tsquery / @@ / ts_rank) | PARTIALLY VERIFIED | `simple`-style config; no ispell/synonym dictionaries |
 | COPY FROM/TO (text, csv) | VERIFIED | Via `copyFrom` API hook / rows out |
 | PREPARE / EXECUTE / DEALLOCATE, SET / SHOW / RESET | VERIFIED | GUC subset |
@@ -68,7 +68,7 @@ The oracle exposes **2787 builtin functions** and **74 operators** in `pg_catalo
 | 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 / PL/pgSQL | UNSUPPORTED | Fail loud `0A000`, registered |
+| 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 | |
 

package/README.md

@@ -1,12 +1,14 @@
 # postgres-mem
 
+[npm](https://www.npmjs.com/package/@crvouga/postgres-mem) · [GitHub](https://github.com/crvouga/postgres-mem)
+
 Pure TypeScript, completely in-memory PostgreSQL implementation aiming for **PostgreSQL 18 SQL dialect parity** (same statements → same results).
 
 - Runs in modern browsers and Node.js / Bun
 - **Zero** WASM, native bindings, workers, or filesystem dependencies
 - Entire database stored in memory
 - **Synchronous** ESM-only API (no Promises, no `require`)
-- **SQL dialect verified** against real PostgreSQL 18.3 (PGlite) via differential contracts + fail-closed gate
+- **SQL dialect verified** against real PostgreSQL 18.3 (PGlite by default; optional native server via `test:postgres-native`) via differential contracts + fail-closed gate
 - **Not** a drop-in for `pg` / `postgres.js` client APIs, the wire protocol, or on-disk clusters
 - Intentional differences: deterministic `random()` / `now()` by default, and a custom snapshot format (not `pg_dump`)
 
@@ -41,7 +43,7 @@ Requires Node.js ≥ 20 or Bun ≥ 1.1. The published package is **ESM only** (`
 ## Usage
 
 ```ts
-import { Database } from "@crvouga/postgres-mem";
+import { Database, Snapshot } from "@crvouga/postgres-mem";
 
 const db = new Database();
 
@@ -57,9 +59,10 @@ db.prepare(`INSERT INTO users (name) VALUES ($1)`).run("Alice");
 const users = db.query<{ id: number; name: string }>(`SELECT * FROM users`);
 console.log(users);
 
-const snap = db.snapshot();
-const db2 = new Database();
-db2.restore(snap);
+const seed = db.snapshot();
+const db2 = seed.open();
+const bytes = seed.encode();
+const db3 = Snapshot.decode(bytes).open();
 ```
 
 All methods are **synchronous** — do not `await` them. Browser and Node/Bun share the same in-memory JS surface (no filesystem, no server, no wire protocol).
@@ -79,28 +82,41 @@ From the repo root after that install: `bun run example`.
 ## API
 
 ```ts
-import { Database, PostgresError } from "@crvouga/postgres-mem";
+import { Database, Snapshot, PostgresError } from "@crvouga/postgres-mem";
 
 interface DatabaseOptions {
   seed?: number | bigint;                 // default 1 — ignored when random is "os"
   random?: "deterministic" | "os";        // default "deterministic"; "os" is CSPRNG like PostgreSQL
   now?: Date | (() => Date) | "system";   // default 2000-01-01T00:00:00.000Z; "system" is wall clock
+  int8?: "bigint" | "number" | "string"; // default "bigint"; "number" is unsafe beyond MAX_SAFE_INTEGER
 }
 
 interface Database {
   constructor(options?: DatabaseOptions);
   exec(sql: string): void;
+  registerFunction(spec: {
+    name: string;
+    args: string[];
+    returns: string;
+    strict?: boolean;
+    fn: (...args: JsValue[]) => JsValue;
+  }): void;
   query<T = QueryRow>(sql: string, params?: BindValue[]): T[];
   prepare(sql: string): Statement;
   transaction<T>(fn: () => T): T;
   copyFrom(sql: string, data: string): number;  // COPY t FROM STDIN payload (\copy analog)
-  snapshot(): Uint8Array;
-  restore(snapshot: Uint8Array): void;
+  snapshot(): Snapshot;
   close(): void;
   [Symbol.dispose]?(): void;        // alias for close() when Symbol.dispose exists
   readonly changes: number;         // rows affected by the most recent INSERT/UPDATE/DELETE
 }
 
+class Snapshot {
+  open(options?: DatabaseOptions): Database;
+  encode(): Uint8Array;
+  static decode(bytes: Uint8Array): Snapshot;
+}
+
 interface Statement {
   run(...params: BindValue[]): RunResult;
   all<T = QueryRow>(...params: BindValue[]): T[];
@@ -129,18 +145,22 @@ class PostgresError extends Error {
 }
 ```
 
-Stick to `Database`, `Statement`, and `PostgresError` for application code. Advanced internals (`parse`, `tokenize`, `executeStatement`, snapshot codec pieces, `Prng`, …) are available only from `@crvouga/postgres-mem/unstable` and are **exempt from semver**.
+Stick to `Database`, `Snapshot`, `Statement`, and `PostgresError` for application code. Advanced internals (`parse`, `tokenize`, `executeStatement`, snapshot codec pieces, `Prng`, …) are available only from `@crvouga/postgres-mem/unstable` and are **exempt from semver**.
 
 ### Method semantics
 
 | Method | Behavior |
 | --- | --- |
-| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` afterward if needed (reflects the **most recent** completed DML statement). |
+| `exec(sql)` | Runs all semicolon-separated statements; **discards** row results (`void`). Does **not** accept bind parameters. Read `db.changes` afterward if needed (reflects the **most recent** completed DML statement). Dump-only `DO` blocks and `ALTER TABLE … SET (` storage parameters are no-ops. |
+| `registerFunction(spec)` | Install a JavaScript scalar. Not stored in PGMM snapshots; `open()` of a live snapshot copies the impl by reference. |
 | `query(sql, params?)` | **Single statement only** (trailing `;` is fine). Returns all rows. Multi-statement scripts throw `misuse`. |
 | `prepare(sql)` | **Single statement only**. Parses immediately; AST is reused. Pass binds as rest args to `run` / `all` / `get` / `result` on each call. |
 | `transaction(fn)` | If idle: `BEGIN` → `fn()` → `COMMIT`, or `ROLLBACK` + rethrow. If already in a transaction: nested savepoint. Nested SQL `BEGIN` inside is a no-op warning like PostgreSQL. `close()` inside `fn` throws `misuse`. |
 | `copyFrom(sql, data)` | Executes `COPY table [(cols)] FROM STDIN` with `data` as the copy-in payload (text or csv per the COPY options). Returns rows copied. `COPY ... TO STDOUT` output is returned as result rows by `query`. |
-| `snapshot` / `restore` | Custom binary format (see below). |
+| `snapshot()` | Freeze a reusable {@link Snapshot} template (no encode). Illegal inside a transaction (`25P01`). |
+| `Snapshot.open()` | Copy-on-write fork from a template. Parent stays open. |
+| `Snapshot.encode()` | Lazy PGMM blob for persistence / worker boot (computed once, cached). |
+| `Snapshot.decode(bytes)` | Decode a blob once per `Uint8Array` (WeakMap); later `open()` calls are CoW. |
 | `close()` | Idempotent; rolls back an open SQL transaction; further ops throw `misuse`. Also available as `[Symbol.dispose]` when supported. |
 
 SQL `BEGIN` / `COMMIT` / `ROLLBACK` / `SAVEPOINT` / `RELEASE` are first-class. Empty / comment-only SQL on `prepare` / `query` / `exec` throws `misuse` (`empty statement`).
@@ -174,12 +194,16 @@ Duplicate column names collapse in row objects (last write wins). Use `stmt.resu
 
 ### Snapshots
 
+- `db.snapshot()` returns a frozen in-memory {@link Snapshot}. Per-test isolation should `seed.open()` (copy-on-write, ~µs). Encoded bytes are **lazy** via `snapshot.encode()`.
 - Format magic `PGMM` followed by an explicit little-endian format-version `u32` — **not** `pg_dump` output and not loadable by real PostgreSQL.
-- Round-trips schemas, tables, rows, sequences (counters included), indexes, views, enums, domains, SQL functions, change counters, PRNG state, and clock.
-- Cannot `restore()` while a transaction is open (`25P01`).
-- `restore()` replaces `now` with a fixed clock from the snapshot (a live `() => Date` is overwritten). `{ now: "system" }` stays live after restore.
-- Equivalent databases produce byte-identical snapshots (schema/rows sorted) **within a single library version**.
-- **Compatibility policy:** newer library versions can always restore older snapshots; older libraries cannot restore newer format versions (`snapshot_version`). Corrupt magic yields a distinct error.
+- Round-trips schemas, tables, rows, sequences (counters included), indexes, views, enums, domains, SQL functions, change counters, PRNG state, and clock. JavaScript `registerFunction` impls are omitted.
+- Cannot `snapshot()` while a transaction is open (`25P01`).
+- `Snapshot.decode(bytes)` does not mutate the input `Uint8Array`. The same buffer object is decoded once (WeakMap) and later opens are CoW.
+- `open()` shares frozen tables until either side writes; idle `open().snapshot().encode()` is byte-identical to `snapshot().encode()`.
+- `open()` uses a fixed clock from the snapshot unless you pass `{ now: "system" }`, which stays live.
+- Equivalent databases produce byte-identical `encode()` output (schema/rows sorted) **within a single library version**.
+- Per-test isolation (CI-tier, 200 users + 800 items): `Snapshot.open` ~µs; `encode()` / `decode().open()` is the persistence path. See [benchmarks/PERFORMANCE.md](benchmarks/PERFORMANCE.md).
+- **Compatibility policy:** newer library versions can always decode older snapshots; older libraries cannot decode newer format versions (`snapshot_version`). Corrupt magic yields a distinct error.
 
 ## Determinism
 
@@ -188,7 +212,7 @@ The engine is deterministic by default. Invariants:
 | Source | Default | Override / notes |
 | --- | --- | --- |
 | `random()` / `gen_random_uuid()` | Seeded xorshift64* (`seed: 1`) | `new Database({ seed })` or `{ random: "os" }` for CSPRNG (not rolled back / not restored) |
-| `now()` / `current_timestamp` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })` — `"system"` is wall clock and is **not** frozen by `restore()` |
+| `now()` / `current_timestamp` / friends | Fixed `2000-01-01T00:00:00.000Z` | `new Database({ now: Date \| (() => Date) \| "system" })` — `"system"` is wall clock and is **not** frozen by `open()` |
 | `setseed()` / `random()` | Deterministic stream | Matches the engine PRNG, repeatable |
 | Table scans | Insertion order | Same order after `snapshot`/`restore` |
 | Snapshots | Sorted schema/rows + PRNG state + clock | Restored into PRNG and `now` |
@@ -228,11 +252,11 @@ This is **not** a drop-in replacement for `pg`, `postgres.js`, or PGlite's clien
 - `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`, PL/pgSQL bodies fail loud (`0A000`)
+- `MERGE`, `CALL`/procedures, cursors (`DECLARE`/`FETCH`), `LISTEN`/`NOTIFY`, and full PL/pgSQL (packages, NOTICE, cursors) fail loud (`0A000`)
 - `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
 
-**Also supported (oracle-parity):** schemas + `search_path`, `pg_catalog` / `information_schema` introspection, sequences (`serial`, identity, `nextval`/`currval`/`setval`), enums, domains, `LANGUAGE sql` functions, row-level triggers, recursive + data-modifying CTEs, window functions with full frame specs, `GROUPING SETS`/`ROLLUP`/`CUBE`, `DISTINCT ON`, `LATERAL`, arrays + `unnest` + subscripting, JSON/JSONB operator + function surface, `tsvector` text search, `ON CONFLICT DO NOTHING/UPDATE`, `RETURNING`, `PREPARE`/`EXECUTE`/`DEALLOCATE`, `SET`/`SHOW`/`RESET` GUCs, `COPY` text and csv.
+**Also supported (oracle-parity):** schemas + `search_path`, `pg_catalog` / `information_schema` introspection, sequences (`serial`, identity, `nextval`/`currval`/`setval`), enums, domains, `LANGUAGE sql` functions, plpgsql-lite UDFs (`DECLARE`, `EXCEPTION WHEN others`, `RETURN NEXT`), row-level triggers, recursive + data-modifying CTEs, window functions with full frame specs, `GROUPING SETS`/`ROLLUP`/`CUBE`, `DISTINCT ON`, `LATERAL`, arrays + `unnest` + subscripting, JSON/JSONB operator + function surface including `jsonb_path_query_first`, `tsvector` text search, `ON CONFLICT DO NOTHING/UPDATE`, `RETURNING`, `PREPARE`/`EXECUTE`/`DEALLOCATE`, `SET`/`SHOW`/`RESET` GUCs, `COPY` text and csv.
 
 ## Common pitfalls
 
@@ -240,10 +264,10 @@ This is **not** a drop-in replacement for `pg`, `postgres.js`, or PGlite's clien
 2. **Parameters are `$1..$n` only** — no `?` placeholders, no named parameters, no sticky `bind()`.
 3. **`query` / `prepare` are single-statement only** — multi-statement scripts belong in `exec()` (which does not take bind parameters).
 4. **`exec` returns `void` and takes no params** — use `db.prepare(…).run(…)` or `db.query(…)` for binds; use `db.changes` / `stmt.run().rowCount` for counters.
-5. **`now()` is not wall-clock** unless you pass `{ now: "system" }` or `{ now: () => new Date() }`. Default is year 2000. `restore()` freezes a snapshot clock except when constructed with `"system"`.
+5. **`now()` is not wall-clock** unless you pass `{ now: "system" }` or `{ now: () => new Date() }`. Default is year 2000. `open()` freezes a snapshot clock except when constructed with `"system"`.
 6. **`random()` is seeded**, not OS entropy, unless you pass `{ random: "os" }`. Snapshots restore the seeded PRNG; OS entropy is not rewound.
 7. **Snapshots are not `pg_dump` output** and cannot be loaded into real PostgreSQL.
-8. **`int8` comes back as `bigint`**, `numeric`/dates/json come back as **text** — parse them explicitly if you need JS numbers/objects.
+8. **`int8` comes back as `bigint` by default** (`{ int8: "number" | "string" }` opts in). `numeric`/dates/json come back as **text** — parse them explicitly if you need JS numbers/objects.
 9. **A failed statement does not abort the transaction** — real PostgreSQL rejects everything after an error inside `BEGIN` until `ROLLBACK`; postgres-mem keeps executing (documented divergence).
 10. **Unquoted identifiers fold to lowercase** (PostgreSQL rule — not uppercase like the SQL standard).
 11. **Do not import `@crvouga/postgres-mem/unstable` in application code** unless you accept breakage in any release.
@@ -254,7 +278,7 @@ Working examples beyond this README: `examples/react-vite`, `tests/contract/api/
 
 Requires [Bun](https://bun.sh). For architecture, change checklists, and how to add contract tests, see **[AGENTS.md](AGENTS.md)**.
 
-Parity is proven only by differential contracts against real PostgreSQL (PGlite, Postgres 18.3 in WASM). Isolated internal unit tests are not PostgreSQL compatibility proof.
+Parity is proven by differential contracts against real PostgreSQL — default oracle PGlite (18.3 in WASM), plus optional native PostgreSQL 18.3 via `bun run test:postgres-native`. Isolated internal unit tests are not PostgreSQL compatibility proof.
 
 ```bash
 bun install
@@ -263,7 +287,8 @@ bun run check                  # format + lint + typecheck + postgres-compat sui
 bun run format                 # write Biome formatting
 bun run lint                   # Biome lint
 bun run typecheck
-bun run test:postgres-compat   # requirements + inventory gate + differential suite
+bun run test:postgres-compat   # requirements + inventory gate + differential suite (PGlite)
+bun run test:postgres-native   # same differential suite vs real PostgreSQL 18.3
 bun test                       # contract + fuzz + harness
 bun run build
 ```
@@ -276,16 +301,16 @@ Publishing is fully automated. You never bump `version` or run `npm publish` by
 
 ### How a release happens
 
-1. Push or merge to `main` with [Conventional Commits](https://www.conventionalcommits.org/).
+1. Push or merge to `main`. Prefer [Conventional Commits](https://www.conventionalcommits.org/) so the bump is `feat` → minor / `fix` → patch / `BREAKING` → major; any other subject still publishes a patch.
 2. CI runs commitlint, format/lint/typecheck, build, package verification, tests, browser smoke, and benchmarks.
 3. If every gate is green, [semantic-release](https://semantic-release.gitbook.io/) analyzes commits since the last git tag, bumps semver, publishes to npm, and creates a GitHub Release.
 
 | Commit | Version bump |
 | --- | --- |
-| `fix: …` | patch (`0.1.0` → `0.1.1`) |
-| `feat: …` | minor (`0.1.0` → `0.2.0`) |
-| `feat!: …` or `BREAKING CHANGE:` footer | major (`0.2.0` → `1.0.0`) |
-| `docs:`, `chore:`, `refactor:`, `test:`, … | no release |
+| `fix: …` / `perf: …` | patch (`1.0.1` → `1.0.2`) |
+| `feat: …` | minor (`1.0.1` → `1.1.0`) |
+| `feat!: …` or `BREAKING CHANGE:` footer | major (`1.1.0` → `2.0.0`) |
+| any other message on `main` (including Cursor-style subjects) | patch |
 
 PR titles must also follow Conventional Commits (enforced in CI). Prefer squash merges with a conventional title.
 
@@ -318,7 +343,7 @@ Do this once so CI can publish. Full checklist: **[docs/SECRETS.md](./docs/SECRE
 
 Validate the checklist anytime with `bun run secrets:doctor`.
 
-After that, every green push to `main` with releasable commits updates npm automatically.
+After that, every green push to `main` updates npm automatically (`feat`/`fix`/`BREAKING` pick the bump; anything else is a patch).
 
 ## License
 

package/compat/coverage.json

@@ -375,7 +375,7 @@
       "evidence": [
         "tests/contract/functions/"
       ],
-      "notes": "LANGUAGE sql bodies only; PL/pgSQL fails loud"
+      "notes": "LANGUAGE sql plus plpgsql-lite (DECLARE, EXCEPTION WHEN others, CASE, FOR-IN-SELECT, RETURN NEXT); no cursors/NOTICE/packages"
     },
     "sql-creategroup": {
       "status": "NOT_APPLICABLE",

package/compat/divergences.json

@@ -4,9 +4,9 @@
     {
       "id": "oracle-pglite-version",
       "scope": "oracle",
-      "predicate": "The differential oracle is PGlite (embedded PostgreSQL 18.x WASM); server_version must be 18.3 or 18.1",
-      "specifiedBehavior": "Harness bootstrap asserts current_setting('server_version') is in {18.3, 18.1}. Differential results are only meaningful against these lines.",
-      "pinnedBy": ["scripts/postgres-compat-gate.ts", "tests/harness/oracle-versions.ts"]
+      "predicate": "The default differential oracle is PGlite (embedded PostgreSQL 18.x WASM); a secondary native-server oracle is available via POSTGRES_MEM_ORACLE=server. server_version must be 18.3 or 18.1 for either path.",
+      "specifiedBehavior": "Harness bootstrap asserts current_setting('server_version') is in {18.3, 18.1}. Default CI uses PGlite; `bun run test:postgres-native` (and CI job test-native-oracle) runs the same suite against a real PostgreSQL 18.3 process.",
+      "pinnedBy": ["scripts/postgres-compat-gate.ts", "tests/harness/oracle-versions.ts", "scripts/run-postgres-native-tests.ts"]
     },
     {
       "id": "deterministic-runtime",
@@ -30,7 +30,7 @@
     {
       "id": "pgmm-snapshot-codec",
       "scope": "engine",
-      "predicate": "snapshot()/restore() use the custom PGMM binary codec (magic 'PGMM' + LE u32 version), not pg_dump or the on-disk PostgreSQL format",
+      "predicate": "snapshot()/encode()/decode() use the custom PGMM binary codec (magic 'PGMM' + LE u32 version), not pg_dump or the on-disk PostgreSQL format",
       "specifiedBehavior": "Snapshots are byte-identical for equivalent logical state, refuse corrupt/truncated/future-version blobs, and cannot run inside a transaction. No PostgreSQL equivalent exists; tests assert memory behavior only.",
       "pinnedBy": [
         "SNP-rt-01",
@@ -44,7 +44,8 @@
         "SNP-hdr-03",
         "SNP-hdr-04",
         "SNP-txn-01",
-        "SNP-rep-01",
+        "SNP-open-01",
+        "SNP-open-02",
         "tests/contract/snapshots/basic.test.ts"
       ]
     },
@@ -93,9 +94,19 @@
         "API-txn-02",
         "API-sync-01",
         "API-copy-01",
+        "API-int8-01",
+        "API-int8-02",
+        "API-fn-01",
         "tests/contract/api/basic.test.ts"
       ]
     },
+    {
+      "id": "dump-compat-noop",
+      "scope": "sql",
+      "predicate": "DO blocks and ALTER TABLE SET (storage/reloptions) execute as no-ops so schema dumps can load without intercepts; PL/pgSQL and storage parameters are NOT APPLICABLE",
+      "specifiedBehavior": "exec() loads schema dumps. DO $$ … $$ and ALTER TABLE … SET (fillfactor=…) succeed and change nothing. PGlite executes plpgsql; these cases are memory-only.",
+      "pinnedBy": ["API-dump-01", "API-do-01", "API-set-01"]
+    },
     {
       "id": "empty-script-rejected",
       "scope": "sql",

package/compat/sections/api.ts

@@ -25,4 +25,10 @@ export const API_SECTION: CatalogSection = section("API", "JavaScript surface co
   ["txn-02", "nested transaction(fn) uses savepoints", D, "JS API surface, no oracle analog", undefined, DIV],
   ["sync-01", "methods return values, not Promises", D, "JS API surface, no oracle analog", undefined, DIV],
   ["copy-01", "copyFrom API loads COPY FROM STDIN data", D, "API-level COPY hook", ["tests/contract/copy/"], DIV],
+  ["int8-01", "int8 mode number surfaces IEEE number", D, "JS API overlay, no oracle analog", undefined, DIV],
+  ["int8-02", "int8 mode string surfaces decimal text", D, "JS API overlay, no oracle analog", undefined, DIV],
+  ["fn-01", "registerFunction installs a JS scalar", D, "JS API overlay, not in PGMM", undefined, DIV],
+  ["dump-01", "exec loads dump no-ops", D, "dump-compat overlay", undefined, "dump-compat-noop"],
+  ["do-01", "DO blocks are no-ops", D, "PL/pgSQL is NOT APPLICABLE", undefined, "dump-compat-noop"],
+  ["set-01", "ALTER TABLE SET storage parameters are no-ops", D, "storage params are NOT APPLICABLE", undefined, "dump-compat-noop"],
 ]);

package/compat/sections/fzz.ts

@@ -26,8 +26,13 @@ const rows: ScenarioRow[] = [
   ["comb-01", "feature combination fuzz", F, undefined, ["tests/fuzz/combinations.test.ts"]],
   ["dst-01", "stateful DST dump-after-each engine", F, undefined, ["tests/fuzz/stateful.test.ts"]],
   ["mix-01", "mixed DDL/DML stateful simulation", F, undefined, ["tests/fuzz/mixed-stateful.test.ts"]],
+  ["snap-01", "snapshot restore probe fuzz", F, undefined, ["tests/fuzz/snapshot.test.ts"]],
+  ["snap-02", "snapshot object round-trip contracts", F, undefined, ["tests/contract/snapshots/objects.test.ts"]],
+  ["snap-03", "extended logical dump (views/matviews/sequences)", F, undefined, ["tests/harness/state-dump.ts"]],
   ["robust-01", "PostgresError-only / snapshot bit-flip robustness", F, undefined, ["tests/fuzz/robustness.test.ts"]],
   ["corpus-01", "corpus regression replay", F, undefined, ["tests/fuzz/corpus.test.ts"]],
+  ["num-01", "numeric arithmetic differential fuzz", F, undefined, ["tests/fuzz/numeric.test.ts"]],
+  ["cpy-01", "COPY FROM STDIN differential fuzz", F, undefined, ["tests/fuzz/copy.test.ts"]],
   ["seed-01", "default seed 0x5a17e0e1", P, undefined, ["tests/fuzz/config.ts"]],
   ["replay-01", "POSTGRES_MEM_FUZZ_SEED / PATH replay", P, undefined, ["tests/fuzz/config.ts"]],
   ["min-01", "DST minimizer and repro script", P, undefined, ["tests/fuzz/dst/minimize.ts"]],

package/compat/sections/snp.ts

@@ -16,6 +16,7 @@ export const SNP_SECTION: CatalogSection = section("SNP", "Snapshot / restore",
   ["hdr-02", "corrupt magic errors distinctly", D, SNAP_NOTE, EXTRA, DIV],
   ["hdr-03", "truncated blob errors", D, SNAP_NOTE, EXTRA, DIV],
   ["hdr-04", "future version raises snapshot_version", D, SNAP_NOTE, EXTRA, DIV],
-  ["txn-01", "restore during transaction errors", D, SNAP_NOTE, EXTRA, DIV],
-  ["rep-01", "restore replaces entire state", D, SNAP_NOTE, EXTRA, DIV],
+  ["txn-01", "snapshot during transaction errors", D, SNAP_NOTE, EXTRA, DIV],
+  ["open-01", "Snapshot.open CoW fork", D, SNAP_NOTE, EXTRA, DIV],
+  ["open-02", "encode does not mutate; decode reuses buffer", D, SNAP_NOTE, EXTRA, DIV],
 ]);

package/compat/unsupported-register.json

@@ -1116,7 +1116,6 @@
     "jsonb_path_query": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
     "jsonb_path_query_array": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
     "jsonb_path_query_array_tz": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
-    "jsonb_path_query_first": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
     "jsonb_path_query_first_tz": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
     "jsonb_path_query_tz": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",
     "jsonb_populate_record": "not implemented in this milestone; calls fail loud with SQLSTATE 42883",

package/dist/api/bind.d.ts

@@ -1,3 +1,4 @@
+import type { Int8Mode } from "../runtime/options.js";
 import { type Datum, type OutputCtx, type TypedValue, type TypeId } from "../types/value.js";
 /** JavaScript values accepted as query parameters (`$1..$n`). */
 export type BindValue = null | undefined | boolean | number | bigint | string | Uint8Array | Date;
@@ -7,4 +8,4 @@ export type JsValue = null | boolean | number | bigint | string | Uint8Array;
 export type QueryRow = Record<string, JsValue>;
 export declare function bindValueToTyped(value: BindValue, index: number): TypedValue;
 /** Convert an engine datum to the public JS value for result rows. */
-export declare function datumToJs(t: TypeId, v: Datum, ctx: OutputCtx): JsValue;
+export declare function datumToJs(t: TypeId, v: Datum, ctx: OutputCtx, int8?: Int8Mode): JsValue;

package/dist/api/database.d.ts

@@ -1,5 +1,6 @@
-import { type DatabaseOptions, type RandomMode } from "../runtime/index.js";
-import type { BindValue, QueryRow } from "./bind.js";
+import { type DatabaseOptions, type Int8Mode, type RandomMode } from "../runtime/index.js";
+import type { BindValue, JsValue, QueryRow } from "./bind.js";
+import { type Snapshot } from "./snapshot.js";
 import { Statement } from "./statement.js";
 /**
  * Pure TypeScript in-memory PostgreSQL database.
@@ -24,6 +25,8 @@ export declare class Database {
     readonly seed: number | bigint;
     /** Entropy mode for `random()` / `gen_random_uuid()`. */
     readonly randomMode: RandomMode;
+    /** How `int8` columns surface in query rows. */
+    readonly int8Mode: Int8Mode;
     private closed;
     private transactionSequence;
     private apiTransactionDepth;
@@ -33,6 +36,13 @@ export declare class Database {
      * are allowed. Does not accept bind parameters — use {@link prepare} / {@link query}.
      */
     exec(sql: string): void;
+    /**
+     * Register a JavaScript function callable from SQL. Not encoded in PGMM
+     * snapshots — re-register after {@link Snapshot.decode} / {@link Snapshot.open}.
+     * {@link Snapshot.open} copies the implementation by reference when opening
+     * a live in-memory snapshot.
+     */
+    registerFunction(spec: RegisterFunctionOptions): void;
     /** Execute a single-statement query and return all rows keyed by column name. */
     query<T = QueryRow>(sql: string, params?: readonly BindValue[]): T[];
     /** Compile a single SQL statement into a reusable {@link Statement}. */
@@ -43,12 +53,11 @@ export declare class Database {
      */
     transaction<T>(fn: () => T): T;
     /**
-     * Serialize schema, rows, PRNG state, and clock into a `PGMM` snapshot blob.
-     * Restore with {@link restore}. Not an on-disk PostgreSQL format.
+     * Freeze this database into a reusable {@link Snapshot} template.
+     * Does not encode PGMM bytes. Call {@link Snapshot.encode} to persist, or
+     * {@link Snapshot.open} for a copy-on-write fork.
      */
-    snapshot(): Uint8Array;
-    /** Replace this database's contents with a blob from {@link snapshot}. */
-    restore(snapshot: Uint8Array): void;
+    snapshot(): Snapshot;
     /** Close the database. Further SQL throws. Idempotent. */
     close(): void;
     /**
@@ -66,4 +75,13 @@ export declare class Database {
     get changes(): number;
     private prepareSingle;
 }
+export { Snapshot } from "./snapshot.js";
+/** Options for {@link Database.registerFunction}. */
+export interface RegisterFunctionOptions {
+    name: string;
+    args: string[];
+    returns: string;
+    strict?: boolean;
+    fn: (...args: JsValue[]) => JsValue;
+}
 export type { DatabaseOptions };

package/dist/api/snapshot.d.ts

@@ -0,0 +1,21 @@
+import { type DatabaseOptions } from "../runtime/index.js";
+import { type Database } from "./database.js";
+/**
+ * Frozen in-memory database template. {@link open} is a copy-on-write fork.
+ * Encoded PGMM bytes are produced lazily via {@link encode}.
+ */
+export declare class Snapshot {
+    private cachedBytes;
+    /** Encoded PGMM blob. Computed once; never mutates a buffer passed to {@link decode}. */
+    encode(): Uint8Array;
+    /**
+     * Copy-on-write database from this frozen template. Does not re-encode or re-decode.
+     */
+    open(options?: DatabaseOptions): Database;
+    /**
+     * Decode `bytes` once and freeze the result. The same `Uint8Array` object
+     * returns the same {@link Snapshot} (WeakMap), so later {@link open} calls
+     * are copy-on-write forks after the first hydrate.
+     */
+    static decode(bytes: Uint8Array): Snapshot;
+}

package/dist/ast/nodes.d.ts

@@ -680,6 +680,8 @@ export type AlterTableAction = {
 } | {
     kind: "validate_constraint";
     name: string;
+} | {
+    kind: "reloptions";
 };
 export interface AlterTableStmt {
     readonly type: "alter_table";

package/dist/constraints/enforce.d.ts

@@ -18,6 +18,7 @@ interface UniqueSpec {
     isPrimary: boolean;
 }
 export declare function uniqueSpecsFor(env: ExecEnv, table: TableData): UniqueSpec[];
+export declare function uniqueKeyOf(env: ExecEnv, table: TableData, spec: UniqueSpec, row: Datum[]): string | null;
 /**
  * Unique / primary key enforcement (23505). `selfIdx` is the row's own index
  * in table.rows (already inserted / updated in place).