open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: Improve documentation discoverability for pgoutput.

Browse Source 
Previously, the documentation for pgoutput was located in the section on
the logical streaming replication protocol, and there was no index entry
for it. As a result, users had difficulty finding information about pgoutput.

This commit moves the pgoutput documentation under the logical decoding
section and adds an index entry, making it easier for users to locate and
access this information.

Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Chao Li <li.evan.chao@gmail.com>
Reviewed-by: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Reviewed-by: Euler Taveira <euler@eulerto.com>
Discussion: https://postgr.es/m/CAHGQGwFJTbygdhhjR_iP4Oem=Lo1xsptWWOq825uoW+hG_Lfnw@mail.gmail.com
pull/239/head
Fujii Masao 3 weeks ago
parent 16d434d53d
commit 34a62c2c7f
3 changed files with 156 additions and 129 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 8
      doc/src/sgml/logical-replication.sgml
  2. 146
      doc/src/sgml/logicaldecoding.sgml
  3. 131
      doc/src/sgml/protocol.sgml

8
doc/src/sgml/logical-replication.sgml
Unescape View File

@ -542,8 +542,8 @@
it manually before the subscription can be activated. The steps to create
the slot and activate the subscription are shown in the following examples.
These examples specify the standard logical decoding output plugin
(<literal>pgoutput</literal>), which is what the built-in logical
replication uses.
(<xref linkend="logicaldecoding-pgoutput"/>),
which is what the built-in logical replication uses.
</para>
<para>
First, create a publication for the examples to use.
@ -2173,8 +2173,8 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
implemented by <literal>walsender</literal> and <literal>apply</literal>
processes. The walsender process starts logical decoding (described
in <xref linkend="logicaldecoding"/>) of the WAL and loads the standard
logical decoding output plugin (<literal>pgoutput</literal>). The plugin
transforms the changes read
logical decoding output plugin (<xref linkend="logicaldecoding-pgoutput"/>).
The plugin transforms the changes read
from WAL to the logical replication protocol
(see <xref linkend="protocol-logical-replication"/>) and filters the data
according to the publication specification. The data is then continuously

146
doc/src/sgml/logicaldecoding.sgml
Unescape View File

@ -574,6 +574,152 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs
<sect1 id="logicaldecoding-output-plugin">
<title>Logical Decoding Output Plugins</title>
<para>
<productname>PostgreSQL</productname> provides two logical decoding
output plugins, <xref linkend="logicaldecoding-pgoutput"/> and
<xref linkend="test-decoding"/>. You can also develop custom output plugins
(see <xref linkend="logicaldecoding-output-plugin-writing"/> for details).
</para>
<sect2 id="logicaldecoding-pgoutput" xreflabel="pgoutput">
<title>pgoutput &mdash; Standard Logical Decoding Output Plugin</title>
<indexterm zone="logicaldecoding-pgoutput">
<primary>pgoutput</primary>
</indexterm>
<para>
<filename>pgoutput</filename> is the standard logical decoding output
plugin provided by <productname>PostgreSQL</productname>.
It's used for the built-in <link linkend="logical-replication">
logical replication</link>.
</para>
<sect3 id="logicaldecoding-pgoutput-options">
<title>Options</title>
<variablelist>
<varlistentry>
<term>
proto_version
</term>
<listitem>
<para>
Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
<literal>3</literal>, and <literal>4</literal> are supported. A valid
version is required.
</para>
<para>
Version <literal>2</literal> is supported only for server version 14
and above, and it allows streaming of large in-progress transactions.
</para>
<para>
Version <literal>3</literal> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</para>
<para>
Version <literal>4</literal> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
publication_names
</term>
<listitem>
<para>
Comma-separated list of publication names for which to subscribe
(receive changes). The individual publication names are treated
as standard objects names and can be quoted the same as needed.
At least one publication name is required.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
binary
</term>
<listitem>
<para>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
messages
</term>
<listitem>
<para>
Boolean option to enable sending the messages that are written
by <function>pg_logical_emit_message</function>.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
streaming
</term>
<listitem>
<para>
Option to enable streaming of in-progress transactions. Valid values are
<literal>off</literal> (the default), <literal>on</literal> and
<literal>parallel</literal>. The setting <literal>parallel</literal>
enables sending extra information with some messages to be used for
parallelization. Minimum protocol version 2 is required to turn it
<literal>on</literal>. Minimum protocol version 4 is required for the
<literal>parallel</literal> value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
two_phase
</term>
<listitem>
<para>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
origin
</term>
<listitem>
<para>
Option to send changes by their origin. Possible values are
<literal>none</literal> to only send the changes that have no origin
associated, or <literal>any</literal>
to send the changes regardless of their origin. This can be used
to avoid loops (infinite replication of the same data) among
replication nodes.
The default is <literal>any</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect3>
</sect2>
</sect1>
<sect1 id="logicaldecoding-output-plugin-writing">
<title>Writing Logical Decoding Output Plugins</title>
<para>
An example output plugin can be found in the
<link linkend="test-decoding">

131
doc/src/sgml/protocol.sgml
Unescape View File

@ -2955,7 +2955,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
The name of an option passed to the slot's logical decoding output
plugin. See <xref linkend="protocol-logical-replication"/> for
plugin. See <xref linkend="logicaldecoding-pgoutput-options"/> for
options that are accepted by the standard (<literal>pgoutput</literal>)
plugin.
</para>
@ -3523,134 +3523,15 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
the physical streaming replication protocol.
</para>
<para>
<productname>PostgreSQL</productname> logical decoding supports output
plugins. <literal>pgoutput</literal> is the standard one used for
the built-in logical replication.
</para>
<sect2 id="protocol-logical-replication-params">
<title>Logical Streaming Replication Parameters</title>
<para>
Using the <literal>START_REPLICATION</literal> command,
<literal>pgoutput</literal> accepts the following options:
<variablelist>
<varlistentry>
<term>
proto_version
</term>
<listitem>
<para>
Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
<literal>3</literal>, and <literal>4</literal> are supported. A valid
version is required.
</para>
<para>
Version <literal>2</literal> is supported only for server version 14
and above, and it allows streaming of large in-progress transactions.
</para>
<para>
Version <literal>3</literal> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</para>
<para>
Version <literal>4</literal> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
publication_names
</term>
<listitem>
<para>
Comma-separated list of publication names for which to subscribe
(receive changes). The individual publication names are treated
as standard objects names and can be quoted the same as needed.
At least one publication name is required.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
binary
</term>
<listitem>
<para>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
messages
</term>
<listitem>
<para>
Boolean option to enable sending the messages that are written
by <function>pg_logical_emit_message</function>.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
streaming
</term>
<listitem>
<para>
Option to enable streaming of in-progress transactions. Valid values are
<literal>off</literal> (the default), <literal>on</literal> and
<literal>parallel</literal>. The setting <literal>parallel</literal>
enables sending extra information with some messages to be used for
parallelization. Minimum protocol version 2 is required to turn it
<literal>on</literal>. Minimum protocol version 4 is required for the
<literal>parallel</literal> value.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
two_phase
</term>
<listitem>
<para>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
The default is <literal>off</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
origin
</term>
<listitem>
<para>
Option to send changes by their origin. Possible values are
<literal>none</literal> to only send the changes that have no origin
associated, or <literal>any</literal>
to send the changes regardless of their origin. This can be used
to avoid loops (infinite replication of the same data) among
replication nodes.
The default is <literal>any</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
The <literal>START_REPLICATION</literal> command can pass
options to the logical decoding output plugin associated
with the specified replication slot.
See <xref linkend="logicaldecoding-pgoutput-options"/> for options
that are accepted by the standard (<literal>pgoutput</literal>) plugin.
</para>
</sect2>

Write Preview
Loading…
Cancel
Save