prisma-pglite-bridge 0.5.2 → 0.6.0

package/README.md

@@ -19,17 +19,16 @@ TypeScript users also need `@types/pg`.
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
-import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 
 const pglite = new PGlite();
-const { adapter, resetDb } = await createPgliteAdapter({
-  pglite,
-  migrationsPath: './prisma/migrations',
-});
-const prisma = new PrismaClient({ adapter });
+const bridge = await createPGliteBridge({ pglite });
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
 
-beforeEach(() => resetDb());
+const prisma = new PrismaClient({ adapter: bridge.adapter });
+
+beforeEach(() => bridge.resetDb());
 ```
 
 Call `resetDb()` in `beforeEach` to wipe all data between tests.
@@ -40,34 +39,31 @@ 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
+## Populating the database
 
-When you pass any of `sql`, `migrationsPath`, or `configRoot`,
-`createPgliteAdapter` applies schema SQL. Resolution order:
+`createPGliteBridge` returns an empty database. The bridge offers
+two helpers to populate it — pick the one that matches your
+project layout:
 
-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`),
-   triggered by passing `configRoot`. Requires `prisma` to be
-   installed (which provides `@prisma/config` as a transitive
-   dependency).
+| Helper | When to use | Cost |
+| --- | --- | --- |
+| [`pushMigrations`](#pushmigrationstarget-options) | You already run `prisma migrate dev` and have a `prisma/migrations` directory | No WASM schema engine; no Node `ExperimentalWarning` |
+| [`pushSchema`](#pushschematarget-options) | You only have `schema.prisma` (test fixtures, prototypes) and want it applied via `prisma db push` semantics | Loads `@prisma/schema-engine-wasm` once per process |
 
-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`).
+Both accept the same `PGliteBridge` returned by
+`createPGliteBridge`, so you can swap helpers without touching the
+bridge wiring. If you reopen a persistent `dataDir` that already
+holds the schema, call neither.
 
-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.
+Schema SQL is executed verbatim with no checksum or signature
+verification. Compose it from trusted, version-controlled source
+only — never from environment variables, network input, or any
+value that crosses a trust boundary, and keep the migrations
+directory writable only by trusted processes.
 
 ## Bridge fs-sync policy
 
-The adapter defaults `syncToFs` to `'auto'`:
+The bridge defaults `syncToFs` to `'auto'`:
 
 - in-memory PGlite (`new PGlite()` or `memory://...`) resolves to `false`
 - persistent `dataDir` usage resolves to `true`
@@ -75,31 +71,36 @@ The adapter defaults `syncToFs` to `'auto'`:
 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.
+bridge cannot infer whether that storage is durable.
 
 ## API
 
-### `createPgliteAdapter(options)`
+### `createPGliteBridge(options)`
 
-Creates a Prisma adapter backed by a caller-supplied PGlite
-instance.
+Creates a `PGliteBridge` — a bundle holding a Prisma driver adapter,
+the underlying PGlite instance, and lifecycle helpers — backed by a
+caller-supplied PGlite instance.
 
 ```typescript
 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
-  max: 1,                     // pool connections (default: 1, see "Pool sizing" below)
+const bridge = await createPGliteBridge({
+  pglite,                     // required — caller owns lifecycle
+  max: 1,                     // pool connections (default: 1)
   statsLevel: 'off',          // 'off' | 'basic' | 'full' (default: 'off')
+  syncToFs: 'auto',           // 'auto' | true | false (default: 'auto')
 });
 ```
 
-Returns:
+To apply schema SQL, call [`pushMigrations`](#pushmigrationstarget-options)
+or [`pushSchema`](#pushschematarget-options) on the returned
+bridge — see [Populating the database](#populating-the-database).
+
+Returns a `PGliteBridge`:
 
 - `adapter` — pass to `new PrismaClient({ adapter })`
+- `pglite` — the caller-supplied PGlite instance, re-exposed for
+  symmetry with `pushSchema` / `pushMigrations`
 - `resetDb()` — truncates all user tables and discards
   session-local state via `DISCARD ALL` (for example `SET`
   variables, prepared statements, temp tables, and `LISTEN`
@@ -107,15 +108,105 @@ Returns:
   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.
+  instance is not closed — you own its lifecycle. Recommended in
+  explicit test teardown, long-running scripts, and dev servers so
+  the pool is released promptly and leak warnings do not fire.
 - `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
+- `bridgeId` — a unique `symbol` identifying this bridge. Use it
   to filter events from the public
   [diagnostics channels](#diagnostics-channels) when multiple
-  adapters share a process.
+  bridges share a process.
+- `snapshotDb()` — captures the current DB contents into an internal
+  snapshot so later `resetDb()` calls restore to that state instead of
+  truncating to empty.
+- `resetSnapshot()` — discards the current snapshot so later
+  `resetDb()` calls truncate back to empty again.
+
+### `pushMigrations(target, options)`
+
+Applies SQL migrations to a `PGliteBridge`. Use this for projects
+that already have a `prisma/migrations` directory generated by
+`prisma migrate dev`. Does not load `@prisma/schema-engine-wasm`.
+
+```typescript
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
+
+const bridge = await createPGliteBridge({ pglite });
+
+// inline SQL
+await pushMigrations(bridge, { sql: 'CREATE TABLE ...' });
+
+// from a migrations directory
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+
+// auto-discovered via prisma.config.ts (monorepo: pass configRoot)
+await pushMigrations(bridge, { configRoot: process.cwd() });
+```
+
+Resolution order — first match wins:
+
+1. **`sql` option** — pre-generated SQL string, applied directly
+2. **`migrationsPath` option** — concatenates every
+   `migration.sql` found one directory level below, in
+   directory-name order
+3. **Auto-discovered migrations** — uses `@prisma/config` to find
+   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).
+
+Returns `{ durationMs }` — the wall-clock time PGlite spent applying
+the SQL, useful when you want to log schema-setup cost.
+
+### `pushSchema(target, options)`
+
+Applies a Prisma schema to the database via
+`@prisma/schema-engine-wasm`, in-process. No native schema-engine
+binary, no TCP, no Docker. `prisma generate` still goes through the
+regular CLI; only schema apply / reset is bridged.
+
+Use this for projects without a migrations directory — typical of
+test fixtures or quick prototypes — or when you want `prisma db
+push` semantics (diff `schema.prisma` against the live DB).
+
+```typescript
+import { readFile } from 'node:fs/promises';
+import { PGlite } from '@electric-sql/pglite';
+import { createPGliteBridge, pushSchema } from 'prisma-pglite-bridge';
+
+const pglite = new PGlite();
+const bridge = await createPGliteBridge({ pglite });
+
+await pushSchema(bridge, {
+  schema: await readFile('prisma/schema.prisma', 'utf8'),
+  // acceptDataLoss: true,  // apply destructive changes flagged as warnings
+  // forceReset: true,      // drop every non-system schema before applying
+});
+```
+
+Returns `{ executedSteps, warnings, unexecutable }`.
+`acceptDataLoss: true` lets the engine apply destructive changes
+that would otherwise be reported as warnings; `unexecutable` steps
+are independent — the engine refuses them either way and the
+caller must reshape the schema. `forceReset: true` drops every
+non-system schema before applying.
+
+The first call in a Node process emits an
+[`ExperimentalWarning`](#experimentalwarning-importing-webassembly-module-instances-is-an-experimental-feature)
+about WebAssembly imports.
+
+### `resetSchema(target)`
+
+Drops every non-system schema and recreates `public`. Useful as a
+between-suite reset when you want a clean slate without re-running
+all migrations.
+
+```typescript
+import { resetSchema } from 'prisma-pglite-bridge';
+
+await resetSchema(bridge);
+```
 
 ### `createPool(options)`
 
@@ -133,22 +224,22 @@ const { pool, close } = await createPool({ pglite });
 const adapter = new PrismaPg(pool);
 ```
 
-Returns `pool` (pg.Pool), `adapterId` (a unique `symbol` for
+Returns `pool` (pg.Pool), `bridgeId` (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`.
+`max`, `bridgeId`, and `syncToFs`.
 
-### `PGliteBridge`
+### `PGliteDuplex`
 
 The Duplex stream that replaces `pg.Client`'s network socket.
 Exported for advanced use cases (custom `pg.Client` setup, direct
-wire protocol access). When using multiple bridges against the
-same PGlite instance, pass a shared `SessionLock` to prevent
+wire protocol access). When using multiple duplex streams against
+the same PGlite instance, pass a shared `SessionLock` to prevent
 transaction interleaving.
 
 ```typescript
-import { PGliteBridge, SessionLock } from 'prisma-pglite-bridge';
+import { PGliteDuplex, SessionLock } from 'prisma-pglite-bridge';
 import { PGlite } from '@electric-sql/pglite';
 import pg from 'pg';
 
@@ -157,10 +248,51 @@ await pglite.waitReady;
 
 const lock = new SessionLock();
 const client = new pg.Client({
-  stream: () => new PGliteBridge(pglite, lock),
+  stream: () => new PGliteDuplex(pglite, lock),
 });
 ```
 
+### `SessionLock`
+
+An async mutex that serializes PGlite access across multiple
+duplex streams sharing one PGlite instance. `createPGliteBridge`
+and `createPool` install one automatically; export it for custom
+multi-duplex setups built on top of `PGliteDuplex`.
+
+### Diagnostics channel exports
+
+`QUERY_CHANNEL`, `LOCK_WAIT_CHANNEL`, and the matching
+`QueryEvent` / `LockWaitEvent` types are exported for subscribing
+to live per-query and per-lock-wait events. See
+[Diagnostics channels](#diagnostics-channels) for the wiring.
+
+## CLI (`ppb`)
+
+The `ppb` CLI exposes [`pushSchema`](#pushschematarget-options) and
+[`resetSchema`](#resetschematarget) as standalone commands so you
+can apply a Prisma schema to a PGlite database without writing
+glue code.
+
+```sh
+pnpm exec ppb db-push   [--schema <path>]            # default: prisma/schema.prisma
+                        [--force-reset]
+                        [--accept-data-loss]
+                        [--data-dir <path>]          # overrides DATABASE_URL
+pnpm exec ppb db-reset  [--data-dir <path>]
+```
+
+`DATABASE_URL` is read from env / `.env` and parsed as a `pglite://`
+URL — `pglite://memory` for in-memory, `pglite:///abs/path` or
+`pglite://./rel/path` for filesystem-backed PGlite. `--data-dir`
+overrides it.
+
+Exit codes:
+
+- **0** — success.
+- **1** — engine reported `unexecutable` steps, or `warnings` were
+  reported and `--accept-data-loss` was not supplied, or the
+  schema failed to parse / push.
+
 ## Examples
 
 ### Replacing your production database in tests
@@ -184,19 +316,18 @@ the in-memory PGlite version:
 ```typescript
 // vitest.setup.ts
 import { PGlite } from '@electric-sql/pglite';
-import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
+import { beforeEach, vi } from 'vitest';
 
 const pglite = new PGlite();
-const { adapter, resetDb } = await createPgliteAdapter({
-  pglite,
-  migrationsPath: './prisma/migrations',
-});
-export const testPrisma = new PrismaClient({ adapter });
+const bridge = await createPGliteBridge({ pglite });
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+export const testPrisma = new PrismaClient({ adapter: bridge.adapter });
 
 vi.mock('./lib/prisma', () => ({ prisma: testPrisma }));
 
-beforeEach(() => resetDb());
+beforeEach(() => bridge.resetDb());
 ```
 
 ```typescript
@@ -219,7 +350,7 @@ the top level, not inside `beforeAll`:
 ```typescript
 // jest.setup.ts
 const { PGlite } = require('@electric-sql/pglite');
-const { createPgliteAdapter } = require('prisma-pglite-bridge');
+const { createPGliteBridge, pushMigrations } = require('prisma-pglite-bridge');
 const { PrismaClient } = require('@prisma/client');
 
 let testPrisma;
@@ -231,12 +362,10 @@ jest.mock('./lib/prisma', () => ({
 
 beforeAll(async () => {
   const pglite = new PGlite();
-  const result = await createPgliteAdapter({
-    pglite,
-    migrationsPath: './prisma/migrations',
-  });
-  testPrisma = new PrismaClient({ adapter: result.adapter });
-  resetDb = result.resetDb;
+  const bridge = await createPGliteBridge({ pglite });
+  await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+  testPrisma = new PrismaClient({ adapter: bridge.adapter });
+  resetDb = bridge.resetDb;
 });
 
 beforeEach(() => resetDb());
@@ -248,7 +377,7 @@ If your code accepts `PrismaClient` as a parameter:
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
-import { createPgliteAdapter, type ResetDbFn } from 'prisma-pglite-bridge';
+import { createPGliteBridge, pushMigrations, type ResetDbFn } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 import { beforeAll, beforeEach, it, expect } from 'vitest';
 
@@ -257,12 +386,10 @@ let resetDb: ResetDbFn;
 
 beforeAll(async () => {
   const pglite = new PGlite();
-  const result = await createPgliteAdapter({
-    pglite,
-    migrationsPath: './prisma/migrations',
-  });
-  prisma = new PrismaClient({ adapter: result.adapter });
-  resetDb = result.resetDb;
+  const bridge = await createPGliteBridge({ pglite });
+  await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+  prisma = new PrismaClient({ adapter: bridge.adapter });
+  resetDb = bridge.resetDb;
 });
 
 beforeEach(() => resetDb());
@@ -300,7 +427,7 @@ Then reuse it in tests:
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
-import { createPgliteAdapter, type ResetDbFn } from 'prisma-pglite-bridge';
+import { createPGliteBridge, pushMigrations, type ResetDbFn } from 'prisma-pglite-bridge';
 import { PrismaClient } from '@prisma/client';
 import { seed } from '../prisma/seed';
 
@@ -309,12 +436,10 @@ let resetDb: ResetDbFn;
 
 beforeAll(async () => {
   const pglite = new PGlite();
-  const result = await createPgliteAdapter({
-    pglite,
-    migrationsPath: './prisma/migrations',
-  });
-  prisma = new PrismaClient({ adapter: result.adapter });
-  resetDb = result.resetDb;
+  const bridge = await createPGliteBridge({ pglite });
+  await pushMigrations(result, { migrationsPath: './prisma/migrations' });
+  prisma = new PrismaClient({ adapter: bridge.adapter });
+  resetDb = bridge.resetDb;
   await seed(prisma);
 });
 
@@ -325,6 +450,23 @@ beforeEach(async () => {
 });
 ```
 
+### Applying a schema directly (no migrations directory)
+
+For test fixtures or prototypes without `prisma/migrations`, swap
+`pushMigrations` for `pushSchema`:
+
+```typescript
+import { readFile } from 'node:fs/promises';
+import { PGlite } from '@electric-sql/pglite';
+import { createPGliteBridge, pushSchema } from 'prisma-pglite-bridge';
+
+const pglite = new PGlite();
+const bridge = await createPGliteBridge({ pglite });
+await pushSchema(bridge, {
+  schema: await readFile('prisma/schema.prisma', 'utf8'),
+});
+```
+
 ### Using PostgreSQL extensions
 
 If your schema uses `uuid-ossp`, `pgcrypto`, or other extensions,
@@ -332,15 +474,13 @@ pass them via the `extensions` option:
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
-import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { createPGliteBridge, pushMigrations } 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({
-  pglite,
-  migrationsPath: './prisma/migrations',
-});
+const bridge = await createPGliteBridge({ pglite });
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
 ```
 
 Extensions are included in the `@electric-sql/pglite` package —
@@ -349,18 +489,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.
+The `sql` option on `pushMigrations` 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.
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
 
 const pglite = new PGlite();
-const { adapter } = await createPgliteAdapter({
-  pglite,
+const bridge = await createPGliteBridge({ pglite });
+await pushMigrations(bridge, {
   sql: `
     CREATE TABLE "User" (id text PRIMARY KEY, name text NOT NULL);
     CREATE TABLE "Post" (
@@ -389,11 +529,9 @@ const dataDir = './data/pglite';
 const firstRun = !existsSync(join(dataDir, 'PG_VERSION'));
 
 const pglite = new PGlite(dataDir);
-const { adapter, close } = await createPgliteAdapter({
-  pglite,
-  ...(firstRun ? { migrationsPath: './prisma/migrations' } : {}),
-});
-const prisma = new PrismaClient({ adapter });
+const bridge = await createPGliteBridge({ pglite });
+if (firstRun) await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+const prisma = new PrismaClient({ adapter: bridge.adapter });
 ```
 
 **Add `data/pglite/` to `.gitignore`.** Delete the data directory
@@ -405,19 +543,18 @@ or environments where installing PostgreSQL is impractical.
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
 
 const pglite = new PGlite();
-const { adapter, close } = await createPgliteAdapter({
-  pglite,
-  migrationsPath: './prisma/migrations',
-});
-const prisma = new PrismaClient({ adapter });
+const bridge = await createPGliteBridge({ pglite });
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+const prisma = new PrismaClient({ adapter: bridge.adapter });
 
 try {
   await seedDatabase(prisma);
 } finally {
   await prisma.$disconnect();
-  await close();
+  await bridge.close();
   await pglite.close();
 }
 ```
@@ -427,7 +564,7 @@ try {
 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
+Enable `statsLevel` when creating the bridge, 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
@@ -442,19 +579,20 @@ external consumer subscribes to the public
 
 ```typescript
 import { PGlite } from '@electric-sql/pglite';
+import { createPGliteBridge, pushMigrations } from 'prisma-pglite-bridge';
 
 const pglite = new PGlite();
-const { adapter, stats, close } = await createPgliteAdapter({
+const bridge = await createPGliteBridge({
   pglite,
-  migrationsPath: './prisma/migrations',
   statsLevel: 'basic', // or 'full'
 });
-const prisma = new PrismaClient({ adapter });
+await pushMigrations(bridge, { migrationsPath: './prisma/migrations' });
+const prisma = new PrismaClient({ adapter: bridge.adapter });
 
 afterAll(async () => {
   await prisma.$disconnect();
-  await close();
-  const s = await stats();
+  await bridge.close();
+  const s = await bridge.stats();
   if (s) console.log(s);
   await pglite.close();
 });
@@ -473,9 +611,8 @@ described below. That path is more flexible, but also more advanced.
 
 **`'basic'`** — timing and counters:
 
-- `durationMs` — adapter lifetime (frozen at `close()`, drain
+- `durationMs` — bridge 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.
@@ -483,7 +620,7 @@ described below. That path is more flexible, but also more advanced.
   durations
 - `recentP50QueryMs`, `recentP95QueryMs`, `recentMaxQueryMs` —
   nearest-rank percentiles (no interpolation) over the most recent
-  ~10,000 queries. On long-lived adapters these describe a different
+  ~10,000 queries. On long-lived bridges these describe a different
   population than `avgQueryMs`.
 - `resetDbCalls` — counts `resetDb()` attempts
 - `dbSizeBytes` — `pg_database_size(current_database())`, cached
@@ -511,7 +648,7 @@ rejects, `processRssPeakBytes` on runtimes without
 
 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
+channels. Built-in bridge 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.
@@ -523,16 +660,16 @@ Subscribing opts you in to that work.
 ```typescript
 import diagnostics_channel from 'node:diagnostics_channel';
 import {
-  createPgliteAdapter,
+  createPGliteBridge,
   QUERY_CHANNEL,
   type QueryEvent,
 } from 'prisma-pglite-bridge';
 
-const { adapterId } = await createPgliteAdapter({ /* ... */ });
+const { bridgeId } = await createPGliteBridge({ /* ... */ });
 
 const listener = (msg: unknown) => {
   const e = msg as QueryEvent;
-  if (e.adapterId !== adapterId) return;
+  if (e.bridgeId !== bridgeId) return;
   myMetrics.record('db.query', e.durationMs, { ok: e.succeeded });
 };
 diagnostics_channel.channel(QUERY_CHANNEL).subscribe(listener);
@@ -541,33 +678,37 @@ diagnostics_channel.channel(QUERY_CHANNEL).subscribe(listener);
 Channels:
 
 - `QUERY_CHANNEL` (`prisma-pglite-bridge:query`) — every
-  whole-query boundary. Payload: `{ adapterId: symbol; durationMs:
+  whole-query boundary. Payload: `{ bridgeId: 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;
+  session-lock acquisition. Payload: `{ bridgeId: 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
+Filter on `bridgeId` to isolate events when multiple bridges
+share a process. Obtain it from the `createPGliteBridge()` or
 `createPool()` return value.
 
 ## Limitations
 
 - **Node.js 20+ only** — requires `node:stream` and `node:fs`.
   Does not work in browsers despite PGlite's browser support.
-- **WASM cold start** — first `createPgliteAdapter()` call takes
+- **WASM cold start** — first `createPGliteBridge()` call takes
   ~2s for PGlite WASM compilation. Subsequent calls in the same
   process reuse the compiled module.
 - **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 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.
+  All pool connections share one session. With `max > 1`, a
+  `SessionLock` serializes transactions (one at a time), but `SET`
+  variables leak between connections within a single test. `resetDb()`
+  clears more of this between tests via `DISCARD ALL`. The default
+  `max: 1` avoids extra bridge connections and session-lock overhead.
+- **Schema source required** — pick one of
+  [`pushMigrations`](#pushmigrationstarget-options) (run
+  `prisma migrate dev` first or pass `sql` directly) or
+  [`pushSchema`](#pushschematarget-options) (apply
+  `schema.prisma` directly). `createPGliteBridge` alone returns
+  an empty database.
 
 ## Troubleshooting
 
@@ -599,6 +740,35 @@ If you see more than one version, force a single 0.4.x via
 
 Then `pnpm install`.
 
+### `ExperimentalWarning: Importing WebAssembly module instances is an experimental feature`
+
+Emitted by Node when `pushSchema` / `resetSchema` (or the `ppb` CLI)
+loads `@prisma/schema-engine-wasm`, which uses ESM static `.wasm`
+imports. The warning is harmless and prints once per Node process.
+
+If you only need to apply already-generated migration SQL, use
+[`pushMigrations`](#pushmigrationstarget-options) instead — it does
+not load the schema engine, so the warning never fires.
+
+To silence it in tests or CI, pass Node's `--disable-warning` flag:
+
+```sh
+NODE_OPTIONS=--disable-warning=ExperimentalWarning pnpm test
+```
+
+Or scope it to Vitest workers via `vitest.config.ts`:
+
+```ts
+export default defineConfig({
+  test: {
+    execArgv: ['--disable-warning=ExperimentalWarning'],
+  },
+});
+```
+
+Requires Node ≥ 22. The warning will go away once Node stabilizes
+WebAssembly ESM imports.
+
 ## License
 
 MIT