poc(pglite): deploy pgpm migrations into PGlite in CI (no Postgres service)

Author: pyramation

.github/workflows/pglite-poc.yaml

@@ -0,0 +1,35 @@
+name: PGlite PoC
+
+# Proof of concept: the pgpm migrate engine deploying real migrations into PGlite
+# (WASM Postgres). Deliberately has NO `services:` block — PGlite runs in-process,
+# so no Postgres service container is needed.
+
+on:
+  push:
+    branches: [main, v1]
+    paths:
+      - 'poc/pglite/**'
+      - '.github/workflows/pglite-poc.yaml'
+  pull_request:
+    branches: [main, v1]
+    paths:
+      - 'poc/pglite/**'
+      - '.github/workflows/pglite-poc.yaml'
+  workflow_dispatch:
+
+jobs:
+  pglite-poc:
+    if: github.event.pull_request.draft != true
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Install (standalone, not the monorepo)
+        working-directory: poc/pglite
+        run: npm ci
+      - name: Deploy pgpm migrations into PGlite (no Postgres service)
+        working-directory: poc/pglite
+        run: npm start

poc/pglite/README.md

@@ -0,0 +1,66 @@
+# pgpm → PGlite (proof of concept)
+
+Proof that the **unmodified** pgpm 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, **no Postgres server or
+service container required**.
+
+```bash
+cd poc/pglite
+npm ci
+npm start   # boots PGlite in-process, runs pgpm deploy -> verify -> revert, asserts
+```
+
+This runs in CI via `.github/workflows/pglite-poc.yaml` with no `services:` block —
+the whole point: PGlite needs no external database.
+
+## What it does
+
+`run.mjs` boots a PGlite instance, exposes it over a socket with the official
+`pg-gateway` shim (`@electric-sql/pglite-socket`), and points the published
+`@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 `module/` (a 4-change pgpm plan that ends
+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
+
+## Why the code isn't quite drop-in (the findings this PoC pins down)
+
+The engine works against PGlite **today** with two call-site accommodations; a real
+`pglite` target would fold these into the engine/driver layer:
+
+1. **Single-connection / transaction affinity.** PGlite serializes everything and,
+   while a transaction is open, pins the engine to that one connection. The engine's
+   `deploy({useTransaction:true})` opens `BEGIN` on one pooled connection and calls
+   `isDeployed()` on a *second* — which can never run on PGlite → deadlock. The PoC
+   uses `useTransaction:false`. Proper fix: run all transaction-scoped work on the
+   same client. (Also: the socket shim 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 PoC 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.
+
+## Notes
+
+Standalone on purpose: this directory is **not** part of the pnpm workspace (its own
+`package.json` + `package-lock.json`, run with `npm ci`) so the PoC stays independent
+of the monorepo build. It depends on the *published* `@pgpmjs/core`; it could be
+repointed at the workspace build to track unreleased engine changes.

poc/pglite/module/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;

poc/pglite/module/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;

poc/pglite/module/deploy/schema.sql

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

poc/pglite/module/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;

poc/pglite/module/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

poc/pglite/module/revert/embedding.sql

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

poc/pglite/module/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;

poc/pglite/module/revert/schema.sql

@@ -0,0 +1,7 @@
+-- Revert test-simple:schema from pg
+
+BEGIN;
+
+DROP SCHEMA test_app CASCADE;
+
+COMMIT;