<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>
<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>
</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>
</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>
</para>
</listitem>
</varlistentry>
-
</variablelist>
- </para>
<para>
The following command-line options control the database connection parameters.
</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>
</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>
<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>
<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>.
+ 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>--start</option></term>
+ <term><option>--drop-slot</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.
+ Drop the replication slot with the name specified
+ by <option>--slot</option>, then exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--drop-slot</option></term>
+ <term><option>--start</option></term>
<listitem>
<para>
- Drop the replication slot with the name specified
- in <option>--slot</option>, then exit.
+ 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>
output and other replication behavior:
<variablelist>
-
<varlistentry>
<term><option>-f <replaceable>filename</replaceable></option></term>
<term><option>--file=<replaceable>filename</replaceable></option></term>
</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>-n</option></term>
- <term><option>--no-loop</option></term>
+ <term><option>-I <replaceable>lsn</replaceable></option></term>
+ <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
<listitem>
<para>
- When the connection to the server is lost, do not retry in a loop, just exit.
+ 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>-o <replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
- <term><option>--option=<replaceable>NAME</replaceable>[=<replaceable>VALUE</replaceable>]</option></term>
+ <term><option>-n</option></term>
+ <term><option>--no-loop</option></term>
<listitem>
<para>
- Pass the option <parameter>NAME</parameter> to the output plugin with,
- if specified, the option value <parameter>NAME</parameter>. Which
- options exist and their effects depends on the used output plugin.
+ When the connection to the server is lost, do not retry in a loop, just exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-F <replaceable>interval_seconds</replaceable></option></term>
- <term><option>--fsync-interval=<replaceable>interval_seconds</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>
- 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.
+ 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>
<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>
<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>
</varlistentry>
<varlistentry>
- <term><option>-I <replaceable>lsn</replaceable></option></term>
- <term><option>--startpos=<replaceable>lsn</replaceable></option></term>
- <listitem>
+ <term><option>-v</></term>
+ <term><option>--verbose</></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.
+ Enables verbose mode.
</para>
- </listitem>
+ </listitem>
</varlistentry>
</variablelist>
-
</para>
<para>
- The following additional options are available:
-
+ 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>-v</></term>
- <term><option>--verbose</></term>
+ <varlistentry>
+ <term><option>-h <replaceable>hostname-or-ip</replaceable></option></term>
+ <term><option>--host <replaceable>hostname-or-ip</replaceable></option></term>
<listitem>
- <para>
- Enables verbose mode.
- </para>
+ <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>
</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>
projects / postgresql.git / commitdiff