@crvouga/mockingbird-service-postgres 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — @crvouga/mockingbird-service-postgres
 
+## 3.12.0 (2026-10-24)
+
+### Features
+
+- add buffered SQL durability ([288bdcc](https://github.com/crvouga/mockingbird/commit/288bdcca84582787a54c4fdf9e803db9aac0b8d7))
+- add efficient browser durability ([a8be579](https://github.com/crvouga/mockingbird/commit/a8be5799a883ddf6f731208e06f399410de4661a))
+
 ## 3.11.0 (2026-10-21)
 
 ### Features

package/README.md

@@ -553,7 +553,95 @@ without changing an application database. Accepted statements remain semanticall
 see [schema preflight and row-version metadata](COMPATIBILITY.md#schema-preflight-and-row-version-metadata)
 for limits, the report contract and `xmin` support.
 
-Stable runtime exports of the main entry:
+Browser durability is opt-in through `openDurableDatabase({ key, backend?, databaseOptions?, pageSize? })`.
+It returns a `Durable<Database>` handle: `.value` is the existing synchronous database,
+`.flush()` saves a batch, `.write(db => ...)` serializes a synchronous batch and saves it, and
+`.close()` saves before closing. Await a save before considering writes durable. Wrap related
+SQL operations in `db.transaction()` when they need rollback as well as persistence.
+
+```ts
+import { openDurableDatabase, IndexedDBDurabilityBackend } from "@crvouga/mockingbird-service-postgres";
+
+const backend = new IndexedDBDurabilityBackend({ name: "my-app" });
+const durable = await openDurableDatabase({ key: "main", backend });
+const db = durable.value;
+// Use db.exec / db.prepare / db.transaction as before.
+await durable.flush(); // acknowledges an atomic storage commit
+await durable.close();
+await backend.close(); // release the connection when its last user finishes
+```
+
+`IndexedDBDurabilityBackend` is the default and stores binary pages with atomic revision checks;
+it sends only changed pages in one transaction. `durability: "strict"` is the default;
+`"relaxed"` is available for explicitly weaker power-loss guarantees. Both settings resolve
+only on the IndexedDB transaction's `complete` event.
+`LocalStorageDurabilityBackend({ storage?, prefix?, locks? })` is a small-image fallback with
+whole-image base64 rewrites and synchronous IO. It uses Web Locks when available; without
+Web Locks, use a single writer per key. `MemoryDurabilityBackend` is a reference adapter.
+A stale save throws `DurabilityConflictError`; reopen to reconcile rather than overwriting
+another tab. Quota/IO failures reject the save, preserve the previously committed image and
+can be retried. Saved data remains subject to the browser's storage quota and eviction policy.
+
+`openDurable({ backend, key, codec, pageSize? })` works with any emulator using an injected
+`DurabilityCodec<T>`. The `DurabilityBackend` port exposes `load` and atomic `commit` of a
+`DurablePatch` against an expected revision. `DurableImage` carries the binary image, revision
+and page size. The port and adapters are shared with `@crvouga/mockingbird-core`.
+`withDurability(api, durable)` serializes Fetch requests and flushes before returning each
+response. For other Mockingbird services, inject `durable.value` through their existing
+`sqlite` option, then send requests through this wrapper. Route all writes through the same
+handle/wrapper to preserve serialization; do not mutate the database during an outstanding save.
+
+The immediate durability opener encodes one full SQLM/PGMM snapshot per batch and compares fixed-size pages (default
+16 KiB). This targets small to moderate databases, not unbounded datasets. It avoids per-row
+storage IO, but encoding is still O(database size). It is not an SQLite file or OPFS VFS.
+See [the browser benchmark](https://github.com/crvouga/mockingbird/blob/main/packages/service/sqlite/benchmarks/DURABILITY.md) for measurements and limits.
+
+For higher write throughput, use `openBufferedDurableDatabase({ key, backend?, ... })`.
+The returned `BufferedDurable<Database>` keeps the synchronous SQL API and schedules a save
+1,000 ms after the first unsaved change. This is a background deadline, not a debounce;
+suspended tabs and storage failures can delay it. The default owned IndexedDB adapter uses
+`durability: "relaxed"`. Use one writer per database key. Recent unsaved changes can be lost.
+
+```ts
+import { openBufferedDurableDatabase } from "@crvouga/mockingbird-service-postgres";
+
+const durable = await openBufferedDurableDatabase({
+  key: "main",
+  flushIntervalMs: 1000,
+  onError: (error) => console.error("Background save failed", error),
+});
+durable.value.exec("UPDATE items SET value = value + 1 WHERE id = 1");
+// SQL returns immediately; persistence runs in the background.
+await durable.flush(); // use when an acknowledgement is required
+await durable.close(); // flush and release the handle before leaving
+```
+
+Ordinary saves coalesce changed rows and append physical values plus runtime metadata;
+they do not encode or scan every stored row, and recovery does not replay SQL/functions.
+`pending` reports unacknowledged changes/queued work; `lastError` records background failures.
+IO/quota failures retain pending work and retry with bounded backoff; a revision conflict
+stops background persistence. Explicit `write`, `flush`, and `close` reject on failure and
+await storage acknowledgement. Close through the handle, not `durable.value.close()`.
+Do not leave SQL transactions open across a flush. Page-hide persistence is best effort.
+
+Checkpoints compact after 256 delta batches or journal growth of at least
+`max(4 MiB, checkpoint size)` by default (`compactAfterBatches`, `compactAfterBytes`).
+Schema changes, unsupported incremental shapes, public raw state/native container access
+and borrowed binary results/parameters conservatively select full checkpoints. Both openers read old
+SQLM/PGMM images and the versioned checkpoint/journal envelope; opting in upgrades the image
+on save. `Snapshot.encode/decode` formats and the existing immediate opener's defaults stay
+unchanged. LocalStorage uses the same port but still rewrites the whole image.
+
+`openBufferedDurable` is the reusable controller for other emulators, via an injected
+`IncrementalDurabilityCodec`, `DurabilityScheduler`, `DurabilityLifecycle` and the same
+`DurabilityBackend`. `browserDurabilityLifecycle` supplies optional page-hide notifications.
+`encodeDurableCheckpoint`, `readDurableJournal`, `packDurableRecord`, and
+`unpackDurableRecord` provide the shared versioned envelope/record framing.
+
+Stable runtime exports of the main entry include `openDurableDatabase`, `openDurable`,
+`withDurability`, `IndexedDBDurabilityBackend`, `LocalStorageDurabilityBackend`,
+`MemoryDurabilityBackend`, `DurabilityConflictError`, and the existing exports:
+
 
 | Export | Description |
 | --- | --- |