pg_durable: Microsoft open sources in-database durable execution

pg_durable：微软开源数据库内持久化执行引擎

Durable Execution inside PostgreSQL: Long-running, fault-tolerant SQL functions for teams that already keep their state in Postgres and want to stop stitching together cron jobs, workers, queues, and status tables to make background work reliable. PostgreSQL 内部的持久化执行：为那些已将状态存储在 Postgres 中，并希望摆脱通过拼接 cron 任务、工作进程、队列和状态表来确保后台任务可靠性的团队，提供长运行、容错的 SQL 函数。

Define the workflow in SQL, let pg_durable checkpoint each step, and resume after crashes, restarts, or failed steps. Durable execution is now a standard industry pattern, and pg_durable brings it inside Postgres with no extra service infrastructure required. Part of our mission to bring compute close to data. 在 SQL 中定义工作流，让 pg_durable 对每一步进行检查点（checkpoint）记录，并在崩溃、重启或步骤失败后恢复执行。持久化执行现已成为行业标准模式，而 pg_durable 将其引入 Postgres 内部，无需额外的服务基础设施。这是我们将计算能力带向数据所在之处这一使命的一部分。

Try pg_durable now in Azure HorizonDB, Microsoft’s new PostgreSQL cloud service engineered for performance and built with pg_durable inside. 立即在 Azure HorizonDB 中尝试 pg_durable，这是微软全新的 PostgreSQL 云服务，专为高性能设计，并内置了 pg_durable。

Is this for me? Who it’s for

这适合我吗？适用人群

• Backend and data engineers who want workflows to live next to the data they touch.
• 后端和数据工程师：希望工作流与所处理的数据共存。
• DBAs and SREs automating runbooks that must survive restarts and be auditable in SQL.
• DBA 和 SRE：需要自动化那些必须在重启后存活且可在 SQL 中审计的运维手册（runbooks）。
• Teams building data or AI pipelines that need durable execution per row, document, or batch.
• 构建数据或 AI 流水线的团队：需要针对每一行、每一个文档或每一个批次进行持久化执行。

The core idea

核心理念

A pg_durable function is a graph of SQL steps that PostgreSQL executes and checkpoints as it goes. If the database crashes, restarts, or a step fails, execution resumes from the last durable checkpoint instead of making you reconstruct state by hand. pg_durable 函数是一个 SQL 步骤图，PostgreSQL 会在执行过程中对其进行检查点记录。如果数据库崩溃、重启或某个步骤失败，执行将从上一个持久化检查点恢复，而无需你手动重建状态。

Workloads this is useful for

适用工作负载

• Vector embedding pipelines: chunk, call an embedding API, and upsert into pgvector.
• 向量嵌入流水线：分块、调用嵌入 API，并 upsert 到 pgvector。
• Ingest pipelines: stage, deduplicate, transform, and publish large batches.
• 数据摄取流水线：暂存、去重、转换并发布大批量数据。
• Scheduled maintenance: detect bloat, notify, wait for approval, then run the next action.
• 计划内维护：检测膨胀、通知、等待审批，然后执行下一步操作。
• Fan-out aggregation: run independent queries in parallel, then join the results.
• 扇出聚合：并行运行独立查询，然后合并结果。
• External API workflows: enrichment, classification, and webhook-style calls from SQL.
• 外部 API 工作流：从 SQL 进行数据增强、分类和 Webhook 式调用。

What you’re probably doing today instead

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

• pg_cron 加上一个任务表、状态列、重试计数器和一个轮询工作进程。
• 外部编排器（如 Airflow、Temporal、Step Functions 或 Argo）回调到 Postgres。
• 队列加上工作进程，以及一个单独的状态表来协调重试和部分完成。
• 一个 plpgsql 存储过程，它能运行，直到崩溃或长事务迫使你从头开始。

Pain points it addresses

它解决的痛点

• 长任务中间的重启意味着必须重新运行已经成功的任务。
• 一行数据或一次 API 调用失败会导致手动清理和不确定的重试。
• 长事务会持有锁、增加 WAL 日志，并使批处理任务在大规模下变得脆弱。
• 应用层的并行工作创造了更多导致部分失败错误和数据漂移的地方。
• 工作流逻辑最终分散在 SQL、工作进程、队列、仪表板和状态表中。

What changes in your architecture

架构上的变化

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

When not to use it

何时不应使用

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

How it works

工作原理

Define a workflow in SQL using composable operators such as ~> and |=>. Start it with df.start() and get back an instance ID. Let the runtime execute each step durably with checkpointing between steps. Query status and results from PostgreSQL while the workflow runs or after it completes. 使用可组合运算符（如 ~> 和 |=>）在 SQL 中定义工作流。使用 df.start() 启动它并获取实例 ID。让运行时在步骤之间通过检查点持久化地执行每一步。在工作流运行期间或完成后，从 PostgreSQL 查询状态和结果。

Limitations

局限性

The model is intentionally SQL-shaped. If a step needs arbitrary code, a non-HTTP SDK, or rich in-memory control flow, you may need to wrap that logic in a SQL function, expose it behind an HTTP endpoint for df.http(), or use a general-purpose orchestrator for that part of the system. 该模型被刻意设计为 SQL 风格。如果某个步骤需要任意代码、非 HTTP SDK 或丰富的内存控制流，你可能需要将该逻辑封装在 SQL 函数中，通过 HTTP 端点暴露给 df.http()，或者在该系统部分使用通用编排器。

Features

特性

• Durable — Function state persists to PostgreSQL. Survives crashes, restarts, and failovers.
• 持久化 — 函数状态持久化到 PostgreSQL。可从崩溃、重启和故障转移中恢复。
• SQL-native — Define functions in SQL using composable operators.
• SQL 原生 — 使用可组合运算符在 SQL 中定义函数。
• Database-aware — First-class primitives for scheduling, conditions, and parallel execution.
• 数据库感知 — 提供用于调度、条件判断和并行执行的一等公民原语。
• Zero infrastructure — Runs as a PostgreSQL extension. No Redis, no Temporal, no external services.
• 零基础设施 — 作为 PostgreSQL 扩展运行。无需 Redis、Temporal 或外部服务。

Quick Example

快速示例

-- A durable function that processes data in steps
-- 一个分步处理数据的持久化函数
SELECT df.start(
  'SELECT id FROM documents WHERE processed = false LIMIT 100'
  |=> 'batch'
  ~> 'UPDATE documents SET processed = true WHERE id = ANY($batch)'
);