From 7670add9f43aeb291603c7052a2610675e1924f7 Mon Sep 17 00:00:00 2001 From: Amit Kapila Date: Fri, 20 Jan 2023 08:12:19 +0530 Subject: [PATCH] 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 --- doc/src/sgml/logicaldecoding.sgml | 50 +++++++++++++++++-------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index 4cf863a76f..4e912b4bd4 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -479,8 +479,8 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb); The begin_cb, change_cb and commit_cb callbacks are required, - while startup_cb, - filter_by_origin_cb, truncate_cb, + while startup_cb, truncate_cb, + message_cb, filter_by_origin_cb, and shutdown_cb are optional. If truncate_cb is not set but a TRUNCATE is to be decoded, the action will be ignored. @@ -490,19 +490,21 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb); An output plugin may also define functions to support streaming of large, in-progress transactions. The stream_start_cb, stream_stop_cb, stream_abort_cb, - stream_commit_cb, stream_change_cb, - and stream_prepare_cb + stream_commit_cb, and stream_change_cb are required, while stream_message_cb and - stream_truncate_cb are optional. + stream_truncate_cb are optional. The + stream_prepare_cb is also required if the output + plugin also support two-phase commits. An output plugin may also define functions to support two-phase commits, which allows actions to be decoded on the PREPARE TRANSACTION. The begin_prepare_cb, prepare_cb, - stream_prepare_cb, commit_prepared_cb and rollback_prepared_cb callbacks are required, while filter_prepare_cb is optional. + The stream_prepare_cb is also required if the output plugin + also supports the streaming of large in-progress transactions. @@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx, Truncate Callback - The truncate_cb callback is called for a + The optional truncate_cb callback is called for a TRUNCATE command. typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx, @@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext * Stream Start Callback - The stream_start_cb callback is called when opening - a block of streamed changes from an in-progress transaction. + The required stream_start_cb callback is called when + opening a block of streamed changes from an in-progress transaction. typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn); @@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx, Stream Stop Callback - The stream_stop_cb callback is called when closing - a block of streamed changes from an in-progress transaction. + The required stream_stop_cb callback is called when + closing a block of streamed changes from an in-progress transaction. typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn); @@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx, Stream Abort Callback - The stream_abort_cb callback is called to abort - a previously streamed transaction. + The required stream_abort_cb callback is called to + abort a previously streamed transaction. typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn, @@ -957,8 +959,10 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx, Stream Prepare Callback The stream_prepare_cb callback is called to prepare - a previously streamed transaction as part of a two-phase commit. - + a previously streamed transaction as part of a two-phase commit. This + callback is required when the output plugin supports both the streaming + of large in-progress transactions and two-phase commits. + typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn, XLogRecPtr prepare_lsn); @@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx Stream Commit Callback - The stream_commit_cb callback is called to commit - a previously streamed transaction. + The required stream_commit_cb callback is called to + commit a previously streamed transaction. typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx, ReorderBufferTXN *txn, @@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx, Stream Change Callback - The stream_change_cb callback is called when sending - a change in a block of streamed changes (demarcated by + The required stream_change_cb callback is called + when sending a change in a block of streamed changes (demarcated by stream_start_cb and stream_stop_cb calls). The actual changes are not displayed as the transaction can abort at a later point in time and we don't decode changes for aborted transactions. @@ -999,8 +1003,8 @@ typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx, Stream Message Callback - The stream_message_cb callback is called when sending - a generic message in a block of streamed changes (demarcated by + The optional stream_message_cb callback is called when + sending a generic message in a block of streamed changes (demarcated by stream_start_cb and stream_stop_cb calls). The message contents for transactional messages are not displayed as the transaction 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 Stream Truncate Callback - The stream_truncate_cb callback is called for a - TRUNCATE command in a block of streamed changes + The optional stream_truncate_cb callback is called + for a TRUNCATE command in a block of streamed changes (demarcated by stream_start_cb and stream_stop_cb calls). -- 2.39.5