feat(pglite): pgpm→PGlite plugin — pg-cache + pgsql-client driver seams, @pgpmjs/pglite-adapter, pglite-test

[pyramation]

Summary

Brings PGlite (WASM Postgres) into the pgpm ecosystem as a plugin, keeping all @electric-sql/pglite* deps out of pgpm core and out of pgsql-client/pgsql-test — mirroring the drizzle-orm-test/supabase-test precedent. Nobody using pgpm/pgsql-test is affected; the default path is byte-identical.

The stack talks to Postgres through node-pg in two places, so there are two independent seams (both default-preserving), and the PGlite deps live only in two new leaf packages:

pg-cache.getPgPool ──registerPgPoolFactory──▶ QueryablePool   ┐
pgsql-client.PgClient ─registerPgClientFactory▶ QueryablePgClient ┘  default = pg.Pool / new pg.Client
                                        ▲
        @pgpmjs/pglite-adapter ─ registerPglite() ─ one in-process PGlite session backs both
                                        ▲
                 pglite-test ─ drop-in getConnections() (no server / createdb / psql)

What's here (in rollout order)

1. Socket e2e + CI (poc/pglite/, .github/workflows/pglite.yaml, job pglite-socket-e2e) — the unmodified pgpm engine does deploy → verify → pgvector round-trip → revert against PGlite over a pg-gateway socket shim, no Postgres service container. Standalone (own lockfile, outside the pnpm workspace). Kept as a wire-protocol demonstration distinct from the in-process path below.

2. pg-cache driver seam — getPgPool routes pool construction through a registrable factory; default unchanged. Factory return broadened so an adapter can return any QueryablePool (a real pg.Pool structurally satisfies it). 19 unit tests.

3. @pgpmjs/pglite-adapter (new — one of only two packages importing @electric-sql/pglite) — registers an in-process PGlite instance as the pg-cache factory, so the unmodified pgpm engine deploys into PGlite with no socket, no server:

const { db, close } = await registerPglite();       // creates PGlite, registers pool factory
const migrate = new PgpmMigrate({ database: 'postgres' });
await migrate.deploy({ modulePath });               // useTransaction:true (default)
await close();

The pool maps node-pg's two protocols onto PGlite: parameterized → db.query, parameterless/multi-statement (pgpm bootstrap) → db.exec. 6 tests.

4. pgsql-client client-factory seam — mirror of the pg-cache pool seam, because pgsql-client/pgsql-test build pg.Clients directly (not via getPgPool):

// pgsql-client/src/driver.ts  (no pglite import)
export type PgClientFactory = (config) => Client | QueryablePgClient; // { connect, query, end }
export const registerPgClientFactory = (f?) => { activeFactory = f; };
// PgClient ctor:
this.client = (getActivePgClientFactory() ?? defaultPgClientFactory)(config) as Client;

Default = new pg.Client(...), fully backward-compatible. 4 unit tests.

Publish readiness: @electric-sql/pglite is a peerDependency of both new packages (pinned devDependency for the monorepo build/tests) so consumers pin the version and avoid duplicate installs. pglite-test.getConnections restores the previous client factory on teardown and unwinds the seams if setup throws (no cross-suite leakage). Both packages carry CHANGELOG.md and publishConfig.

5. pglite-test (new — the second pglite-importing package) — a drop-in getConnections() like drizzle-orm-test/supabase-test, backed by an in-process PGlite instance. Composes both seams (registerPglite + registerPgClientFactory) so pg and db share one PGlite session:

const { pg, db, teardown } = await getConnections(
  { pglite: { extensionSql: ['CREATE ROLE authenticated;'] } },
  [seed.pgpm(moduleDir)]                // deploys via getPgPool → PGlite
);

Because PGlite is a single session, transaction control is ref-counted (SharedTxn) so the standard two-client beforeEach()/afterEach() savepoint harness emits exactly one BEGIN/SAVEPOINT/ROLLBACK/COMMIT per test (single-client db-only also works). No PGlite-aware DbAdmin subclass was needed — the instance is the database; extension/role bootstrap runs via pglite.extensionSql. 5 tests: deploy, per-test isolation, and RLS role + JWT-claim switching incl. WITH CHECK.

Key findings

• No core transaction fix needed for the in-process path. The socket PoC required useTransaction:false (a txn on one TCP session + isDeployed() on another deadlocks a single-connection backend). In-process, both seams funnel to PGlite's single session, so BEGIN/isDeployed()/COMMIT interleave safely. Deferred as optional — only relevant to a hypothetical multi-connection single-writer backend.
• pgsql-test bypasses the pg-cache seam, which is exactly why the client-factory seam (part 4) exists: PgTestClient extends pgsql-client's PgClient (new Client()) and never calls getPgPool.

Tests / CI

All 38 checks green, including the new no-services unit-tests (pglite, postgres/pglite-adapter postgres/pglite-test) job and Socket Security for @electric-sql/pglite@0.5.4.

Scope: no pgpm core source changed. Both seams are additive and default-preserving; all @electric-sql/pglite* code lives in @pgpmjs/pglite-adapter and pglite-test.

Not in this PR (follow-ups)

• Fuller pglite-test-suite wiring + getConnections manager/admin parity.
• Optional core transaction-client fix (only for a multi-connection single-writer backend).
• pgpm init --pglite scaffolder (CLI-layer convenience; no PGlite dep in core).
• Browser-target validation (pgsql-parser is libpg_query WASM → two WASM modules load in-browser; fine in Node/CI, untested in-browser).

Link to Devin session: https://app.devin.ai/sessions/424b76f81a60499493ac946b57136ad9
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​electric-sql/​pglite-pgvector@​0.0.5
	@​electric-sql/​pglite@​0.5.4
	@​electric-sql/​pglite-socket@​0.2.7

View full report