diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_recvlogical.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_recvlogical.sgml | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml new file mode 100644 index 0000000..7c01a5c --- /dev/null +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -0,0 +1,453 @@ +<!-- +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> + </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>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> |