pgrundev/pgx

它是什么

PGX “Postgres for agents” 是一个数据库运行时，在单个进程内运行许多短期的、兼容 Postgres 的数据库。它使用 Postgres 的线协议和 SQL 方言，因此框架工具（Rails、Django、Prisma、SQLAlchemy、node-postgres）无需修改即可运行其完整的 migrate → test → schema-change 生命周期。

它解决的问题

今天，一个数据库意味着一个 PostgreSQL 服务器——一个进程、几十兆字节的内存，以及每次的冷启动。代理工作流、CI 作业、测试套件和预览环境会不断创建数据库，并在几分钟或几小时后将其丢弃。PGX 用不同的生命周期取代了这种模式：

密封模板 → 铸造数据库（毫秒级，写时复制） → 代理/CI/测试使用 → 丢弃

不是 1 个数据库 → 1 个 PostgreSQL 服务器，PGX 运行 1 个 PGX 运行时 → 数百或数千个隔离的数据库。

工作原理（主要思路）

• 共享所有不可变内容，仅为差异付费。 从同一模板克隆的所有数据库共享不可变状态——内存（目录缓存）和存储（未更改的块）都是如此。每个数据库主要为其差异部分付费。
• 共享运行时。 数据库在单个进程内通过名称、角色和限制进行隔离。一个数据库的成本是其目录缓存，而不是一个完整的服务器。
• 连接时铸造。 连接到像 <prefix><template>__<token> 这样的特殊名称会从密封模板创建该数据库并连接到它。预热池提供预创建的空闲数据库以应对突发流量。
• 写时复制存储。 在 ZFS 文件系统上使用 file_copy_method = clone，10 GB 数据库的分支与其模板共享每个未更改的块——准备时间约 674 毫秒，仅需约 13.6 MB 的新物理存储。在没有块克隆的文件系统上，则是完整复制。
• 每个级别都有限制。 引擎内的会话、数据库和运行时内存限制，每个数据库的连接限制，以及围绕运行时的 Linux cgroup 作为最终后备。

关键测量数据

基准测试来自 PostgreSQL 自己的测试套件，以及一个具有 ZFS 块克隆的 4 vCPU / 8 GB Linux VPS（测试工具位于 benchmarks/）。所有数据均为描述的配置，并非声称普遍优越。

领域	数值
数据库创建（预热池，p50）	~6.2 毫秒
每个未触碰的空闲数据库内存	~70 KB
执行一次查询后每个空闲数据库的内存	~128 KB
单个 4 vCPU / 8 GB 虚拟机上的数据库数量	1,000
1000 个未触碰数据库的总运行时内存	128–155 MB
PostgreSQL src/test/regress（PG 18.6 预期输出）	219 / 231 字节完全匹配；0 个结果差异（12 个仅在 EXPLAIN 计划文本上有所不同）
框架运行（Rails 8.1、Django 5.2、Prisma 6、SQLAlchemy 2、node-postgres）	36 / 36 通过
10 GB 模板的分支（ZFS 克隆）	准备时间约 674 毫秒，新增存储约 13.6 MB
长期轮换：30,000 次创建→使用→丢弃生命周期	总运行时内存约 111 MB
查询速度对比 PostgreSQL 18	短语句慢约 0.05–0.15 毫秒；大型单线程扫描慢 1.5–2.2 倍；COPY 和 4 客户端吞吐量相同

PGX 并不试图在单个查询上超越 Postgres——它的优势在于创建延迟、密度、内存效率、写时复制存储、高轮换率以及每租户隔离。

它不是（v0.1 限制）

README 明确说明：PGX v0.1 用于一次性数据库（代理、CI、PR、测试、预览），这些数据库由生产环境的净化副本构建。它不是生产主库、记录系统或 HA/PITR。具体差距：

• 不具备崩溃安全性 — 该配置文件使用 fsync = off 运行。
• 单进程 — 一个运行时是一个故障域。
• 无 C 扩展 — 无法加载 PostgreSQL C 扩展；仅内置 contrib 模块（包括 pgvector）。PL/Python、PL/Perl、PL/Tcl 不可用。
• 它处于 0.1.0 版本，是一个早期版本。

快速开始

一条命令即可安装、启动、创建 app 数据库，并打印连接 URL：

npx pgxdb@latest

然后将 DATABASE_URL 指向打印出的 URL。其他 CLI 命令（可通过 npx pgxdb <cmd> 或全局安装后的 pgx 使用）：

pgx clone app agent-001 --ttl 5m   # 5 分钟写时复制分支
pgx ls                             # 数据库、TTL、过期时间、大小
pgx create scratch --ttl 2h        # 自动删除的一次性数据库
pgx ttl pr-123 unlimited           # 更改分支的 TTL
pgx stop                           # 停止运行时

未使用 --ttl 创建的数据库是永久的；后台管理器会在临时数据库到期后将其丢弃，并在重启后恢复清理。二进制文件经过 SHA-256 验证并缓存于 ~/.pgx/dist/<version>。无需 Docker — 原生支持 Mac（Apple 芯片）和 Linux（arm64、x86-64）；不支持 Intel Mac。Shell 安装脚本（curl -fsSL https://pgx.dev/install | sh）可在无 Node 环境下使用。

与 PGRun 的关系

PGX 是 PGRun 中 PGX 分支背后的数据库引擎。PGRun 在其周围添加了控制平面——编排、路由、模板、生命周期、访问、分支管理、自动过期——而 PGX 是运行时。它们是独立的项目。

项目状态与贡献指南

项目表示正确性和可复现性优先于基准测试营销。它追踪 PostgreSQL 兼容性、Rails/应用程序兼容性、并发语义、生命周期正确性、资源隔离以及真实的代理工作负载。最有用的贡献是一个具体的兼容性案例：一个问题，包含 PostgreSQL 版本、PGX 版本、最小 SQL 复现、预期和实际结果——尤其是涉及 MVCC、锁、死锁、隔离级别、事务性 DDL 和 ORM 的问题。