microsoft/pg_durable

什么是 pg_durable？

pg_durable 是一个 PostgreSQL 扩展，让您可以直接用 SQL 编写长时间运行、容错的工作流。持久函数 是 SQL 步骤的图形；扩展在每个步骤后检查点进度，将状态存储在数据库内，并在崩溃、重启或步骤失败后自动恢复。不需要外部编排器、队列或 cron 服务 – 一切都在 PostgreSQL 服务器内作为 Rust 编写的后台工作者执行。

谁应该考虑使用？

后端/数据工程师，他们已经将数据保存在 Postgres 中，并希望编排逻辑与数据放在一起。
DBA 和 SRE，他们需要可靠的 runbook，这些 runbook 能在重启后存活，并可透过 SQL 审计。
构建数据或 AI 管道（例如，向量嵌入、摄取、扩充）的团队，这些管道需要逐行或批次级别的持久性。

核心概念与运作方式

定义工作流，使用小型 SQL DSL（|=>、~>、df.if()、df.join() 等）。
启动它，使用 df.start(...)；调用会返回实例 ID。
后台工作者（持久运行时）执行每个步骤，将检查点数据持久化在 duroxide.* schema 中。
如果服务器崩溃或步骤失败，执行会从最后一个检查点自动恢复。
查询状态，从 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、将结果 upsert 到 pgvector。
摄取管道 – 暂存、去重、转换和发布大批次。
计划维护 – 检测膨胀、通知、等待批准，然后执行清理。
扇出聚合 – 并行执行独立查询并连接结果。
外部 API 工作流 – 通过 df.http() 进行扩充、分类或 webhook 式调用。

何时不应使用

作业是单一简单的 INSERT … SELECT 或其他一次性语句。
您需要亚毫秒、同步请求处理（pg_durable 用于后台工作）。
您的环境不允许安装扩展或后台工作者。
工作流跨越许多异构系统，无法用 SQL 干净地表达。
您需要无法包装在 SQL 函数或 HTTP 调用中的任意进程内代码。

安装与开始使用

先决条件 – PostgreSQL 17 或 18、开发头文件、Rust 工具链，以及 cargo-pgrx（v0.16.1）。
选择安装方法：
- Debian 包 – 从 GitHub release 下载 .deb，并使用 dpkg 安装。
- PGXN – pgxn install --sudo -- pg_durable（从源码构建）。
- Docker 镜像 – ghcr.io/microsoft/pg_durable:pg17（或 pg18）。此镜像在官方 Postgres 镜像之上预安装扩展。
在 postgresql.conf 中将 pg_durable 加入 shared_preload_libraries，然后重启。
在目标数据库（默认 postgres）中：CREATE EXTENSION pg_durable;
授予应用程序角色使用权限，例如 SELECT df.grant_usage('app_role');。

完整的逐步指南位于 repo 的 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 观察。