# Claude Code: install inside a session (native plugin, lightweight repository)
/plugin marketplace add pgrundev/pgx-plugin
/plugin install pgx@pgx-plugin
# Any agent host (Claude Code, Cursor, Codex): the Agent Skills CLI
npx skills add pgrundev/pgx --skill pgx
# Manual PGX installation
npx pgxdb@latest
PGX is a database runtime for short-lived Postgres databases: agent
sandboxes, CI and per-PR databases, test and preview environments. One PGX
process holds many isolated databases. Each costs tens of kilobytes of
memory while idle, is created in milliseconds from a sealed template, and
is backed, on a copy-on-write storage backend such as ZFS, by a clone
that starts at a few megabytes whatever the template's size (on a
filesystem without block cloning a branch is a full copy).
PGX speaks the Postgres wire protocol and SQL dialect. Rails, Django,
Prisma, SQLAlchemy and node-postgres run their full migrate → test →
schema-change lifecycles on it unchanged.
PGX is the database engine behind PGRun branches.
A database should be cheap enough to allocate like an object, not
provision like a server.
Why PGX
Agent workflows, test suites, CI jobs and preview environments create
databases constantly and throw them away minutes or hours later. Giving
each one its own PostgreSQL server costs a process, tens of megabytes and
a cold start every time. PostgreSQL is built to keep one database running
for years; PGX is built to create one in milliseconds, use it briefly and
delete it.
1 PostgreSQL server → 1 database
1 PGX runtime → hundreds or thousands of isolated databases
Immutable state is shared. Each database pays mainly for what makes it
different, and follows a lifecycle built for being thrown away:
sealed template
↓
mint database milliseconds, copy-on-write
↓
agent / CI / test minutes or hours
↓
discard dropped a grace period after the last session
On Linux, ZFS block cloning lets a branch share every unchanged block with
its template, so a branch of a 10 GB database is ready in under a second
and starts at about 14 MB of its own storage. Every agent, every pull
request and every test run can have its own real Postgres-compatible
database.
Disposable by design
Postgres was built to run for years. An AI agent needs a database for two
minutes: create → migrate → test → destroy. Multiply that by 1,000 agents
running in parallel and you do not need 1,000 Postgres servers. You need
one runtime holding thousands of isolated, disposable databases, each
dropped the moment its agent, pull request or CI job is done.
Benchmarks
Measured on a 4 vCPU / 8 GB / $8.50-a-month VPS with ZFS block cloning. The
load generator ran on the same CPUs, so these are architecture numbers,
not capacity limits.
~6.2 ms warm database mint, p50 (cold copy-on-write clone: 74 ms)
~70 KB memory per untouched idle database (~128 KB once queried)
128–155 MB one runtime holding 1,000 idle databases; 213 MB after all were used
111 MB runtime memory after 30,000 create → use → drop lifecycles
~674 ms copy-on-write branch of a 10 GB template, ~13.6 MB new storage
0 result differences on PostgreSQL's src/test/regress (219 / 231 byte-exact vs PG 18.6)
36 / 36 framework runs: Rails 8.1, Django 5.2, Prisma 6, SQLAlchemy 2, node-postgres
PGX is not trying to beat Postgres on single queries. Short statements are
about 0.05–0.15 ms slower than PostgreSQL 18, large single-threaded scans
1.5–2.2× slower, COPY and 4-client throughput equal; whole framework
lifecycles take 0–15 % longer. Transactional behaviour follows PostgreSQL,
including transactional DDL, savepoints and temporary tables.
These describe measured configurations and workloads, not a claim that
PGX is faster than PostgreSQL in general. The regression figure is
PostgreSQL's own test suite on one platform under the regress profile,
not a compatibility percentage for arbitrary SQL. Every figure has a
script and a committed raw result. The tables, the isolation results and
how to reproduce them: docs/pgx/benchmarks.md.
The full report: docs/pgx/linux-results.md.
Architecture
The central idea: share everything immutable, pay for divergence. It
applies to memory and to storage alike.
One process, one shared SQL engine, and one isolated database per client:
each agent, CI job or app connects over the ordinary Postgres wire protocol
and gets a database branched copy-on-write from a sealed template. The
engine, catalog, caches and warm pool are shared; only each database's own
changed blocks are written. Nothing is shared between databases.
1,000 databases, one PGX process
One idle PostgreSQL server: 16.6 MB. One idle PGX database: about 70 KB.
Databases are isolated by name, roles and limits inside one process with a
thread per connection. A database costs its catalog caches, not a server:
databases cloned from the same template share identical relation-cache
entries, and idle databases are skipped by autovacuum. Measured on a
4 vCPU / 8 GB VM:
one idle PostgreSQL 18 server 16.6 MB
one idle PGX database ~70 KB (~128 KB once it has been queried)
1,000 idle PGX databases 128–155 MB in one process
1,000 databases, each queried once 213 MB
1,000 databases, 100 active 283 MB
Benchmarks →
1,000 databases on a MacBook in 46.6 seconds
Not a cluster, not Docker, not the cloud: PGX on a 16 GB M1 Pro, cloning a
31 MB app database 1,000 times with pgx clone. All 1,000 clones in
46.6 s, 41 ms median per clone, 0 errors, and the engine idles at 20 MB
RSS with all 1,000 present. Under load it grows with the sessions, not the
databases: 340 MB at 100 concurrent readers, back to 20 MB when they
disconnect.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
