Skip to content
Back to search

pgrundev

MarketplaceWorks with Claude CodeGitHub

PostgreSQL developer tools for AI coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pgrundev/pgx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pgrundev/pgx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pgrundev--pgx/badge.svg)](/listings/pgrundev--pgx)

HTML

<a href="/listings/pgrundev--pgx"><img src="/api/listings/pgrundev--pgx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One command installs PGBoxDB, starts it, creates an `app` database and prints its connection URL. No Docker, Rust or system PostgreSQL; the native distribution is self-contained and relocatable.

npx pgboxdb@latest
PGBoxDB is ready.

  postgres://postgres:…@127.0.0.1:5432/app

Point `DATABASE_URL` at that URL. `npx pgboxdb` with no arguments is `pgboxdb run`; every other `pgboxdb` command works the same way through npx, and `npm install -g pgboxdb` puts `pgboxdb` on your PATH for good:

pgboxdb url app                      # its connection URL
pgboxdb ls                           # databases, TTL, expiry, size
pgboxdb branch app agent-001         # a disposable 2-hour branch for one agent
pgboxdb clone app pr-123 --ttl 5m    # a 5-minute copy-on-write clone
pgboxdb create scratch --ttl 2h      # a throwaway database, gone in 2 hours
pgboxdb --json ls                    # machine-readable output for agents
pgboxdb stop

Without Node, `curl -fsSL https://pgboxdb.com/install | sh` does the same install. Supported: Apple silicon Macs and Linux (arm64, x86-64); Intel Macs are not supported yet. Any PostgreSQL client or ORM works against `pgboxdb url <db>`.

Clones are copy-on-write on a backend with block cloning (such as ZFS), a full copy elsewhere. `pgboxdb branch` is `pgboxdb clone` for agents: a 2-hour TTL by default and the connection URL as the last line of output, so an agent can be handed `DATABASE_URL="$(pgboxdb branch myapp agent-1 | tail -1)"`. Databases created without `--ttl` are permanent; a background supervisor drops each temporary one shortly after its deadline and never touches permanent or system databases ([`ttl.md`](docs/pgboxdb/local-dev/ttl.md)).

The full CLI, install options, integrations (Rails, Node, Python, Go, psql), storage model and troubleshooting are under [`docs/pgboxdb/local-dev/`](docs/pgboxdb/local-dev/). Building the engine yourself, running a bare runtime and minting from a sealed template by hand: [`build-from-source.md`](docs/pgboxdb/local-dev/build-from-source.md).

Every AI agent gets its own Postgres

Install the Skill, then ask your agent. In Claude Code, from inside a session:

/plugin marketplace add pgrundev/pgboxdb-plugin
/plugin install pgboxdb@pgboxdb-plugin
/pgboxdb:pgboxdb Set up isolated Postgres databases for this project.

For Cursor, Codex or several hosts at once, the Agent Skills CLI installs the same Skill into the project:

npx skills add pgrundev/pgboxdb --skill pgboxdb

> Use PGBoxDB to give this project isolated databases for coding agents. Set everything up.

The agent detects your database setup, installs PGBoxDB if needed, imports your development database **schema-only** into a template (`pgboxdb copy`), writes a committed `.pgboxdb.toml`, installs lifecycle hooks (`pgboxdb agent setup`) and proves a branch. From then on each session gets its own branch with `DATABASE_URL` already set, extended while the agent works and removed after it stops, and every subagent gets a branch of its own; two agents never see each other's changes and your PostgreSQL is never written. Installing the Skill executes nothing by itself: the agent does the setup when the Skill is activated and your permissions allow it.

| Host | Automatic isolation | Status | |---|---|---| | Claude Code | yes, through hooks: one branch per session and one per subagent | verified live | | Cursor | hooks installed; `pgboxdb agent exec --` when `PGBOXDB_ISOLATION` is unset | env propagation pending live verification | | Codex | `pgboxdb agent exec -- codex` (Codex hooks cannot set environment) | wrapper verified |

Requires PGBoxDB 0.1.2 or newer; the Skill checks the installed version before it does anything. [`pgrundev/pgboxdb-plugin`](https://github.com/pgrundev/pgboxdb-plugin) holds only the plugin (about 110 KB, generated from this repository), so the install takes seconds; adding this repository itself as the marketplace

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "pgrundev",
  4. "description": "PostgreSQL developer tools for AI coding agents",
  5. "owner": {
  6. "name": "PGRunDev",
  7. "url": "https://pgboxdb.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "pgboxdb",
  12. "source": "./plugins/pgboxdb",
  13. "description": "Give every AI coding agent its own isolated, disposable Postgres database.",
  14. "category": "database",
  15. "tags": ["postgres", "postgresql", "database", "ai-agents", "database-branching"],
  16. "homepage": "https://github.com/pgrundev/pgboxdb"
  17. }
  18. ]
  19. }
README.md · README · 523 lines · 1 finding marked
  1. <h1 align="center">PGBoxDB</h1>
  2. <p align="center">
  3. Lightweight Postgres-compatible database runtime for AI agents<br>
  4. <a href="https://pgboxdb.com">pgboxdb.com</a> · documentation: <a href="https://pgbox.dev/db">pgbox.dev/db</a>
  5. </p>
  6. <p align="center">
  7. <strong>Every AI agent gets its own Postgres.</strong><br>
  8. One runtime. Thousands of Postgres databases.
  9. </p>
  10. <p align="center">
  11. <img alt="Postgres 18.6" src="https://img.shields.io/badge/Postgres-18.6-336791">
  12. <img alt="Version: v0.1" src="https://img.shields.io/badge/version-v0.1-blue">
  13. <img alt="PostgreSQL regression suite: 219 of 231 byte-exact, 0 result differences" src="https://img.shields.io/badge/src%2Ftest%2Fregress-219%2F231_byte--exact%2C_0_result_diffs-green">
  14. <a href="LICENSE"><img alt="License: AGPL-3.0" src="https://img.shields.io/badge/license-AGPL--3.0-blue"></a>
  15. </p>
  16. <p align="center">
  17. <a href="#quickstart">Quickstart</a> ·
  18. <a href="#every-ai-agent-gets-its-own-postgres">Agents</a> ·
  19. <a href="#why-pgboxdb">Why PGBoxDB</a> ·
  20. <a href="#benchmarks">Benchmarks</a> ·
  21. <a href="#architecture">Architecture</a> ·
  22. <a href="#status">Status</a> ·
  23. <a href="#documentation">Docs</a>
  24. </p>
  25. <p align="center">
  26. <strong>Install one Skill. Your coding agent handles the database.</strong><br>
  27. No Docker required · Native Mac &amp; Linux · Automatic cleanup
  28. </p>
  29. ```text
  30. # Claude Code: install inside a session (native plugin, lightweight repository)
  31. /plugin marketplace add pgrundev/pgboxdb-plugin
  32. /plugin install pgboxdb@pgboxdb-plugin
  33. ```
  34. ```bash
  35. # Any agent host (Claude Code, Cursor, Codex): the Agent Skills CLI
  36. npx skills add pgrundev/pgboxdb --skill pgboxdb
  37. # Manual PGBoxDB installation
  38. npx pgboxdb@latest
  39. ```
  40. <!-- skills.sh badge: add [![skills.sh](https://skills.sh/b/pgrundev/pgboxdb)](https://skills.sh/pgrundev/pgboxdb) once https://skills.sh/pgrundev/pgboxdb lists the skill -->
  41. <p align="center">
  42. <sub>Open source · Free · v0.1.3 · For disposable databases, not production data</sub>
  43. </p>
  44. PGBoxDB is a database runtime for short-lived Postgres databases: agent
  45. sandboxes, CI and per-PR databases, test and preview environments. One PGBoxDB
  46. process holds many isolated databases. Each costs tens of kilobytes of
  47. memory while idle, is created in milliseconds from a sealed template, and
  48. is backed, on a copy-on-write storage backend such as ZFS, by a clone
  49. that starts at a few megabytes whatever the template's size (on a
  50. filesystem without block cloning a branch is a full copy).
  51. PGBoxDB speaks the Postgres wire protocol and SQL dialect. Rails, Django,
  52. Prisma, SQLAlchemy and node-postgres run their full migrate → test →
  53. schema-change lifecycles on it unchanged.
  54. PGBoxDB is the database engine behind PGRun branches.
  55. > A database should be cheap enough to allocate like an object, not
  56. > provision like a server.
  57. ## Why PGBoxDB
  58. <p align="center">
  59. <img alt="PGBoxDB architecture: your machine's agents, CI and apps speak the Postgres wire protocol to one PGBoxDB process, a shared Rust SQL engine with a thread per connection, shared catalog and caches, and one isolated database per client, each branched copy-on-write from a sealed template" src="docs/pgboxdb/img/architecture.gif" width="900">
  60. </p>
  61. Agent workflows, test suites, CI jobs and preview environments create
  62. databases constantly and throw them away minutes or hours later. Giving
  63. each one its own PostgreSQL server costs a process, tens of megabytes and
  64. a cold start every time. PostgreSQL is built to keep one database running
  65. for years; PGBoxDB is built to create one in milliseconds, use it briefly and
  66. delete it.
  67. ```text
  68. 1 PostgreSQL server → 1 database
  69. 1 PGBoxDB runtime → hundreds or thousands of isolated databases
  70. ```
  71. Immutable state is shared. Each database pays mainly for what makes it
  72. different, and follows a lifecycle built for being thrown away:
  73. ```text
  74. sealed template
  75. ↓
  76. mint database milliseconds, copy-on-write
  77. ↓
  78. agent / CI / test minutes or hours
  79. ↓
  80. discard dropped a grace period after the last session
  81. ```
  82. On Linux, ZFS block cloning lets a branch share every unchanged block with
  83. its template, so a branch of a 10 GB database is ready in under a second
  84. and starts at about 14 MB of its own storage. Every agent, every pull
  85. request and every test run can have its own real Postgres-compatible
  86. database.
  87. ## Disposable by design
  88. Postgres was built to run for years. An AI agent needs a database for two
  89. minutes: create → migrate → test → destroy. Multiply that by 1,000 agents
  90. running in parallel and you do not need 1,000 Postgres servers. You need
  91. one runtime holding thousands of isolated, disposable databases, each
  92. dropped the moment its agent, pull request or CI job is done.
  93. <p align="center">
  94. <picture><source srcset="docs/pgboxdb/img/disposable.gif" type="image/gif"><img src="docs/pgboxdb/img/disposable.jpg" alt="Agents, PRs and CI jobs on one PGBoxDB runtime, each creating, migrating, testing and dropping its own database" width="720" /></picture>
  95. </p>
  96. ## Benchmarks
  97. Measured on a 4 vCPU / 8 GB / $8.50-a-month VPS with ZFS block cloning. The
  98. load generator ran on the same CPUs, so these are architecture numbers,
  99. not capacity limits.
  100. ```text
  101. ~6.2 ms warm database mint, p50 (cold copy-on-write clone: 74 ms)
  102. ~70 KB memory per untouched idle database (~128 KB once queried)
  103. 128–155 MB one runtime holding 1,000 idle databases; 213 MB after all were used
  104. 111 MB runtime memory after 30,000 create → use → drop lifecycles
  105. ~674 ms copy-on-write branch of a 10 GB template, ~13.6 MB new storage
  106. 0 result differences on PostgreSQL's src/test/regress (219 / 231 byte-exact vs PG 18.6)
  107. 36 / 36 framework runs: Rails 8.1, Django 5.2, Prisma 6, SQLAlchemy 2, node-postgres
  108. ```
  109. PGBoxDB is not trying to beat Postgres on single queries. Short statements are
  110. about 0.05–0.15 ms slower than PostgreSQL 18, large single-threaded scans
  111. 1.5–2.2× slower, COPY and 4-client throughput equal; whole framework
  112. lifecycles take 0–15 % longer. Transactional behaviour follows PostgreSQL,
  113. including transactional DDL, savepoints and temporary tables.
  114. These describe measured configurations and workloads, not a claim that
  115. PGBoxDB is faster than PostgreSQL in general. The regression figure is
  116. PostgreSQL's own test suite on one platform under the regress profile,
  117. not a compatibility percentage for arbitrary SQL. Every figure has a
  118. script and a committed raw result. The tables, the isolation results and
  119. how to reproduce them: [`docs/pgboxdb/benchmarks.md`](docs/pgboxdb/benchmarks.md).
  120. The full report: [`docs/pgboxdb/linux-results.md`](docs/pgboxdb/linux-results.md).
  121. ## Architecture
  122. The central idea: **share everything immutable, pay for divergence.** It
  123. applies to memory and to storage alike.
  124. One process, one shared SQL engine, and one isolated database per client:
  125. each agent, CI job or app connects over the ordinary Postgres wire protocol
  126. and gets a database branched copy-on-write from a sealed template. The
  127. engine, catalog, caches and warm pool are shared; only each database's own
  128. changed blocks are written. Nothing is shared between databases.
  129. ### 1,000 databases, one PGBoxDB process
  130. One idle PostgreSQL server: 16.6 MB. One idle PGBoxDB database: about 70 KB.
  131. Databases are isolated by name, roles and limits inside one process with a
  132. thread per connection. A database costs its catalog caches, not a server:
  133. databases cloned from the same template share identical relation-cache
  134. entries, and idle databases are skipped by autovacuum. Measured on a
  135. 4 vCPU / 8 GB VM:
  136. ```text
  137. one idle PostgreSQL 18 server 16.6 MB
  138. one idle PGBoxDB database ~70 KB (~128 KB once it has been queried)
  139. 1,000 idle PGBoxDB databases 128–155 MB in one process
  140. 1,000 databases, each queried once 213 MB
  141. 1,000 databases, 100 active 283 MB
  142. ```
  143. [Benchmarks →](docs/pgboxdb/benchmarks.md)
  144. ### 1,000 databases on a MacBook in 46.6 seconds
  145. Not a cluster, not Docker, not the cloud: PGBoxDB on a 16 GB M1 Pro, cloning a
  146. 31 MB app database 1,000 times with `pgboxdb clone`. All 1,000 clones in
  147. 46.6 s, 41 ms median per clone, 0 errors, and the engine idles at 20 MB
  148. RSS with all 1,000 present. Under load it grows with the sessions, not the
  149. databases: 340 MB at 100 concurrent readers, back to 20 MB when they
  150. disconnect.
  151. <p align="center">
  152. <a href="docs/pgboxdb/benchmarks.md"><picture><source srcset="docs/pgboxdb/img/arch-density.gif" type="image/gif"><img src="docs/pgboxdb/img/arch-density.jpg" alt="1,000 databases in one PGBoxDB runtime" width="720" /></picture></a>
  153. </p>
  154. ### Mint-on-connect
  155. Connecting to `<prefix><template>__<token>` creates that database from a
  156. sealed template and connects you to it, in about 6 ms from a warm pool of
  157. pre-created spares and 74 ms cold. A janitor drops it a grace period after
  158. its last session ends, unless it is pinned.
  159. ```text
  160. psql -d tdb_tpl_app__agent42 # does not exist yet
  161. # → minted from tpl_app, 6.2 ms p50
  162. psql -d tdb_tpl_app__agent43 # a second, isolated one
  163. # → 0 rows: it sees none of agent42's writes
  164. …last session ends…
  165. # → dropped after the grace period
  166. ```
  167. [Sealing templates and minting by hand →](docs/pgboxdb/local-dev/build-from-source.md#make-a-template-and-mint-databases)
  168. ### Copy-on-write storage
  169. `file_copy_method = clone` turns database creation into ZFS block clones.
  170. A branch shares every unchanged block with its template, so its cost grows
  171. with divergence: a branch of a 10 GB template is ready in 674 ms and starts
  172. at 13.6 MB of its own storage. On a filesystem without block cloning a
  173. branch is a full copy.
  174. ```text
  175. template (10 GB)
  176. ├── branch A → only changed blocks 674 ms, +13.6 MB
  177. ├── branch B → only changed blocks
  178. └── branch C → only changed blocks
  179. 1 GB template → 135 ms, +2.3 MB
  180. 2 GB → 198 ms, +3.7 MB
  181. 5 GB → 417 ms, +7.0 MB
  182. 10 GB → 674 ms, +13.6 MB
  183. ```
  184. [ZFS copy-on-write →](docs/pgboxdb/zfs-cow.md)
  185. ### Limits at every level
  186. Session, database and runtime memory limits inside the engine, connection
  187. limits per database, and a Linux cgroup around the runtime. Memory-heavy
  188. work fails with a PostgreSQL-style error (SQLSTATE 53200) instead of
  189. taking the host down; the session stays usable and other databases see
  190. 0 errors. `pgrust_runtime_status()` returns the whole picture as JSON:
  191. databases, sessions, memory against limits, warm-pool and mint counters.
  192. ```text
  193. session → database / runtime → Linux cgroup
  194. ERROR: out of memory SQLSTATE 53200
  195. HINT: The session reached pgrust.session_memory_limit.
  196. (transaction aborted; session stays connected; other databases: 0 errors)
  197. SELECT pgrust_runtime_status();
  198. {"memory":{"rss_bytes":…,"session_limit_mb":256,"database_limit_mb":512,"runtime_limit_mb":3072},
  199. "connections":42,
  200. "databases":{"total":1003,"ephemeral":998,"spares":8,"pinned":2},
  201. "janitor":{"prefix":"tdb_","pool_size":8,"pending_mints":0}}
  202. ```
  203. [Memory limits and the cgroup backstop →](docs/pgboxdb/linux-limits.md)
  204. ### A branch per agent
  205. The PGBoxDB Skill and `pgboxdb agent` put the lifecycle on hooks: each Claude Code
  206. session gets its own branch with `DATABASE_URL` already set, extended while
  207. the agent works and dropped after it stops, and every subagent gets a
  208. branch of its own. Two agents never see each other's changes, and your
  209. PostgreSQL is only ever read.
  210. ```text
  211. session start → pgboxdb branch myapp <session> DATABASE_URL set
  212. subagent → pgboxdb branch myapp <subagent> its own branch
  213. agent works → TTL extended
  214. session end → branch dropped
  215. ```
  216. [Agents →](docs/pgboxdb/local-dev/agents.md)
  217. ## Status
  218. PGBoxDB is at **v0.1.3**, an early release with known limitations listed in the
  219. [release notes](https://github.com/pgrundev/pgboxdb/releases/tag/v0.1.3). It
  220. already powers PGBoxDB branches in [PGRun](https://pgrun.dev), which adds the
  221. control plane around it: safe masked copies of a source database, sealed
  222. templates, one branch per agent, PR or CI job, routing, access and
  223. automatic expiry. The current focus is PostgreSQL and application
  224. compatibility, concurrency semantics, lifecycle correctness, predictable
  225. resource containment and real agent workloads. If PGBoxDB behaves differently
  226. from PostgreSQL for a supported workload, we want a reproducible test case
  227. (see Contributing).
  228. **PGBoxDB v0.1 is for disposable databases:** agent, CI, PR, test and preview
  229. databases built from sanitized copies of production. Use it where losing
  230. a branch is acceptable. It is **not** a production primary, a system of
  231. record, or an HA or PITR database:
  232. - **Not crash-safe.** The PGBoxDB profile runs with `fsync = off`.
  233. - **One process.** A runtime is one crash domain.
  234. - **No C extensions.** Existing PostgreSQL C extensions cannot load; only
  235. the built-in contrib modules exist, pgvector among them. PL/Python,
  236. PL/Perl and PL/Tcl are not available.
  237. Keep Postgres as the source of truth for data you can't afford to lose.
  238. The full list is in [`docs/pgboxdb/v0.1-readiness.md`](docs/pgboxdb/v0.1-readiness.md).
  239. ## Quickstart
  240. One command installs PGBoxDB, starts it, creates an `app` database and prints its
  241. connection URL. No Docker, Rust or system PostgreSQL; the native distribution
  242. is self-contained and relocatable.
  243. ```bash
  244. npx pgboxdb@latest
  245. ```
  246. ```console
  247. PGBoxDB is ready.
  248. postgres://postgres:…@127.0.0.1:5432/app
  249. ```
  250. Point `DATABASE_URL` at that URL. `npx pgboxdb` with no arguments is `pgboxdb run`;
  251. every other `pgboxdb` command works the same way through npx, and
  252. `npm install -g pgboxdb` puts `pgboxdb` on your PATH for good:
  253. ```bash
  254. pgboxdb url app # its connection URL
  255. pgboxdb ls # databases, TTL, expiry, size
  256. pgboxdb branch app agent-001 # a disposable 2-hour branch for one agent
  257. pgboxdb clone app pr-123 --ttl 5m # a 5-minute copy-on-write clone
  258. pgboxdb create scratch --ttl 2h # a throwaway database, gone in 2 hours
  259. pgboxdb --json ls # machine-readable output for agents
  260. pgboxdb stop
  261. ```
  262. Without Node, `curl -fsSL https://pgboxdb.com/install | sh` does the same
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 333 on GitHub
  263. install. Supported: Apple silicon Macs and Linux (arm64, x86-64); Intel
  264. Macs are not supported yet. Any PostgreSQL client or ORM works against
  265. `pgboxdb url <db>`.
  266. Clones are copy-on-write on a backend with block cloning (such as ZFS), a
  267. full copy elsewhere. `pgboxdb branch` is `pgboxdb clone` for agents: a 2-hour TTL by
  268. default and the connection URL as the last line of output, so an agent can
  269. be handed `DATABASE_URL="$(pgboxdb branch myapp agent-1 | tail -1)"`. Databases
  270. created without `--ttl` are permanent; a background supervisor drops each
  271. temporary one shortly after its deadline and never touches permanent or
  272. system databases ([`ttl.md`](docs/pgboxdb/local-dev/ttl.md)).
  273. The full CLI, install options, integrations (Rails, Node, Python, Go, psql),
  274. storage model and troubleshooting are under
  275. [`docs/pgboxdb/local-dev/`](docs/pgboxdb/local-dev/). Building the engine yourself,
  276. running a bare runtime and minting from a sealed template by hand:
  277. [`build-from-source.md`](docs/pgboxdb/local-dev/build-from-source.md).
  278. ### Every AI agent gets its own Postgres
  279. Install the Skill, then ask your agent. In Claude Code, from inside a session:
  280. ```text
  281. /plugin marketplace add pgrundev/pgboxdb-plugin
  282. /plugin install pgboxdb@pgboxdb-plugin
  283. /pgboxdb:pgboxdb Set up isolated Postgres databases for this project.
  284. ```
  285. For Cursor, Codex or several hosts at once, the Agent Skills CLI installs the
  286. same Skill into the project:
  287. ```bash
  288. npx skills add pgrundev/pgboxdb --skill pgboxdb
  289. ```
  290. > Use PGBoxDB to give this project isolated databases for coding agents. Set everything up.
  291. The agent detects your database setup, installs PGBoxDB if needed, imports your
  292. development database **schema-only** into a template (`pgboxdb copy`), writes a
  293. committed `.pgboxdb.toml`, installs lifecycle hooks (`pgboxdb agent setup`) and
  294. proves a branch. From then on each session gets its own branch with
  295. `DATABASE_URL` already set, extended while the agent works and removed after
  296. it stops, and every subagent gets a branch of its own; two agents never see
  297. each other's changes and your PostgreSQL is never written. Installing the
  298. Skill executes nothing by itself: the agent does the setup when the Skill is
  299. activated and your permissions allow it.
  300. | Host | Automatic isolation | Status |
  301. |---|---|---|
  302. | Claude Code | yes, through hooks: one branch per session and one per subagent | verified live |
  303. | Cursor | hooks installed; `pgboxdb agent exec --` when `PGBOXDB_ISOLATION` is unset | env propagation pending live verification |
  304. | Codex | `pgboxdb agent exec -- codex` (Codex hooks cannot set environment) | wrapper verified |
  305. Requires PGBoxDB 0.1.2 or newer; the Skill checks the installed version before it
  306. does anything. [`pgrundev/pgboxdb-plugin`](https://github.com/pgrundev/pgboxdb-plugin)
  307. holds only the plugin (about 110 KB, generated from this repository), so
  308. the install takes seconds; adding this repository itself as the marketplace
  309. works too but clones about 2 GB. The lifecycle, security rules and host
  310. differences: [`agents.md`](docs/pgboxdb/local-dev/agents.md),
  311. [`claude-plugin.md`](docs/pgboxdb/local-dev/claude-plugin.md); the Skill
  312. itself: [`skills/pgboxdb/SKILL.md`](skills/pgboxdb/SKILL.md).
  313. ### One Git branch, one isolated Postgres
  314. ```bash
  315. cd my-project
  316. pgboxdb git init # main database, first main snapshot, Git hooks
  317. git switch -c feature/auth # ✓ PGBoxDB database ready: feature/auth (cloned from main in ~40 ms)
  318. pgboxdb git exec -- bin/rails db:migrate
  319. git switch main # main's database again; feature/auth keeps its migrations
  320. pgboxdb git sync # publish main's new schema as the next immutable snapshot
  321. git switch -c feature/billing # starts from the latest validated main snapshot
  322. pgboxdb git status
  323. ```
  324. Plain `git switch` stays plain Git: the hooks create or reuse the branch's
  325. copy-on-write database, worktrees get their own, main updates never replace
  326. an existing branch database, and every AI agent session on a branch still
  327. gets a private copy of that branch's database. A hook cannot change your
  328. shell's environment, so commands run with `pgboxdb git exec -- …`, or
  329. `pgboxdb git install-shell` refreshes `DATABASE_URL` at every prompt. Details:
  330. [`git.md`](docs/pgboxdb/local-dev/git.md).
  331. ### Watch every agent's database live
  332. ```bash
  333. pgboxdb top # project → Git branch → session → subagent, live connections, TTLs, lifecycle
  334. pgboxdb top --demo # try it without PGBoxDB: a simulated session with five agents
  335. pgboxdb agent activity --state testing --task "Implement OAuth" # what an agent reports shows in TASK
  336. ```
  337. Read-only and native (a Ratatui terminal UI); `pgboxdb --json top --snapshot`
  338. gives the same view as one JSON object. Details:
  339. [`top.md`](docs/pgboxdb/local-dev/top.md).
  340. ### Keep your Postgres, branch it in PGBoxDB (by hand)
  341. The same thing without an agent. Copy PostgreSQL into PGBoxDB once, then give
  342. every agent its own branch. The source is only read; PostgreSQL stays your
  343. source of truth.
  344. ```bash
  345. PGBOXDB_PORT=5433 npx pgboxdb@latest # PGBoxDB beside PostgreSQL on 5432
  346. # Import PostgreSQL once (pg_dump → pg_restore, read-only on the source)
  347. pgboxdb copy --from "$DATABASE_URL" --to myapp --schema-only
  348. # Give each AI agent its own database (isolated, self-expiring after 2h)
  349. pgboxdb branch myapp agent-1
  350. pgboxdb branch myapp agent-2
  351. pgboxdb agent exec -- bin/rails test # or: any command in a branch of its own
  352. ```
  353. `--schema-only` copies the structure without the rows (migration bookkeeping
  354. such as `schema_migrations` is kept). The copy needs `pg_dump`/`pg_restore`
  355. on the machine, refuses sources that use extensions PGBoxDB does not ship
  356. (PostGIS, TimescaleDB, …) and never overwrites an existing database.
  357. Details, limitations and measurements: [`copy.md`](docs/pgboxdb/local-dev/copy.md).
  358. ## Documentation
  359. The documentation site is [pgbox.dev/db](https://pgbox.dev/db); the files below are its source.
  360. Upgrading an installation made before the rename to PGBoxDB: see
  361. [`local-dev/upgrading.md`](docs/pgboxdb/local-dev/upgrading.md) (`pgboxdb migrate`).
  362. | Document | What's in it |
  363. |---|---|
  364. | [`benchmarks.md`](docs/pgboxdb/benchmarks.md) | every benchmark table, isolation results, and how to reproduce them |
  365. | [`linux-results.md`](docs/pgboxdb/linux-results.md) | the full benchmark report |
  366. | [`v0.1-baseline.md`](docs/pgboxdb/v0.1-baseline.md) | the frozen v0.1 numbers and the build each came from |
  367. | [`v0.1-readiness.md`](docs/pgboxdb/v0.1-readiness.md) | what is ready, known limitations, approved use |
  368. | [`compatibility-gate.md`](docs/pgboxdb/compatibility-gate.md) | how to decide whether a database can run on PGBoxDB |
  369. | [`local-dev/`](docs/pgboxdb/local-dev/) | install, CLI, integrations, storage, TTL, troubleshooting |
  370. | [`local-dev/build-from-source.md`](docs/pgboxdb/local-dev/build-from-source.md) | build the engine, run a bare runtime, seal a template and mint databases by hand |
  371. | [`local-dev/claude-plugin.md`](docs/pgboxdb/local-dev/claude-plugin.md) | the PGBoxDB plugin for Claude Code and the lightweight `pgrundev/pgboxdb-plugin` repository |
  372. | [`local-dev/agents.md`](docs/pgboxdb/local-dev/agents.md) | the PGBoxDB Skill and `pgboxdb agent`: automatic per-session isolation for Claude Code, Cursor and Codex |
  373. | [`local-dev/git.md`](docs/pgboxdb/local-dev/git.md) | PGBoxDB Git: one database per Git branch and worktree, main snapshots, shell integration, agents |
  374. | [`local-dev/copy.md`](docs/pgboxdb/local-dev/copy.md) | `pgboxdb copy`: import an existing PostgreSQL database and branch it per agent |
  375. | [`local-dev/top.md`](docs/pgboxdb/local-dev/top.md) | `pgboxdb top`: a live, read-only terminal view of the runtime, its databases and every agent session; `pgboxdb agent activity` task phases |
  376. | [`pgrun-integration.md`](docs/pgboxdb/pgrun-integration.md) | the host-agent API PGRun builds against |
  377. | [`lifecycle-memory.md`](docs/pgboxdb/lifecycle-memory.md), [`linux-churn.md`](docs/pgboxdb/linux-churn.md) | memory under long churn, and what was fixed |
  378. | [`zfs-cow.md`](docs/pgboxdb/zfs-cow.md) | copy-on-write branch cost and the recordsize trade-off |
  379. | [`linux-limits.md`](docs/pgboxdb/linux-limits.md) | memory limits and the cgroup backstop |
  380. ## Contributing
  381. PGBoxDB is early, and the most useful contribution is a concrete
  382. compatibility case. If something works on PostgreSQL 18 and behaves
  383. differently on PGBoxDB, open an issue with:
  384. ```text
  385. PostgreSQL version
  386. PGBoxDB version
  387. minimal SQL reproduction
  388. expected result
  389. actual result
  390. ```
  391. The areas where a case helps most: MVCC, locking, deadlocks, isolation
  392. levels, transactional DDL, ORMs (Rails, Django, Prisma, SQLAlchemy),
  393. schema migrations and client compatibility. Every real compatibility bug
  394. becomes a permanent regression test.
  395. <p align="center">
  396. <a href="https://star-history.com/#pgrundev/pgboxdb&Date"><img alt="GitHub star history of pgrundev/pgboxdb" src="docs/pgboxdb/img/star-history.png" width="720"></a>
  397. </p>
  398. ## Origin
  399. PGBoxDB is built on [pgrust](https://github.com/malisper/pgrust), a
  400. PostgreSQL-compatible database written in Rust. We are grateful to the
  401. pgrust project and its contributors for the foundation PGBoxDB builds on.
  402. PGBoxDB narrows that foundation to one problem, high-density disposable
  403. Postgres-compatible databases for agents and tests, and its own changes
  404. concentrate on shared database state, lifecycle and churn, density,
  405. memory containment, copy-on-write branching, fast minting and agent/test
  406. compatibility.
  407. ## License
  408. PGBoxDB is licensed under [AGPL-3.0](LICENSE). Portions derived from PostgreSQL
  409. remain under the PostgreSQL License; see [`NOTICE`](NOTICE).
  410. ---
  411. Production PostgreSQL is optimized to live for years. PGBoxDB is optimized to
  412. live for minutes.
  413. **One runtime. Thousands of isolated databases. Postgres for agents.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.