mirror of
https://github.com/postgres/postgres.git
synced 2025-05-26 18:17:33 +03:00
cf42550d51
Reported-by: Alexander Lakhin Discussion: https://postgr.es/m/16486-b9c93d71c02c4907@postgresql.org Backpatch-through: 9.5
386 lines
12 KiB
Plaintext
386 lines
12 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-pgreceivexlog">, plus those for logical
|
|
replication (see <xref linkend="logicaldecoding">).
|
|
</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>
|
|
</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>-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>-</> 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-pgreceivexlog">. 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>-v</></term>
|
|
<term><option>--verbose</></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</> to avoid the extra
|
|
connection attempt.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
The following additional options are available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>-V</></term>
|
|
<term><option>--version</></term>
|
|
<listitem>
|
|
<para>
|
|
Print the <application>pg_recvlogical</application> version and exit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-?</></term>
|
|
<term><option>--help</></term>
|
|
<listitem>
|
|
<para>
|
|
Show help about <application>pg_recvlogical</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>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-pgreceivexlog"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
</refentry>
|