Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 7670add

Browse filesBrowse files
author
Amit Kapila
committed
Improve the description of Output Plugin Callbacks.
We were inconsistently specifying the required and optional marking for plugin callbacks. Additionally, this patch improves the description for stream_prepare callback. Author: Wang wei Reviewed-by: Amit Kapila Discussion: https://postgr.es/m/OS3PR01MB627553DAFD39ECDADD08DC909EFC9@OS3PR01MB6275.jpnprd01.prod.outlook.com
1 parent efb6f4a commit 7670add
Copy full SHA for 7670add

File tree

1 file changed

+27
-23
lines changed
Filter options

1 file changed

+27
-23
lines changed

‎doc/src/sgml/logicaldecoding.sgml

Copy file name to clipboardExpand all lines: doc/src/sgml/logicaldecoding.sgml
+27-23Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -479,8 +479,8 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
479479
</programlisting>
480480
The <function>begin_cb</function>, <function>change_cb</function>
481481
and <function>commit_cb</function> callbacks are required,
482-
while <function>startup_cb</function>,
483-
<function>filter_by_origin_cb</function>, <function>truncate_cb</function>,
482+
while <function>startup_cb</function>, <function>truncate_cb</function>,
483+
<function>message_cb</function>, <function>filter_by_origin_cb</function>,
484484
and <function>shutdown_cb</function> are optional.
485485
If <function>truncate_cb</function> is not set but a
486486
<command>TRUNCATE</command> is to be decoded, the action will be ignored.
@@ -490,19 +490,21 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
490490
An output plugin may also define functions to support streaming of large,
491491
in-progress transactions. The <function>stream_start_cb</function>,
492492
<function>stream_stop_cb</function>, <function>stream_abort_cb</function>,
493-
<function>stream_commit_cb</function>, <function>stream_change_cb</function>,
494-
and <function>stream_prepare_cb</function>
493+
<function>stream_commit_cb</function>, and <function>stream_change_cb</function>
495494
are required, while <function>stream_message_cb</function> and
496-
<function>stream_truncate_cb</function> are optional.
495+
<function>stream_truncate_cb</function> are optional. The
496+
<function>stream_prepare_cb</function> is also required if the output
497+
plugin also support two-phase commits.
497498
</para>
498499

499500
<para>
500501
An output plugin may also define functions to support two-phase commits,
501502
which allows actions to be decoded on the <command>PREPARE TRANSACTION</command>.
502503
The <function>begin_prepare_cb</function>, <function>prepare_cb</function>,
503-
<function>stream_prepare_cb</function>,
504504
<function>commit_prepared_cb</function> and <function>rollback_prepared_cb</function>
505505
callbacks are required, while <function>filter_prepare_cb</function> is optional.
506+
The <function>stream_prepare_cb</function> is also required if the output plugin
507+
also supports the streaming of large in-progress transactions.
506508
</para>
507509
</sect2>
508510

@@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
721723
<title>Truncate Callback</title>
722724

723725
<para>
724-
The <function>truncate_cb</function> callback is called for a
726+
The optional <function>truncate_cb</function> callback is called for a
725727
<command>TRUNCATE</command> command.
726728
<programlisting>
727729
typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
@@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *
919921
<sect3 id="logicaldecoding-output-plugin-stream-start">
920922
<title>Stream Start Callback</title>
921923
<para>
922-
The <function>stream_start_cb</function> callback is called when opening
923-
a block of streamed changes from an in-progress transaction.
924+
The required <function>stream_start_cb</function> callback is called when
925+
opening a block of streamed changes from an in-progress transaction.
924926
<programlisting>
925927
typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
926928
ReorderBufferTXN *txn);
@@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
931933
<sect3 id="logicaldecoding-output-plugin-stream-stop">
932934
<title>Stream Stop Callback</title>
933935
<para>
934-
The <function>stream_stop_cb</function> callback is called when closing
935-
a block of streamed changes from an in-progress transaction.
936+
The required <function>stream_stop_cb</function> callback is called when
937+
closing a block of streamed changes from an in-progress transaction.
936938
<programlisting>
937939
typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
938940
ReorderBufferTXN *txn);
@@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
943945
<sect3 id="logicaldecoding-output-plugin-stream-abort">
944946
<title>Stream Abort Callback</title>
945947
<para>
946-
The <function>stream_abort_cb</function> callback is called to abort
947-
a previously streamed transaction.
948+
The required <function>stream_abort_cb</function> callback is called to
949+
abort a previously streamed transaction.
948950
<programlisting>
949951
typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
950952
ReorderBufferTXN *txn,
@@ -957,8 +959,10 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
957959
<title>Stream Prepare Callback</title>
958960
<para>
959961
The <function>stream_prepare_cb</function> callback is called to prepare
960-
a previously streamed transaction as part of a two-phase commit.
961-
<programlisting>
962+
a previously streamed transaction as part of a two-phase commit. This
963+
callback is required when the output plugin supports both the streaming
964+
of large in-progress transactions and two-phase commits.
965+
<programlisting>
962966
typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
963967
ReorderBufferTXN *txn,
964968
XLogRecPtr prepare_lsn);
@@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx
969973
<sect3 id="logicaldecoding-output-plugin-stream-commit">
970974
<title>Stream Commit Callback</title>
971975
<para>
972-
The <function>stream_commit_cb</function> callback is called to commit
973-
a previously streamed transaction.
976+
The required <function>stream_commit_cb</function> callback is called to
977+
commit a previously streamed transaction.
974978
<programlisting>
975979
typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
976980
ReorderBufferTXN *txn,
@@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
982986
<sect3 id="logicaldecoding-output-plugin-stream-change">
983987
<title>Stream Change Callback</title>
984988
<para>
985-
The <function>stream_change_cb</function> callback is called when sending
986-
a change in a block of streamed changes (demarcated by
989+
The required <function>stream_change_cb</function> callback is called
990+
when sending a change in a block of streamed changes (demarcated by
987991
<function>stream_start_cb</function> and <function>stream_stop_cb</function> calls).
988992
The actual changes are not displayed as the transaction can abort at a later
989993
point in time and we don't decode changes for aborted transactions.
@@ -999,8 +1003,8 @@ typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,
9991003
<sect3 id="logicaldecoding-output-plugin-stream-message">
10001004
<title>Stream Message Callback</title>
10011005
<para>
1002-
The <function>stream_message_cb</function> callback is called when sending
1003-
a generic message in a block of streamed changes (demarcated by
1006+
The optional <function>stream_message_cb</function> callback is called when
1007+
sending a generic message in a block of streamed changes (demarcated by
10041008
<function>stream_start_cb</function> and <function>stream_stop_cb</function> calls).
10051009
The message contents for transactional messages are not displayed as the transaction
10061010
can abort at a later point in time and we don't decode changes for aborted
@@ -1020,8 +1024,8 @@ typedef void (*LogicalDecodeStreamMessageCB) (struct LogicalDecodingContext *ctx
10201024
<sect3 id="logicaldecoding-output-plugin-stream-truncate">
10211025
<title>Stream Truncate Callback</title>
10221026
<para>
1023-
The <function>stream_truncate_cb</function> callback is called for a
1024-
<command>TRUNCATE</command> command in a block of streamed changes
1027+
The optional <function>stream_truncate_cb</function> callback is called
1028+
for a <command>TRUNCATE</command> command in a block of streamed changes
10251029
(demarcated by <function>stream_start_cb</function> and
10261030
<function>stream_stop_cb</function> calls).
10271031
<programlisting>

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.