Pgfailover Documentation

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

Connection parameters are specified using DSN format:

./pgfailover -bind :5432 \
    -server postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 \
    -server postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5

The server role (primary/standby) is checked using pg_is_in_recovery(), every 5 seconds by default. This interval can be adjusted with the -interval parameter. The number of connection attempts is controlled by the -attempts parameter (default: 1).

pgfailover can automatically promote the local PostgreSQL instance to replication leader role. It is assumed that the order of the servers participating in the cluster is specified. pgfailover runs on each server and is assigned an index for that server. When communication with the leader is lost, pgfailover promotes the first in order server with the standby PostgreSQL to leader role.

The local server index is given by the -index parameter, starting from 0. pgfailover creates the trigger file to promote the local PostgreSQL instance. All pgfailover instances must have the same list of PostgreSQL servers and unique numbers with no gaps.

Example for the first server (index 0):

./pgfailover -index 0 -trigger /var/lib/postgresql/11/database/trigger \
    -server postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 \
    -server postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5

Example for the second server (index 1):

./pgfailover -index 1 -trigger /srv/postgres/database/promote \
    -server postgres://repuser@pg0.example.com/database?sslmode=disable&connect_timeout=5 \
    -server postgres://repuser@pg1.example.com/database?sslmode=disable&connect_timeout=5