Pgfailover Documentation

pgfailover monitors the state of a PostgreSQL cluster and acts as a TCP proxy for clients, directing them to the current Primary. When the Primary changes, pgfailover terminates client connections, and they must reconnect.

Connection parameters are specified via environment variables with the PGFAILOVER_ prefix:

export PGFAILOVER_BIND_ADDRESS=":5432"
export PGFAILOVER_SERVERS="postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5"
./pgfailover

The server role (Primary/Standby) is checked using pg_is_in_recovery(), by default every 5 seconds (PGFAILOVER_INTERVAL), with the number of connection attempts controlled by the PGFAILOVER_ATTEMPTS environment variable (default: 1).

pgfailover can automatically promote the local PostgreSQL instance to Primary. The address of the local database is set via the PGFAILOVER_PROMOTION_ADDRESS environment variable and must match the host of one of the entries in PGFAILOVER_SERVERS. When communication with the Primary is lost, pgfailover promotes the first Standby in PGFAILOVER_SERVERS to Primary. If PGFAILOVER_PROMOTION_ADDRESS is not set, promotion is disabled.

Promotion is performed by calling the pg_promote() SQL function. All pgfailover instances must have the same list of PostgreSQL servers.

Example for the first server:

export PGFAILOVER_PROMOTION_ADDRESS=pg0.example.com
export PGFAILOVER_SERVERS="postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5"
./pgfailover

Example for the second server:

export PGFAILOVER_PROMOTION_ADDRESS=pg1.example.com
export PGFAILOVER_SERVERS="postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5"
./pgfailover