database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-28 23:42:10 +03:00
Code Activity

Improve the description of Output Plugin Callbacks.

Browse Source 
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
This commit is contained in:
Amit Kapila
2023-01-20 08:12:19 +05:30
parent efb6f4a4f9
commit 7670add9f4
1 changed files with 27 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/src/sgml/logicaldecoding.sgml
View File

@ -479,8 +479,8 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
</programlisting> </programlisting>
The <function>begin_cb</function>, <function>change_cb</function> The <function>begin_cb</function>, <function>change_cb</function>
and <function>commit_cb</function> callbacks are required, and <function>commit_cb</function> callbacks are required,
while <function>startup_cb</function>, while <function>startup_cb</function>, <function>truncate_cb</function>,
<function>filter_by_origin_cb</function>, <function>truncate_cb</function>, <function>message_cb</function>, <function>filter_by_origin_cb</function>,
and <function>shutdown_cb</function> are optional. and <function>shutdown_cb</function> are optional.
If <function>truncate_cb</function> is not set but a If <function>truncate_cb</function> is not set but a
<command>TRUNCATE</command> is to be decoded, the action will be ignored. <command>TRUNCATE</command> 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, An output plugin may also define functions to support streaming of large,
in-progress transactions. The <function>stream_start_cb</function>, in-progress transactions. The <function>stream_start_cb</function>,
<function>stream_stop_cb</function>, <function>stream_abort_cb</function>, <function>stream_stop_cb</function>, <function>stream_abort_cb</function>,
<function>stream_commit_cb</function>, <function>stream_change_cb</function>, <function>stream_commit_cb</function>, and <function>stream_change_cb</function>
and <function>stream_prepare_cb</function>
are required, while <function>stream_message_cb</function> and are required, while <function>stream_message_cb</function> and
<function>stream_truncate_cb</function> are optional. <function>stream_truncate_cb</function> are optional. The
<function>stream_prepare_cb</function> is also required if the output
plugin also support two-phase commits.
</para> </para>
<para> <para>
An output plugin may also define functions to support two-phase commits, An output plugin may also define functions to support two-phase commits,
which allows actions to be decoded on the <command>PREPARE TRANSACTION</command>. which allows actions to be decoded on the <command>PREPARE TRANSACTION</command>.
The <function>begin_prepare_cb</function>, <function>prepare_cb</function>, The <function>begin_prepare_cb</function>, <function>prepare_cb</function>,
<function>stream_prepare_cb</function>,
<function>commit_prepared_cb</function> and <function>rollback_prepared_cb</function> <function>commit_prepared_cb</function> and <function>rollback_prepared_cb</function>
callbacks are required, while <function>filter_prepare_cb</function> is optional. callbacks are required, while <function>filter_prepare_cb</function> is optional.
The <function>stream_prepare_cb</function> is also required if the output plugin
also supports the streaming of large in-progress transactions.
</para> </para>
</sect2> </sect2>
@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
<title>Truncate Callback</title> <title>Truncate Callback</title>
<para> <para>
The <function>truncate_cb</function> callback is called for a The optional <function>truncate_cb</function> callback is called for a
<command>TRUNCATE</command> command. <command>TRUNCATE</command> command.
<programlisting> <programlisting>
typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *
<sect3 id="logicaldecoding-output-plugin-stream-start"> <sect3 id="logicaldecoding-output-plugin-stream-start">
<title>Stream Start Callback</title> <title>Stream Start Callback</title>
<para> <para>
The <function>stream_start_cb</function> callback is called when opening The required <function>stream_start_cb</function> callback is called when
a block of streamed changes from an in-progress transaction. opening a block of streamed changes from an in-progress transaction.
<programlisting> <programlisting>
typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn); ReorderBufferTXN *txn);
@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-stop"> <sect3 id="logicaldecoding-output-plugin-stream-stop">
<title>Stream Stop Callback</title> <title>Stream Stop Callback</title>
<para> <para>
The <function>stream_stop_cb</function> callback is called when closing The required <function>stream_stop_cb</function> callback is called when
a block of streamed changes from an in-progress transaction. closing a block of streamed changes from an in-progress transaction.
<programlisting> <programlisting>
typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn); ReorderBufferTXN *txn);
@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-abort"> <sect3 id="logicaldecoding-output-plugin-stream-abort">
<title>Stream Abort Callback</title> <title>Stream Abort Callback</title>
<para> <para>
The <function>stream_abort_cb</function> callback is called to abort The required <function>stream_abort_cb</function> callback is called to
a previously streamed transaction. abort a previously streamed transaction.
<programlisting> <programlisting>
typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn, ReorderBufferTXN *txn,
@ -957,8 +959,10 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
<title>Stream Prepare Callback</title> <title>Stream Prepare Callback</title>
<para> <para>
The <function>stream_prepare_cb</function> callback is called to prepare The <function>stream_prepare_cb</function> 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
<programlisting> callback is required when the output plugin supports both the streaming
of large in-progress transactions and two-phase commits.
<programlisting>
typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn, ReorderBufferTXN *txn,
XLogRecPtr prepare_lsn); XLogRecPtr prepare_lsn);
@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx
<sect3 id="logicaldecoding-output-plugin-stream-commit"> <sect3 id="logicaldecoding-output-plugin-stream-commit">
<title>Stream Commit Callback</title> <title>Stream Commit Callback</title>
<para> <para>
The <function>stream_commit_cb</function> callback is called to commit The required <function>stream_commit_cb</function> callback is called to
a previously streamed transaction. commit a previously streamed transaction.
<programlisting> <programlisting>
typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx, typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn, ReorderBufferTXN *txn,
@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-change"> <sect3 id="logicaldecoding-output-plugin-stream-change">
<title>Stream Change Callback</title> <title>Stream Change Callback</title>
<para> <para>
The <function>stream_change_cb</function> callback is called when sending The required <function>stream_change_cb</function> callback is called
a change in a block of streamed changes (demarcated by when sending a change in a block of streamed changes (demarcated by
<function>stream_start_cb</function> and <function>stream_stop_cb</function> calls). <function>stream_start_cb</function> and <function>stream_stop_cb</function> calls).
The actual changes are not displayed as the transaction can abort at a later 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. point in time and we don't decode changes for aborted transactions.
@ -999,8 +1003,8 @@ typedef void (*LogicalDecodeStreamChangeCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-message"> <sect3 id="logicaldecoding-output-plugin-stream-message">
<title>Stream Message Callback</title> <title>Stream Message Callback</title>
<para> <para>
The <function>stream_message_cb</function> callback is called when sending The optional <function>stream_message_cb</function> callback is called when
a generic message in a block of streamed changes (demarcated by sending a generic message in a block of streamed changes (demarcated by
<function>stream_start_cb</function> and <function>stream_stop_cb</function> calls). <function>stream_start_cb</function> and <function>stream_stop_cb</function> calls).
The message contents for transactional messages are not displayed as the transaction 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 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
<sect3 id="logicaldecoding-output-plugin-stream-truncate"> <sect3 id="logicaldecoding-output-plugin-stream-truncate">
<title>Stream Truncate Callback</title> <title>Stream Truncate Callback</title>
<para> <para>
The <function>stream_truncate_cb</function> callback is called for a The optional <function>stream_truncate_cb</function> callback is called
<command>TRUNCATE</command> command in a block of streamed changes for a <command>TRUNCATE</command> command in a block of streamed changes
(demarcated by <function>stream_start_cb</function> and (demarcated by <function>stream_start_cb</function> and
<function>stream_stop_cb</function> calls). <function>stream_stop_cb</function> calls).
<programlisting> <programlisting>