Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
app-pgreceivewal.html251 linesDownload Raw Back to 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 16.3 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>3   <span class="application">pg_receivewal</span> is used to stream the write-ahead log4   from a running <span class="productname">PostgreSQL</span> cluster. The write-ahead5   log is streamed using the streaming replication protocol, and is written6   to a local directory of files. This directory can be used as the archive7   location for doing a restore using point-in-time recovery (see8   <a class="xref" href="continuous-archiving.html" title="26.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 26.3</a>).9  </p><p>10   <span class="application">pg_receivewal</span> streams the write-ahead11   log in real time as it's being generated on the server, and does not wait12   for segments to complete like <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> and13   <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> do.14   For this reason, it is not necessary to set15   <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT">archive_timeout</a> when using16    <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 data21   in real time. Since <span class="application">pg_receivewal</span> does not22   apply WAL, you should not allow it to become a synchronous standby when23   <a class="xref" href="runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT">synchronous_commit</a> equals24   <code class="literal">remote_apply</code>. If it does, it will appear to be a25   standby that never catches up, and will cause transaction commits to26   block. To avoid this, you should either configure an appropriate value27   for <a class="xref" href="runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES">synchronous_standby_names</a>, or specify28   <code class="varname">application_name</code> for29   <span class="application">pg_receivewal</span> that does not match it, or30   change the value of <code class="varname">synchronous_commit</code> to31   something other than <code class="literal">remote_apply</code>.32  </p><p>33   The write-ahead log is streamed over a regular34   <span class="productname">PostgreSQL</span> connection and uses the replication35   protocol. The connection must be made with a user having36   <code class="literal">REPLICATION</code> permissions (see37   <a class="xref" href="role-attributes.html" title="22.2. Role Attributes">Section 22.2</a>) or a superuser, and38   <code class="filename">pg_hba.conf</code> must permit the replication connection.39   The server must also be configured with40   <a class="xref" href="runtime-config-replication.html#GUC-MAX-WAL-SENDERS">max_wal_senders</a> set high enough to leave at least41   one session available for the stream.42  </p><p>43   The starting point of the write-ahead log streaming is calculated when44   <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 and47      find the newest completed segment file, using as the starting point the48      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 extra52      <code class="command">READ_REPLICATION_SLOT</code> command is issued to retrieve53      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 from55      <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 from59      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> will64   retry the connection indefinitely, and reestablish streaming as soon65   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.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>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 when78        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 specified84        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 with87        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 WAL90        data to be flushed to disk.  This is faster, but means that a91        subsequent operating system crash can leave the WAL segments corrupt.92        Generally, this option is useful for testing but should not be used93        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 the98        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, to101        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 existing104         replication slot (see <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="27.2.6. Replication Slots">Section 27.2.6</a>).105         When this option is used, <span class="application">pg_receivewal</span> will report106         a flush position to the server, indicating when each segment has been107         synchronized to disk so that the server can remove that segment if it108         is not otherwise needed.109        </p><p>110         When the replication client111         of <span class="application">pg_receivewal</span> is configured on the112         server as a synchronous standby, then using a replication slot will113         report the flush position to the server, but only when a WAL file is114         closed.  Therefore, that configuration will cause transactions on the115         primary to wait for a long time and effectively not work116         satisfactorily.  The option <code class="literal">--synchronous</code> (see117         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. Also120        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 client124        of <span class="application">pg_receivewal</span> is configured on the125        server as a synchronous standby, to ensure that timely feedback is126        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>) or135        <code class="literal">none</code> for no compression.136        A compression detail string can optionally be specified.  If the137        detail string is an integer, it specifies the compression level.138        Otherwise, it should be a comma-separated list of items, each of the139        form <code class="literal">keyword</code> or <code class="literal">keyword=value</code>.140        Currently, the only supported keyword is <code class="literal">level</code>.141       </p><p>142        If no compression level is specified, the default compression level143        will be used. If only a level is specified without mentioning an144        algorithm, <code class="literal">gzip</code> compression will be used if the145        level is greater than 0, and no compression will be used if the level146        is 0.147       </p><p>148        The suffix <code class="filename">.gz</code> will automatically be added to149        all filenames when using <code class="literal">gzip</code>, and the suffix150        <code class="filename">.lz4</code> is added when using <code class="literal">lz4</code>.151       </p></dd></dl></div><p>152    The following command-line options control the database connection parameters.153 154    </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>155        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>;  these156        will override any conflicting command line options.157       </p><p>158        The option is called <code class="literal">--dbname</code> for consistency with other159        client applications, but because <span class="application">pg_receivewal</span>160        doesn't connect to any particular database in the cluster, database161        name in the connection string will be ignored.162       </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>163        Specifies the host name of the machine on which the server is164        running.  If the value begins with a slash, it is used as the165        directory for the Unix domain socket. The default is taken166        from the <code class="envar">PGHOST</code> environment variable, if set,167        else a Unix domain socket connection is attempted.168       </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>169        Specifies the TCP port or local Unix domain socket file170        extension on which the server is listening for connections.171        Defaults to the <code class="envar">PGPORT</code> environment variable, if172        set, or a compiled-in default.173       </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>174        User name to connect as.175       </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>176        Never issue a password prompt.  If the server requires177        password authentication and a password is not available by178        other means such as a <code class="filename">.pgpass</code> file, the179        connection attempt will fail.  This option can be useful in180        batch jobs and scripts where no user is present to enter a181        password.182       </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>183        Force <span class="application">pg_receivewal</span> to prompt for a184        password before connecting to a database.185       </p><p>186        This option is never essential, since187        <span class="application">pg_receivewal</span> will automatically prompt188        for a password if the server demands password authentication.189        However, <span class="application">pg_receivewal</span> will waste a190        connection attempt finding out that the server wants a password.191        In some cases it is worth typing <code class="option">-W</code> to avoid the extra192        connection attempt.193       </p></dd></dl></div><p>194   </p><p>195    <span class="application">pg_receivewal</span> can perform one of the two196    following actions in order to control physical replication slots:197 198    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">--create-slot</code></span></dt><dd><p>199        Create a new physical replication slot with the name specified in200        <code class="option">--slot</code>, then exit.201       </p></dd><dt><span class="term"><code class="option">--drop-slot</code></span></dt><dd><p>202        Drop the replication slot with the name specified in203        <code class="option">--slot</code>, then exit.204       </p></dd></dl></div><p>205   </p><p>206    Other options are also available:207 208    </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>209       Print the <span class="application">pg_receivewal</span> version and exit.210       </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>211       Show help about <span class="application">pg_receivewal</span> command line212       arguments, and exit.213       </p></dd></dl></div><p>214   </p></div><div class="refsect1" id="id-1.9.4.16.7"><h2>Exit Status</h2><p>215   <span class="application">pg_receivewal</span> will exit with status 0 when216   terminated by the <span class="systemitem">SIGINT</span> or217   <span class="systemitem">SIGTERM</span> signal.  (That is the218   normal way to end it.  Hence it is not an error.)  For fatal errors or219   other signals, the exit status will be nonzero.220  </p></div><div class="refsect1" id="id-1.9.4.16.8"><h2>Environment</h2><p>221   This utility, like most other <span class="productname">PostgreSQL</span> utilities,222   uses the environment variables supported by <span class="application">libpq</span>223   (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).224  </p><p>225   The environment variable <code class="envar">PG_COLOR</code> specifies whether to use226   color in diagnostic messages. Possible values are227   <code class="literal">always</code>, <code class="literal">auto</code> and228   <code class="literal">never</code>.229  </p></div><div class="refsect1" id="id-1.9.4.16.9"><h2>Notes</h2><p>230   When using <span class="application">pg_receivewal</span> instead of231   <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or232   <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> as the main WAL backup method, it is233   strongly recommended to use replication slots.  Otherwise, the server is234   free to recycle or remove write-ahead log files before they are backed up,235   because it does not have any information, either236   from <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-COMMAND">archive_command</a> or237   <a class="xref" href="runtime-config-wal.html#GUC-ARCHIVE-LIBRARY">archive_library</a> or the replication slots, about238   how far the WAL stream has been archived.  Note, however, that a239   replication slot will fill up the server's disk space if the receiver does240   not keep up with fetching the WAL data.241  </p><p>242   <span class="application">pg_receivewal</span> will preserve group permissions on243   the received WAL files if group permissions are enabled on the source244   cluster.245  </p></div><div class="refsect1" id="id-1.9.4.16.10"><h2>Examples</h2><p>246   To stream the write-ahead log from the server at247   <code class="literal">mydbserver</code> and store it in the local directory248   <code class="filename">/usr/local/pgsql/archive</code>:249</p><pre class="screen">250<code class="prompt">$</code> <strong class="userinput"><code>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</code></strong>251</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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_recvlogical</span></td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai