2 doc/src/sgml/ref/pg_receivewal.sgml
3 PostgreSQL documentation
6 <refentry id="app-pgreceivewal">
7 <indexterm zone="app-pgreceivewal">
8 <primary>pg_receivewal</primary>
12 <refentrytitle>pg_receivewal</refentrytitle>
13 <manvolnum>1</manvolnum>
14 <refmiscinfo>Application</refmiscinfo>
18 <refname>pg_receivewal</refname>
19 <refpurpose>stream write-ahead logs from a <productname>PostgreSQL</productname> server</refpurpose>
24 <command>pg_receivewal</command>
25 <arg rep="repeat"><replaceable>option</></arg>
34 <application>pg_receivewal</application> is used to stream the write-ahead log
35 from a running <productname>PostgreSQL</productname> cluster. The write-ahead
36 log is streamed using the streaming replication protocol, and is written
37 to a local directory of files. This directory can be used as the archive
38 location for doing a restore using point-in-time recovery (see
39 <xref linkend="continuous-archiving">).
43 <application>pg_receivewal</application> streams the write-ahead
44 log in real time as it's being generated on the server, and does not wait
45 for segments to complete like <xref linkend="guc-archive-command"> does.
46 For this reason, it is not necessary to set
47 <xref linkend="guc-archive-timeout"> when using
48 <application>pg_receivewal</application>.
52 Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivewal</>
53 by default flushes WAL data only when a WAL file is closed.
54 The option <option>--synchronous</> must be specified to flush WAL data
59 The write-ahead log is streamed over a regular
60 <productname>PostgreSQL</productname> connection and uses the replication
61 protocol. The connection must be made with a superuser or a user
62 having <literal>REPLICATION</literal> permissions (see
63 <xref linkend="role-attributes">), and <filename>pg_hba.conf</filename>
64 must permit the replication connection. The server must also be
65 configured with <xref linkend="guc-max-wal-senders"> set high enough to
66 leave at least one session available for the stream.
70 If the connection is lost, or if it cannot be initially established,
71 with a non-fatal error, <application>pg_receivewal</application> will
72 retry the connection indefinitely, and reestablish streaming as soon
73 as possible. To avoid this behavior, use the <literal>-n</literal>
79 <title>Options</title>
83 <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
84 <term><option>--directory=<replaceable class="parameter">directory</replaceable></option></term>
87 Directory to write the output to.
90 This parameter is required.
96 <term><option>--if-not-exists</option></term>
99 Do not error out when <option>--create-slot</option> is specified
100 and a slot with the specified name already exists.
106 <term><option>-n</option></term>
107 <term><option>--no-loop</option></term>
110 Don't loop on connection errors. Instead, exit right away with
117 <term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
118 <term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>
121 Specifies the number of seconds between status packets sent back to the
122 server. This allows for easier monitoring of the progress from server.
123 A value of zero disables the periodic status updates completely,
124 although an update will still be sent when requested by the server, to
125 avoid timeout disconnect. The default value is 10 seconds.
131 <term><option>-S <replaceable>slotname</replaceable></option></term>
132 <term><option>--slot=<replaceable class="parameter">slotname</replaceable></option></term>
135 Require <application>pg_receivewal</application> to use an existing
136 replication slot (see <xref linkend="streaming-replication-slots">).
137 When this option is used, <application>pg_receivewal</> will report
138 a flush position to the server, indicating when each segment has been
139 synchronized to disk so that the server can remove that segment if it
140 is not otherwise needed.
144 When the replication client
145 of <application>pg_receivewal</application> is configured on the
146 server as a synchronous standby, then using a replication slot will
147 report the flush position to the server, but only when a WAL file is
148 closed. Therefore, that configuration will cause transactions on the
149 primary to wait for a long time and effectively not work
150 satisfactorily. The option <literal>--synchronous</literal> (see
151 below) must be specified in addition to make this work correctly.
157 <term><option>--synchronous</option></term>
160 Flush the WAL data to disk immediately after it has been received. Also
161 send a status packet back to the server immediately after flushing,
162 regardless of <literal>--status-interval</>.
166 This option should be specified if the replication client
167 of <application>pg_receivewal</application> is configured on the
168 server as a synchronous standby, to ensure that timely feedback is
175 <term><option>-v</option></term>
176 <term><option>--verbose</option></term>
179 Enables verbose mode.
185 <term><option>-Z <replaceable class="parameter">level</replaceable></option></term>
186 <term><option>--compress=<replaceable class="parameter">level</replaceable></option></term>
189 Enables gzip compression of write-ahead logs, and specifies the
190 compression level (0 through 9, 0 being no compression and 9 being best
191 compression). The suffix <filename>.gz</filename> will
192 automatically be added to all filenames.
199 The following command-line options control the database connection parameters.
203 <term><option>-d <replaceable class="parameter">connstr</replaceable></option></term>
204 <term><option>--dbname=<replaceable class="parameter">connstr</replaceable></option></term>
207 Specifies parameters used to connect to the server, as a connection
208 string. See <xref linkend="libpq-connstring"> for more information.
211 The option is called <literal>--dbname</> for consistency with other
212 client applications, but because <application>pg_receivewal</application>
213 doesn't connect to any particular database in the cluster, database
214 name in the connection string will be ignored.
220 <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
221 <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
224 Specifies the host name of the machine on which the server is
225 running. If the value begins with a slash, it is used as the
226 directory for the Unix domain socket. The default is taken
227 from the <envar>PGHOST</envar> environment variable, if set,
228 else a Unix domain socket connection is attempted.
234 <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
235 <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
238 Specifies the TCP port or local Unix domain socket file
239 extension on which the server is listening for connections.
240 Defaults to the <envar>PGPORT</envar> environment variable, if
241 set, or a compiled-in default.
247 <term><option>-U <replaceable>username</replaceable></option></term>
248 <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
251 User name to connect as.
257 <term><option>-w</></term>
258 <term><option>--no-password</></term>
261 Never issue a password prompt. If the server requires
262 password authentication and a password is not available by
263 other means such as a <filename>.pgpass</filename> file, the
264 connection attempt will fail. This option can be useful in
265 batch jobs and scripts where no user is present to enter a
272 <term><option>-W</option></term>
273 <term><option>--password</option></term>
276 Force <application>pg_receivewal</application> to prompt for a
277 password before connecting to a database.
281 This option is never essential, since
282 <application>pg_receivewal</application> will automatically prompt
283 for a password if the server demands password authentication.
284 However, <application>pg_receivewal</application> will waste a
285 connection attempt finding out that the server wants a password.
286 In some cases it is worth typing <option>-W</> to avoid the extra
295 <application>pg_receivewal</application> can perform one of the two
296 following actions in order to control physical replication slots:
300 <term><option>--create-slot</option></term>
303 Create a new physical replication slot with the name specified in
304 <option>--slot</option>, then exit.
310 <term><option>--drop-slot</option></term>
313 Drop the replication slot with the name specified in
314 <option>--slot</option>, then exit.
322 Other options are also available:
326 <term><option>-V</></term>
327 <term><option>--version</></term>
330 Print the <application>pg_receivewal</application> version and exit.
336 <term><option>-?</></term>
337 <term><option>--help</></term>
340 Show help about <application>pg_receivewal</application> command line
352 <title>Environment</title>
355 This utility, like most other <productname>PostgreSQL</> utilities,
356 uses the environment variables supported by <application>libpq</>
357 (see <xref linkend="libpq-envars">).
366 When using <application>pg_receivewal</application> instead of
367 <xref linkend="guc-archive-command"> as the main WAL backup method, it is
368 strongly recommended to use replication slots. Otherwise, the server is
369 free to recycle or remove write-ahead log files before they are backed up,
370 because it does not have any information, either
371 from <xref linkend="guc-archive-command"> or the replication slots, about
372 how far the WAL stream has been archived. Note, however, that a
373 replication slot will fill up the server's disk space if the receiver does
374 not keep up with fetching the WAL data.
380 <title>Examples</title>
383 To stream the write-ahead log from the server at
384 <literal>mydbserver</literal> and store it in the local directory
385 <filename>/usr/local/pgsql/archive</filename>:
387 <prompt>$</prompt> <userinput>pg_receivewal -h mydbserver -D /usr/local/pgsql/archive</userinput>
392 <title>See Also</title>
394 <simplelist type="inline">
395 <member><xref linkend="APP-PGBASEBACKUP"></member>