pg_durable

概览

Requires preload and a superuser worker role; pgrx 0.19.2.

版本

构建

您可以使用 pig build 命令构建 pg_durable 扩展的 RPM / DEB 包：

pig build pkg pg_durable         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_durable 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install pg_durable;          # 当前活跃 PG 版本安装

pig ext install -y pg_durable -v 18  # PG 18
pig ext install -y pg_durable -v 17  # PG 17
pig ext install -y pg_durable -v 16  # PG 16
pig ext install -y pg_durable -v 15  # PG 15
pig ext install -y pg_durable -v 14  # PG 14

dnf install -y pg_durable_18       # PG 18
dnf install -y pg_durable_17       # PG 17
dnf install -y pg_durable_16       # PG 16
dnf install -y pg_durable_15       # PG 15
dnf install -y pg_durable_14       # PG 14

apt install -y postgresql-18-pg-durable   # PG 18
apt install -y postgresql-17-pg-durable   # PG 17
apt install -y postgresql-16-pg-durable   # PG 16
apt install -y postgresql-15-pg-durable   # PG 15
apt install -y postgresql-14-pg-durable   # PG 14

预加载配置：

shared_preload_libraries = 'pg_durable';

创建扩展：

CREATE EXTENSION pg_durable;

用法

来源：

• PGXN 0.2.6 README
• 0.2.6 用户指南
• 0.2.6 变更日志
• pg_durable 控制文件
• 0.2.5 至 0.2.6 升级 SQL

pg_durable 在PostgreSQL中运行持久、容错的SQL工作流。一个工作流是一系列SQL步骤、定时器、信号、条件和并行分支组成的图，通过df.start()提交。执行状态会在PostgreSQL中进行检查点记录，因此在崩溃、重启或重试后不会重复已完成的步骤。

启用和授权访问

预加载工作进程，如果默认设置不合适，则选择其数据库和超级用户角色，然后重启PostgreSQL：

shared_preload_libraries = 'pg_durable'
pg_durable.database = 'postgres'
pg_durable.worker_role = 'postgres'

在pg_durable.database中创建扩展，并授予应用程序登录角色访问权限：

CREATE EXTENSION pg_durable;
SELECT df.grant_usage('app_role');

工作进程角色必须是超级用户，因为它会管理所有用户的实例并绕过行级安全。调用df.start()的角色必须具有LOGIN权限，因为工作流SQL是通过该捕获角色认证的连接执行的。

构建和运行一个工作流

SELECT df.start(
    'SELECT 100 AS amount' |=> 'total'
    ~> 'SELECT $total.amount * 2 AS doubled',
    'double-total'
);

df.start()返回实例ID。使用它来监控或控制运行：

SELECT df.status('a1b2c3d4');
SELECT df.result('a1b2c3d4');
SELECT * FROM df.instance_nodes('a1b2c3d4');
SELECT * FROM df.instance_executions('a1b2c3d4', 20);
SELECT df.cancel('a1b2c3d4', 'No longer needed');

DSL索引

• ~> 用于序列化步骤；|=> 为$name、$name.column 或 $name.* 替换命名结果。
• & / df.join() 等待并行分支；| / df.race() 保留第一个结果。
• ?> 和 !> / df.if() 选择条件分支；@> / df.loop() 重复一个图。
• df.sleep()、df.wait_for_schedule() 和 df.wait_for_signal() 使等待持久化。
• df.signal()、df.wait_for_completion()、df.explain() 及实例检查函数操作正在运行或存储的实例。
• df.setvar()、df.getvar()、df.unsetvar() 和 df.clearvars() 管理在调用df.start()时捕获的用户变量。

0.2.6 版本边界

• 上游源码安装与发布镜像使用 pgrx 0.16.1，支持 PostgreSQL 17 与 18。扩展仍要求 shared_preload_libraries、重启以及超级用户工作角色。
• 经由 0.2.4 与 0.2.5 的升级包含会破坏重放的工作流变更。升级前应排空或取消运行中的 JOIN、RACE、循环与 df.wait_for_schedule() 工作；0.2.4 的 df.nodes 键迁移还会获取 ACCESS EXCLUSIVE 锁。
• df.start(..., transaction_mode => 'new') 会在调用者事务之外持久化独立启动。集群默认最多并发启动两个，由 pg_durable.max_new_transaction_starts 与 pg_durable.new_transaction_start_timeout 控制。
• 0.2.6 从左到右只解析一次变量替换，所以变量值引入的令牌形文本不会再次扫描。它仍是原始 SQL 替换；绝不能把不可信输入放进 {name} 变量。通过 $name 的命名步骤结果替换会执行 SQL 转义。
• 未公开的 df.ensure_durofut(text) 辅助函数已移除。升级前应删除或改写客户自有的依赖对象。
• 在 ALTER EXTENSION ... UPDATE 后重新运行 df.grant_usage()，因为对全部函数的授权不会自动覆盖后来新增的函数。
• df.http() 与 df.http_multipart() 的可用性和出站策略是编译时特性。其限制不会沙箱化任意 SQL 或其他已安装扩展。
• 项目仍处于 1.0 之前，上游发布的 Docker 镜像用于评估与学习，而不是生产。应阅读每个相邻版本的升级警告，不要假设未经测试的跨版本跳跃可安全重放。