pgrundev/pgx

PGX — Lightweight Postgres for AI agents. Written in Rust. Thousands of isolated databases in one runtime. 🐘

概要

PGX「Postgres for agents」 は、単一プロセス内で多数の短命なPostgres互換データベースを実行するデータベースランタイムです。PostgresのワイヤプロトコルとSQL方言を話すため、フレームワークツール（Rails、Django、Prisma、SQLAlchemy、node-postgres）は、変更なしで完全な移行→テスト→スキーマ変更のライフサイクルを実行できます。

解決する問題

今日、1つのデータベースは1つのPostgreSQLサーバーを意味します。プロセス、数十メガバイトのメモリ、そして毎回のコールドスタートです。エージェントワークフロー、CIジョブ、テストスイート、プレビュー環境は、絶えずデータベースを作成し、数分後または数時間後に破棄します。PGXはこれを異なるライフサイクルに置き換えます。

シールドテンプレート → データベースを作成（ミリ秒、コピーオンライト） → エージェント/CI/テストが使用 → 破棄

1データベース→1PostgreSQLサーバー の代わりに、PGXは 1つのPGXランタイム→数百または数千の分離されたデータベース を実行します。

仕組み（主なアイデア）

不変なものはすべて共有し、差分にのみコストを払う。 同じテンプレートからクローンされたすべてのデータベースは、不変状態（メモリ（カタログキャッシュ）とストレージ（変更されていないブロック））を共有します。各データベースは、主にそれを他と異なるものにしている部分にのみコストを支払います。
共有ランタイム。 データベースは、単一プロセス内で名前、ロール、制限によって分離されます。データベースのコストはカタログキャッシュであり、完全なサーバーではありません。
接続時に作成。 <プレフィックス><テンプレート>__<トークン> のような特別な名前への接続は、シールドテンプレートからそのデータベースを作成し、接続します。事前に作成されたスペアのウォームプールは、バーストに対応します。
コピーオンライトストレージ。 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
1回のクエリ後のアイドルデータベースあたりのメモリ	~128 KB
1台の4 vCPU / 8 GB VM上のデータベース数	1,000
1,000の未使用データベースでの総ランタイムメモリ	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、初期リリースです。

クイックスタート

1つのコマンドでインストール、起動、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はサポートされていません。シェルインストーラー（curl -fsSL https://pgx.dev/install | sh）はNodeなしで動作します。

PGRunとの関係

PGXは、PGRun のPGXブランチの背後にあるデータベースエンジンです。PGRunは、その周りにコントロールプレーン（オーケストレーション、ルーティング、テンプレート、ライフサイクル、アクセス、ブランチ管理、自動有効期限）を追加しますが、PGXはランタイムです。それらは別々のプロジェクトです。

プロジェクトの状態と貢献ガイドライン

プロジェクトは、正確性と再現性がベンチマークマーケティングに優先すると述べています。PostgreSQL互換性、Rails/アプリケーション互換性、並行性セマンティクス、ライフサイクルの正確性、リソース封じ込め、および実際のエージェントワークロードを追跡します。最も有用な貢献は、具体的な互換性ケースです：PostgreSQLバージョン、PGXバージョン、最小限のSQL再現、期待される結果と実際の結果を含む問題 — 特にMVCC、ロック、デッドロック、分離レベル、トランザクションDDL、およびORM関連。