database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

doc: Clean up pg_recvlogical reference page

Browse Source 
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.
This commit is contained in:
Peter Eisentraut
2014-10-18 09:10:12 -04:00
parent 60f8133dc9
commit 52c1ae22d6
2 changed files with 243 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

362
doc/src/sgml/ref/pg_recvlogical.sgml
View File

@ -16,39 +16,35 @@ PostgreSQL documentation
<refnamediv>
<refname>pg_recvlogical</refname>
<refpurpose>Control logical decoding (see <xref linkend="logicaldecoding">)
streams over a walsender connection.</refpurpose>
<refpurpose>control <productname>PostgreSQL</productname> logical decoding streams</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_recvlogical</command>
<arg rep="repeat" choice="opt"><option>option</option></arg>
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="R1-APP-PGRECVLOGICAL-1">
<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 <link
linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>,
plus those for logical replication (see <xref
linkend="logicaldecoding">).
constraints as <xref linkend="app-pgreceivexlog">, plus those for logical
replication (see <xref linkend="logicaldecoding">).
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<application>pg_recvlogical</application> runs in one of three modes, which
control its primary action:
At least one of the following options must be specified to select an action:
<variablelist>
@ -56,27 +52,10 @@ PostgreSQL documentation
<term><option>--create-slot</option></term>
<listitem>
<para>
Create a new logical replication slot with the name specified in
<option>--slot</option>, using the output plugin
<option>--plugin</option>. The slot is created for the database
given in <option>--dbname</option>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--start</option></term>
<listitem>
<para>
Begin streaming changes from the logical replication slot with the name
specified in <option>--slot</option>, continuing until terminated with 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. 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.
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>
@ -86,99 +65,39 @@ PostgreSQL documentation
<listitem>
<para>
Drop the replication slot with the name specified
in <option>--slot</option>, then exit.
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>
<application>pg_recvlogical</application> supports all the usual
<literal>libpq</literal>-based options. These are explained in detail in
the documentation for
<link linkend="APP-PSQL"><application>psql</application></link> and for
<link linkend="libpq"><literal>libpq</literal></link>.
<variablelist>
<varlistentry>
<term><option>-U <replaceable>user</replaceable></option></term>
<term><option>--username <replaceable>user</replaceable></option></term>
<listitem>
<para>
Username to connect as. Must have a suitable <literal>pg_hba.conf</literal>
entry allowing <literal>replication</literal> connections. Defaults to
current operating system user name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d <replaceable>database</replaceable></option></term>
<term><option>--dbname <replaceable>database</replaceable></option></term>
<listitem>
<para>
The database to connect to in <literal>replication</literal> mode; see
mode descriptions for details. May be
a <link linkend="LIBPQ-CONNSTRING">libpq connstring</link>
instead. Defaults to 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>
Host or socket to connect
to. See <link linkend="APP-PSQL"><application>psql</application></link>
and <link linkend="libpq"><literal>libpq</literal></link>
documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p <replaceable>port</replaceable></option></term>
<term><option>--port <replaceable>port</replaceable></option></term>
<listitem>
<para>
Port number to connect to. See
<link linkend="R1-APP-PSQL-3"><application>psql</application></link>
for an explanation of default port choices when this is not
specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-w</option></term>
<term><option>--no-password</option></term>
<listitem>
<para>
Prevent prompting for a password. Will exit with an error code if a
password is required but not available.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-W</option></term>
<term><option>--password</option></term>
<listitem>
<para>
Provide a password for this connection. Please use the pgservice file
(see <xref linkend="libpq-pgservice">) or an environment variable
instead of this option.
</para>
</listitem>
</varlistentry>
</variablelist>
<option>--create-slot</option> and <option>--start</option> can be
specified together. <option>--drop-slot</option> cannot be combined with
another action.
</para>
<para>
@ -186,7 +105,6 @@ PostgreSQL documentation
output and other replication behavior:
<variablelist>
<varlistentry>
<term><option>-f <replaceable>filename</replaceable></option></term>
<term><option>--file=<replaceable>filename</replaceable></option></term>
@ -198,6 +116,43 @@ PostgreSQL documentation
</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>-n</option></term>
@ -210,38 +165,23 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
<term><option>-o <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
<term><option>--option=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
<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 <parameter>NAME</parameter> to the output plugin with,
if specified, the option value <parameter>NAME</parameter>. Which
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>-F <replaceable>interval_seconds</replaceable></option></term>
<term><option>--fsync-interval=<replaceable>interval_seconds</replaceable></option></term>
<listitem>
<para>
How often should <application>pg_recvlogical</application> issue sync
commands to ensure the <parameter>--outputfile</parameter> is safely
flushed to disk without being asked by the server to do so. Specifying
an interval of <literal>0</literal> disables issuing fsyncs altogether,
while still reporting progress the server. In this case, data may be
lost in the event of a crash.
</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 logical decoding output
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>
@ -253,9 +193,8 @@ PostgreSQL documentation
<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 <link
linkend="app-pgreceivexlog"><application>pg_receivexlog</application></link>.
See the description there.
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>
@ -273,27 +212,6 @@ PostgreSQL documentation
</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>
</variablelist>
</para>
<para>
The following additional options are available:
<variablelist>
<varlistentry>
<term><option>-v</></term>
<term><option>--verbose</></term>
@ -303,7 +221,106 @@ PostgreSQL documentation
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following command-line options control the database connection parameters.
<variablelist>
<varlistentry>
<term><option>-d <replaceable>database</replaceable></option></term>
<term><option>--dbname <replaceable>database</replaceable></option></term>
<listitem>
<para>
The database to connect to. See the description of the actions for
what this means in detail. This can be a libpq connection string;
see <xref linkend="LIBPQ-CONNSTRING"> for more information. Defaults
to 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>
Username 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>
@ -324,8 +341,25 @@ PostgreSQL documentation
</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>See Also</title>
<simplelist type="inline">
<member><xref linkend="app-pgreceivexlog"></member>
</simplelist>
</refsect1>
</refentry>