pgrundev/pgx

이것이 무엇인가

PGX “Postgres for agents” 는 단일 프로세스 내에서 수명이 짧은 여러 Postgres 호환 데이터베이스를 실행하는 데이터베이스 런타임입니다. Postgres 와이어 프로토콜과 SQL 방언을 사용하므로 프레임워크 도구(Rails, Django, Prisma, SQLAlchemy, node-postgres)는 수정 없이 전체 마이그레이션 → 테스트 → 스키마 변경 수명 주기를 실행합니다.

해결하는 문제

오늘날 하나의 데이터베이스는 하나의 PostgreSQL 서버, 즉 프로세스, 수십 메가바이트의 메모리, 그리고 매번 콜드 스타트를 의미합니다. 에이전트 워크플로, CI 작업, 테스트 스위트, 미리보기 환경은 데이터베이스를 지속적으로 생성하고 몇 분 또는 몇 시간 후에 폐기합니다. PGX는 이를 다른 수명 주기로 대체합니다:

밀봉된 템플릿 → 데이터베이스 생성(밀리초, copy-on-write) → 에이전트/CI/테스트가 사용 → 폐기

1 데이터베이스 → 1 PostgreSQL 서버 대신, PGX는 1 PGX 런타임 → 수백 또는 수천 개의 격리된 데이터베이스를 실행합니다.

작동 방식 (주요 아이디어)

• 불변 상태는 모두 공유하고, 분기된 부분에 대해서만 비용을 지불합니다. 동일한 템플릿에서 복제된 모든 데이터베이스는 불변 상태(메모리(카탈로그 캐시) 및 스토리지(변경되지 않은 블록))를 공유합니다. 각 데이터베이스는 주로 차이가 나는 부분에 대해서만 비용을 지불합니다.
• 공유 런타임. 데이터베이스는 단일 프로세스 내에서 이름, 역할 및 제한에 따라 격리됩니다. 데이터베이스는 전체 서버가 아닌 카탈로그 캐시만 비용으로 지불합니다.
• 연결 시 생성. <prefix><template>__<token>과 같은 특수 이름에 연결하면 밀봉된 템플릿에서 해당 데이터베이스를 생성하고 연결합니다. 미리 생성된 예비 풀이 버스트를 처리합니다.
• Copy-on-write 스토리지. ZFS 파일 시스템에서 file_copy_method = clone을 사용하면 10GB 데이터베이스의 분기가 변경되지 않은 모든 블록을 템플릿과 공유합니다. 약 674ms 만에 준비되며 새 물리적 스토리지는 약 13.6MB에 불과합니다. 블록 복제가 없는 파일 시스템에서는 전체 복사본입니다.
• 모든 수준에서 제한. 엔진 내부의 세션, 데이터베이스 및 런타임 메모리 제한, 데이터베이스별 연결 제한, 그리고 마지막 백스톱으로 런타임 주변의 Linux cgroup이 있습니다.

주요 측정 수치

벤치마크는 PostgreSQL 자체 테스트 스위트와 ZFS 블록 복제가 있는 4 vCPU / 8GB Linux VPS에서 가져왔습니다(하네스는 benchmarks/에 있음). 모든 수치는 설명된 구성이며 일반적 우월성을 주장하는 것이 아닙니다.

영역	수치
데이터베이스 생성(웜 풀, p50)	~6.2ms
터치되지 않은 유휴 데이터베이스당 메모리	~70KB
한 번의 쿼리 후 유휴 데이터베이스당 메모리	~128KB
단일 4 vCPU / 8GB VM의 데이터베이스 수	1,000
1,000개의 터치되지 않은 데이터베이스가 있는 총 런타임 메모리	128–155MB
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 통과
10GB 템플릿의 분기 (ZFS clone)	~674ms 준비, ~13.6MB 새 스토리지
긴 변동: 30,000회 생성→사용→폐기 수명 주기	총 런타임 메모리 ~111MB
PostgreSQL 18 대비 쿼리 속도	짧은 문: ~0.05–0.15ms 느림; 대규모 단일 스레드 스캔: 1.5–2.2배 느림; COPY 및 4클라이언트 처리량 동일

PGX는 단일 쿼리에서 Postgres를 능가하려고 하지 않습니다 — 강점은 생성 지연 시간, 밀도, 메모리 효율성, copy-on-write 스토리지, 높은 변동, 그리고 테넌트별 격리입니다.

이것이 아닌 것 (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분 copy-on-write 분기
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에 대한 것입니다.