mirror of
https://github.com/postgres/postgres.git
synced 2025-12-22 17:42:17 +03:00
aa05c37e82
Without this, there's no way to pass arbitrary libpq connection parameters to these applications. It's a bit strange that the option is called -d/--dbname, when in fact you can *not* pass a database name in it, but it's consistent with other client applications where a connection string is also passed using -d. Original patch by Amit Kapila, heavily modified by me.
313 lines
10 KiB
Plaintext
313 lines
10 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_receivexlog.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgreceivexlog">
|
|
<refmeta>
|
|
<refentrytitle>pg_receivexlog</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_receivexlog</refname>
|
|
<refpurpose>streams transaction logs from a <productname>PostgreSQL</productname> cluster</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="app-pgreceivexlog">
|
|
<primary>pg_receivexlog</primary>
|
|
</indexterm>
|
|
|
|
<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>
|
|
|
|
<para>
|
|
The following command-line options control the location and format of the
|
|
output.
|
|
|
|
<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>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
The following command-line options control the running of the program.
|
|
|
|
<variablelist>
|
|
<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>-v</option></term>
|
|
<term><option>--verbose</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables verbose mode.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<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_basebackup</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>-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>-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>
|
|
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">, the server will continue to
|
|
recycle transaction log files even if the backups are not properly
|
|
archived, since there is no command that fails. This can be worked
|
|
around by having an <xref linkend="guc-archive-command"> that fails
|
|
when the file has not been properly archived yet, for example:
|
|
<programlisting>
|
|
archive_command = 'sleep 5 && test -f /mnt/server/archivedir/%f'
|
|
</programlisting>
|
|
The initial timeout is necessary because
|
|
<application>pg_receivexlog</application> works using asynchronous
|
|
replication and can therefore be slightly behind the master.
|
|
</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>
|