pgautofailover

Overview

Version

Install

You can install pgautofailover directly. First, make sure the PGDG repository is added and enabled:

pig repo add pgdg -u          # Add PGDG repo and update cache

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

• Install
• pig
• dnf
• apt

pig install pgautofailover;          # Install for current active PG version

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

dnf install -y pg_auto_failover_18       # PG 18
dnf install -y pg_auto_failover_17       # PG 17
dnf install -y pg_auto_failover_16       # PG 16
dnf install -y pg_auto_failover_15       # PG 15
dnf install -y pg_auto_failover_14       # PG 14

apt install -y postgresql-18-auto-failover   # PG 18
apt install -y postgresql-17-auto-failover   # PG 17
apt install -y postgresql-16-auto-failover   # PG 16
apt install -y postgresql-15-auto-failover   # PG 15
apt install -y postgresql-14-auto-failover   # PG 14

Preload:

shared_preload_libraries = 'pgautofailover';

Create Extension:

CREATE EXTENSION pgautofailover CASCADE;  -- requires: btree_gist

Usage

pgautofailover: pg_auto_failover

pg_auto_failover is an extension and service for automated PostgreSQL failover. It consists of a monitor node (running the pgautofailover extension), and keeper processes on each data node managed by the pg_autoctl CLI.

Architecture

• Monitor: a PostgreSQL instance with the pgautofailover extension that implements a state machine for failover decisions
• Keeper (pg_autoctl run): runs on each data node, reports health to the monitor and executes state transitions
• Supports 2+ node setups with synchronous replication by default
• Supports Citus HA (since v2.0)

Key CLI Commands

# Create the monitor
pg_autoctl create monitor --pgdata /path/to/monitor --pgport 5000

# Create a data node (primary or secondary auto-assigned)
pg_autoctl create postgres --pgdata /path/to/data --pgport 5001 --monitor postgres://monitor:5000/pg_auto_failover

# Run the keeper (foreground)
pg_autoctl run --pgdata /path/to/data

# Check cluster state
pg_autoctl show state --pgdata /path/to/monitor

# Perform a manual switchover
pg_autoctl perform switchover --pgdata /path/to/monitor

# Perform a manual failover
pg_autoctl perform failover --pgdata /path/to/monitor

Failover Behavior

The monitor tracks node health. When a secondary becomes unavailable or its lag is too high, it is removed from synchronous_standby_names on the primary. Failover/switchover operations are blocked until the secondary is healthy again, preventing data loss.

Documentation

Full documentation: pg-auto-failover.readthedocs.io