prisma-pglite-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+# prisma-pglite-bridge
+
+In-process PGlite bridge for Prisma. Replaces the TCP socket in
+`pg.Client` with a Duplex stream that speaks PostgreSQL wire protocol
+directly to PGlite's WASM engine.
+
+## Install
+
+Requires **Prisma 7+** and **Node.js 20+**.
+
+```sh
+pnpm add -D prisma-pglite-bridge @electric-sql/pglite @prisma/adapter-pg pg
+```
+
+TypeScript users also need `@types/pg`.
+
+## Quickstart
+
+```typescript
+import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { PrismaClient } from '@prisma/client';
+
+const { adapter, resetDb } = await createPgliteAdapter();
+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. 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:
+
+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.
+
+## API
+
+### `createPgliteAdapter(options?)`
+
+Creates a Prisma adapter backed by an in-process PGlite instance.
+
+```typescript
+const { adapter, pglite, resetDb, close } = await createPgliteAdapter({
+  // All optional — migrations auto-discovered from prisma.config.ts
+  migrationsPath: './prisma/migrations',
+  sql: 'CREATE TABLE ...',
+  configRoot: '../..',        // monorepo: where to find prisma.config.ts
+  dataDir: './data/pglite',   // omit for in-memory
+  extensions: {},             // PGlite extensions
+  max: 5,                     // pool connections (default: 5)
+});
+```
+
+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?)`
+
+Lower-level escape hatch. Creates a `pg.Pool` backed by PGlite
+without Prisma wiring.
+
+```typescript
+import { createPool } from 'prisma-pglite-bridge';
+import { PrismaPg } from '@prisma/adapter-pg';
+
+const { pool, pglite, close } = await createPool();
+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).
+
+### `PGliteBridge`
+
+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
+transaction interleaving.
+
+```typescript
+import { PGliteBridge } from 'prisma-pglite-bridge';
+import { PGlite } from '@electric-sql/pglite';
+import pg from 'pg';
+
+const pglite = new PGlite();
+await pglite.waitReady;
+const client = new pg.Client({
+  stream: () => new PGliteBridge(pglite),
+});
+```
+
+## Examples
+
+### Replacing your production database in tests
+
+Most Prisma projects use a singleton module:
+
+```typescript
+// lib/prisma.ts — your production singleton
+import { PrismaPg } from '@prisma/adapter-pg';
+import { PrismaClient } from '@prisma/client';
+import pg from 'pg';
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const adapter = new PrismaPg(pool);
+export const prisma = new PrismaClient({ adapter });
+```
+
+In tests, swap the singleton via `vi.mock` so every import gets
+the in-memory PGlite version:
+
+```typescript
+// vitest.setup.ts
+import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { PrismaClient } from '@prisma/client';
+
+const { adapter, resetDb } = await createPgliteAdapter();
+export const testPrisma = new PrismaClient({ adapter });
+
+vi.mock('./lib/prisma', () => ({ prisma: testPrisma }));
+
+beforeEach(() => resetDb());
+```
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    setupFiles: ['./vitest.setup.ts'],
+  },
+});
+```
+
+Now every test file that imports `prisma` from `lib/prisma`
+gets the PGlite-backed instance. No Docker, no test database,
+no cleanup scripts.
+
+For Jest, the same pattern works with `jest.mock`:
+
+```typescript
+// jest.setup.ts
+const { createPgliteAdapter } = require('prisma-pglite-bridge');
+const { PrismaClient } = require('@prisma/client');
+
+let testPrisma;
+let resetDb;
+
+// jest.mock is hoisted — must be at top level, not inside beforeAll
+jest.mock('./lib/prisma', () => ({
+  get prisma() { return testPrisma; },
+}));
+
+beforeAll(async () => {
+  const result = await createPgliteAdapter();
+  testPrisma = new PrismaClient({ adapter: result.adapter });
+  resetDb = result.resetDb;
+});
+
+beforeEach(() => resetDb());
+```
+
+### Vitest with per-test isolation (no singleton)
+
+If your code accepts `PrismaClient` as a parameter:
+
+```typescript
+import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { PrismaClient } from '@prisma/client';
+import { beforeAll, beforeEach, it, expect } from 'vitest';
+
+let prisma: PrismaClient;
+let resetDb: () => Promise<void>;
+
+beforeAll(async () => {
+  const { adapter, resetDb: reset } = await createPgliteAdapter();
+  prisma = new PrismaClient({ adapter });
+  resetDb = reset;
+});
+
+beforeEach(() => resetDb());
+
+it('creates a user', async () => {
+  const user = await prisma.user.create({
+    data: { name: 'Test' },
+  });
+  expect(user.id).toBeDefined();
+});
+```
+
+### Sharing seed logic between `prisma db seed` and tests
+
+Extract your seed logic into a function that accepts a
+PrismaClient:
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient } from '@prisma/client';
+
+export const seed = async (prisma: PrismaClient) => {
+  await prisma.user.create({ data: { name: 'Alice', role: 'ADMIN' } });
+  await prisma.user.create({ data: { name: 'Bob', role: 'MEMBER' } });
+};
+
+// Still works as a script for `prisma db seed`
+const prisma = new PrismaClient();
+seed(prisma).then(() => prisma.$disconnect());
+```
+
+Then reuse it in tests:
+
+```typescript
+import { createPgliteAdapter } from 'prisma-pglite-bridge';
+import { PrismaClient } from '@prisma/client';
+import { seed } from '../prisma/seed';
+
+let prisma: PrismaClient;
+let resetDb: () => Promise<void>;
+
+beforeAll(async () => {
+  const { adapter, resetDb: reset } = await createPgliteAdapter();
+  prisma = new PrismaClient({ adapter });
+  resetDb = reset;
+  await seed(prisma);
+});
+
+// resetDb() clears all data — re-seed if needed
+beforeEach(async () => {
+  await resetDb();
+  await seed(prisma);
+});
+```
+
+### Using PostgreSQL extensions
+
+If your schema uses `uuid-ossp`, `pgcrypto`, or other extensions,
+pass them via the `extensions` option:
+
+```typescript
+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 { adapter } = await createPgliteAdapter({
+  extensions: { uuid_ossp, pgcrypto },
+});
+```
+
+See [PGlite extensions](https://pglite.dev/extensions/) for the
+full list of available extensions.
+
+### Pre-generated SQL (fastest)
+
+```typescript
+const { adapter } = await createPgliteAdapter({
+  sql: `
+    CREATE TABLE "User" (id text PRIMARY KEY, name text NOT NULL);
+    CREATE TABLE "Post" (
+      id text PRIMARY KEY,
+      title text NOT NULL,
+      "userId" text REFERENCES "User"(id)
+    );
+  `,
+});
+```
+
+### Persistent dev database (optional)
+
+By default, prisma-pglite-bridge 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`:
+
+```typescript
+const { adapter, close } = await createPgliteAdapter({
+  dataDir: './data/pglite',
+});
+const prisma = new PrismaClient({ adapter });
+
+// Data persists across restarts. Schema is only applied
+// on first run (PGlite detects an existing PGDATA directory).
+```
+
+Add `data/pglite/` to `.gitignore`. 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();
+const prisma = new PrismaClient({ adapter });
+
+try {
+  await seedDatabase(prisma);
+} finally {
+  await prisma.$disconnect();
+  await close();
+}
+```
+
+## 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
+  ~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 this between
+  tests via `RESET ALL` and `DEALLOCATE ALL`.
+- **Migration files required** — run `prisma migrate dev` once to
+  generate migration files, or pass schema SQL directly via the
+  `sql` option.
+
+## License
+
+MIT