microsoft/pg_durable

pg_durable とは？

pg_durable は、長時間実行され、フォールトトレラントなワークフロー を SQL で直接記述できる PostgreSQL 拡張機能です。永続関数 は SQL ステップのグラフです。拡張機能は各ステップの後に進行状況をチェックポイントし、状態をデータベース内に保存し、クラッシュ、再起動、またはステップの失敗後に自動的に再開します。外部のオーケストレーター、キュー、cron サービスは不要です – すべては Rust で書かれたバックグラウンドワーカーとして PostgreSQL サーバー内で実行されます。

誰が検討すべきか？

バックエンド/データエンジニア – データを Postgres に保存しており、オーケストレーションロジックをそのデータの隣に置きたいと考えている方。
DBA と SRE – 再起動後も存続し、SQL で監査できる信頼性の高い runbook が必要な方。
データまたは 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() を使用したエンリッチメント、分類、または webhook スタイルの呼び出し。

使用すべきでない場合

ジョブが単一の単純な 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/ワーカー設定を、状態を永続化し、自動的に再試行し、SQL で完全に観察可能な単一の拡張機能に置き換えることを可能にします。