Merge pull request #1350 from constructive-io/feat/pglite-poc

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

Author: pyramation

.github/workflows/run-tests.yaml

@@ -94,6 +94,8 @@ jobs:
             packages: 'packages/postmaster packages/smtppostmaster packages/csv-to-pg packages/cli postgres/pgsql-client postgres/pg-ast'
           - batch: graphql
             packages: 'graphql/query graphql/codegen'
+          - batch: pglite
+            packages: 'postgres/pglite-adapter postgres/pglite-test examples/pglite-socket'
 
     steps:
       - name: Download workspace

examples/pglite-socket/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.

examples/pglite-socket/README.md

@@ -0,0 +1,58 @@
+# pgpm → PGlite
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+</p>
+
+An end-to-end demonstration that the **unmodified** `@pgpmjs/core` migrate engine can deploy real migrations into [**PGlite**](https://github.com/electric-sql/pglite) — ElectricSQL's WASM build of Postgres ("SQLite for Postgres"): embedded, in-process, with **no Postgres server or service container**.
+
+It proves the wire-protocol path (pgpm ↔ PGlite over a socket). The **in-process driver** path — `@pgpmjs/pglite-adapter` + `pglite-test`, with no socket — is the productized version. Both run in the same no-services `unit-tests (pglite …)` job in [`run-tests.yaml`](../../.github/workflows/run-tests.yaml).
+
+## Run
+
+```sh
+cd examples/pglite-socket
+pnpm test   # jest: boots PGlite, runs pgpm deploy → verify → data → revert, asserts
+```
+
+It's a normal workspace package, so `pnpm install` / `pnpm build` at the repo root wires it up. The test needs **no Postgres service** — PGlite runs in-process.
+
+## How it works
+
+The jest test boots a PGlite instance, exposes it over a socket with the official `pg-gateway` shim (`@electric-sql/pglite-socket`), and points the `@pgpmjs/core` `PgpmMigrate` engine at it as if it were ordinary Postgres:
+
+```
+pgpm (@pgpmjs/core, unmodified)  ──node-pg / TCP──▶  PGLiteSocketServer  ──▶  PGlite (WASM)
+```
+
+It then asserts a full lifecycle against `__fixtures__/` (a 4-change pgpm plan ending in a `pgvector` column):
+
+* **initialize** — bootstraps the `pgpm_migrate` schema (tables + PL/pgSQL procs)
+* **deploy** — `schema → table → index → embedding`
+* **verify** — all four verified
+* **data round-trip** — a pgvector nearest-neighbor query returns the seeded row
+* **revert** — everything reverted, registry emptied
+
+## The two accommodations this pins down
+
+The engine runs against PGlite **today** with two call-site accommodations; the productized in-process driver folds these into the adapter layer:
+
+1. **Single-connection / transaction affinity.** PGlite serializes everything and, while a transaction is open, pins the engine to that one connection. `deploy({ useTransaction: true })` opens `BEGIN` on one pooled connection and calls `isDeployed()` on a *second* — which can never run on PGlite → deadlock. This demo uses `useTransaction: false`; the in-process adapter avoids it entirely because both seams funnel to PGlite's single session. (The socket shim also defaults to `maxConnections: 1`; we raise it — PGlite still serializes, so multiplexing is safe.)
+
+2. **Extensions are provisioned out-of-band.** pgpm's `cleanSql` deliberately strips `CREATE EXTENSION` (and `BEGIN`/`COMMIT`) from migrations — extensions come from the environment (the `postgres-plus` image / `pgsql-test`'s `installExtensions()`), not migrations. So the demo creates the extension at PGlite bootstrap, and PGlite additionally requires the extension registered in JS at construction (`PGlite.create({ extensions: { vector } })`).
+
+Extension availability — not pgpm — is the functional boundary. Bundled/available: `pg_trgm`, `citext`, `ltree`, `uuid_ossp`, `pgvector`, … Not available (no WASM / no background workers): `pg_cron`, `pg_partman`, the BM25 search ext; PostGIS is experimental. A module needing those simply won't deploy to PGlite.
+
+## See also
+
+* [`@pgpmjs/pglite-adapter`](../../postgres/pglite-adapter) — the productized in-process driver (no socket): registers a PGlite instance as the `pg-cache` pool factory.
+* [`pglite-test`](../../postgres/pglite-test) — a drop-in `getConnections()` on in-process PGlite for writing tests.

examples/pglite-socket/__fixtures__/deploy/embedding.sql

@@ -0,0 +1,9 @@
+-- Deploy test-simple:embedding to pg
+-- requires: table
+
+BEGIN;
+
+CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA public;
+ALTER TABLE test_app.users ADD COLUMN embedding public.vector(3);
+
+COMMIT;

examples/pglite-socket/__fixtures__/deploy/index.sql

@@ -0,0 +1,9 @@
+-- Deploy test-simple:index to pg
+-- requires: table
+
+BEGIN;
+
+CREATE INDEX idx_users_email ON test_app.users(email);
+CREATE INDEX idx_users_created_at ON test_app.users(created_at);
+
+COMMIT;

examples/pglite-socket/__fixtures__/deploy/schema.sql

@@ -0,0 +1,7 @@
+-- Deploy test-simple:schema to pg
+
+BEGIN;
+
+CREATE SCHEMA test_app;
+
+COMMIT;

examples/pglite-socket/__fixtures__/deploy/table.sql

@@ -0,0 +1,13 @@
+-- Deploy test-simple:table to pg
+-- requires: schema
+
+BEGIN;
+
+CREATE TABLE test_app.users (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+COMMIT;

examples/pglite-socket/__fixtures__/pgpm.plan

@@ -0,0 +1,8 @@
+%syntax-version=1.0.0
+%project=test-simple
+%uri=https://github.com/test/simple
+
+schema 2024-01-01T00:00:00Z test <test@example.com> # Create schema
+table [schema] 2024-01-02T00:00:00Z test <test@example.com> # Create table
+index [table] 2024-01-03T00:00:00Z test <test@example.com> # Create index
+embedding [table] 2024-01-04T00:00:00Z test <test@example.com> # Add pgvector column

examples/pglite-socket/__fixtures__/revert/embedding.sql

@@ -0,0 +1,4 @@
+-- Revert test-simple:embedding from pg
+BEGIN;
+ALTER TABLE test_app.users DROP COLUMN embedding;
+COMMIT;

examples/pglite-socket/__fixtures__/revert/index.sql

@@ -0,0 +1,8 @@
+-- Revert test-simple:index from pg
+
+BEGIN;
+
+DROP INDEX test_app.idx_users_email;
+DROP INDEX test_app.idx_users_created_at;
+
+COMMIT;