pg_durable

概览

Requires shared_preload_libraries=pg_durable and a superuser worker role. Upstream README targets PG17; DEB validated PG14-18 on u24a arm64, RPM spec targets PG14-18; pgrx patched to 0.18.1.

版本

构建

您可以使用 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
• dnf
• apt

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;

来源：pg_durable v0.2.2 README、User Guide、control file、GUC definitions。

用法

pg_durable 在 PostgreSQL 内运行持久、容错的 SQL 工作流。工作流由 SQL 字符串、函数和 DSL 操作符组成，并通过 df.start() 提交。状态会持久化在 PostgreSQL 中，因此崩溃或重启后已完成的步骤不会被重复执行。

pg_durable 必须通过 shared_preload_libraries 加载，然后重启 PostgreSQL。它的后台 worker 会连接到 pg_durable.database 指定的数据库，并以 pg_durable.worker_role 运行；上游默认值分别为 postgres 和 azuresu，且 worker role 必须是 superuser。

启用并授权访问

CREATE EXTENSION pg_durable;

SELECT df.grant_usage('app_role');

CREATE EXTENSION 不会把 usage 授给 PUBLIC。请为应用角色使用 df.grant_usage()，并在扩展升级后重新执行，确保新增加的函数也被覆盖。后台 worker 会在扩展创建后异步初始化；如果 df.* 调用报告 worker 尚未初始化，可以稍后重试。

启动并监控工作流

SELECT df.start('SELECT ''Hello, durable world!''', 'hello-job');

SELECT *
FROM df.list_instances();

SELECT df.status('a1b2c3d4');
SELECT df.result('a1b2c3d4');
SELECT df.cancel('a1b2c3d4', 'No longer needed');

df.start() 返回一个 instance ID。使用该 ID 调用 df.status()、df.result()、df.cancel()、df.signal() 和 df.explain()。

组合 SQL 步骤

-- Run one step, name its result, then substitute it in the next step.
SELECT df.start(
  'SELECT 100 AS amount' |=> 'total'
  ~> 'SELECT $total * 2 AS doubled',
  'double-total'
);

-- Branch on a SQL condition.
SELECT df.start(
  'SELECT count(*) > 10 FROM orders'
    ?> 'SELECT ''high volume'''
    !> 'SELECT ''low volume''',
  'order-volume'
);

-- Run in parallel and wait for both branches.
SELECT df.start(
  'SELECT refresh_accounts()' & 'SELECT refresh_orders()',
  'parallel-refresh'
);

核心操作符包括表示顺序执行的 ~>、为结果命名的 |=>、join 的 &、race 的 |、条件分支 ?> 和 !>，以及循环 @>。

定时器、计划任务与信号

SELECT df.start(
  @> (
    df.wait_for_schedule('0 * * * *')
    ~> 'SELECT run_hourly_rollup()'
  ),
  'hourly-rollup'
);

SELECT df.start(
  'SELECT create_invoice()' |=> 'invoice'
  ~> df.wait_for_signal('approval', 86400)
  ~> 'SELECT finalize_invoice($invoice.id)',
  'invoice-approval'
);

常用 DSL 函数包括 df.sleep(seconds)、df.wait_for_schedule(cron)、df.wait_for_signal(name, timeout)、df.signal(id, name, data)、df.join()、df.race()、df.if()、df.loop() 和 df.explain()。

配置与注意事项

• 必需 preload：把 pg_durable 加入 shared_preload_libraries 并重启 PostgreSQL。
• pg_durable.database 必须指向创建该扩展的数据库；工作流不会在其他数据库中被处理。
• pg_durable.worker_role 必须存在且为 superuser，因为 worker 会绕过 RLS 来管理所有用户的实例。
• 连接相关 GUC 包括 pg_durable.max_management_connections、pg_durable.max_duroxide_connections、pg_durable.max_user_connections 和 pg_durable.execution_acquire_timeout。
• df.http() 会执行出站 HTTP 工作，除非使用 df.grant_usage(..., include_http => true)，否则不会包含在标准授权中。
• 上游将 v0.2.2 标记为早期开发版本，尚不适合生产环境。