Skip to content

P
Postgres FD Implementation
Commit 52c1ae22 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

doc: Clean up pg_recvlogical reference page 

This needed a general cleanup of wording, typos, outdated terminology,
formatting, and hard-to-understand and borderline incorrect information.

Also tweak the pg_receivexlog page a bit to make the two more
consistent.
parent 60f8133d
Show whitespace changes
Inline Side-by-side
Showing with 231 additions and 210 deletions
doc/src/sgml/ref/pg_receivexlog.sgml
View file @ 52c1ae22
...@@ -16,7 +16,7 @@ PostgreSQL documentation ...@@ -16,7 +16,7 @@ PostgreSQL documentation
<refnamediv> <refnamediv>
<refname>pg_receivexlog</refname> <refname>pg_receivexlog</refname>
<refpurpose>streams transaction logs from a <productname>PostgreSQL</productname> cluster</refpurpose> <refpurpose>stream transaction logs from a <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
...@@ -71,10 +71,6 @@ PostgreSQL documentation ...@@ -71,10 +71,6 @@ PostgreSQL documentation
<refsect1> <refsect1>
<title>Options</title> <title>Options</title>
<para>
The following command-line options control the location and format of the
output.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term> <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
...@@ -88,12 +84,22 @@ PostgreSQL documentation ...@@ -88,12 +84,22 @@ PostgreSQL documentation
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist>
</para> <varlistentry>
<term><option>-F <replaceable class="parameter">interval</replaceable></option></term>
<term><option>--fsync-interval=<replaceable class="parameter">interval</replaceable></option></term>
<listitem>
<para> <para>
The following command-line options control the running of the program. 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>
<variablelist>
<varlistentry> <varlistentry>
<term><option>-n</option></term> <term><option>-n</option></term>
<term><option>--no-loop</option></term> <term><option>--no-loop</option></term>
...@@ -106,16 +112,34 @@ PostgreSQL documentation ...@@ -106,16 +112,34 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-F <replaceable class="parameter">interval</replaceable></option></term> <term><option>-s <replaceable class="parameter">interval</replaceable></option></term>
<term><option>--fsync-interval=<replaceable class="parameter">interval</replaceable></option></term> <term><option>--status-interval=<replaceable class="parameter">interval</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Specifies the maximum time to issue sync commands to ensure the Specifies the number of seconds between status packets sent back to the
received WAL file is safely flushed to disk, in seconds. The default server. This allows for easier monitoring of the progress from server.
value is zero, which disables issuing fsyncs except when WAL file is A value of zero disables the periodic status updates completely,
closed. If <literal>-1</literal> is specified, WAL file is flushed as although an update will still be sent when requested by the server, to
soon as possible, that is, as soon as there are WAL data which has avoid timeout disconnect. The default value is 10 seconds.
not been flushed yet. </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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -129,9 +153,7 @@ PostgreSQL documentation ...@@ -129,9 +153,7 @@ PostgreSQL documentation
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para>
<para> <para>
The following command-line options control the database connection parameters. The following command-line options control the database connection parameters.
...@@ -181,20 +203,6 @@ PostgreSQL documentation ...@@ -181,20 +203,6 @@ PostgreSQL documentation
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><option>-U <replaceable>username</replaceable></option></term> <term><option>-U <replaceable>username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
...@@ -240,27 +248,6 @@ PostgreSQL documentation ...@@ -240,27 +248,6 @@ PostgreSQL documentation
</para> </para>
</listitem> </listitem>
</varlistentry> </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. 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>
</variablelist> </variablelist>
</para> </para>
......
doc/src/sgml/ref/pg_recvlogical.sgml
View file @ 52c1ae22
...@@ -16,39 +16,35 @@ PostgreSQL documentation ...@@ -16,39 +16,35 @@ PostgreSQL documentation
<refnamediv> <refnamediv>
<refname>pg_recvlogical</refname> <refname>pg_recvlogical</refname>
<refpurpose>Control logical decoding (see <xref linkend="logicaldecoding">) <refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
streams over a walsender connection.</refpurpose>
</refnamediv> </refnamediv>
<refsynopsisdiv> <refsynopsisdiv>
<cmdsynopsis> <cmdsynopsis>
<command>pg_recvlogical</command> <command>pg_recvlogical</command>
<arg rep="repeat" choice="opt"><option>option</option></arg> <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
<refsect1 id="R1-APP-PGRECVLOGICAL-1"> <refsect1>
<title>Description</title> <title>Description</title>
<para> <para>
<command>pg_recvlogical</command> controls logical decoding replication <command>pg_recvlogical</command> controls logical decoding replication
slots and streams data from such replication slots. slots and streams data from such replication slots.
</para> </para>
<para> <para>
It creates a replication-mode connection, so it is subject to the same It creates a replication-mode connection, so it is subject to the same
constraints as <link constraints as <xref linkend="app-pgreceivexlog">, plus those for logical
linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>, replication (see <xref linkend="logicaldecoding">).
plus those for logical replication (see <xref
linkend="logicaldecoding">).
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Options</title> <title>Options</title>
<para> <para>
<application>pg_recvlogical</application> runs in one of three modes, which At least one of the following options must be specified to select an action:
control its primary action:
<variablelist> <variablelist>
...@@ -56,254 +52,275 @@ PostgreSQL documentation ...@@ -56,254 +52,275 @@ PostgreSQL documentation
<term><option>--create-slot</option></term> <term><option>--create-slot</option></term>
<listitem> <listitem>
<para> <para>
Create a new logical replication slot with the name specified in Create a new logical replication slot with the name specified by
<option>--slot</option>, using the output plugin <option>--slot</option>, using the output plugin specified by
<option>--plugin</option>. The slot is created for the database <option>--plugin</option>, for the database specified
given in <option>--dbname</option>. by <option>--dbname</option>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>--start</option></term> <term><option>--drop-slot</option></term>
<listitem> <listitem>
<para> <para>
Begin streaming changes from the logical replication slot with the name Drop the replication slot with the name specified
specified in <option>--slot</option>, continuing until terminated with a by <option>--slot</option>, then exit.
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. The stream format is
determined by the output plugin specified when the slot was created.
</para>
<para>
You must connect to the same database used to create the slot.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>--drop-slot</option></term> <term><option>--start</option></term>
<listitem> <listitem>
<para> <para>
Drop the replication slot with the name specified Begin streaming changes from the logical replication slot specified
in <option>--slot</option>, then exit. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </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>
<para> <para>
<application>pg_recvlogical</application> supports all the usual The following command-line options control the location and format of the
<literal>libpq</literal>-based options. These are explained in detail in output and other replication behavior:
the documentation for
<link linkend="APP-PSQL"><application>psql</application></link> and for
<link linkend="libpq"><literal>libpq</literal></link>.
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><option>-U <replaceable>user</replaceable></option></term> <term><option>-f <replaceable>filename</replaceable></option></term>
<term><option>--username <replaceable>user</replaceable></option></term> <term><option>--file=<replaceable>filename</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Username to connect as. Must have a suitable <literal>pg_hba.conf</literal> Write received and decoded transaction data into this
entry allowing <literal>replication</literal> connections. Defaults to file. Use <literal>-</> for stdout.
current operating system user name.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-d <replaceable>database</replaceable></option></term> <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
<term><option>--dbname <replaceable>database</replaceable></option></term> <term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
<listitem> <listitem>
<para> <para>
The database to connect to in <literal>replication</literal> mode; see Specifies how often <application>pg_recvlogical</application> should
mode descriptions for details. May be issue <function>fsync()</function> calls to ensure the output file is
a <link linkend="LIBPQ-CONNSTRING">libpq connstring</link> safely flushed to disk.
instead. Defaults to user name. </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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-h <replaceable>hostname-or-ip</replaceable></option></term> <term><option>-I <replaceable>lsn</replaceable></option></term>
<term><option>--host <replaceable>hostname-or-ip</replaceable></option></term> <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Host or socket to connect In <option>--start</option> mode, start replication from the given
to. See <link linkend="APP-PSQL"><application>psql</application></link> LSN. For details on the effect of this, see the documentation
and <link linkend="libpq"><literal>libpq</literal></link> in <xref linkend="logicaldecoding">
documentation. and <xref linkend="protocol-replication">. Ignored in other modes.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-p <replaceable>port</replaceable></option></term> <term><option>-n</option></term>
<term><option>--port <replaceable>port</replaceable></option></term> <term><option>--no-loop</option></term>
<listitem> <listitem>
<para> <para>
Port number to connect to. See When the connection to the server is lost, do not retry in a loop, just exit.
<link linkend="R1-APP-PSQL-3"><application>psql</application></link>
for an explanation of default port choices when this is not
specified.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-w</option></term> <term><option>-o <replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
<term><option>--no-password</option></term> <term><option>--option=<replaceable>name</replaceable>[=<replaceable>value</replaceable>]</option></term>
<listitem> <listitem>
<para> <para>
Prevent prompting for a password. Will exit with an error code if a Pass the option <replaceable>name</replaceable> to the output plugin with,
password is required but not available. if specified, the option value <replaceable>value</replaceable>. Which
options exist and their effects depends on the used output plugin.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-W</option></term> <term><option>-P <replaceable>plugin</replaceable></option></term>
<term><option>--password</option></term> <term><option>--plugin=<replaceable>plugin</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Provide a password for this connection. Please use the pgservice file When creating a slot, use the specified logical decoding output
(see <xref linkend="libpq-pgservice">) or an environment variable plugin. See <xref linkend="logicaldecoding">. This option has no
instead of this option. effect if the slot already exists.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> <varlistentry>
<term><option>-s <replaceable>interval_seconds</replaceable></option></term>
</para> <term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term>
<listitem>
<para> <para>
The following command-line options control the location and format of the This option has the same effect as the option of the same name
output and other replication behavior: in <xref linkend="app-pgreceivexlog">. See the description there.
</para>
<variablelist> </listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option>-f <replaceable>filename</replaceable></option></term> <term><option>-S <replaceable>slot_name</replaceable></option></term>
<term><option>--file=<replaceable>filename</replaceable></option></term> <term><option>--slot=<replaceable>slot_name</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Write received and decoded transaction data into this In <option>--start</option> mode, use the existing logical replication slot named
file. Use <literal>-</> for stdout. <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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-n</option></term> <term><option>-v</></term>
<term><option>--no-loop</option></term> <term><option>--verbose</></term>
<listitem> <listitem>
<para> <para>
When the connection to the server is lost, do not retry in a loop, just exit. Enables verbose mode.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist>
</para>
<para>
The following command-line options control the database connection parameters.
<variablelist>
<varlistentry> <varlistentry>
<term><option>-o <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term> <term><option>-d <replaceable>database</replaceable></option></term>
<term><option>--option=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term> <term><option>--dbname <replaceable>database</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Pass the option <parameter>NAME</parameter> to the output plugin with, The database to connect to. See the description of the actions for
if specified, the option value <parameter>NAME</parameter>. Which what this means in detail. This can be a libpq connection string;
options exist and their effects depends on the used output plugin. see <xref linkend="LIBPQ-CONNSTRING"> for more information. Defaults
to user name.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-F <replaceable>interval_seconds</replaceable></option></term> <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
<term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term> <term><option>--host <replaceable>hostname-or-ip</replaceable></option></term>
<listitem> <listitem>
<para> <para>
How often should <application>pg_recvlogical</application> issue sync Specifies the host name of the machine on which the server is
commands to ensure the <parameter>--outputfile</parameter> is safely running. If the value begins with a slash, it is used as the
flushed to disk without being asked by the server to do so. Specifying directory for the Unix domain socket. The default is taken
an interval of <literal>0</literal> disables issuing fsyncs altogether, from the <envar>PGHOST</envar> environment variable, if set,
while still reporting progress the server. In this case, data may be else a Unix domain socket connection is attempted.
lost in the event of a crash.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-P <replaceable>plugin</replaceable></option></term> <term><option>-p <replaceable>port</replaceable></option></term>
<term><option>--plugin=<replaceable>plugin</replaceable></option></term> <term><option>--port <replaceable>port</replaceable></option></term>
<listitem> <listitem>
<para> <para>
When creating a slot, use the logical decoding output Specifies the TCP port or local Unix domain socket file
plugin. See <xref linkend="logicaldecoding">. This option has no extension on which the server is listening for connections.
effect if the slot already exists. Defaults to the <envar>PGPORT</envar> environment variable, if
set, or a compiled-in default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-s <replaceable>interval_seconds</replaceable></option></term> <term><option>-U <replaceable>user</replaceable></option></term>
<term><option>--status-interval=<replaceable>interval_seconds</replaceable></option></term> <term><option>--username <replaceable>user</replaceable></option></term>
<listitem> <listitem>
<para> <para>
This option has the same effect as the option of the same name in <link Username to connect as. Defaults to current operating system user
linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>. name.
See the description there.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-S <replaceable>slot_name</replaceable></option></term> <term><option>-w</option></term>
<term><option>--slot=<replaceable>slot_name</replaceable></option></term> <term><option>--no-password</option></term>
<listitem> <listitem>
<para> <para>
In <option>--start</option> mode, use the existing logical replication slot named Never issue a password prompt. If the server requires
<replaceable>slot_name</replaceable>. In <option>--create-slot</option> password authentication and a password is not available by
mode, create the slot with this name. In <option>--drop-slot</option> other means such as a <filename>.pgpass</filename> file, the
mode, delete the slot with this name. connection attempt will fail. This option can be useful in
batch jobs and scripts where no user is present to enter a
password.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-I <replaceable>lsn</replaceable></option></term> <term><option>-W</option></term>
<term><option>--startpos=<replaceable>lsn</replaceable></option></term> <term><option>--password</option></term>
<listitem> <listitem>
<para> <para>
In <option>--start</option> mode, start replication from the given Force <application>pg_recvlogical</application> to prompt for a
LSN. For details on the effect of this, see the documentation password before connecting to a database.
in <xref linkend="logicaldecoding"> </para>
and <xref linkend="protocol-replication">. Ignored in other modes.
<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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
<para> <para>
The following additional options are available: The following additional options are available:
<variablelist> <variablelist>
<varlistentry>
<term><option>-v</></term>
<term><option>--verbose</></term>
<listitem>
<para>
Enables verbose mode.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term><option>-V</></term> <term><option>-V</></term>
<term><option>--version</></term> <term><option>--version</></term>
...@@ -324,8 +341,25 @@ PostgreSQL documentation ...@@ -324,8 +341,25 @@ PostgreSQL documentation
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</para> </para>
</refsect1> </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>See Also</title>
<simplelist type="inline">
<member><xref linkend="app-pgreceivexlog"></member>
</simplelist>
</refsect1>
</refentry> </refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment