table of contents
PG_RECEIVEWAL(1) | PostgreSQL 10.5 Documentation | PG_RECEIVEWAL(1) |
NAME¶
pg_receivewal - stream write-ahead logs from a PostgreSQL server
SYNOPSIS¶
pg_receivewal [option...]
DESCRIPTION¶
pg_receivewal is used to stream the write-ahead log from a running PostgreSQL cluster. The write-ahead log is streamed using the streaming replication protocol, and is written to a local directory of files. This directory can be used as the archive location for doing a restore using point-in-time recovery (see Section 25.3).
pg_receivewal streams the write-ahead log in real time as it's being generated on the server, and does not wait for segments to complete like archive_command does. For this reason, it is not necessary to set archive_timeout when using pg_receivewal.
Unlike the WAL receiver of a PostgreSQL standby server, pg_receivewal by default flushes WAL data only when a WAL file is closed. The option --synchronous must be specified to flush WAL data in real time.
The write-ahead log is streamed over a regular PostgreSQL connection and uses the replication protocol. The connection must be made with a superuser or a user having REPLICATION permissions (see Section 21.2), and pg_hba.conf must permit the replication connection. The server must also be configured with max_wal_senders set high enough to leave at least one session available for the stream.
If the connection is lost, or if it cannot be initially established, with a non-fatal error, pg_receivewal will retry the connection indefinitely, and reestablish streaming as soon as possible. To avoid this behavior, use the -n parameter.
OPTIONS¶
-D directory
--directory=directory
This parameter is required.
--if-not-exists
-n
--no-loop
-s interval
--status-interval=interval
-S slotname
--slot=slotname
When the replication client of pg_receivewal is configured on the server as a synchronous standby, then using a replication slot will report the flush position to the server, but only when a WAL file is closed. Therefore, that configuration will cause transactions on the primary to wait for a long time and effectively not work satisfactorily. The option --synchronous (see below) must be specified in addition to make this work correctly.
--synchronous
This option should be specified if the replication client of pg_receivewal is configured on the server as a synchronous standby, to ensure that timely feedback is sent to the server.
-v
--verbose
-Z level
--compress=level
The following command-line options control the database connection parameters.
-d connstr
--dbname=connstr
The option is called --dbname for consistency with other client applications, but because pg_receivewal doesn't connect to any particular database in the cluster, database name in the connection string will be ignored.
-h host
--host=host
-p port
--port=port
-U username
--username=username
-w
--no-password
-W
--password
This option is never essential, since pg_receivewal will automatically prompt for a password if the server demands password authentication. However, pg_receivewal will waste a connection attempt finding out that the server wants a password. In some cases it is worth typing -W to avoid the extra connection attempt.
pg_receivewal can perform one of the two following actions in order to control physical replication slots:
--create-slot
--drop-slot
Other options are also available:
-V
--version
-?
--help
ENVIRONMENT¶
This utility, like most other PostgreSQL utilities, uses the environment variables supported by libpq (see Section 33.14).
NOTES¶
When using pg_receivewal instead of archive_command as the main WAL backup method, it is strongly recommended to use replication slots. Otherwise, the server is free to recycle or remove write-ahead log files before they are backed up, because it does not have any information, either from archive_command or the replication slots, about how far the WAL stream has been archived. Note, however, that a replication slot will fill up the server's disk space if the receiver does not keep up with fetching the WAL data.
EXAMPLES¶
To stream the write-ahead log from the server at mydbserver and store it in the local directory /usr/local/pgsql/archive:
$ pg_receivewal -h mydbserver -D /usr/local/pgsql/archive
SEE ALSO¶
pg_basebackup(1)
2018 | PostgreSQL 10.5 |