mirror of
https://github.com/postgres/postgres.git
synced 2025-12-19 17:02:53 +03:00
552faefd68
The old note about how to use pg_receivexlog as an alternative to archive_command was obsoleted by replication slots.
360 lines
12 KiB
Plaintext
360 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>
|
|
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>-F <replaceable class="parameter">interval</replaceable></option></term>
|
|
<term><option>--fsync-interval=<replaceable class="parameter">interval</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies the maximum time to issue sync commands to ensure the
|
|
received WAL file is safely flushed to disk, in seconds. The default
|
|
value is zero, which disables issuing fsyncs except when WAL file is
|
|
closed. If <literal>-1</literal> is specified, WAL file is flushed as
|
|
soon as possible, that is, as soon as there are WAL data which has
|
|
not been flushed yet.
|
|
</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. When using this parameter, it is important
|
|
to make sure that <application>pg_receivexlog</> cannot become the
|
|
synchronous standby through an incautious setting of
|
|
<xref linkend="guc-synchronous-standby-names">; it does not flush
|
|
data frequently enough for this to work correctly.
|
|
</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>
|