'\" t .\" Title: pg_receivexlog .\" Author: The PostgreSQL Global Development Group .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 2019 .\" Manual: PostgreSQL 9.6.12 Documentation .\" Source: PostgreSQL 9.6.12 .\" Language: English .\" .TH "PG_RECEIVEXLOG" "1" "2019" "PostgreSQL 9.6.12" "PostgreSQL 9.6.12 Documentation" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" pg_receivexlog \- stream transaction logs from a PostgreSQL server .SH "SYNOPSIS" .HP \w'\fBpg_receivexlog\fR\ 'u \fBpg_receivexlog\fR [\fIoption\fR...] .SH "DESCRIPTION" .PP pg_receivexlog is used to stream the transaction log from a running PostgreSQL cluster\&. The transaction 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, \(lqContinuous Archiving and Point-in-Time Recovery (PITR)\(rq, in the documentation)\&. .PP pg_receivexlog streams the transaction log in real time as it\*(Aqs 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_receivexlog\&. .PP Unlike the WAL receiver of a PostgreSQL standby server, pg_receivexlog by default flushes WAL data only when a WAL file is closed\&. The option \fB\-\-synchronous\fR must be specified to flush WAL data in real time\&. .PP The transaction 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, \(lqRole Attributes\(rq, in the documentation), 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\&. .PP If the connection is lost, or if it cannot be initially established, with a non\-fatal error, pg_receivexlog will retry the connection indefinitely, and reestablish streaming as soon as possible\&. To avoid this behavior, use the \-n parameter\&. .SH "OPTIONS" .PP \fB\-D \fR\fB\fIdirectory\fR\fR .br \fB\-\-directory=\fR\fB\fIdirectory\fR\fR .RS 4 Directory to write the output to\&. .sp This parameter is required\&. .RE .PP \fB\-\-if\-not\-exists\fR .RS 4 Do not error out when \fB\-\-create\-slot\fR is specified and a slot with the specified name already exists\&. .RE .PP \fB\-n\fR .br \fB\-\-no\-loop\fR .RS 4 Don\*(Aqt loop on connection errors\&. Instead, exit right away with an error\&. .RE .PP \fB\-s \fR\fB\fIinterval\fR\fR .br \fB\-\-status\-interval=\fR\fB\fIinterval\fR\fR .RS 4 Specifies the number of seconds between status packets sent back to the server\&. This allows for easier monitoring of the progress from server\&. A value of zero disables the periodic status updates completely, although an update will still be sent when requested by the server, to avoid timeout disconnect\&. The default value is 10 seconds\&. .RE .PP \fB\-S \fR\fB\fIslotname\fR\fR .br \fB\-\-slot=\fR\fB\fIslotname\fR\fR .RS 4 Require pg_receivexlog to use an existing replication slot (see Section 26.2.6, \(lqReplication Slots\(rq, in the documentation)\&. When this option is used, pg_receivexlog will report a flush position to the server, indicating when each segment has been synchronized to disk so that the server can remove that segment if it is not otherwise needed\&. .sp When the replication client of pg_receivexlog 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\&. .RE .PP \fB\-\-synchronous\fR .RS 4 Flush the WAL data to disk immediately after it has been received\&. Also send a status packet back to the server immediately after flushing, regardless of \-\-status\-interval\&. .sp This option should be specified if the replication client of pg_receivexlog is configured on the server as a synchronous standby, to ensure that timely feedback is sent to the server\&. .RE .PP \fB\-v\fR .br \fB\-\-verbose\fR .RS 4 Enables verbose mode\&. .RE .PP The following command\-line options control the database connection parameters\&. .PP \fB\-d \fR\fB\fIconnstr\fR\fR .br \fB\-\-dbname=\fR\fB\fIconnstr\fR\fR .RS 4 Specifies parameters used to connect to the server, as a connection string\&. See Section 32.1.1, \(lqConnection Strings\(rq, in the documentation for more information\&. .sp The option is called \-\-dbname for consistency with other client applications, but because pg_receivexlog doesn\*(Aqt connect to any particular database in the cluster, database name in the connection string will be ignored\&. .RE .PP \fB\-h \fR\fB\fIhost\fR\fR .br \fB\-\-host=\fR\fB\fIhost\fR\fR .RS 4 Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the \fBPGHOST\fR environment variable, if set, else a Unix domain socket connection is attempted\&. .RE .PP \fB\-p \fR\fB\fIport\fR\fR .br \fB\-\-port=\fR\fB\fIport\fR\fR .RS 4 Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the \fBPGPORT\fR environment variable, if set, or a compiled\-in default\&. .RE .PP \fB\-U \fR\fB\fIusername\fR\fR .br \fB\-\-username=\fR\fB\fIusername\fR\fR .RS 4 User name to connect as\&. .RE .PP \fB\-w\fR .br \fB\-\-no\-password\fR .RS 4 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a \&.pgpass file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. .RE .PP \fB\-W\fR .br \fB\-\-password\fR .RS 4 Force pg_receivexlog to prompt for a password before connecting to a database\&. .sp This option is never essential, since pg_receivexlog will automatically prompt for a password if the server demands password authentication\&. However, pg_receivexlog will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing \fB\-W\fR to avoid the extra connection attempt\&. .RE .PP pg_receivexlog can perform one of the two following actions in order to control physical replication slots: .PP \fB\-\-create\-slot\fR .RS 4 Create a new physical replication slot with the name specified in \fB\-\-slot\fR, then exit\&. .RE .PP \fB\-\-drop\-slot\fR .RS 4 Drop the replication slot with the name specified in \fB\-\-slot\fR, then exit\&. .RE .PP Other options are also available: .PP \fB\-V\fR .br \fB\-\-version\fR .RS 4 Print the pg_receivexlog version and exit\&. .RE .PP \fB\-?\fR .br \fB\-\-help\fR .RS 4 Show help about pg_receivexlog command line arguments, and exit\&. .RE .SH "ENVIRONMENT" .PP This utility, like most other PostgreSQL utilities, uses the environment variables supported by libpq (see Section 32.14, \(lqEnvironment Variables\(rq, in the documentation)\&. .SH "NOTES" .PP When using pg_receivexlog 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 transaction 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\*(Aqs disk space if the receiver does not keep up with fetching the WAL data\&. .SH "EXAMPLES" .PP To stream the transaction log from the server at mydbserver and store it in the local directory /usr/local/pgsql/archive: .sp .if n \{\ .RS 4 .\} .nf $ \fBpg_receivexlog \-h mydbserver \-D /usr/local/pgsql/archive\fR .fi .if n \{\ .RE .\} .SH "SEE ALSO" \fBpg_basebackup\fR(1)