prisma-pglite-bridge 0.4.1 → 0.5.0

package/README.md

@@ -15,88 +15,129 @@ pnpm add -D prisma-pglite-bridge @electric-sql/pglite @prisma/adapter-pg pg
 The last three are peer dependencies you may already have.
 TypeScript users also need `@types/pg`.
 
+### Bridge fs-sync policy
+
+The adapter defaults `syncToFs` to `'auto'`:
+
+- in-memory PGlite (`new PGlite()` or `memory://...`) resolves to `false`
+- persistent `dataDir` usage resolves to `true`
+
+That keeps bridge-heavy test workloads on the lower-memory fast path
+without changing durability defaults for persistent databases.
+If you use a custom `fs`, set `syncToFs` explicitly because the
+adapter cannot infer whether that storage is durable.
+
 ## Quickstart
 
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
 import { createPgliteAdapter } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 
-const { adapter, resetDb } = await createPgliteAdapter();
+const pglite = new PGlite();
+const { adapter, resetDb } = await createPgliteAdapter({
+  pglite,
+  migrationsPath: './prisma/migrations',
+});
 const prisma = new PrismaClient({ adapter });
 
-// Per-test isolation (optional)
 beforeEach(() => resetDb());
 ```
 
-That's it. Schema is auto-discovered from `prisma.config.ts`
-and migration files (run `prisma migrate dev` first if you
-haven't already). No Docker, no database server — works
-in GitHub Actions, GitLab CI, and any environment where
-Node.js runs.
+Call `resetDb()` in `beforeEach` to wipe all data between tests.
+Skip it if your tests are read-only or you want state to carry
+over.
+
+That's it. Run `prisma migrate dev` first to generate migration
+files. No Docker, no database server — works in GitHub Actions,
+GitLab CI, and any environment where Node.js runs.
 
 ## Schema Resolution
 
-`createPgliteAdapter()` resolves schema SQL in this order:
+When you pass any of `sql`, `migrationsPath`, or `configRoot`,
+`createPgliteAdapter` applies schema SQL. Resolution order:
 
 1. **`sql` option** — pre-generated SQL string, applied directly
 2. **`migrationsPath` option** — reads migration files from the
    given directory
 3. **Auto-discovered migrations** — uses `@prisma/config` to find
-   migration files (same resolution as `prisma migrate dev`).
-   Requires `prisma` to be installed (which provides
-   `@prisma/config` as a transitive dependency).
-
-If no migration files are found, it throws with a message to run
-`prisma migrate dev` first.
+   migration files (same resolution as `prisma migrate dev`),
+   triggered by passing `configRoot`. Requires `prisma` to be
+   installed (which provides `@prisma/config` as a transitive
+   dependency).
+
+When none of these options is provided, no SQL is applied — the
+PGlite instance is assumed to already hold the schema (useful
+for reopening a persistent `dataDir`).
+
+Schema SQL — whether inline via `sql` or loaded from `migrationsPath`
+— is executed verbatim with no checksum or signature verification.
+Ensure the source is trusted and version-controlled. Do not compose
+it from environment variables, network input, or any value that
+crosses a trust boundary, and keep the migrations directory
+writable only by trusted processes.
 
 ## API
 
-### `createPgliteAdapter(options?)`
+### `createPgliteAdapter(options)`
 
-Creates a Prisma adapter backed by an in-process PGlite instance.
+Creates a Prisma adapter backed by a caller-supplied PGlite
+instance.
 
 ```typescript
-const { adapter, pglite, resetDb, close } = await createPgliteAdapter({
-  // All optional — migrations auto-discovered from prisma.config.ts
+const pglite = new PGlite(/* dataDir, extensions, ... */);
+
+const { adapter, resetDb, close, stats } = await createPgliteAdapter({
+  pglite,                                // required — caller owns lifecycle
   migrationsPath: './prisma/migrations', // or:
   sql: 'CREATE TABLE ...',              // (first match wins, see Schema Resolution)
   configRoot: '../..',        // monorepo: where to find prisma.config.ts
-  dataDir: './data/pglite',   // omit for in-memory
-  extensions: {},             // PGlite extensions
-  max: 5,                     // pool connections (default: 5)
+  max: 1,                     // pool connections (default: 1, see "Pool sizing" below)
+  statsLevel: 'off',          // 'off' | 'basic' | 'full' (default: 'off')
 });
 ```
 
 Returns:
 
 - `adapter` — pass to `new PrismaClient({ adapter })`
-- `pglite` — the underlying PGlite instance for direct SQL,
-  snapshots, or extension access
-- `resetDb()` — truncates all user tables, resets session state
-  (`RESET ALL`, `DEALLOCATE ALL`). Call in `beforeEach` for
-  per-test isolation. Note: this clears all data including seed
-  data — re-seed after reset if needed.
-- `close()` — shuts down pool and PGlite. Not needed in tests
-  (process exit handles it). Use in long-running scripts or dev
-  servers.
-
-### `createPool(options?)`
+- `resetDb()` — truncates all user tables and discards
+  session-local state via `DISCARD ALL` (for example `SET`
+  variables, prepared statements, temp tables, and `LISTEN`
+  registrations). Call in `beforeEach` for per-test isolation.
+  Note: this clears all data including seed data — re-seed after
+  reset if needed.
+- `close()` — shuts down the pool. The caller-supplied PGlite
+  instance is not closed — you own its lifecycle. Not needed in
+  tests (process exit handles it); use in long-running scripts
+  or dev servers.
+- `stats()` — returns telemetry when `statsLevel` is `'basic'` or
+  `'full'`, else `undefined`. See [Stats collection](#stats-collection).
+- `adapterId` — a unique `symbol` identifying this adapter. Use it
+  to filter events from the public
+  [diagnostics channels](#diagnostics-channels) when multiple
+  adapters share a process.
+
+### `createPool(options)`
 
 Lower-level escape hatch. Creates a `pg.Pool` backed by PGlite
-without automatic schema resolution — useful for custom Prisma
-setups, other ORMs, or raw SQL.
+without schema handling — useful for custom Prisma setups,
+other ORMs, or raw SQL.
 
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
 import { createPool } from 'prisma-pglite-bridge';
 import { PrismaPg } from '@prisma/adapter-pg';
 
-const { pool, pglite, close } = await createPool();
+const pglite = new PGlite();
+const { pool, close } = await createPool({ pglite });
 const adapter = new PrismaPg(pool);
 ```
 
-Returns `pool` (pg.Pool), `pglite` (the underlying PGlite
-instance), and `close()`. Accepts `dataDir`, `extensions`, `max`,
-and `pglite` (bring your own pre-configured PGlite instance).
+Returns `pool` (pg.Pool), `adapterId` (a unique `symbol` for
+[diagnostics channel](#diagnostics-channels) filtering), and
+`close()` (which shuts down the pool only — the caller-supplied
+PGlite instance is not closed). Accepts `pglite` (required),
+`max`, and `adapterId`.
 
 ### `PGliteBridge`
 
@@ -142,10 +183,15 @@ the in-memory PGlite version:
 
 ```typescript
 // vitest.setup.ts
+import { PGlite } from '@electric-sql/pglite';
 import { createPgliteAdapter } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 
-const { adapter, resetDb } = await createPgliteAdapter();
+const pglite = new PGlite();
+const { adapter, resetDb } = await createPgliteAdapter({
+  pglite,
+  migrationsPath: './prisma/migrations',
+});
 export const testPrisma = new PrismaClient({ adapter });
 
 vi.mock('./lib/prisma', () => ({ prisma: testPrisma }));
@@ -172,6 +218,7 @@ the top level, not inside `beforeAll`:
 
 ```typescript
 // jest.setup.ts
+const { PGlite } = require('@electric-sql/pglite');
 const { createPgliteAdapter } = require('prisma-pglite-bridge');
 const { PrismaClient } = require('@prisma/client');
 
@@ -183,7 +230,11 @@ jest.mock('./lib/prisma', () => ({
 }));
 
 beforeAll(async () => {
-  const result = await createPgliteAdapter();
+  const pglite = new PGlite();
+  const result = await createPgliteAdapter({
+    pglite,
+    migrationsPath: './prisma/migrations',
+  });
   testPrisma = new PrismaClient({ adapter: result.adapter });
   resetDb = result.resetDb;
 });
@@ -196,6 +247,7 @@ beforeEach(() => resetDb());
 If your code accepts `PrismaClient` as a parameter:
 
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
 import { createPgliteAdapter, type ResetDbFn } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 import { beforeAll, beforeEach, it, expect } from 'vitest';
@@ -204,7 +256,11 @@ let prisma: PrismaClient;
 let resetDb: ResetDbFn;
 
 beforeAll(async () => {
-  const result = await createPgliteAdapter();
+  const pglite = new PGlite();
+  const result = await createPgliteAdapter({
+    pglite,
+    migrationsPath: './prisma/migrations',
+  });
   prisma = new PrismaClient({ adapter: result.adapter });
   resetDb = result.resetDb;
 });
@@ -243,6 +299,7 @@ if (import.meta.url === new URL(process.argv[1]!, 'file:').href) {
 Then reuse it in tests:
 
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
 import { createPgliteAdapter, type ResetDbFn } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 import { seed } from '../prisma/seed';
@@ -251,7 +308,11 @@ let prisma: PrismaClient;
 let resetDb: ResetDbFn;
 
 beforeAll(async () => {
-  const result = await createPgliteAdapter();
+  const pglite = new PGlite();
+  const result = await createPgliteAdapter({
+    pglite,
+    migrationsPath: './prisma/migrations',
+  });
   prisma = new PrismaClient({ adapter: result.adapter });
   resetDb = result.resetDb;
   await seed(prisma);
@@ -270,12 +331,15 @@ If your schema uses `uuid-ossp`, `pgcrypto`, or other extensions,
 pass them via the `extensions` option:
 
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
 import { createPgliteAdapter } from 'prisma-pglite-bridge';
 import { uuid_ossp } from '@electric-sql/pglite/contrib/uuid_ossp';
 import { pgcrypto } from '@electric-sql/pglite/contrib/pgcrypto';
 
+const pglite = new PGlite({ extensions: { uuid_ossp, pgcrypto } });
 const { adapter } = await createPgliteAdapter({
-  extensions: { uuid_ossp, pgcrypto },
+  pglite,
+  migrationsPath: './prisma/migrations',
 });
 ```
 
@@ -285,8 +349,18 @@ for the full list.
 
 ### Pre-generated SQL (fastest)
 
+The `sql` option runs verbatim with no sandbox or checksum. Compose
+it from trusted, version-controlled source only — never from
+environment variables, network input, or values that cross a trust
+boundary. See [Schema Resolution](#schema-resolution) for the
+full source-of-trust guidance.
+
 ```typescript
+import { PGlite } from '@electric-sql/pglite';
+
+const pglite = new PGlite();
 const { adapter } = await createPgliteAdapter({
+  pglite,
   sql: `
     CREATE TABLE "User" (id text PRIMARY KEY, name text NOT NULL);
     CREATE TABLE "Post" (
@@ -300,30 +374,43 @@ const { adapter } = await createPgliteAdapter({
 
 ### Persistent dev database (optional)
 
-By default, prisma-pglite-bridge runs entirely in memory — the database
+By default, PGlite runs entirely in memory — the database
 disappears when the process exits. This is ideal for tests. If you
 want data to survive restarts (local development, prototyping),
-pass a `dataDir`:
+pass a `dataDir` when constructing PGlite, and only apply
+migrations on first run:
 
 ```typescript
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PGlite } from '@electric-sql/pglite';
+
+const dataDir = './data/pglite';
+const firstRun = !existsSync(join(dataDir, 'PG_VERSION'));
+
+const pglite = new PGlite(dataDir);
 const { adapter, close } = await createPgliteAdapter({
-  dataDir: './data/pglite',
+  pglite,
+  ...(firstRun ? { migrationsPath: './prisma/migrations' } : {}),
 });
 const prisma = new PrismaClient({ adapter });
-
-// Data persists across restarts. Schema is only applied on first run
-// (PGlite detects an existing PGDATA directory). Delete the data
-// directory after schema changes to pick up new migrations.
 ```
 
-**Add `data/pglite/` to `.gitignore`.** This gives you a local
-PostgreSQL without Docker — useful for offline development or
-environments where installing PostgreSQL is impractical.
+**Add `data/pglite/` to `.gitignore`.** Delete the data directory
+after schema changes to pick up new migrations. This gives you a
+local PostgreSQL without Docker — useful for offline development
+or environments where installing PostgreSQL is impractical.
 
 ### Long-running script with clean shutdown
 
 ```typescript
-const { adapter, close } = await createPgliteAdapter();
+import { PGlite } from '@electric-sql/pglite';
+
+const pglite = new PGlite();
+const { adapter, close } = await createPgliteAdapter({
+  pglite,
+  migrationsPath: './prisma/migrations',
+});
 const prisma = new PrismaClient({ adapter });
 
 try {
@@ -331,9 +418,141 @@ try {
 } finally {
   await prisma.$disconnect();
   await close();
+  await pglite.close();
 }
 ```
 
+## Stats collection
+
+For most developers, this is the easiest way to see how the bridge
+performed in tests.
+
+Enable `statsLevel` when creating the adapter, run your tests, then
+call `await stats()` at the end. You get one snapshot with the main
+things you usually care about: query counts, timing percentiles,
+database size, and, at `'full'`, process RSS and session-lock wait
+times.
+
+This is the built-in, low-friction path for test diagnostics. It is
+useful for CI cost insight, perf tuning, and understanding test-suite
+behavior without wiring up a separate metrics pipeline. **Off by
+default**; the hot path stays effectively zero-cost as long as no
+external consumer subscribes to the public
+[diagnostics channels](#diagnostics-channels).
+
+```typescript
+import { PGlite } from '@electric-sql/pglite';
+
+const pglite = new PGlite();
+const { adapter, stats, close } = await createPgliteAdapter({
+  pglite,
+  migrationsPath: './prisma/migrations',
+  statsLevel: 'basic', // or 'full'
+});
+const prisma = new PrismaClient({ adapter });
+
+afterAll(async () => {
+  await prisma.$disconnect();
+  await close();
+  const s = await stats();
+  if (s) console.log(s);
+  await pglite.close();
+});
+```
+
+`stats()` returns `Promise<Stats | undefined>` — `undefined` when
+`statsLevel` is `'off'` (or omitted). Safe to call before or after
+`close()`; post-close reads return frozen values from the moment
+`close()` was invoked.
+
+If you need live per-query or per-lock-wait events instead of a final
+snapshot, use the public [diagnostics channels](#diagnostics-channels)
+described below. That path is more flexible, but also more advanced.
+
+### Levels
+
+**`'basic'`** — timing and counters:
+
+- `durationMs` — adapter lifetime (frozen at `close()`, drain
+  excluded)
+- `schemaSetupMs` — one-time cost of applying migration SQL
+- `queryCount`, `failedQueryCount` — WASM round-trips (a Prisma
+  extended-query pipeline is one round-trip, not five). Lifetime
+  counters.
+- `totalQueryMs`, `avgQueryMs` — lifetime sum and mean of query
+  durations
+- `recentP50QueryMs`, `recentP95QueryMs`, `recentMaxQueryMs` —
+  nearest-rank percentiles (no interpolation) over the most recent
+  ~10,000 queries. On long-lived adapters these describe a different
+  population than `avgQueryMs`.
+- `resetDbCalls` — counts `resetDb()` attempts
+- `dbSizeBytes` — `pg_database_size(current_database())`, cached
+  at close
+
+**`'full'`** — adds:
+
+- `processRssPeakBytes` — process-wide RSS peak, read from
+  `process.resourceUsage().maxRSS` (kernel-tracked, lossless) at
+  the moment `stats()` is called. Contaminated if unrelated work
+  shares the process — use as an ordering signal, not an absolute
+  measurement. `undefined` on runtimes without
+  `process.resourceUsage` (Bun, Deno, edge workers).
+- `totalSessionLockWaitMs`, `sessionLockAcquisitionCount`,
+  `avgSessionLockWaitMs`, `maxSessionLockWaitMs` — session-lock
+  contention across pool connections
+
+`statsLevel` is echoed on the returned object. Any field typed
+`T | undefined` in the returned `Stats` is the exhaustive list of
+fields that can be missing — `dbSizeBytes` if `pg_database_size`
+rejects, `processRssPeakBytes` on runtimes without
+`process.resourceUsage`. Every other field is always defined.
+
+## Diagnostics channels
+
+The bridge publishes per-query and per-lock-wait events to
+[`node:diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)
+channels. Built-in adapter stats are updated directly by the bridge
+when `statsLevel` is `'basic'` or `'full'`; external consumers (OpenTelemetry, APM,
+custom loggers) can subscribe directly without touching the bridge
+API.
+
+Publication is gated by `channel.hasSubscribers`, so when nobody
+is listening the hot path pays no timing or payload cost.
+Subscribing opts you in to that work.
+
+```typescript
+import diagnostics_channel from 'node:diagnostics_channel';
+import {
+  createPgliteAdapter,
+  QUERY_CHANNEL,
+  type QueryEvent,
+} from 'prisma-pglite-bridge';
+
+const { adapterId } = await createPgliteAdapter({ /* ... */ });
+
+const listener = (msg: unknown) => {
+  const e = msg as QueryEvent;
+  if (e.adapterId !== adapterId) return;
+  myMetrics.record('db.query', e.durationMs, { ok: e.succeeded });
+};
+diagnostics_channel.channel(QUERY_CHANNEL).subscribe(listener);
+```
+
+Channels:
+
+- `QUERY_CHANNEL` (`prisma-pglite-bridge:query`) — every
+  whole-query boundary. Payload: `{ adapterId: symbol; durationMs:
+  number; succeeded: boolean }`. `succeeded` is `false` for both
+  thrown errors and protocol-level `ErrorResponse` frames.
+- `LOCK_WAIT_CHANNEL` (`prisma-pglite-bridge:lock-wait`) — every
+  session-lock acquisition. Payload: `{ adapterId: symbol;
+  durationMs: number }`. `durationMs` is how long the acquirer
+  waited before the lock was granted.
+
+Filter on `adapterId` to isolate events when multiple adapters
+share a process. Obtain it from the `createPgliteAdapter()` or
+`createPool()` return value.
+
 ## Limitations
 
 - **Node.js 20+ only** — requires `node:stream` and `node:fs`.
@@ -344,12 +563,42 @@ try {
 - **Single PostgreSQL session** — PGlite runs in single-user mode.
   All pool connections share one session. A `SessionLock` serializes
   transactions (one at a time), but `SET` variables leak between
-  connections within a single test. `resetDb()` clears this between
-  tests via `RESET ALL` and `DEALLOCATE ALL`.
+  connections within a single test. `resetDb()` clears more of this
+  between tests via `DISCARD ALL`.
 - **Migration files required** — run `prisma migrate dev` once to
   generate migration files, or pass schema SQL directly via the
   `sql` option.
 
+## Troubleshooting
+
+### `this.pglite.execProtocolRawStream is not a function`
+
+The bridge uses PGlite 0.4's streaming protocol API. Some packages
+in the Prisma ecosystem (e.g. `@prisma/dev`) still pin
+`@electric-sql/pglite` to 0.3.x, which pnpm will install alongside
+0.4 — and the bridge can end up with the older copy.
+
+Check your tree:
+
+```sh
+pnpm why @electric-sql/pglite
+```
+
+If you see more than one version, force a single 0.4.x via
+`pnpm.overrides` in your project's `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "@electric-sql/pglite": "^0.4.4"
+    }
+  }
+}
+```
+
+Then `pnpm install`.
+
 ## License
 
 MIT