feat(pglite): client-factory seam + pglite-test drop-in getConnections

- pgsql-client: add registerPgClientFactory/defaultPgClientFactory seam
  (mirror of pg-cache pool seam); PgClient routes its underlying client
  through it. Default = new pg.Client, fully backward-compatible.
- pglite-adapter: extract shared query runner; add createPgliteClient so
  the same in-process session backs both pool and client seams.
- pglite-test: new drop-in getConnections backed by in-process PGlite
  (no server/createdb/psql). SharedTxn ref-counts transaction control so
  the standard two-client beforeEach/afterEach savepoint harness works
  over one PGlite session. Seeds via seed.pgpm(). 5 tests: deploy, per-test
  isolation, RLS role/JWT switching incl. WITH CHECK.
- CI: add postgres/pglite-test to the no-services unit-tests (pglite) batch.

Author: pyramation

.github/workflows/run-tests.yaml

@@ -95,7 +95,7 @@ jobs:
           - batch: graphql
             packages: 'graphql/query graphql/codegen'
           - batch: pglite
-            packages: 'postgres/pglite-adapter'
+            packages: 'postgres/pglite-adapter postgres/pglite-test'
 
     steps:
       - name: Download workspace

pnpm-lock.yaml

@@ -175,9 +175,11 @@ single-writer backend, but is not required for this rollout.
 
 1. **`pg-cache` driver seam + registry** (default = pg; zero behavior change). ✅ **DONE** — `registerPgPoolFactory` / `defaultPgPoolFactory`, 19 unit tests, CI green.
 2. **`@pgpmjs/pglite-adapter`** (in-process driver, all pglite deps here). ✅ **DONE** — `registerPglite()` registers a PGlite-backed `QueryablePool`; 6 tests deploy→verify→revert an unmodified pgpm plan into in-process PGlite (no socket), with `useTransaction: true`.
-3. **`pglite-test`** drop-in `getConnections` (instance-per-test). Needs a matching client-factory seam in `pgsql-client` + a PGlite-aware admin, because `pgsql-test` bypasses `pg-cache` (`new Pool`/`new Client` directly + `createdb`/`psql`).
-4. Convert this PoC's CI job to use the adapter instead of the socket shim.
+2b. **`pgsql-client` client-factory seam** (default = `new pg.Client`; zero behavior change). ✅ **DONE** — `registerPgClientFactory` / `defaultPgClientFactory` / `getActivePgClientFactory`, mirroring the `pg-cache` pool seam; `PgClient` routes its underlying client through it; 4 unit tests. Needed because `pgsql-test`/`pgsql-client` build `pg.Client`s directly rather than via `getPgPool`.
+3. **`pglite-test`** drop-in `getConnections` (instance-per-suite). ✅ **DONE** — composes `registerPglite()` (pool seam) + `registerPgClientFactory` (client seam) so `pg`/`db` share one in-process PGlite session; a `SharedTxn` ref-counter keeps the standard two-client `beforeEach`/`afterEach` savepoint harness working over a single session; seeds via `seed.pgpm()`; no `createdb`/`psql`. 5 tests cover deploy, per-test isolation, and RLS role/JWT switching (incl. `WITH CHECK`). No separate PGlite-aware `DbAdmin` subclass was needed — the instance *is* the database and extension/role bootstrap runs via `pglite.extensionSql`.
+4. This PoC's socket-shim CI job (`pglite-poc.yaml`) is **kept as-is** — it's a standalone, out-of-workspace demonstration of the `pg-gateway` wire-protocol path (own lockfile, published `@pgpmjs/core`). The canonical in-process path is now proven by the `@pgpmjs/pglite-adapter` and `pglite-test` jest suites in `run-tests.yaml` (no-services tier).
 5. (Optional) Core transaction-client fix — only if a *multi-connection* single-writer backend is ever targeted; the in-process adapter does not need it.
+6. (Future) `pgpm init --pglite` scaffolder — CLI-layer convenience; no PGlite dep in core.
 
 Each shipped step is independently testable; only step 1 touches core, and it adds
 no PGlite dependency to it. All `@electric-sql/pglite*` deps live in

poc/pglite/DESIGN.md

@@ -0,0 +1,33 @@
+import type { PGlite } from '@electric-sql/pglite';
+
+import { boundQuery, type PgResultLike } from './runner';
+
+/**
+ * The minimal node-`pg` `Client` surface that `pgsql-client`'s `PgClient` uses:
+ * `connect()`, `query()` and `end()`. A real `pg.Client` structurally satisfies
+ * it, so registering a factory that returns this is transparent to consumers.
+ */
+export interface QueryablePgClient {
+  connect(): Promise<void>;
+  query(text: any, values?: any[]): Promise<PgResultLike>;
+  end(): Promise<void>;
+}
+
+/**
+ * Build a `pg.Client`-shaped object backed by an existing PGlite instance.
+ *
+ * Every client returned for the same instance shares that single in-process
+ * session, so transaction control (`BEGIN`/`SAVEPOINT`/`ROLLBACK`/`COMMIT`) is
+ * shared too. `end()` is a no-op: the instance lifecycle is owned by whoever
+ * created it (see `registerPglite`), not by an individual client.
+ */
+export const createPgliteClient = (db: PGlite): QueryablePgClient => {
+  const query = boundQuery(db);
+  return {
+    connect: async () => {
+      await db.waitReady;
+    },
+    query,
+    end: async () => {}
+  };
+};

postgres/pglite-adapter/src/client.ts

@@ -3,7 +3,9 @@ import { getActivePgPoolFactory, registerPgPoolFactory } from 'pg-cache';
 
 import { createPglitePool } from './pool';
 
+export { createPgliteClient, type QueryablePgClient } from './client';
 export { createPglitePool } from './pool';
+export type { PgResultLike } from './runner';
 
 export interface PgliteAdapterOptions {
   /** Persist to a directory (default: in-memory). */

postgres/pglite-adapter/src/index.ts

@@ -1,47 +1,7 @@
 import type { PGlite } from '@electric-sql/pglite';
 import type { QueryableClient, QueryablePool } from 'pg-cache';
 
-/**
- * A node-`pg`-shaped result. pgpm only reads `rows` and (occasionally)
- * `rowCount`, so we normalize PGlite's `{ rows, affectedRows, fields }` onto
- * that shape.
- */
-interface PgResultLike {
-  rows: any[];
-  rowCount: number;
-  fields: any[];
-}
-
-const toResult = (r: any): PgResultLike => {
-  const rows = r?.rows ?? [];
-  const rowCount = typeof r?.affectedRows === 'number' ? r.affectedRows : rows.length;
-  return { rows, rowCount, fields: r?.fields ?? [] };
-};
-
-/**
- * Run a statement against the single in-process PGlite engine.
- *
- * PGlite mirrors node-`pg`'s two protocols:
- * - parameterized (`$1`, ...) -> `db.query` (extended protocol, single statement)
- * - no parameters -> `db.exec` (simple protocol, supports the multi-statement
- *   bootstrap SQL pgpm runs in `initialize()`), returning the last result.
- */
-const run = async (db: PGlite, text: string, values?: any[]): Promise<PgResultLike> => {
-  if (values && values.length > 0) {
-    return toResult(await db.query(text, values));
-  }
-  const results = await db.exec(text);
-  const last = Array.isArray(results) && results.length ? results[results.length - 1] : undefined;
-  return toResult(last);
-};
-
-/** Normalize the two call shapes pgpm/pg accept: `(text, values)` or `({ text, values })`. */
-const normalize = (first: any, second?: any[]): { text: string; values?: any[] } => {
-  if (first && typeof first === 'object' && 'text' in first) {
-    return { text: first.text, values: first.values };
-  }
-  return { text: first, values: second };
-};
+import { boundQuery } from './runner';
 
 /**
  * Build a `QueryablePool` backed by an existing PGlite instance.
@@ -55,27 +15,22 @@ const normalize = (first: any, second?: any[]): { text: string; values?: any[] }
  *
  * `end()` intentionally does NOT close the PGlite instance: the same instance
  * may back several cached pool wrappers (pg-cache keys by database name), and
- * its lifecycle is owned by whoever created it (see `createPglite`).
+ * its lifecycle is owned by whoever created it (see `registerPglite`).
  */
 export const createPglitePool = (db: PGlite): QueryablePool => {
   let ended = false;
+  const query = boundQuery(db);
 
   const client: QueryableClient = {
-    query: (text: any, values?: any[]) => {
-      const q = normalize(text, values);
-      return run(db, q.text, q.values);
-    },
+    query,
     release: () => {}
   };
 
   const pool = {
     get ended() {
       return ended;
     },
-    query: (text: any, values?: any[]) => {
-      const q = normalize(text, values);
-      return run(db, q.text, q.values);
-    },
+    query,
     connect: async () => client,
     end: async () => {
       ended = true;

postgres/pglite-adapter/src/pool.ts

@@ -0,0 +1,55 @@
+import type { PGlite } from '@electric-sql/pglite';
+
+/**
+ * A node-`pg`-shaped result. pgpm / pgsql-client read `rows` and (occasionally)
+ * `rowCount`, so we normalize PGlite's `{ rows, affectedRows, fields }` onto that
+ * shape.
+ */
+export interface PgResultLike {
+  rows: any[];
+  rowCount: number;
+  fields: any[];
+}
+
+const toResult = (r: any): PgResultLike => {
+  const rows = r?.rows ?? [];
+  const rowCount = typeof r?.affectedRows === 'number' ? r.affectedRows : rows.length;
+  return { rows, rowCount, fields: r?.fields ?? [] };
+};
+
+/**
+ * Run a statement against the single in-process PGlite engine.
+ *
+ * PGlite mirrors node-`pg`'s two protocols:
+ * - parameterized (`$1`, ...) -> `db.query` (extended protocol, single statement)
+ * - no parameters -> `db.exec` (simple protocol, supports the multi-statement
+ *   bootstrap SQL pgpm runs in `initialize()`), returning the last result.
+ */
+export const run = async (
+  db: PGlite,
+  text: string,
+  values?: any[]
+): Promise<PgResultLike> => {
+  if (values && values.length > 0) {
+    return toResult(await db.query(text, values));
+  }
+  const results = await db.exec(text);
+  const last = Array.isArray(results) && results.length ? results[results.length - 1] : undefined;
+  return toResult(last);
+};
+
+/** Normalize the two call shapes pg accepts: `(text, values)` or `({ text, values })`. */
+export const normalize = (first: any, second?: any[]): { text: string; values?: any[] } => {
+  if (first && typeof first === 'object' && 'text' in first) {
+    return { text: first.text, values: first.values };
+  }
+  return { text: first, values: second };
+};
+
+/** A bound `(text, values | { text, values })` query function over a PGlite instance. */
+export const boundQuery =
+  (db: PGlite) =>
+    (text: any, values?: any[]): Promise<PgResultLike> => {
+      const q = normalize(text, values);
+      return run(db, q.text, q.values);
+    };

postgres/pglite-adapter/src/runner.ts

@@ -0,0 +1,84 @@
+# pglite-test
+
+A drop-in [`pgsql-test`](../pgsql-test) `getConnections()` backed by an in-process
+[**PGlite**](https://github.com/electric-sql/pglite) instance (WASM Postgres) —
+**no Postgres server, no `createdb`, no `psql`, no TCP.**
+
+It follows the same pattern as `drizzle-orm-test` / `supabase-test`: compose the
+existing seams instead of forking the base.
+
+- [`@pgpmjs/pglite-adapter`](../pglite-adapter)'s `registerPglite()` routes
+  `pg-cache`'s `getPgPool()` at PGlite, so `seed.pgpm()` deploys your module into
+  it with the unmodified pgpm engine.
+- `pgsql-client`'s client-factory seam routes `PgTestClient`'s underlying
+  `pg.Client` at the same PGlite session.
+
+## Usage
+
+```typescript
+import { getConnections, PgTestClient } from 'pglite-test';
+
+let pg: PgTestClient;
+let db: PgTestClient;
+let teardown: () => Promise<void>;
+
+beforeAll(async () => {
+  ({ pg, db, teardown } = await getConnections());
+});
+
+afterAll(async () => {
+  await teardown();
+});
+
+beforeEach(async () => {
+  await pg.beforeEach();
+  await db.beforeEach();
+});
+
+afterEach(async () => {
+  await db.afterEach();
+  await pg.afterEach();
+});
+
+it('queries the pgpm-deployed schema', async () => {
+  const { rows } = await db.query('SELECT count(*)::int AS n FROM app.users');
+  expect(rows[0].n).toBe(0);
+});
+```
+
+Jest must run with `NODE_OPTIONS=--experimental-vm-modules` (PGlite loads a WASM
+module); the package's `test` script sets this.
+
+## Single-session model
+
+PGlite is one in-process session, so `pg` and `db` share it. That differs from
+`pgsql-test` (two authenticated connections on a real server):
+
+- Transaction control is **ref-counted** (`SharedTxn`) so the standard
+  two-client `beforeEach`/`afterEach` harness emits exactly one
+  `BEGIN`/`SAVEPOINT`/`ROLLBACK`/`COMMIT` per test. The single-client (`db` only)
+  pattern also works.
+- Role-based RLS uses `setContext({ role })` (i.e. `SET LOCAL role`) on the shared
+  session rather than separate authenticated connections. Any role you switch to
+  must exist — create it via `pglite.extensionSql` (e.g.
+  `['CREATE ROLE authenticated;']`).
+- `publish()` (commit-and-continue) is not supported under the shared-session
+  coordinator.
+
+## Options
+
+```typescript
+await getConnections(
+  {
+    pglite: {
+      dataDir: undefined,          // in-memory by default
+      extensions: { vector },       // WASM extensions (e.g. pglite-pgvector)
+      extensionSql: [               // run once after ready
+        'CREATE EXTENSION IF NOT EXISTS vector;',
+        'CREATE ROLE authenticated;'
+      ]
+    }
+  },
+  [seed.pgpm()]                     // default seed adapter
+);
+```