microsoft/pg_durable

pg_durable란?

pg_durable는 장기 실행되고 내결함성이 있는 워크플로우를 SQL로 직접 작성할 수 있는 PostgreSQL 확장 프로그램입니다. 내구성 함수는 SQL 단계의 그래프입니다. 확장 프로그램은 각 단계 후 진행 상황을 체크포인트하고, 상태를 데이터베이스 내에 저장하며, 충돌, 재시작 또는 단계 실패 후 자동으로 재개합니다. 외부 오케스트레이터, 큐, cron 서비스가 필요 없습니다 – 모든 것이 Rust로 작성된 백그라운드 작업자로 PostgreSQL 서버 내에서 실행됩니다.

누가 고려해야 하나요?

백엔드/데이터 엔지니어 – 데이터를 Postgres에 저장하고 있으며 오케스트레이션 로직을 데이터 옆에 두고 싶은 분.
DBA 및 SRE – 재시작 후에도 유지되고 SQL로 감사할 수 있는 안정적인 런북이 필요한 분.
데이터 또는 AI 파이프라인 (예: 벡터 임베딩, 수집, 강화)을 구축하고 있으며 행 단위 또는 배치 수준의 내구성이 필요한 팀.

핵심 아이디어 및 작동 방식

워크플로우 정의 – 작은 SQL DSL(|=>, ~>, df.if(), df.join() 등)을 사용합니다.
시작 – df.start(...)로 시작합니다. 호출은 인스턴스 ID를 반환합니다.
백그라운드 작업자(내구성 런타임)가 각 단계를 실행하고 체크포인트 데이터를 duroxide.* 스키마에 영구 저장합니다.
서버가 충돌하거나 단계가 실패하면 마지막 체크포인트에서 자동으로 재개됩니다.
상태 조회 – df.instances 및 df.nodes와 같은 테이블에서 워크플로우 실행 중 또는 완료 후에 조회합니다.

빠른 예제

SELECT df.start(
    'SELECT id FROM documents WHERE processed = false LIMIT 100' |=> 'batch'
    ~> 'UPDATE documents SET processed = true WHERE id IN (SELECT id FROM $batch.*)'
);

이 예제는 처리되지 않은 행의 배치를 선택한 다음 업데이트하는 내구성 함수를 만듭니다. 데이터베이스가 중간에 재시작되면 업데이트 단계는 이미 처리된 행에 대해 다시 실행되지 않습니다.

일반적인 사용 사례

벡터 임베딩 파이프라인 – 텍스트를 청크로 나누고, 외부 임베딩 API를 호출하고, 결과를 pgvector에 upsert합니다.
수집 파이프라인 – 대규모 배치를 스테이징, 중복 제거, 변환, 게시합니다.
예약 유지 관리 – 블로트 감지, 알림, 승인 대기, 정리 실행.
팬아웃 집계 – 독립적인 쿼리를 병렬로 실행하고 결과를 결합합니다.
외부 API 워크플로우 – df.http()를 사용한 강화, 분류 또는 웹훅 스타일 호출.

사용하지 말아야 할 경우

작업이 단일 단순 INSERT … SELECT 또는 기타 일회성 문인 경우.
서브밀리초 동기 요청 처리가 필요한 경우(pg_durable은 백그라운드 작업용입니다).
환경에서 확장 프로그램이나 백그라운드 작업자 설치를 허용하지 않는 경우.
워크플로우가 많은 이기종 시스템에 걸쳐 있고 SQL로 깔끔하게 표현할 수 없는 경우.
SQL 함수나 HTTP 호출로 래핑할 수 없는 임의의 프로세스 내 코드가 필요한 경우.

설치 및 시작하기

전제 조건 – PostgreSQL 17 또는 18, 개발 헤더, Rust 툴체인, cargo-pgrx(v0.16.1).
설치 방법 선택:
- Debian 패키지 – GitHub 릴리스에서 .deb를 다운로드하고 dpkg로 설치합니다.
- PGXN – pgxn install --sudo -- pg_durable(소스에서 빌드).
- Docker 이미지 – ghcr.io/microsoft/pg_durable:pg17(또는 pg18). 이 이미지는 공식 Postgres 이미지 위에 확장 프로그램을 사전 설치합니다.
postgresql.conf의 shared_preload_libraries에 pg_durable을 추가하고 재시작합니다.
대상 데이터베이스(기본값 postgres)에서: CREATE EXTENSION pg_durable;
애플리케이션 역할에 사용 권한을 부여합니다. 예: SELECT df.grant_usage('app_role');.

전체 단계별 가이드는 리포지토리의 User Guide 및 Quick Example 섹션에 있습니다.

제한 사항 및 고려 사항

모델은 SQL 중심입니다. 임의 코드는 SQL 함수로 래핑하거나 HTTP 엔드포인트(df.http())를 통해 노출해야 합니다.
백그라운드 작업자 역할(pg_durable.worker_role)은 행 수준 보안을 우회하여 모든 사용자의 인스턴스를 관리하므로 슈퍼유저여야 합니다.
게시된 Docker 이미지는 평가 전용입니다 – 슈퍼유저 내구성 인스턴스와 제한된 HTTP 보안으로 실행됩니다.
arm64 Docker 이미지는 아직 없습니다. Debian 패키지를 사용할 수 있게 되면 추가될 예정입니다.
Windows 소스 빌드는 지원되지 않습니다.

자세히 알아보기

웹사이트 및 문서 – https://microsoft.github.io/pg_durable/
사용자 가이드 – USER_GUIDE.md
예제 – examples/README.md
아키텍처 개요 – README의 다이어그램 및 연결된 duroxide 라이브러리.

요약: pg_durable는 내구성 있고 체크포인트된 워크플로우 패턴을 PostgreSQL 내부로 가져와 팀이 외부 cron/worker 설정을 상태를 영구 저장하고 자동으로 재시도하며 SQL로 완전히 관찰 가능한 단일 확장 프로그램으로 대체할 수 있게 합니다.