pg_durable：微软开源 PostgreSQL 内持久执行扩展 - CodeMart

pg_durable：PostgreSQL 内的持久执行

Microsoft 开源了 pg_durable，一个 PostgreSQL 扩展，为那些已经在 Postgres 中存储状态、希望停止拼凑 cron 任务、worker、队列和状态表来使后台工作可靠的团队，提供长时间运行、容错的 SQL 函数。

核心理念

pg_durable 函数是一个 SQL 步骤图，PostgreSQL 按顺序执行并在过程中进行 checkpoint。如果数据库崩溃、重启或某一步骤失败，执行会从最后一个持久 checkpoint 恢复，而不是让你手动重建状态。

适用场景

向量嵌入管道：分块、调用嵌入 API、upsert 到 pgvector
数据注入管道：暂存、去重、转换并发布大批量数据
定时维护：检测膨胀、通知、等待批准，然后执行下一步
扇出聚合：并行运行独立查询，然后合并结果
外部 API 工作流：从 SQL 中进行富化、分类和 webhook 式调用

你当前可能正在用的替代方案

pg_cron + 任务表、状态列、重试计数器和轮询 worker
外部编排器（如 Airflow、Temporal、Step Functions、Argo）回调 Postgres
队列 + worker + 独立状态表来协调重试和部分完成
一个 plpgsql 过程，直到崩溃或长事务迫使你重新开始

解决的问题

长任务中间重启需要重做已成功的工作
单行失败或单次 API 调用失败导致手动清理和不确定的重放
长事务持有锁、增长 WAL，使批处理作业在大规模下变得脆弱
应用层的并行工作创造了更多部分失败 bug 和漂移的机会
工作流逻辑最终分散在 SQL、worker、队列、仪表盘和状态表中

架构变化

工作流定义移入 SQL，以 df.start(...) 开始
重试状态、进度跟踪和 checkpoint 移入 Postgres，而不是定制应用代码
一些应用层 worker、队列消费者或调度器胶水可以完全消失
运维可见性来自 Postgres 表（如 df.instances），使用与数据相同的认证和备份模型

何时不使用

任务已经是单个 INSERT ... SELECT 或一个普通 SQL 语句
需要亚毫秒级同步请求处理，而不是持久后台执行
无法在 Postgres 环境中安装扩展或运行后台 worker
工作流主要存在于 Postgres 之外，跨越多个异构系统
需要无法清晰映射到 SQL 步骤、分支、循环或 HTTP 调用的任意应用逻辑

工作原理

使用可组合操作符（如 ~> 和 |=>）在 SQL 中定义工作流
使用 df.start() 启动，获取实例 ID
让运行时持久地执行每一步，并在步骤之间进行 checkpoint
在工作流运行期间或完成后，从 PostgreSQL 查询状态和结果

特性

持久化：函数状态持久化到 PostgreSQL。能承受崩溃、重启和故障转移
SQL 原生：使用可组合操作符在 SQL 中定义函数
数据库感知：为调度、条件和并行执行提供一等公民原语
零基础设施：作为 PostgreSQL 扩展运行。无需 Redis、Temporal 或外部服务

快速示例

1
2
3
4
5
-- 一个持久函数，分步处理数据
SELECT df.start(
  'SELECT id FROM documents WHERE processed = false LIMIT 100'
  |=> 'batch' ~> 'UPDATE documents SET processed = true WHERE id = ANY($batch)'
);

限制

该模型有意设计为 SQL 形态。如果一个步骤需要任意代码、非 HTTP SDK 或丰富的内存控制流，你可能需要将该逻辑包装在 SQL 函数中、通过 HTTP 端点暴露给 df.http()，或对该部分系统使用通用编排器。

安装

支持 PostgreSQL 17 和 18（amd64），提供 Debian 包
作为扩展安装：CREATE EXTENSION pg_durable;
开发需要 Rust（nightly）、cargo-pgrx 0.16.1

多用户设置

安装后，管理员必须显式授予应用角色访问权限。行级安全（RLS）确保每个用户只能看到和管理自己的持久函数实例和节点。

架构

pg_durable 是一个用 pgrx 构建的 PostgreSQL 扩展——一切都在 PostgreSQL 服务器内部运行，无需外部服务。它暴露了一个 SQL DSL 用于构建函数图，并注册一个后台 worker 在其上执行。底层基于两个 Rust 库：

duroxide：提供编排运行时的持久任务框架（确定性重放、checkpoint、子编排、定时器）
duroxide-pg：为 duroxide 提供 PostgreSQL 支持的状态提供者，将运行时状态持久化在扩展拥有的 duroxide.* 模式中