pg_retry

Retry SQL statements on transient errors with exponential backoff

Overview

PackageVersionCategoryLicenseLanguage
pg_retry1.0.0UTILPostgreSQLC
IDExtensionBinLibLoadCreateTrustRelocSchema
4100pg_retryNoYesNoYesNoYes-

Version

TypeRepoVersionPG VerPackageDeps
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

Build

You can build the RPM / DEB packages for pg_retry using pig build:

pig build pkg pg_retry         # build RPM / DEB packages

Install

You can install pg_retry directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_retry;          # Install for current active PG version
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:

CREATE EXTENSION pg_retry;

Usage

pg_retry: Retry SQL statements on transient errors with exponential backoff

Function Signature

retry.retry(
  sql TEXT,                          -- SQL statement to run (exactly one)
  max_tries INT DEFAULT 3,           -- total attempts (1 + retries), >= 1
  base_delay_ms INT DEFAULT 50,      -- initial backoff delay in ms
  max_delay_ms INT DEFAULT 1000,     -- cap for exponential backoff
  retry_sqlstates TEXT[] DEFAULT ARRAY['40001','40P01','55P03','57014']
) RETURNS INT                       -- number of rows processed

Default retryable SQLSTATEs: 40001 (serialization_failure), 40P01 (deadlock_detected), 55P03 (lock_not_available), 57014 (query_canceled).

Examples

Basic retry with defaults:

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

Custom retry parameters:

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

GUC Configuration

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();

Safety Rules

  • Only one SQL statement per call (multi-statement fails)
  • Transaction control statements (BEGIN, COMMIT, ROLLBACK) are prohibited
  • Parameters are validated (max_tries >= 1, non-negative delays, base <= max delay)

Last Modified 2026-03-12: add pg extension catalog (95749bf)