pg-web — Current State Overview
pg-web is a PostgreSQL extension that runs an HTTP server inside a Postgres background worker. Everything a browser sees comes out of a single OS process tree rooted at the Postgres postmaster.
Phase 1 — Synchronous Core (v0.2.0) is complete. All core milestones shipped.
The 30-second picture
- Installs via
CREATE EXTENSION pg_web_ext;— creates thepgwebschema (routes,templates,migrations) and seeds a defaultGET /. - Starts an HTTP server on
:8080when Postgres boots (viashared_preload_libraries). - Serves HTML rendered from a database-stored Tera template merged with a SQL-function-returned JSON payload.
- Returns 404 for unmatched paths (override with
pages/_404.html).
A CLI (pg-web) scaffolds apps (init), applies forward-only SQL migrations (migrate apply), and syncs the pages/ tree into the DB (push). The prebuilt Docker image pgweb/postgres:latest packages PG 17 + the extension.
Phase 1 milestones (all shipped)
| Milestone | Key deliverables |
|---|---|
| M1.1 Walking Skeleton | Framework schema + BGW + Axum + SPI→Tera + CLI init/push + Docker image |
| M1.3 Interactive Contracts | Directory-as-route, (req json) contract, _404, examples/todo/, Docker E2E |
| M1.2 Dev Loop | pg-web up/down/dev, hot reload, dynamic [id] routes, dev error page, static assets |
| M1.4 Closeout | html_escape, validation UX, env/check, init --template, push flags + ledger, live-reload SSE, release bits |
| v0.2 polish (Session 5) | Push retry, CLI bundled in image (F.3), content-hash immutable assets (H), 20 MiB asset cap |
Try it
See the quickstart on the home page or follow the tutorial that builds the full todo app.
What's not in v0.2
- Auth / sessions / RLS (Phase 2)
- Async job queue (Phase 3)
- Declarative migrations (Phase 2.5)
- Real-time subscriptions (Phase 2)
- Managed DB support (RDS etc. cannot load custom extensions)
Full details and the decision log live in docs/ROADMAP.md in the source repo.