Implementing Warm Standby Servers with pg_standby

What is pg_standby?

pg_standby is a PostgreSQL utility that supports the creation of a warm standby server by managing a continuous archive recovery process. It is primarily used in log shipping replication setups where transaction log files (WAL files) are transferred from a primary server to a standby server.

How pg_standby Works

The tool acts as a restore_command in the PostgreSQL recovery process. It is responsible for fetching WAL files from an archive location and applying them to the standby server. pg_standby can also handle cleanup of old WAL files and supports delayed recovery to protect against data corruption on the primary server.

Using pg_standby for Log Shipping Replication

Before using pg_standby, ensure that the primary PostgreSQL server is configured to archive completed WAL files to a location accessible by the standby server.

Configuring the Standby Server

On the standby server, set the restore_command in the recovery.conf or postgresql.conf (for PostgreSQL 12 and above) to use pg_standby.

restore_command = 'pg_standby -l -d -s 2 -t /tmp/trigger /path/to/wal_archive %f %p %r'

This configuration uses pg_standby to manage WAL file restoration, with a delay of 2 seconds (-s 2), a trigger file at /tmp/trigger, and a WAL archive path at /path/to/wal_archive.

Starting the Standby Server

Once configured, start the standby server. PostgreSQL will invoke pg_standby to manage WAL file restoration automatically.

Use Cases for pg_standby

  • High Availability: Implement a warm standby server that can be quickly promoted to a primary server in case of a failure, reducing downtime.
  • Read Scaling: Use the standby server for read-only queries, offloading the primary server and improving overall performance.
  • Backup: Maintain a near real-time copy of the primary server’s data, which can be used for backups without impacting the primary server’s performance.

Common Mistakes and Issues

  • Incorrect File Paths: Ensure that the paths specified in the restore_command are correct and accessible by the PostgreSQL process.
  • Trigger File Mismanagement: The trigger file should be managed carefully. Creating it prematurely can cause the standby server to exit recovery mode and start as a normal server.
  • WAL Archive Cleanup: pg_standby can clean up old WAL files, but it must be configured correctly to prevent premature deletion that could be necessary for recovery.

Troubleshooting Errors

  • Recovery Process Stuck: If the standby server is not recovering, check the PostgreSQL logs for errors related to restore_command or connectivity issues with the WAL archive location.
  • WAL File Mismatch: Ensure that the WAL files generated by the primary server match the expected timeline on the standby server. Any discrepancies can halt the recovery process.
  • Permission Issues: Verify that the PostgreSQL user has the necessary permissions to read from the WAL archive and write to the data directory.


pg_standby provides a straightforward and reliable method for setting up and managing warm standby servers in a PostgreSQL environment. By effectively using this utility, you can enhance your database’s high availability, scale your read operations, and ensure data safety through an efficient log shipping setup. Proper configuration and management of pg_standby are crucial for maintaining a robust replication system.

For comprehensive usage instructions and best practices, please refer to the official PostgreSQL documentation on pg_standby.

Leave a Comment