Skip to content

Commit 34a62c2

Browse files
MasaoFujiiMasaoFujii
committed
doc: Improve documentation discoverability for pgoutput.
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
1 parent 16d434d commit 34a62c2

File tree

3 files changed

+156
-129
lines changed

3 files changed

+156
-129
lines changed

‎doc/src/sgml/logical-replication.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -542,8 +542,8 @@
542542
it manually before the subscription can be activated. The steps to create
543543
the slot and activate the subscription are shown in the following examples.
544544
These examples specify the standard logical decoding output plugin
545-
(<literal>pgoutput</literal>), which is what the built-in logical
546-
replication uses.
545+
(<xref linkend="logicaldecoding-pgoutput"/>),
546+
which is what the built-in logical replication uses.
547547
</para>
548548
<para>
549549
First, create a publication for the examples to use.
@@ -2173,8 +2173,8 @@ CONTEXT: processing remote data for replication origin "pg_16395" during "INSER
21732173
implemented by <literal>walsender</literal> and <literal>apply</literal>
21742174
processes. The walsender process starts logical decoding (described
21752175
in <xref linkend="logicaldecoding"/>) of the WAL and loads the standard
2176-
logical decoding output plugin (<literal>pgoutput</literal>). The plugin
2177-
transforms the changes read
2176+
logical decoding output plugin (<xref linkend="logicaldecoding-pgoutput"/>).
2177+
The plugin transforms the changes read
21782178
from WAL to the logical replication protocol
21792179
(see <xref linkend="protocol-logical-replication"/>) and filters the data
21802180
according to the publication specification. The data is then continuously

‎doc/src/sgml/logicaldecoding.sgml

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -574,6 +574,152 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs
574574

575575
<sect1 id="logicaldecoding-output-plugin">
576576
<title>Logical Decoding Output Plugins</title>
577+
578+
<para>
579+
<productname>PostgreSQL</productname> provides two logical decoding
580+
output plugins, <xref linkend="logicaldecoding-pgoutput"/> and
581+
<xref linkend="test-decoding"/>. You can also develop custom output plugins
582+
(see <xref linkend="logicaldecoding-output-plugin-writing"/> for details).
583+
</para>
584+
585+
<sect2 id="logicaldecoding-pgoutput" xreflabel="pgoutput">
586+
<title>pgoutput &mdash; Standard Logical Decoding Output Plugin</title>
587+
588+
<indexterm zone="logicaldecoding-pgoutput">
589+
<primary>pgoutput</primary>
590+
</indexterm>
591+
592+
<para>
593+
<filename>pgoutput</filename> is the standard logical decoding output
594+
plugin provided by <productname>PostgreSQL</productname>.
595+
It's used for the built-in <link linkend="logical-replication">
596+
logical replication</link>.
597+
</para>
598+
599+
<sect3 id="logicaldecoding-pgoutput-options">
600+
<title>Options</title>
601+
602+
<variablelist>
603+
<varlistentry>
604+
<term>
605+
proto_version
606+
</term>
607+
<listitem>
608+
<para>
609+
Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
610+
<literal>3</literal>, and <literal>4</literal> are supported. A valid
611+
version is required.
612+
</para>
613+
<para>
614+
Version <literal>2</literal> is supported only for server version 14
615+
and above, and it allows streaming of large in-progress transactions.
616+
</para>
617+
<para>
618+
Version <literal>3</literal> is supported only for server version 15
619+
and above, and it allows streaming of two-phase commits.
620+
</para>
621+
<para>
622+
Version <literal>4</literal> is supported only for server version 16
623+
and above, and it allows streams of large in-progress transactions to
624+
be applied in parallel.
625+
</para>
626+
</listitem>
627+
</varlistentry>
628+
629+
<varlistentry>
630+
<term>
631+
publication_names
632+
</term>
633+
<listitem>
634+
<para>
635+
Comma-separated list of publication names for which to subscribe
636+
(receive changes). The individual publication names are treated
637+
as standard objects names and can be quoted the same as needed.
638+
At least one publication name is required.
639+
</para>
640+
</listitem>
641+
</varlistentry>
642+
643+
<varlistentry>
644+
<term>
645+
binary
646+
</term>
647+
<listitem>
648+
<para>
649+
Boolean option to use binary transfer mode. Binary mode is faster
650+
than the text mode but slightly less robust.
651+
The default is <literal>off</literal>.
652+
</para>
653+
</listitem>
654+
</varlistentry>
655+
656+
<varlistentry>
657+
<term>
658+
messages
659+
</term>
660+
<listitem>
661+
<para>
662+
Boolean option to enable sending the messages that are written
663+
by <function>pg_logical_emit_message</function>.
664+
The default is <literal>off</literal>.
665+
</para>
666+
</listitem>
667+
</varlistentry>
668+
669+
<varlistentry>
670+
<term>
671+
streaming
672+
</term>
673+
<listitem>
674+
<para>
675+
Option to enable streaming of in-progress transactions. Valid values are
676+
<literal>off</literal> (the default), <literal>on</literal> and
677+
<literal>parallel</literal>. The setting <literal>parallel</literal>
678+
enables sending extra information with some messages to be used for
679+
parallelization. Minimum protocol version 2 is required to turn it
680+
<literal>on</literal>. Minimum protocol version 4 is required for the
681+
<literal>parallel</literal> value.
682+
</para>
683+
</listitem>
684+
</varlistentry>
685+
686+
<varlistentry>
687+
<term>
688+
two_phase
689+
</term>
690+
<listitem>
691+
<para>
692+
Boolean option to enable two-phase transactions. Minimum protocol
693+
version 3 is required to turn it on.
694+
The default is <literal>off</literal>.
695+
</para>
696+
</listitem>
697+
</varlistentry>
698+
699+
<varlistentry>
700+
<term>
701+
origin
702+
</term>
703+
<listitem>
704+
<para>
705+
Option to send changes by their origin. Possible values are
706+
<literal>none</literal> to only send the changes that have no origin
707+
associated, or <literal>any</literal>
708+
to send the changes regardless of their origin. This can be used
709+
to avoid loops (infinite replication of the same data) among
710+
replication nodes.
711+
The default is <literal>any</literal>.
712+
</para>
713+
</listitem>
714+
</varlistentry>
715+
</variablelist>
716+
717+
</sect3>
718+
</sect2>
719+
</sect1>
720+
721+
<sect1 id="logicaldecoding-output-plugin-writing">
722+
<title>Writing Logical Decoding Output Plugins</title>
577723
<para>
578724
An example output plugin can be found in the
579725
<link linkend="test-decoding">

‎doc/src/sgml/protocol.sgml

Lines changed: 6 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -2955,7 +2955,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
29552955
<listitem>
29562956
<para>
29572957
The name of an option passed to the slot's logical decoding output
2958-
plugin. See <xref linkend="protocol-logical-replication"/> for
2958+
plugin. See <xref linkend="logicaldecoding-pgoutput-options"/> for
29592959
options that are accepted by the standard (<literal>pgoutput</literal>)
29602960
plugin.
29612961
</para>
@@ -3523,134 +3523,15 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
35233523
the physical streaming replication protocol.
35243524
</para>
35253525

3526-
<para>
3527-
<productname>PostgreSQL</productname> logical decoding supports output
3528-
plugins. <literal>pgoutput</literal> is the standard one used for
3529-
the built-in logical replication.
3530-
</para>
3531-
35323526
<sect2 id="protocol-logical-replication-params">
35333527
<title>Logical Streaming Replication Parameters</title>
35343528

35353529
<para>
3536-
Using the <literal>START_REPLICATION</literal> command,
3537-
<literal>pgoutput</literal> accepts the following options:
3538-
3539-
<variablelist>
3540-
<varlistentry>
3541-
<term>
3542-
proto_version
3543-
</term>
3544-
<listitem>
3545-
<para>
3546-
Protocol version. Currently versions <literal>1</literal>, <literal>2</literal>,
3547-
<literal>3</literal>, and <literal>4</literal> are supported. A valid
3548-
version is required.
3549-
</para>
3550-
<para>
3551-
Version <literal>2</literal> is supported only for server version 14
3552-
and above, and it allows streaming of large in-progress transactions.
3553-
</para>
3554-
<para>
3555-
Version <literal>3</literal> is supported only for server version 15
3556-
and above, and it allows streaming of two-phase commits.
3557-
</para>
3558-
<para>
3559-
Version <literal>4</literal> is supported only for server version 16
3560-
and above, and it allows streams of large in-progress transactions to
3561-
be applied in parallel.
3562-
</para>
3563-
</listitem>
3564-
</varlistentry>
3565-
3566-
<varlistentry>
3567-
<term>
3568-
publication_names
3569-
</term>
3570-
<listitem>
3571-
<para>
3572-
Comma-separated list of publication names for which to subscribe
3573-
(receive changes). The individual publication names are treated
3574-
as standard objects names and can be quoted the same as needed.
3575-
At least one publication name is required.
3576-
</para>
3577-
</listitem>
3578-
</varlistentry>
3579-
3580-
<varlistentry>
3581-
<term>
3582-
binary
3583-
</term>
3584-
<listitem>
3585-
<para>
3586-
Boolean option to use binary transfer mode. Binary mode is faster
3587-
than the text mode but slightly less robust.
3588-
The default is <literal>off</literal>.
3589-
</para>
3590-
</listitem>
3591-
</varlistentry>
3592-
3593-
<varlistentry>
3594-
<term>
3595-
messages
3596-
</term>
3597-
<listitem>
3598-
<para>
3599-
Boolean option to enable sending the messages that are written
3600-
by <function>pg_logical_emit_message</function>.
3601-
The default is <literal>off</literal>.
3602-
</para>
3603-
</listitem>
3604-
</varlistentry>
3605-
3606-
<varlistentry>
3607-
<term>
3608-
streaming
3609-
</term>
3610-
<listitem>
3611-
<para>
3612-
Option to enable streaming of in-progress transactions. Valid values are
3613-
<literal>off</literal> (the default), <literal>on</literal> and
3614-
<literal>parallel</literal>. The setting <literal>parallel</literal>
3615-
enables sending extra information with some messages to be used for
3616-
parallelization. Minimum protocol version 2 is required to turn it
3617-
<literal>on</literal>. Minimum protocol version 4 is required for the
3618-
<literal>parallel</literal> value.
3619-
</para>
3620-
</listitem>
3621-
</varlistentry>
3622-
3623-
<varlistentry>
3624-
<term>
3625-
two_phase
3626-
</term>
3627-
<listitem>
3628-
<para>
3629-
Boolean option to enable two-phase transactions. Minimum protocol
3630-
version 3 is required to turn it on.
3631-
The default is <literal>off</literal>.
3632-
</para>
3633-
</listitem>
3634-
</varlistentry>
3635-
3636-
<varlistentry>
3637-
<term>
3638-
origin
3639-
</term>
3640-
<listitem>
3641-
<para>
3642-
Option to send changes by their origin. Possible values are
3643-
<literal>none</literal> to only send the changes that have no origin
3644-
associated, or <literal>any</literal>
3645-
to send the changes regardless of their origin. This can be used
3646-
to avoid loops (infinite replication of the same data) among
3647-
replication nodes.
3648-
The default is <literal>any</literal>.
3649-
</para>
3650-
</listitem>
3651-
</varlistentry>
3652-
</variablelist>
3653-
3530+
The <literal>START_REPLICATION</literal> command can pass
3531+
options to the logical decoding output plugin associated
3532+
with the specified replication slot.
3533+
See <xref linkend="logicaldecoding-pgoutput-options"/> for options
3534+
that are accepted by the standard (<literal>pgoutput</literal>) plugin.
36543535
</para>
36553536
</sect2>
36563537

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy