472 lines
15 KiB
Plaintext
472 lines
15 KiB
Plaintext
<!--
|
|
doc/src/sgml/ref/pg_recvlogical.sgml
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="app-pgrecvlogical">
|
|
<indexterm zone="app-pgrecvlogical">
|
|
<primary>pg_recvlogical</primary>
|
|
</indexterm>
|
|
|
|
<refmeta>
|
|
<refentrytitle><application>pg_recvlogical</application></refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pg_recvlogical</refname>
|
|
<refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>pg_recvlogical</command>
|
|
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
<command>pg_recvlogical</command> controls logical decoding replication
|
|
slots and streams data from such replication slots.
|
|
</para>
|
|
|
|
<para>
|
|
It creates a replication-mode connection, so it is subject to the same
|
|
constraints as <xref linkend="app-pgreceivewal"/>, plus those for logical
|
|
replication (see <xref linkend="logicaldecoding"/>).
|
|
</para>
|
|
|
|
<para>
|
|
<command>pg_recvlogical</command> has no equivalent to the logical decoding
|
|
SQL interface's peek and get modes. It sends replay confirmations for
|
|
data lazily as it receives it and on clean exit. To examine pending data on
|
|
a slot without consuming it, use
|
|
<link linkend="functions-replication"><function>pg_logical_slot_peek_changes</function></link>.
|
|
</para>
|
|
|
|
<para>
|
|
In the absence of fatal errors, <application>pg_recvlogical</application>
|
|
will run until terminated by the <systemitem>SIGINT</systemitem>
|
|
(<keycombo action="simul"><keycap>Control</keycap><keycap>C</keycap></keycombo>)
|
|
or <systemitem>SIGTERM</systemitem> signal.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
At least one of the following options must be specified to select an action:
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--create-slot</option></term>
|
|
<listitem>
|
|
<para>
|
|
Create a new logical replication slot with the name specified by
|
|
<option>--slot</option>, using the output plugin specified by
|
|
<option>--plugin</option>, for the database specified
|
|
by <option>--dbname</option>.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>--two-phase</option> can be specified with
|
|
<option>--create-slot</option> to enable decoding of prepared transactions.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--drop-slot</option></term>
|
|
<listitem>
|
|
<para>
|
|
Drop the replication slot with the name specified
|
|
by <option>--slot</option>, then exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--start</option></term>
|
|
<listitem>
|
|
<para>
|
|
Begin streaming changes from the logical replication slot specified
|
|
by <option>--slot</option>, continuing until terminated by a
|
|
signal. If the server side change stream ends with a server shutdown
|
|
or disconnect, retry in a loop unless
|
|
<option>--no-loop</option> is specified.
|
|
</para>
|
|
|
|
<para>
|
|
The stream format is determined by the output plugin specified when
|
|
the slot was created.
|
|
</para>
|
|
|
|
<para>
|
|
The connection must be to the same database used to create the slot.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
<option>--create-slot</option> and <option>--start</option> can be
|
|
specified together. <option>--drop-slot</option> cannot be combined with
|
|
another action.
|
|
</para>
|
|
|
|
<para>
|
|
The following command-line options control the location and format of the
|
|
output and other replication behavior:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-E <replaceable>lsn</replaceable></option></term>
|
|
<term><option>--endpos=<replaceable>lsn</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
In <option>--start</option> mode, automatically stop replication
|
|
and exit with normal exit status 0 when receiving reaches the
|
|
specified LSN. If specified when not in <option>--start</option>
|
|
mode, an error is raised.
|
|
</para>
|
|
|
|
<para>
|
|
If there's a record with LSN exactly equal to <replaceable>lsn</replaceable>,
|
|
the record will be output.
|
|
</para>
|
|
|
|
<para>
|
|
The <option>--endpos</option> option is not aware of transaction
|
|
boundaries and may truncate output partway through a transaction.
|
|
Any partially output transaction will not be consumed and will be
|
|
replayed again when the slot is next read from. Individual messages
|
|
are never truncated.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-f <replaceable>filename</replaceable></option></term>
|
|
<term><option>--file=<replaceable>filename</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Write received and decoded transaction data into this
|
|
file. Use <literal>-</literal> for <systemitem>stdout</systemitem>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-F <replaceable>interval_seconds</replaceable></option></term>
|
|
<term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies how often <application>pg_recvlogical</application> should
|
|
issue <function>fsync()</function> calls to ensure the output file is
|
|
safely flushed to disk.
|
|
</para>
|
|
|
|
<para>
|
|
The server will occasionally request the client to perform a flush and
|
|
report the flush position to the server. This setting is in addition
|
|
to that, to perform flushes more frequently.
|
|
</para>
|
|
|
|
<para>
|
|
Specifying an interval of <literal>0</literal> disables
|
|
issuing <function>fsync()</function> calls altogether, while still
|
|
reporting progress to the server. In this case, data could be lost in
|
|
the event of a crash.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-I <replaceable>lsn</replaceable></option></term>
|
|
<term><option>--startpos=<replaceable>lsn</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
In <option>--start</option> mode, start replication from the given
|
|
LSN. For details on the effect of this, see the documentation
|
|
in <xref linkend="logicaldecoding"/>
|
|
and <xref linkend="protocol-replication"/>. Ignored in other modes.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--if-not-exists</option></term>
|
|
<listitem>
|
|
<para>
|
|
Do not error out when <option>--create-slot</option> is specified
|
|
and a slot with the specified name already exists.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-n</option></term>
|
|
<term><option>--no-loop</option></term>
|
|
<listitem>
|
|
<para>
|
|
When the connection to the server is lost, do not retry in a loop, just exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
|
|
<term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
|
|
<listitem>
|
|
<para>
|
|
Pass the option <replaceable>name</replaceable> to the output plugin with,
|
|
if specified, the option value <replaceable>value</replaceable>. Which
|
|
options exist and their effects depends on the used output plugin.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-P <replaceable>plugin</replaceable></option></term>
|
|
<term><option>--plugin=<replaceable>plugin</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
When creating a slot, use the specified logical decoding output
|
|
plugin. See <xref linkend="logicaldecoding"/>. This option has no
|
|
effect if the slot already exists.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-s <replaceable>interval_seconds</replaceable></option></term>
|
|
<term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
This option has the same effect as the option of the same name
|
|
in <xref linkend="app-pgreceivewal"/>. See the description there.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-S <replaceable>slot_name</replaceable></option></term>
|
|
<term><option>--slot=<replaceable>slot_name</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
In <option>--start</option> mode, use the existing logical replication slot named
|
|
<replaceable>slot_name</replaceable>. In <option>--create-slot</option>
|
|
mode, create the slot with this name. In <option>--drop-slot</option>
|
|
mode, delete the slot with this name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-t</option></term>
|
|
<term><option>--two-phase</option></term>
|
|
<listitem>
|
|
<para>
|
|
Enables decoding of prepared transactions. This option may only be specified with
|
|
<option>--create-slot</option>.
|
|
</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>dbname</replaceable></option></term>
|
|
<term><option>--dbname=<replaceable>dbname</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
The database to connect to. See the description
|
|
of the actions for what this means in detail.
|
|
The <replaceable>dbname</replaceable> can be a <link
|
|
linkend="libpq-connstring">connection string</link>. If so,
|
|
connection string parameters will override any conflicting
|
|
command line options. Defaults to the user name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
|
|
<term><option>--host=<replaceable>hostname-or-ip</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>port</replaceable></option></term>
|
|
<term><option>--port=<replaceable>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>user</replaceable></option></term>
|
|
<term><option>--username=<replaceable>user</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
User name to connect as. Defaults to current operating system user
|
|
name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-w</option></term>
|
|
<term><option>--no-password</option></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_recvlogical</application> to prompt for a
|
|
password before connecting to a database.
|
|
</para>
|
|
|
|
<para>
|
|
This option is never essential, since
|
|
<application>pg_recvlogical</application> will automatically prompt
|
|
for a password if the server demands password authentication.
|
|
However, <application>pg_recvlogical</application> will waste a
|
|
connection attempt finding out that the server wants a password.
|
|
In some cases it is worth typing <option>-W</option> to avoid the extra
|
|
connection attempt.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
The following additional options are available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-V</option></term>
|
|
<term><option>--version</option></term>
|
|
<listitem>
|
|
<para>
|
|
Print the <application>pg_recvlogical</application> version and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</option></term>
|
|
<term><option>--help</option></term>
|
|
<listitem>
|
|
<para>
|
|
Show help about <application>pg_recvlogical</application> command line
|
|
arguments, and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Exit Status</title>
|
|
<para>
|
|
<application>pg_recvlogical</application> will exit with status 0 when
|
|
terminated by the <systemitem>SIGINT</systemitem> or
|
|
<systemitem>SIGTERM</systemitem> 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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<para>
|
|
This utility, like most other <productname>PostgreSQL</productname> utilities,
|
|
uses the environment variables supported by <application>libpq</application>
|
|
(see <xref linkend="libpq-envars"/>).
|
|
</para>
|
|
|
|
<para>
|
|
The environment variable <envar>PG_COLOR</envar> specifies whether to use
|
|
color in diagnostic messages. Possible values are
|
|
<literal>always</literal>, <literal>auto</literal> and
|
|
<literal>never</literal>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>
|
|
<application>pg_recvlogical</application> will preserve group permissions on
|
|
the received WAL files if group permissions are enabled on the source
|
|
cluster.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Examples</title>
|
|
|
|
<para>
|
|
See <xref linkend="logicaldecoding-example"/> for an example.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-pgreceivewal"/></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|