rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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.
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
doc/src/sgml/ref/pg_receivexlog.sgml
View File

@ -16,7 +16,7 @@ PostgreSQL documentation
<refnamediv>
<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>
<refsynopsisdiv>
@ -71,10 +71,6 @@ PostgreSQL documentation
<refsect1>
<title>Options</title>
<para>
The following command-line options control the location and format of the
output.
<variablelist>
<varlistentry>
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
@ -88,22 +84,6 @@ PostgreSQL documentation
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following command-line options control the running of the program.
<variablelist>
<varlistentry>
<term><option>-n</option></term>
<term><option>--no-loop</option></term>
<listitem>
<para>
Don't loop on connection errors. Instead, exit right away with
an error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-F <replaceable class="parameter">interval</replaceable></option></term>
@ -120,6 +100,50 @@ PostgreSQL documentation
</listitem>
</varlistentry>
<varlistentry>
<term><option>-n</option></term>
<term><option>--no-loop</option></term>
<listitem>
<para>
Don't loop on connection errors. Instead, exit right away with
an error.
</para>
</listitem>
</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>
<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>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option></term>
<term><option>--verbose</option></term>
@ -129,9 +153,7 @@ PostgreSQL documentation
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following command-line options control the database connection parameters.
@ -181,20 +203,6 @@ PostgreSQL documentation
</listitem>
</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>
<term><option>-U <replaceable>username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
@ -240,27 +248,6 @@ PostgreSQL documentation
</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. 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>
</para>

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>