begriffs open source - ai-pg/blob - full-docs/html/app-pgreceivewal.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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 18.0 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.17.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.17.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.17.5"><h2>Description</h2><p>
   3    <span class="application">pg_receivewal</span> is used to stream the write-ahead log
   4    from a running <span class="productname">PostgreSQL</span> cluster. The write-ahead
   5    log is streamed using the streaming replication protocol, and is written
   6    to a local directory of files. This directory can be used as the archive
   7    location for doing a restore using point-in-time recovery (see
   8    <a class="xref" href="continuous-archiving.html" title="25.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 25.3</a>).
   9   </p><p>
  10    <span class="application">pg_receivewal</span> streams the write-ahead
  11    log in real time as it's being generated on the server, and does not wait
  12    for segments to complete like <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> and
  13    <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> do.
  14    For this reason, it is not necessary to set
  15    <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> when using
  16     <span class="application">pg_receivewal</span>.
  17   </p><p>
  18    Unlike the WAL receiver of a PostgreSQL standby server, <span class="application">pg_receivewal</span>
  19    by default flushes WAL data only when a WAL file is closed.
  20    The option <code class="option">--synchronous</code> must be specified to flush WAL data
  21    in real time. Since <span class="application">pg_receivewal</span> does not
  22    apply WAL, you should not allow it to become a synchronous standby when
  23    <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> equals
  24    <code class="literal">remote_apply</code>. If it does, it will appear to be a
  25    standby that never catches up, and will cause transaction commits to
  26    block. To avoid this, you should either configure an appropriate value
  27    for <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a>, or specify
  28    <code class="varname">application_name</code> for
  29    <span class="application">pg_receivewal</span> that does not match it, or
  30    change the value of <code class="varname">synchronous_commit</code> to
  31    something other than <code class="literal">remote_apply</code>.
  32   </p><p>
  33    The write-ahead log is streamed over a regular
  34    <span class="productname">PostgreSQL</span> connection and uses the replication
  35    protocol. The connection must be made with a user having
  36    <code class="literal">REPLICATION</code> permissions (see
  37    <a class="xref" href="role-attributes.html" title="21.2. Role Attributes">Section 21.2</a>) or a superuser, and
  38    <code class="filename">pg_hba.conf</code> must permit the replication connection.
  39    The server must also be configured with
  40    <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> set high enough to leave at least
  41    one session available for the stream.
  42   </p><p>
  43    The starting point of the write-ahead log streaming is calculated when
  44    <span class="application">pg_receivewal</span> starts:
  45    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  46       First, scan the directory where the WAL segment files are written and
  47       find the newest completed segment file, using as the starting point the
  48       beginning of the next WAL segment file.
  49      </p></li><li class="listitem"><p>
  50       If a starting point cannot be calculated with the previous method,
  51       and if a replication slot is used, an extra
  52       <code class="command">READ_REPLICATION_SLOT</code> command is issued to retrieve
  53       the slot's <code class="literal">restart_lsn</code> to use as the starting point.
  54       This option is only available when streaming write-ahead logs from
  55       <span class="productname">PostgreSQL</span> 15 and up.
  56      </p></li><li class="listitem"><p>
  57       If a starting point cannot be calculated with the previous method,
  58       the latest WAL flush location is used as reported by the server from
  59       an <code class="literal">IDENTIFY_SYSTEM</code> command.
  60      </p></li></ol></div><p>
  61   </p><p>
  62    If the connection is lost, or if it cannot be initially established,
  63    with a non-fatal error, <span class="application">pg_receivewal</span> will
  64    retry the connection indefinitely, and reestablish streaming as soon
  65    as possible. To avoid this behavior, use the <code class="literal">-n</code>
  66    parameter.
  67   </p><p>
  68    In the absence of fatal errors, <span class="application">pg_receivewal</span>
  69    will run until terminated by the <span class="systemitem">SIGINT</span>
  70    (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>)
  71    or <span class="systemitem">SIGTERM</span> signal.
  72   </p></div><div class="refsect1" id="id-1.9.4.17.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>
  73         Directory to write the output to.
  74        </p><p>
  75         This parameter is required.
  76        </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>
  77         Automatically stop replication and exit with normal exit status 0 when
  78         receiving reaches the specified LSN.
  79        </p><p>
  80         If there is a record with LSN exactly equal to <em class="replaceable"><code>lsn</code></em>,
  81         the record will be processed.
  82        </p></dd><dt><span class="term"><code class="option">--if-not-exists</code></span></dt><dd><p>
  83         Do not error out when <code class="option">--create-slot</code> is specified
  84         and a slot with the specified name already exists.
  85        </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>
  86         Don't loop on connection errors. Instead, exit right away with
  87         an error.
  88        </p></dd><dt><span class="term"><code class="option">--no-sync</code></span></dt><dd><p>
  89         This option causes <code class="command">pg_receivewal</code> to not force WAL
  90         data to be flushed to disk.  This is faster, but means that a
  91         subsequent operating system crash can leave the WAL segments corrupt.
  92         Generally, this option is useful for testing but should not be used
  93         when doing WAL archiving on a production deployment.
  94        </p><p>
  95         This option is incompatible with <code class="literal">--synchronous</code>.
  96        </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>
  97         Specifies the number of seconds between status packets sent back to the
  98         server. This allows for easier monitoring of the progress from server.
  99         A value of zero disables the periodic status updates completely,
 100         although an update will still be sent when requested by the server, to
 101         avoid timeout disconnect. The default value is 10 seconds.
 102        </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>
 103          Require <span class="application">pg_receivewal</span> to use an existing
 104          replication slot (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a>).
 105          When this option is used, <span class="application">pg_receivewal</span> will report
 106          a flush position to the server, indicating when each segment has been
 107          synchronized to disk so that the server can remove that segment if it
 108          is not otherwise needed.
 109         </p><p>
 110          When the replication client
 111          of <span class="application">pg_receivewal</span> is configured on the
 112          server as a synchronous standby, then using a replication slot will
 113          report the flush position to the server, but only when a WAL file is
 114          closed.  Therefore, that configuration will cause transactions on the
 115          primary to wait for a long time and effectively not work
 116          satisfactorily.  The option <code class="literal">--synchronous</code> (see
 117          below) must be specified in addition to make this work correctly.
 118         </p></dd><dt><span class="term"><code class="option">--synchronous</code></span></dt><dd><p>
 119         Flush the WAL data to disk immediately after it has been received. Also
 120         send a status packet back to the server immediately after flushing,
 121         regardless of <code class="literal">--status-interval</code>.
 122        </p><p>
 123         This option should be specified if the replication client
 124         of <span class="application">pg_receivewal</span> is configured on the
 125         server as a synchronous standby, to ensure that timely feedback is
 126         sent to the server.
 127        </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>
 128         Enables verbose mode.
 129        </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>
 130         Enables compression of write-ahead logs.
 131        </p><p>
 132         The compression method can be set to <code class="literal">gzip</code>,
 133         <code class="literal">lz4</code> (if <span class="productname">PostgreSQL</span>
 134         was compiled with <code class="option">--with-lz4</code>) or
 135         <code class="literal">none</code> for no compression.
 136         A compression detail string can optionally be specified.  If the
 137         detail string is an integer, it specifies the compression level.
 138         Otherwise, it should be a comma-separated list of items, each of the
 139         form <em class="replaceable"><code>keyword</code></em> or
 140         <em class="replaceable"><code>keyword=value</code></em>.
 141         Currently, the only supported keyword is <code class="literal">level</code>.
 142        </p><p>
 143         If no compression level is specified, the default compression level
 144         will be used. If only a level is specified without mentioning an
 145         algorithm, <code class="literal">gzip</code> compression will be used if the
 146         level is greater than 0, and no compression will be used if the level
 147         is 0.
 148        </p><p>
 149         The suffix <code class="filename">.gz</code> will automatically be added to
 150         all filenames when using <code class="literal">gzip</code>, and the suffix
 151         <code class="filename">.lz4</code> is added when using <code class="literal">lz4</code>.
 152        </p></dd></dl></div><p>
 153     The following command-line options control the database connection parameters.
 154
 155     </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>
 156         Specifies parameters used to connect to the server, as a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">connection string</a>;  these
 157         will override any conflicting command line options.
 158        </p><p>
 159         This option is called <code class="literal">--dbname</code> for consistency with other
 160         client applications, but because <span class="application">pg_receivewal</span>
 161         doesn't connect to any particular database in the cluster, any database
 162         name included in the connection string will be ignored by the server.
 163         However, a database name supplied that way overrides the default
 164         database name (<code class="literal">replication</code>) for purposes of
 165         looking up the replication connection's password
 166         in <code class="filename">~/.pgpass</code>.  Similarly, middleware or proxies
 167         used in connecting to <span class="productname">PostgreSQL</span> might
 168         utilize the name for purposes such as connection routing.
 169        </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>
 170         Specifies the host name of the machine on which the server is
 171         running.  If the value begins with a slash, it is used as the
 172         directory for the Unix domain socket. The default is taken
 173         from the <code class="envar">PGHOST</code> environment variable, if set,
 174         else a Unix domain socket connection is attempted.
 175        </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>
 176         Specifies the TCP port or local Unix domain socket file
 177         extension on which the server is listening for connections.
 178         Defaults to the <code class="envar">PGPORT</code> environment variable, if
 179         set, or a compiled-in default.
 180        </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>
 181         User name to connect as.
 182        </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>
 183         Never issue a password prompt.  If the server requires
 184         password authentication and a password is not available by
 185         other means such as a <code class="filename">.pgpass</code> file, the
 186         connection attempt will fail.  This option can be useful in
 187         batch jobs and scripts where no user is present to enter a
 188         password.
 189        </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>
 190         Force <span class="application">pg_receivewal</span> to prompt for a
 191         password before connecting to a database.
 192        </p><p>
 193         This option is never essential, since
 194         <span class="application">pg_receivewal</span> will automatically prompt
 195         for a password if the server demands password authentication.
 196         However, <span class="application">pg_receivewal</span> will waste a
 197         connection attempt finding out that the server wants a password.
 198         In some cases it is worth typing <code class="option">-W</code> to avoid the extra
 199         connection attempt.
 200        </p></dd></dl></div><p>
 201    </p><p>
 202     <span class="application">pg_receivewal</span> can perform one of the two
 203     following actions in order to control physical replication slots:
 204
 205     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>
 206         Create a new physical replication slot with the name specified in
 207         <code class="option">--slot</code>, then exit.
 208        </p></dd><dt><span class="term"><code class="option">--drop-slot</code></span></dt><dd><p>
 209         Drop the replication slot with the name specified in
 210         <code class="option">--slot</code>, then exit.
 211        </p></dd></dl></div><p>
 212    </p><p>
 213     Other options are also available:
 214
 215     </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>
 216        Print the <span class="application">pg_receivewal</span> version and exit.
 217        </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
 218        Show help about <span class="application">pg_receivewal</span> command line
 219        arguments, and exit.
 220        </p></dd></dl></div><p>
 221    </p></div><div class="refsect1" id="id-1.9.4.17.7"><h2>Exit Status</h2><p>
 222    <span class="application">pg_receivewal</span> will exit with status 0 when
 223    terminated by the <span class="systemitem">SIGINT</span> or
 224    <span class="systemitem">SIGTERM</span> signal.  (That is the
 225    normal way to end it.  Hence it is not an error.)  For fatal errors or
 226    other signals, the exit status will be nonzero.
 227   </p></div><div class="refsect1" id="id-1.9.4.17.8"><h2>Environment</h2><p>
 228    This utility, like most other <span class="productname">PostgreSQL</span> utilities,
 229    uses the environment variables supported by <span class="application">libpq</span>
 230    (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>).
 231   </p><p>
 232    The environment variable <code class="envar">PG_COLOR</code> specifies whether to use
 233    color in diagnostic messages. Possible values are
 234    <code class="literal">always</code>, <code class="literal">auto</code> and
 235    <code class="literal">never</code>.
 236   </p></div><div class="refsect1" id="id-1.9.4.17.9"><h2>Notes</h2><p>
 237    When using <span class="application">pg_receivewal</span> instead of
 238    <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
 239    <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> as the main WAL backup method, it is
 240    strongly recommended to use replication slots.  Otherwise, the server is
 241    free to recycle or remove write-ahead log files before they are backed up,
 242    because it does not have any information, either
 243    from <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or
 244    <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> or the replication slots, about
 245    how far the WAL stream has been archived.  Note, however, that a
 246    replication slot will fill up the server's disk space if the receiver does
 247    not keep up with fetching the WAL data.
 248   </p><p>
 249    <span class="application">pg_receivewal</span> will preserve group permissions on
 250    the received WAL files if group permissions are enabled on the source
 251    cluster.
 252   </p></div><div class="refsect1" id="id-1.9.4.17.10"><h2>Examples</h2><p>
 253    To stream the write-ahead log from the server at
 254    <code class="literal">mydbserver</code> and store it in the local directory
 255    <code class="filename">/usr/local/pgsql/archive</code>:
 256 </p><pre class="screen">
 257 <code class="prompt">$</code> <strong class="userinput"><code>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</code></strong>
 258 </pre></div><div class="refsect1" id="id-1.9.4.17.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 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_recvlogical</span></td></tr></table></div></body></html>