diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:15:05 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:15:05 +0000 |
| commit | 46651ce6fe013220ed397add242004d764fc0153 (patch) | |
| tree | 6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/html/app-pgreceivewal.html | |
| parent | Initial commit. (diff) | |
| download | postgresql-14-upstream.tar.xz postgresql-14-upstream.zip | |
Adding upstream version 14.5.upstream/14.5upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
| -rw-r--r-- | doc/src/sgml/html/app-pgreceivewal.html | 222 |
1 files changed, 222 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..701706d --- /dev/null +++ b/doc/src/sgml/html/app-pgreceivewal.html @@ -0,0 +1,222 @@ +<?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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span xmlns="http://www.w3.org/1999/xhtml" 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 14.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></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> does. + 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, + 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">--compress=<em class="replaceable"><code>level</code></em></code></span></dt><dd><p> + Enables gzip compression of write-ahead logs, and specifies the + compression level (0 through 9, 0 being no compression and 9 being best + compression). The suffix <code class="filename">.gz</code> will + automatically be added to all filenames. + </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> 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 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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></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 xmlns="http://www.w3.org/1999/xhtml" class="application">pg_isready</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span xmlns="http://www.w3.org/1999/xhtml" class="application">pg_recvlogical</span></td></tr></table></div></body></html>
\ No newline at end of file |