From 38c5fbd97ee6a8409c6c41d6af0c06169cd51c2b Mon Sep 17 00:00:00 2001 From: Fujii Masao Date: Tue, 19 Aug 2025 18:54:27 +0900 Subject: doc: Improve pgoutput documentation. This commit updates the pgoutput documentation with the following changes: - Specify the data type for each pgoutput option. - Clarify the relationship between proto_version and options such as streaming and two_phase. - Add a note on the use of pg_logical_slot_peek_changes and pg_logical_slot_get_changes with pgoutput. Author: Fujii Masao Reviewed-by: Chao Li Reviewed-by: Hayato Kuroda Discussion: https://postgr.es/m/CAHGQGwFJTbygdhhjR_iP4Oem=Lo1xsptWWOq825uoW+hG_Lfnw@mail.gmail.com --- doc/src/sgml/func/func-admin.sgml | 2 +- doc/src/sgml/logicaldecoding.sgml | 118 ++++++++++++++++++++++---------------- 2 files changed, 69 insertions(+), 51 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml index 446fdfe56f4..6347fe60b0c 100644 --- a/doc/src/sgml/func/func-admin.sgml +++ b/doc/src/sgml/func/func-admin.sgml @@ -1224,7 +1224,7 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset - + pg_logical_slot_peek_binary_changes diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index 1e3ccc84e65..a1f2efb2420 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -600,109 +600,112 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs Options - - - proto_version - + + proto_version (integer) - Protocol version. Currently versions 1, 2, + Specifies the protocol version. + Currently versions 1, 2, 3, and 4 are supported. A valid version is required. - Version 2 is supported only for server version 14 - and above, and it allows streaming of large in-progress transactions. + Version 2 is supported on server version 14 + and above, and is required when streaming + is set to on to stream large in-progress + transactions. - Version 3 is supported only for server version 15 - and above, and it allows streaming of two-phase commits. + Version 3 is supported on server version 15 + and above, and is required when two_phase + is enabled to stream two-phase commits. - Version 4 is supported only for server version 16 - and above, and it allows streams of large in-progress transactions to - be applied in parallel. + Version 4 is supported on server version 16 + and above, and is required when streaming + is set to parallel to stream large in-progress + transactions to be applied in parallel. - - - publication_names - + + publication_names (string) - Comma-separated list of publication names for which to subscribe - (receive changes). The individual publication names are treated + A comma-separated list of publication names to subscribe to. + 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. - - - binary - + + binary (boolean) - Boolean option to use binary transfer mode. Binary mode is faster + Enables binary transfer mode. Binary mode is faster than the text mode but slightly less robust. The default is off. - - - messages - + + messages (boolean) - Boolean option to enable sending the messages that are written - by pg_logical_emit_message. + Enables sending the messages that are written by + pg_logical_emit_message. The default is off. - - - streaming - + + streaming (enum) - Option to enable streaming of in-progress transactions. Valid values are + Enables streaming of in-progress transactions. Valid values are off (the default), on and - parallel. The setting parallel - enables sending extra information with some messages to be used for - parallelization. Minimum protocol version 2 is required to turn it - on. Minimum protocol version 4 is required for the - parallel value. + parallel. + + + When set to off, pgoutput + fully decodes a transaction before sending it as a whole. + This mode works with any protocol version. + + + When set to on, pgoutput + streams large in-progress transactions. + This requires protocol version 2 or higher. + + + When set to parallel, pgoutput + streams large in-progress transactions and also sends + extra information in some messages to support parallel processing. + This requires protocol version 4 or higher. - - - two_phase - + + two_phase (boolean) - Boolean option to enable two-phase transactions. Minimum protocol - version 3 is required to turn it on. + Enables sending two-phase transactions. + Minimum protocol version 3 is required to turn it on. The default is off. - - - origin - + + origin (enum) - Option to send changes by their origin. Possible values are + Specifies whether to send changes by their origin. Possible values are none to only send the changes that have no origin associated, or any to send the changes regardless of their origin. This can be used @@ -715,6 +718,21 @@ DETAIL: Synchronization could lead to data loss, because the remote slot needs + + + Notes + + + pgoutput produces binary output, + so functions expecting textual data ( + pg_logical_slot_peek_changes and + pg_logical_slot_get_changes) + cannot be used with it. Use + pg_logical_slot_peek_binary_changes or + pg_logical_slot_get_binary_changes + instead. + + -- cgit v1.2.3