Skip to content

Commit faf0669

Browse files
Amit Kapilapull[bot]
Amit Kapila
authored and
pull[bot]
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 a7c1ec1 commit faf0669

File tree

1 file changed

+27
-23
lines changed

1 file changed

+27
-23
lines changed

‎doc/src/sgml/logicaldecoding.sgml

Lines 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)