summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/app-pgreceivewal.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml/html/app-pgreceivewal.html')
-rw-r--r--doc/src/sgml/html/app-pgreceivewal.html249
1 files changed, 249 insertions, 0 deletions
diff --git a/doc/src/sgml/html/app-pgreceivewal.html b/doc/src/sgml/html/app-pgreceivewal.html
new file mode 100644
index 0000000..c5e6b06
--- /dev/null
+++ b/doc/src/sgml/html/app-pgreceivewal.html
@@ -0,0 +1,249 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_receivewal</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-pg-isready.html" title="pg_isready" /><link rel="next" href="app-pgrecvlogical.html" title="pg_recvlogical" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_receivewal</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pg-isready.html" title="pg_isready">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgrecvlogical.html" title="pg_recvlogical">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PGRECEIVEWAL"><div class="titlepage"></div><a id="id-1.9.4.16.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_receivewal</span></span></h2><p>pg_receivewal — stream write-ahead logs from a <span class="productname">PostgreSQL</span> server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.16.4.1"><code class="command">pg_receivewal</code> [<em class="replaceable"><code>option</code></em>...]</p></div></div><div class="refsect1" id="id-1.9.4.16.5"><h2>Description</h2><p>
+ <span class="application">pg_receivewal</span> is used to stream the write-ahead log
+ from a running <span class="productname">PostgreSQL</span> 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
+ <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>).
+ </p><p>
+ <span class="application">pg_receivewal</span> 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 <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> and
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> do.
+ For this reason, it is not necessary to set
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> when using
+ <span class="application">pg_receivewal</span>.
+ </p><p>
+ Unlike the WAL receiver of a PostgreSQL standby server, <span class="application">pg_receivewal</span>
+ by default flushes WAL data only when a WAL file is closed.
+ The option <code class="option">--synchronous</code> must be specified to flush WAL data
+ in real time. Since <span class="application">pg_receivewal</span> does not
+ apply WAL, you should not allow it to become a synchronous standby when
+ <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> equals
+ <code class="literal">remote_apply</code>. 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 <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a>, or specify
+ <code class="varname">application_name</code> for
+ <span class="application">pg_receivewal</span> that does not match it, or
+ change the value of <code class="varname">synchronous_commit</code> to
+ something other than <code class="literal">remote_apply</code>.
+ </p><p>
+ The write-ahead log is streamed over a regular
+ <span class="productname">PostgreSQL</span> connection and uses the replication
+ protocol. The connection must be made with a user having
+ <code class="literal">REPLICATION</code> permissions (see
+ <a class="xref" href="role-attributes.html" title="22.2. Role Attributes">Section 22.2</a>) or a superuser, and
+ <code class="filename">pg_hba.conf</code> must permit the replication connection.
+ The server must also be configured with
+ <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> set high enough to leave at least
+ one session available for the stream.
+ </p><p>
+ The starting point of the write-ahead log streaming is calculated when
+ <span class="application">pg_receivewal</span> starts:
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ 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.
+ </p></li><li class="listitem"><p>
+ If a starting point cannot be calculated with the previous method,
+ and if a replication slot is used, an extra
+ <code class="command">READ_REPLICATION_SLOT</code> command is issued to retrieve
+ the slot's <code class="literal">restart_lsn</code> to use as the starting point.
+ This option is only available when streaming write-ahead logs from
+ <span class="productname">PostgreSQL</span> 15 and up.
+ </p></li><li class="listitem"><p>
+ 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 <code class="literal">IDENTIFY_SYSTEM</code> command.
+ </p></li></ol></div><p>
+ </p><p>
+ If the connection is lost, or if it cannot be initially established,
+ with a non-fatal error, <span class="application">pg_receivewal</span> will
+ retry the connection indefinitely, and reestablish streaming as soon
+ as possible. To avoid this behavior, use the <code class="literal">-n</code>
+ parameter.
+ </p><p>
+ In the absence of fatal errors, <span class="application">pg_receivewal</span>
+ will run until terminated by the <span class="systemitem">SIGINT</span> signal
+ (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>).
+ </p></div><div class="refsect1" id="id-1.9.4.16.6"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-D <em class="replaceable"><code>directory</code></em></code><br /></span><span class="term"><code class="option">--directory=<em class="replaceable"><code>directory</code></em></code></span></dt><dd><p>
+ Directory to write the output to.
+ </p><p>
+ This parameter is required.
+ </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>lsn</code></em></code><br /></span><span class="term"><code class="option">--endpos=<em class="replaceable"><code>lsn</code></em></code></span></dt><dd><p>
+ Automatically stop replication and exit with normal exit status 0 when
+ receiving reaches the specified LSN.
+ </p><p>
+ If there is a record with LSN exactly equal to <em class="replaceable"><code>lsn</code></em>,
+ the record will be processed.
+ </p></dd><dt><span class="term"><code class="option">--if-not-exists</code></span></dt><dd><p>
+ Do not error out when <code class="option">--create-slot</code> is specified
+ and a slot with the specified name already exists.
+ </p></dd><dt><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-loop</code></span></dt><dd><p>
+ Don't loop on connection errors. Instead, exit right away with
+ an error.
+ </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
+ This option causes <code class="command">pg_receivewal</code> 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.
+ </p><p>
+ This option is incompatible with <code class="literal">--synchronous</code>.
+ </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>interval</code></em></code><br /></span><span class="term"><code class="option">--status-interval=<em class="replaceable"><code>interval</code></em></code></span></dt><dd><p>
+ 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.
+ </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>slotname</code></em></code><br /></span><span class="term"><code class="option">--slot=<em class="replaceable"><code>slotname</code></em></code></span></dt><dd><p>
+ Require <span class="application">pg_receivewal</span> to use an existing
+ replication slot (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>).
+ When this option is used, <span class="application">pg_receivewal</span> 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.
+ </p><p>
+ When the replication client
+ of <span class="application">pg_receivewal</span> 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 <code class="literal">--synchronous</code> (see
+ below) must be specified in addition to make this work correctly.
+ </p></dd><dt><span class="term"><code class="option">--synchronous</code></span></dt><dd><p>
+ 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 <code class="literal">--status-interval</code>.
+ </p><p>
+ This option should be specified if the replication client
+ of <span class="application">pg_receivewal</span> is configured on the
+ server as a synchronous standby, to ensure that timely feedback is
+ sent to the server.
+ </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
+ Enables verbose mode.
+ </p></dd><dt><span class="term"><code class="option">-Z <em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">-Z <em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>level</code></em></code><br /></span><span class="term"><code class="option">--compress=<em class="replaceable"><code>method</code></em>[:<em class="replaceable"><code>detail</code></em>]</code></span></dt><dd><p>
+ Enables compression of write-ahead logs.
+ </p><p>
+ The compression method can be set to <code class="literal">gzip</code>,
+ <code class="literal">lz4</code> (if <span class="productname">PostgreSQL</span>
+ was compiled with <code class="option">--with-lz4</code>) or
+ <code class="literal">none</code> 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 <code class="literal">keyword</code> or <code class="literal">keyword=value</code>.
+ Currently, the only supported keyword is <code class="literal">level</code>.
+ </p><p>
+ If no compression level is specified, the default compression level
+ will be used. If only a level is specified without mentioning an
+ algorithm, <code class="literal">gzip</code> compression will be used if the
+ level is greater than 0, and no compression will be used if the level
+ is 0.
+ </p><p>
+ The suffix <code class="filename">.gz</code> will automatically be added to
+ all filenames when using <code class="literal">gzip</code>, and the suffix
+ <code class="filename">.lz4</code> is added when using <code class="literal">lz4</code>.
+ </p></dd></dl></div><p>
+ The following command-line options control the database connection parameters.
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-d <em class="replaceable"><code>connstr</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>connstr</code></em></code></span></dt><dd><p>
+ Specifies parameters used to connect to the server, as a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>; these
+ will override any conflicting command line options.
+ </p><p>
+ The option is called <code class="literal">--dbname</code> for consistency with other
+ client applications, but because <span class="application">pg_receivewal</span>
+ doesn't connect to any particular database in the cluster, database
+ name in the connection string will be ignored.
+ </p></dd><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
+ 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 <code class="envar">PGHOST</code> environment variable, if set,
+ else a Unix domain socket connection is attempted.
+ </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
+ Specifies the TCP port or local Unix domain socket file
+ extension on which the server is listening for connections.
+ Defaults to the <code class="envar">PGPORT</code> environment variable, if
+ set, or a compiled-in default.
+ </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
+ User name to connect as.
+ </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
+ Never issue a password prompt. If the server requires
+ password authentication and a password is not available by
+ other means such as a <code class="filename">.pgpass</code> 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.
+ </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
+ Force <span class="application">pg_receivewal</span> to prompt for a
+ password before connecting to a database.
+ </p><p>
+ This option is never essential, since
+ <span class="application">pg_receivewal</span> will automatically prompt
+ for a password if the server demands password authentication.
+ However, <span class="application">pg_receivewal</span> will waste a
+ connection attempt finding out that the server wants a password.
+ In some cases it is worth typing <code class="option">-W</code> to avoid the extra
+ connection attempt.
+ </p></dd></dl></div><p>
+ </p><p>
+ <span class="application">pg_receivewal</span> can perform one of the two
+ following actions in order to control physical replication slots:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>
+ Create a new physical replication slot with the name specified in
+ <code class="option">--slot</code>, then exit.
+ </p></dd><dt><span class="term"><code class="option">--drop-slot</code></span></dt><dd><p>
+ Drop the replication slot with the name specified in
+ <code class="option">--slot</code>, then exit.
+ </p></dd></dl></div><p>
+ </p><p>
+ Other options are also available:
+
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
+ Print the <span class="application">pg_receivewal</span> version and exit.
+ </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
+ Show help about <span class="application">pg_receivewal</span> command line
+ arguments, and exit.
+ </p></dd></dl></div><p>
+ </p></div><div class="refsect1" id="id-1.9.4.16.7"><h2>Exit Status</h2><p>
+ <span class="application">pg_receivewal</span> will exit with status 0 when
+ terminated by the <span class="systemitem">SIGINT</span> 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.
+ </p></div><div class="refsect1" id="id-1.9.4.16.8"><h2>Environment</h2><p>
+ This utility, like most other <span class="productname">PostgreSQL</span> utilities,
+ uses the environment variables supported by <span class="application">libpq</span>
+ (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
+ </p><p>
+ The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
+ color in diagnostic messages. Possible values are
+ <code class="literal">always</code>, <code class="literal">auto</code> and
+ <code class="literal">never</code>.
+ </p></div><div class="refsect1" id="id-1.9.4.16.9"><h2>Notes</h2><p>
+ When using <span class="application">pg_receivewal</span> instead of
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> 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 <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
+ <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> 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.
+ </p><p>
+ <span class="application">pg_receivewal</span> will preserve group permissions on
+ the received WAL files if group permissions are enabled on the source
+ cluster.
+ </p></div><div class="refsect1" id="id-1.9.4.16.10"><h2>Examples</h2><p>
+ To stream the write-ahead log from the server at
+ <code class="literal">mydbserver</code> and store it in the local directory
+ <code class="filename">/usr/local/pgsql/archive</code>:
+</p><pre class="screen">
+<code class="prompt">$</code> <strong class="userinput"><code>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</code></strong>
+</pre></div><div class="refsect1" id="id-1.9.4.16.11"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-pgbasebackup.html" title="pg_basebackup"><span class="refentrytitle"><span class="application">pg_basebackup</span></span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-pg-isready.html" title="pg_isready">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgrecvlogical.html" title="pg_recvlogical">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_isready</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_recvlogical</span></td></tr></table></div></body></html> \ No newline at end of file
generated by cgit v1.2.3 (git 2.39.1) at 2024-08-07 18:20:10 +0000