bgw_replstatus is a tiny background worker to cheaply report the replication status of a node. It's intended to be polled by a load balancer such as haproxy.

When installed, a background worker will be started that listens on a defined TCP port (configured bgw_replstatus.port). Any connection to this port will get a TCP response back (no request necessary, response will be sent immediately on connect) saying either MASTER or STANDBY depending on the current state of the node. The connection is then automatically closed.

Using a background worker like this will make polling a lot more light weight than making a full PostgreSQL connection, logging in, and checking the status.

Build and install is done using PGXS. As long as pg_config is available in the path, build and install using:

$ make
$ make install

Once the binary is installed, it needs to be enabled in shared_preload_libraries in postgresql.conf:

shared_preload_libraries = 'bgw_replstatus'

If other libraries are already configured for loading, it can be appended to the end of the list. Order should not matter.

By default, the background worker will listen to port 5400 on a wild card IP address. There is no verification of the source done, so protect the port with a proper host firewall!!!

To change the port, set the value of bgw_replstatus.port to another value. Any TCP port above 1024 will work (but don't pick the same one as PostgreSQL itself...).

To change the socket to bind to a specific IP address, set bgw_replstatus.bind to an IP address, which will cause the background worker to bind to this IP on the defined port.

There is no support for multiple ports or multiple IP addresses.

In it's simplest form, you can just verify the status of your system with nc or telnet:

$ nc localhost 5400
MASTER

Since the text coming back is easily identifiable, it's easy enough to integrate with a load balancer such as haproxy. This example haproxy configuration will show how to ensure that haproxy is connected to the master node of the cluster, and automatically switches over to the backup node if the master goes down and the backup is promoted. Multiple backups can be used.

frontend test
	bind 127.0.0.1:5999
	default_backend pgcluster

backend pgcluster
	mode tcp
	option tcp-check
	tcp-check expect string MASTER
	server s1 127.0.0.1:5500 check port 5400
	server s2 127.0.0.1:5501 check port 5401 backup
	server s3 127.0.0.1:5502 check port 5402 backup

In this example all nodes are local, with postgres running on ports 5500/5501/5502 with bgw_replstatus bound to ports 5400/5401/5402 respectively.