pg_receivewal

Stream WAL to a local directory (minimum required)

$ pg_receivewal [[-D|--directory]] [directory]

$ pg_receivewal [[-v|--verbose]] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username] [[-D|--directory]] [directory]

$ pg_receivewal [[-S|--slot]] [slot_name] --create-slot [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username] [[-D|--directory]] [directory]

$ pg_receivewal [[-E|--endpos]] [lsn] [[-D|--directory]] [directory] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username]

$ pg_receivewal [[-n|--no-loop]] [[-D|--directory]] [directory] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username]

$ pg_receivewal --synchronous [[-D|--directory]] [directory] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username]

$ pg_receivewal [[-Z|--compress]] [level|method] [[-D|--directory]] [directory] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username]

$ pg_receivewal [[-s|--status-interval]] [seconds] [[-D|--directory]] [directory] [[-h|--host]] [host] [[-p|--port]] [port] [[-U|--username]] [username]

pg_receivewal [OPTION]...

-D directory, --directory=directory
    The target directory to write the WAL files into. This is a mandatory option.

-d connstr, --dbname=connstr
    Connection string parameters. This can be used instead of or in addition to individual connection options like --host, --port, etc.

-h hostname, --host=hostname
    Hostname or IP address of the database server.

-p port, --port=port
    TCP port number or local Unix domain socket file extension on which the server is listening for connections.

-U username, --username=username
    User name to connect as.

-W, --password
    Force pg_receivewal to prompt for a password before connecting to the database.

-S slotname, --slot=slotname
    Name of the replication slot to use. This is highly recommended to prevent the server from removing WAL files before they are streamed.

-s interval, --status-interval=interval
    Time in seconds between status packets sent back to the server. A value of 0 disables status updates. Default is 10 seconds.

-n, --no-loop
    Do not loop after reaching the end of the WAL stream. Exit instead. The default behavior is to loop indefinitely and wait for new WAL.

-N, --no-sync
    Do not force WAL files to disk with fsync. This can be faster but is unsafe and should only be used for testing or specific scenarios where data integrity risks are understood.

-E LSN, --endpos=LSN
    Stop streaming at the specified LSN (Log Sequence Number). The WAL file containing the LSN will be fully transferred.

-v, --verbose
    Enable verbose output.

-V, --version
    Print the pg_receivewal version and exit.

-Z level, --compress=level
    Compress WAL files using zstd (if compiled with zstd support). Level can be 0 (no compression) to 9 (highest).

--fsync-interval=interval
    The frequency (in seconds) with which the target directory is synchronized to disk using fsync. Default is 10 seconds.

--if-not-exists
    Do not error if the target directory already exists. Use with caution as existing files might be overwritten or moved.

--synchronous=mode
    Controls whether synchronous replication feedback is sent. Modes are "sync" (default) or "async". "sync" allows the server to wait for pg_receivewal to confirm WAL receipt before committing transactions.

--waldir=directory
    Specifies a subdirectory within the target directory (-D) where WAL files should be placed. Defaults to "pg_wal".

pg_receivewal is a utility for streaming transaction log (WAL) data from a running PostgreSQL server. It connects to the server using the streaming replication protocol and writes the received WAL segments into a specified local directory. This tool is fundamental for setting up and maintaining various high-availability and disaster recovery solutions, including physical standby servers, point-in-time recovery (PITR) archives, or general WAL archiving. It can operate in a continuous loop, waiting for new WAL to be generated by the server, or exit after fetching a specific amount of WAL. By utilizing PostgreSQL's replication slots, pg_receivewal can ensure that the server retains necessary WAL segments until they have been successfully streamed, preventing data loss due to early cleanup on the server. It offers robust connectivity options, including host, port, username, and password, similar to other PostgreSQL client applications.

Disk Space: Streaming WAL can consume significant disk space. Ensure the target directory has ample free space, especially for continuous archiving or long-term standbys.
Replication Slots: While optional, using a replication slot (-S) is highly recommended. Without it, the server might remove WAL segments needed by pg_receivewal before they are streamed, leading to replication gaps or errors. This is particularly crucial for continuous operation.
--no-sync Usage: The --no-sync option is inherently unsafe for production environments. It can lead to data loss or corruption in case of system crashes. Use it only for testing or temporary, non-critical scenarios.
Security: Ensure secure network connectivity between pg_receivewal and the PostgreSQL server. Consider using sslmode=verify-full in connection strings for encrypted and authenticated connections.

pg_receivewal uses the standard PostgreSQL connection environment variables (e.g., PGHOST, PGPORT, PGUSER, PGPASSWORD) and the ~/.pgpass file for password authentication, in addition to command-line options.

A replication slot is an object on the primary server that prevents the primary from removing WAL segments until they have been consumed by all configured standbys or archival processes. This mechanism guarantees that pg_receivewal (or any other replication client) will always receive the necessary WAL data without encountering gaps due to WAL file deletion on the primary.

pg_receivewal -D /path/to/wal/archive -S my_archive_slot -v
This command continuously streams WAL to /path/to/wal/archive using the replication slot my_archive_slot, providing verbose output.

pg_receivewal was introduced in PostgreSQL 9.2 as part of the improvements to streaming replication and recovery. Its development aimed to provide a dedicated, robust client for fetching WAL segments directly from a running PostgreSQL server using the streaming replication protocol. This offered a more reliable and efficient alternative to the archive_command for continuous archiving and setting up standby servers, allowing for reduced recovery point objective (RPO) and simplified management of replication. It continues to be a core utility for modern PostgreSQL high-availability setups.

pg_basebackup(1), pg_rewind(1), psql(1), pg_archivecleanup(1)