diff options
Diffstat (limited to 'doc/src/sgml/man1/pg_receivewal.1')
| -rw-r--r-- | doc/src/sgml/man1/pg_receivewal.1 | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/doc/src/sgml/man1/pg_receivewal.1 b/doc/src/sgml/man1/pg_receivewal.1 new file mode 100644 index 0000000..97b19b9 --- /dev/null +++ b/doc/src/sgml/man1/pg_receivewal.1 @@ -0,0 +1,419 @@ +'\" t +.\" Title: pg_receivewal +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "PG_RECEIVEWAL" "1" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 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_receivewal \- stream write\-ahead logs from a PostgreSQL server +.SH "SYNOPSIS" +.HP \w'\fBpg_receivewal\fR\ 'u +\fBpg_receivewal\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +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\ \&26.3)\&. +.PP +pg_receivewal +streams the write\-ahead log in real time as it\*(Aqs being generated on the server, and does not wait for segments to complete like +archive_command +and +archive_library +do\&. For this reason, it is not necessary to set +archive_timeout +when using +pg_receivewal\&. +.PP +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 +\fB\-\-synchronous\fR +must be specified to flush WAL data in real time\&. Since +pg_receivewal +does not apply WAL, you should not allow it to become a synchronous standby when +synchronous_commit +equals +remote_apply\&. If it does, it will appear to be a standby that never catches up, and will cause transaction commits to block\&. To avoid this, you should either configure an appropriate value for +synchronous_standby_names, or specify +\fIapplication_name\fR +for +pg_receivewal +that does not match it, or change the value of +\fIsynchronous_commit\fR +to something other than +remote_apply\&. +.PP +The write\-ahead log is streamed over a regular +PostgreSQL +connection and uses the replication protocol\&. The connection must be made with a user having +REPLICATION +permissions (see +Section\ \&22.2) or a superuser, 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 +The starting point of the write\-ahead log streaming is calculated when +pg_receivewal +starts: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +First, scan the directory where the WAL segment files are written and find the newest completed segment file, using as the starting point the beginning of the next WAL segment file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +If a starting point cannot be calculated with the previous method, and if a replication slot is used, an extra +\fBREAD_REPLICATION_SLOT\fR +command is issued to retrieve the slot\*(Aqs +restart_lsn +to use as the starting point\&. This option is only available when streaming write\-ahead logs from +PostgreSQL +15 and up\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +If a starting point cannot be calculated with the previous method, the latest WAL flush location is used as reported by the server from an +IDENTIFY_SYSTEM +command\&. +.RE +.PP +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\&. +.PP +In the absence of fatal errors, +pg_receivewal +will run until terminated by the +SIGINT +signal (Control+C)\&. +.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\-E \fR\fB\fIlsn\fR\fR +.br +\fB\-\-endpos=\fR\fB\fIlsn\fR\fR +.RS 4 +Automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&. +.sp +If there is a record with LSN exactly equal to +\fIlsn\fR, the record will be processed\&. +.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\-\-no\-sync\fR +.RS 4 +This option causes +\fBpg_receivewal\fR +to not force WAL data to be flushed to disk\&. This is faster, but means that a subsequent operating system crash can leave the WAL segments corrupt\&. Generally, this option is useful for testing but should not be used when doing WAL archiving on a production deployment\&. +.sp +This option is incompatible with +\-\-synchronous\&. +.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_receivewal +to use an existing replication slot (see +Section\ \&27.2.6)\&. When this option is used, +pg_receivewal +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_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\&. +.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_receivewal +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 +\fB\-Z \fR\fB\fIlevel\fR\fR +.br +\fB\-Z \fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.br +\fB\-\-compress=\fR\fB\fIlevel\fR\fR +.br +\fB\-\-compress=\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.RS 4 +Enables compression of write\-ahead logs\&. +.sp +The compression method can be set to +gzip, +lz4 +(if +PostgreSQL +was compiled with +\fB\-\-with\-lz4\fR) or +none +for no compression\&. A compression detail string can optionally be specified\&. If the detail string is an integer, it specifies the compression level\&. Otherwise, it should be a comma\-separated list of items, each of the form +keyword +or +keyword=value\&. Currently, the only supported keyword is +level\&. +.sp +If no compression level is specified, the default compression level will be used\&. If only a level is specified without mentioning an algorithm, +gzip +compression will be used if the level is greater than 0, and no compression will be used if the level is 0\&. +.sp +The suffix +\&.gz +will automatically be added to all filenames when using +gzip, and the suffix +\&.lz4 +is added when using +lz4\&. +.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; these will override any conflicting command line options\&. +.sp +The option is called +\-\-dbname +for consistency with other client applications, but because +pg_receivewal +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_receivewal +to prompt for a password before connecting to a database\&. +.sp +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 +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +pg_receivewal +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_receivewal +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_receivewal +command line arguments, and exit\&. +.RE +.SH "EXIT STATUS" +.PP +pg_receivewal +will exit with status 0 when terminated by the +SIGINT +signal\&. (That is the normal way to end it\&. Hence it is not an error\&.) For fatal errors or other signals, the exit status will be nonzero\&. +.SH "ENVIRONMENT" +.PP +This utility, like most other +PostgreSQL +utilities, uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +When using +pg_receivewal +instead of +archive_command +or +archive_library +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 +archive_library +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\&. +.PP +pg_receivewal +will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&. +.SH "EXAMPLES" +.PP +To stream the write\-ahead log from the server at +mydbserver +and store it in the local directory +/usr/local/pgsql/archive: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_receivewal \-h mydbserver \-D /usr/local/pgsql/archive\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_basebackup\fR(1) |