mirror of
https://github.com/postgres/postgres.git
synced 2025-12-19 17:02:53 +03:00
c4f99d2029
Previously pg_receivexlog flushed WAL data only when WAL file was switched.
Then 3dad73e added -F option to pg_receivexlog so that users could control
how frequently sync commands were issued to WAL files. It also allowed users
to make pg_receivexlog flush WAL data immediately after writing by
specifying 0 in -F option. However feedback messages were not sent back
immediately even after a flush location was updated. So even if WAL data
was flushed in real time, the server could not see that for a while.
This commit removes -F option from and adds --synchronous to pg_receivexlog.
If --synchronous is specified, like the standby's wal receiver, pg_receivexlog
flushes WAL data as soon as there is WAL data which has not been flushed yet.
Then it sends back the feedback message identifying the latest flush location
to the server. This option is useful to make pg_receivexlog behave as sync
standby by using replication slot, for example.
Original patch by Furuya Osamu, heavily rewritten by me.
Reviewed by Heikki Linnakangas, Alvaro Herrera and Sawada Masahiko.
362 lines
12 KiB
Plaintext
362 lines
12 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_receivexlog.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgreceivexlog">
|
|
<indexterm zone="app-pgreceivexlog">
|
|
<primary>pg_receivexlog</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle>pg_receivexlog</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_receivexlog</refname>
|
|
<refpurpose>stream transaction logs from a <productname>PostgreSQL</productname> server</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_receivexlog</command>
|
|
<arg rep="repeat"><replaceable>option</></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>
|
|
Description
|
|
</title>
|
|
<para>
|
|
<application>pg_receivexlog</application> is used to stream transaction log
|
|
from a running <productname>PostgreSQL</productname> cluster. The transaction
|
|
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
|
|
<xref linkend="continuous-archiving">).
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_receivexlog</application> streams the transaction
|
|
log in real time as it's being generated on the server, and does not wait
|
|
for segments to complete like <xref linkend="guc-archive-command"> does.
|
|
For this reason, it is not necessary to set
|
|
<xref linkend="guc-archive-timeout"> when using
|
|
<application>pg_receivexlog</application>.
|
|
</para>
|
|
|
|
<para>
|
|
Unlike the standby's WAL receiver, <application>pg_receivexlog</>
|
|
flushes WAL data only when WAL file is closed, by default.
|
|
<literal>--synchronous</> option must be specified to flush WAL data
|
|
in real time and ensure it's safely flushed to disk.
|
|
</para>
|
|
|
|
<para>
|
|
The transaction log is streamed over a regular
|
|
<productname>PostgreSQL</productname> connection, and uses the replication
|
|
protocol. The connection must be made with a superuser or a user
|
|
having <literal>REPLICATION</literal> permissions (see
|
|
<xref linkend="role-attributes">), and <filename>pg_hba.conf</filename>
|
|
must explicitly permit the replication connection. The server must also be
|
|
configured with <xref linkend="guc-max-wal-senders"> set high enough to
|
|
leave at least one session available for the stream.
|
|
</para>
|
|
|
|
<para>
|
|
If the connection is lost, or if it cannot be initially established,
|
|
with a non-fatal error, <application>pg_receivexlog</application> will
|
|
retry the connection indefinitely, and reestablish streaming as soon
|
|
as possible. To avoid this behavior, use the <literal>-n</literal>
|
|
parameter.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
|
|
<term><option>--directory=<replaceable class="parameter">directory</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Directory to write the output to.
|
|
</para>
|
|
<para>
|
|
This parameter is required.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--no-loop</option></term>
|
|
<listitem>
|
|
<para>
|
|
Don't loop on connection errors. Instead, exit right away with
|
|
an error.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
|
|
<term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-S <replaceable>slotname</replaceable></option></term>
|
|
<term><option>--slot=<replaceable class="parameter">slotname</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Require <application>pg_receivexlog</application> to use an existing
|
|
replication slot (see <xref linkend="streaming-replication-slots">).
|
|
When this option is used, <application>pg_receivexlog</> 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. <literal>--synchronous</literal> option must
|
|
be specified when making <application>pg_receivexlog</> run as
|
|
synchronous standby by using replication slot. Otherwise WAL data
|
|
cannot be flushed frequently enough for this to work correctly.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--synchronous</option></term>
|
|
<listitem>
|
|
<para>
|
|
Issue sync commands as soon as there is WAL data which has not been
|
|
flushed yet. Also status packets are sent back to the server just after
|
|
WAL data is flushed whatever <literal>--status-interval</> is set to.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-v</option></term>
|
|
<term><option>--verbose</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables verbose mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
The following command-line options control the database connection parameters.
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-d <replaceable class="parameter">connstr</replaceable></option></term>
|
|
<term><option>--dbname=<replaceable class="parameter">connstr</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies parameters used to connect to the server, as a connection
|
|
string. See <xref linkend="libpq-connstring"> for more information.
|
|
</para>
|
|
<para>
|
|
The option is called <literal>--dbname</> for consistency with other
|
|
client applications, but because <application>pg_receivexlog</application>
|
|
doesn't connect to any particular database in the cluster, database
|
|
name in the connection string will be ignored.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-h <replaceable class="parameter">host</replaceable></option></term>
|
|
<term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
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 <envar>PGHOST</envar> environment variable, if set,
|
|
else a Unix domain socket connection is attempted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-p <replaceable class="parameter">port</replaceable></option></term>
|
|
<term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the TCP port or local Unix domain socket file
|
|
extension on which the server is listening for connections.
|
|
Defaults to the <envar>PGPORT</envar> environment variable, if
|
|
set, or a compiled-in default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-U <replaceable>username</replaceable></option></term>
|
|
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
User name to connect as.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-w</></term>
|
|
<term><option>--no-password</></term>
|
|
<listitem>
|
|
<para>
|
|
Never issue a password prompt. If the server requires
|
|
password authentication and a password is not available by
|
|
other means such as a <filename>.pgpass</filename> 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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-W</option></term>
|
|
<term><option>--password</option></term>
|
|
<listitem>
|
|
<para>
|
|
Force <application>pg_receivexlog</application> to prompt for a
|
|
password before connecting to a database.
|
|
</para>
|
|
|
|
<para>
|
|
This option is never essential, since
|
|
<application>pg_receivexlog</application> will automatically prompt
|
|
for a password if the server demands password authentication.
|
|
However, <application>pg_receivexlog</application> will waste a
|
|
connection attempt finding out that the server wants a password.
|
|
In some cases it is worth typing <option>-W</> to avoid the extra
|
|
connection attempt.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
<application>pg_receivexlog</application> can perform one of the two
|
|
following actions in order to control physical replication slots:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>--create-slot</option></term>
|
|
<listitem>
|
|
<para>
|
|
Create a new physical replication slot with the name specified in
|
|
<option>--slot</option>, then start to stream WAL.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--drop-slot</option></term>
|
|
<listitem>
|
|
<para>
|
|
Drop the replication slot with the name specified in
|
|
<option>--slot</option>, then exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Other options are also available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-V</></term>
|
|
<term><option>--version</></term>
|
|
<listitem>
|
|
<para>
|
|
Print the <application>pg_receivexlog</application> version and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</></term>
|
|
<term><option>--help</></term>
|
|
<listitem>
|
|
<para>
|
|
Show help about <application>pg_receivexlog</application> command line
|
|
arguments, and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<para>
|
|
This utility, like most other <productname>PostgreSQL</> utilities,
|
|
uses the environment variables supported by <application>libpq</>
|
|
(see <xref linkend="libpq-envars">).
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
When using <application>pg_receivexlog</application> instead of
|
|
<xref linkend="guc-archive-command"> as the main WAL backup method, it is
|
|
strongly recommended to use replication slots. Otherwise, the server is
|
|
free to recycle or remove transaction log files before they are backed up,
|
|
because it does not have any information, either
|
|
from <xref linkend="guc-archive-command"> 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.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
To stream the transaction log from the server at
|
|
<literal>mydbserver</literal> and store it in the local directory
|
|
<filename>/usr/local/pgsql/archive</filename>:
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>pg_receivexlog -h mydbserver -D /usr/local/pgsql/archive</userinput>
|
|
</screen></para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="APP-PGBASEBACKUP"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|