codekingpro/portable-devtools
114k
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>