pg_retry

在临时错误中使用指数退避重试语句

概览

扩展包名版本分类许可证语言
pg_retry1.0.0UTILPostgreSQLC
ID扩展名BinLibLoadCreateTrustReloc模式
4100pg_retry-

版本

类型仓库版本PG 大版本包名依赖
EXTPIGSTY1.0.01817161514pg_retry-
RPMPIGSTY1.0.01817161514pg_retry_$v-
DEBPIGSTY1.0.01817161514postgresql-$v-retry-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
el8.aarch64PIGSTY MISSPIGSTY MISSPIGSTY MISS
el9.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
el9.aarch64PIGSTY MISSPIGSTY MISSPIGSTY MISS
el10.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
el10.aarch64PIGSTY MISSPIGSTY MISSPIGSTY MISS
d12.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
d12.aarch64PIGSTY MISSPIGSTY MISSPIGSTY MISS
d13.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
d13.aarch64PIGSTY MISSPIGSTY MISSPIGSTY MISS
u22.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
u22.aarch64
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY MISSPIGSTY MISSPIGSTY MISS
u24.x86_64PIGSTY MISSPIGSTY MISSPIGSTY MISS
u24.aarch64
PIGSTY 1.0.0
PIGSTY 1.0.0
PIGSTY MISSPIGSTY MISSPIGSTY MISS

构建

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

pig build pkg pg_retry         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_retry 扩展包的预置二进制包,首先确保 PGDGPIGSTY 仓库已经添加并启用:

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

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

pig install pg_retry;          # 当前活跃 PG 版本安装
pig ext install -y pg_retry -v 18  # PG 18
pig ext install -y pg_retry -v 17  # PG 17
dnf install -y pg_retry_18       # PG 18
dnf install -y pg_retry_17       # PG 17
apt install -y postgresql-18-retry   # PG 18
apt install -y postgresql-17-retry   # PG 17

创建扩展

CREATE EXTENSION pg_retry;

用法

pg_retry: 在瞬态错误时使用指数退避重试 SQL 语句

函数签名

retry.retry(
  sql TEXT,                          -- 要执行的 SQL 语句(仅限一条)
  max_tries INT DEFAULT 3,           -- 总尝试次数(1 + 重试次数),>= 1
  base_delay_ms INT DEFAULT 50,      -- 初始退避延迟(毫秒)
  max_delay_ms INT DEFAULT 1000,     -- 指数退避延迟上限
  retry_sqlstates TEXT[] DEFAULT ARRAY['40001','40P01','55P03','57014']
) RETURNS INT                       -- 处理的行数

默认可重试的 SQLSTATE:40001(序列化失败)、40P01(检测到死锁)、55P03(锁不可用)、57014(查询被取消)。

示例

使用默认参数重试:

SELECT retry.retry('UPDATE accounts SET balance = balance - 100 WHERE id = 1');

自定义重试参数:

SELECT retry.retry(
    'INSERT INTO audit_log (event) VALUES (''test'')',
    5,      -- max_tries
    100,    -- base_delay_ms
    5000    -- max_delay_ms
);

GUC 配置

ALTER SYSTEM SET pg_retry.default_max_tries = 5;
ALTER SYSTEM SET pg_retry.default_base_delay_ms = 100;
ALTER SYSTEM SET pg_retry.default_max_delay_ms = 5000;
ALTER SYSTEM SET pg_retry.default_sqlstates = '40001,40P01,55P03,57014';
SELECT pg_reload_conf();

安全规则

  • 每次调用只能执行一条 SQL 语句(多条语句会失败)
  • 禁止使用事务控制语句(BEGIN、COMMIT、ROLLBACK)
  • 参数会被校验(max_tries >= 1,延迟不能为负值,base <= max delay)

最后修改 2026-03-14: update extension metadata (953cbd0)