Adjust the description of OutputPluginCallbacks in pg-doc
Started by wangw.fnst@fujitsu.comabout 3 years ago5 messages
Hi,
When I was reading the "Logical Decoding Output Plugins" chapter in pg-doc [1]https://www.postgresql.org/docs/devel/logicaldecoding-output-plugin.html,
I think in the summary section, only the callback message_cb is not described
whether it is required or optional, and the description of callback
stream_prepare_cb seems inaccurate.
And after the summary section, I think only the callback stream_xxx_cb section
and the callback truncate_cb section are not described this tag (are they
required or optional).
I think we could improve these to be more reader friendly. So I tried to write
a patch for these and attach it.
Any thoughts?
Regards,
Wang Wei
[1]: https://www.postgresql.org/docs/devel/logicaldecoding-output-plugin.html
Attachments:
v1-0001-Adjust-the-description-of-OutputPluginCallbacks-i.patchapplication/octet-stream; name=v1-0001-Adjust-the-description-of-OutputPluginCallbacks-i.patchDownload
From 11da6a483811114f7b2afd7535b7f7a14a3c5341 Mon Sep 17 00:00:00 2001
From: wangw <wangw.fnst@fujitsu.com>
Date: Wed, 11 Jan 2023 16:45:25 +0800
Subject: [PATCH v1] Adjust the description of OutputPluginCallbacks in pg-doc
- In summary section, add a description of the callback message_cb.
- In summary section, adjust description of the callback stream_prepare_cb.
- In sections introducing the callback stream_xxx_cb and truncate_cb, add
description on whether the callback is optional or required.
---
doc/src/sgml/logicaldecoding.sgml | 48 +++++++++++++++++--------------
1 file changed, 26 insertions(+), 22 deletions(-)
diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml
index 4cf863a76f..0f5459276c 100644
--- a/doc/src/sgml/logicaldecoding.sgml
+++ b/doc/src/sgml/logicaldecoding.sgml
@@ -479,8 +479,8 @@ typedef void (*LogicalOutputPluginInit) (struct OutputPluginCallbacks *cb);
</programlisting>
The <function>begin_cb</function>, <function>change_cb</function>
and <function>commit_cb</function> callbacks are required,
- while <function>startup_cb</function>,
- <function>filter_by_origin_cb</function>, <function>truncate_cb</function>,
+ while <function>startup_cb</function>, <function>truncate_cb</function>,
+ <function>message_cb</function>, <function>filter_by_origin_cb</function>,
and <function>shutdown_cb</function> are optional.
If <function>truncate_cb</function> is not set but a
<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,
in-progress transactions. The <function>stream_start_cb</function>,
<function>stream_stop_cb</function>, <function>stream_abort_cb</function>,
- <function>stream_commit_cb</function>, <function>stream_change_cb</function>,
- and <function>stream_prepare_cb</function>
+ <function>stream_commit_cb</function>, and <function>stream_change_cb</function>
are required, while <function>stream_message_cb</function> and
- <function>stream_truncate_cb</function> are optional.
+ <function>stream_truncate_cb</function> are optional. If the output plugin
+ also support two-phase commits, the <function>stream_prepare_cb</function>
+ is required.
</para>
<para>
An output plugin may also define functions to support two-phase commits,
which allows actions to be decoded on the <command>PREPARE TRANSACTION</command>.
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>
callbacks are required, while <function>filter_prepare_cb</function> is optional.
+ If the output plugin also support streaming of large, in-progress transactions,
+ the <function>stream_prepare_cb</function> is required.
</para>
</sect2>
@@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
<title>Truncate Callback</title>
<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.
<programlisting>
typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
@@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *
<sect3 id="logicaldecoding-output-plugin-stream-start">
<title>Stream Start Callback</title>
<para>
- The <function>stream_start_cb</function> callback is called when opening
- a block of streamed changes from an in-progress transaction.
+ The required <function>stream_start_cb</function> callback is called when
+ opening a block of streamed changes from an in-progress transaction.
<programlisting>
typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn);
@@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-stop">
<title>Stream Stop Callback</title>
<para>
- The <function>stream_stop_cb</function> callback is called when closing
- a block of streamed changes from an in-progress transaction.
+ The required <function>stream_stop_cb</function> callback is called when
+ closing a block of streamed changes from an in-progress transaction.
<programlisting>
typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn);
@@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-abort">
<title>Stream Abort Callback</title>
<para>
- The <function>stream_abort_cb</function> callback is called to abort
- a previously streamed transaction.
+ The required <function>stream_abort_cb</function> callback is called to
+ abort a previously streamed transaction.
<programlisting>
typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
@@ -957,7 +959,9 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
<title>Stream Prepare Callback</title>
<para>
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
+ callback is required when the output plugin support both streaming of
+ large, in-progress transactions and two-phase commits.
<programlisting>
typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
@@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx
<sect3 id="logicaldecoding-output-plugin-stream-commit">
<title>Stream Commit Callback</title>
<para>
- The <function>stream_commit_cb</function> callback is called to commit
- a previously streamed transaction.
+ The required <function>stream_commit_cb</function> callback is called to
+ commit a previously streamed transaction.
<programlisting>
typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
@@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-change">
<title>Stream Change Callback</title>
<para>
- The <function>stream_change_cb</function> callback is called when sending
- a change in a block of streamed changes (demarcated by
+ The required <function>stream_change_cb</function> callback is called
+ when sending a change in a block of streamed changes (demarcated by
<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
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">
<title>Stream Message Callback</title>
<para>
- The <function>stream_message_cb</function> callback is called when sending
- a generic message in a block of streamed changes (demarcated by
+ The optional <function>stream_message_cb</function> callback is called when
+ sending a generic message in a block of streamed changes (demarcated by
<function>stream_start_cb</function> and <function>stream_stop_cb</function> 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
<sect3 id="logicaldecoding-output-plugin-stream-truncate">
<title>Stream Truncate Callback</title>
<para>
- The <function>stream_truncate_cb</function> callback is called for a
- <command>TRUNCATE</command> command in a block of streamed changes
+ The optional <function>stream_truncate_cb</function> callback is called
+ for a <command>TRUNCATE</command> command in a block of streamed changes
(demarcated by <function>stream_start_cb</function> and
<function>stream_stop_cb</function> calls).
<programlisting>
--
2.23.0.windows.1
Re: Adjust the description of OutputPluginCallbacks in pg-doc
On Wed, Jan 11, 2023 at 4:20 PM wangw.fnst@fujitsu.com
<wangw.fnst@fujitsu.com> wrote:
When I was reading the "Logical Decoding Output Plugins" chapter in pg-doc [1],
I think in the summary section, only the callback message_cb is not described
whether it is required or optional, and the description of callback
stream_prepare_cb seems inaccurate.And after the summary section, I think only the callback stream_xxx_cb section
and the callback truncate_cb section are not described this tag (are they
required or optional).I think we could improve these to be more reader friendly. So I tried to write
a patch for these and attach it.Any thoughts?
This looks mostly good to me. I have made minor adjustments in the
attached. Do those make sense to you?
--
With Regards,
Amit Kapila.
Attachments:
v2-0001-Improve-the-description-of-Output-Plugin-Callback.patchapplication/octet-stream; name=v2-0001-Improve-the-description-of-Output-Plugin-Callback.patchDownload
From 5b73b5ff775011d6b65cd01cc886429b794c11ef Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Thu, 19 Jan 2023 16:30:44 +0530
Subject: [PATCH v2] 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);
</programlisting>
The <function>begin_cb</function>, <function>change_cb</function>
and <function>commit_cb</function> callbacks are required,
- while <function>startup_cb</function>,
- <function>filter_by_origin_cb</function>, <function>truncate_cb</function>,
+ while <function>startup_cb</function>, <function>truncate_cb</function>,
+ <function>message_cb</function>, <function>filter_by_origin_cb</function>,
and <function>shutdown_cb</function> are optional.
If <function>truncate_cb</function> is not set but a
<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,
in-progress transactions. The <function>stream_start_cb</function>,
<function>stream_stop_cb</function>, <function>stream_abort_cb</function>,
- <function>stream_commit_cb</function>, <function>stream_change_cb</function>,
- and <function>stream_prepare_cb</function>
+ <function>stream_commit_cb</function>, and <function>stream_change_cb</function>
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>
An output plugin may also define functions to support two-phase commits,
which allows actions to be decoded on the <command>PREPARE TRANSACTION</command>.
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>
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>
</sect2>
@@ -721,7 +723,7 @@ typedef void (*LogicalDecodeChangeCB) (struct LogicalDecodingContext *ctx,
<title>Truncate Callback</title>
<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.
<programlisting>
typedef void (*LogicalDecodeTruncateCB) (struct LogicalDecodingContext *ctx,
@@ -919,8 +921,8 @@ typedef void (*LogicalDecodeRollbackPreparedCB) (struct LogicalDecodingContext *
<sect3 id="logicaldecoding-output-plugin-stream-start">
<title>Stream Start Callback</title>
<para>
- The <function>stream_start_cb</function> callback is called when opening
- a block of streamed changes from an in-progress transaction.
+ The required <function>stream_start_cb</function> callback is called when
+ opening a block of streamed changes from an in-progress transaction.
<programlisting>
typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn);
@@ -931,8 +933,8 @@ typedef void (*LogicalDecodeStreamStartCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-stop">
<title>Stream Stop Callback</title>
<para>
- The <function>stream_stop_cb</function> callback is called when closing
- a block of streamed changes from an in-progress transaction.
+ The required <function>stream_stop_cb</function> callback is called when
+ closing a block of streamed changes from an in-progress transaction.
<programlisting>
typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn);
@@ -943,8 +945,8 @@ typedef void (*LogicalDecodeStreamStopCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-abort">
<title>Stream Abort Callback</title>
<para>
- The <function>stream_abort_cb</function> callback is called to abort
- a previously streamed transaction.
+ The required <function>stream_abort_cb</function> callback is called to
+ abort a previously streamed transaction.
<programlisting>
typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
@@ -957,8 +959,10 @@ typedef void (*LogicalDecodeStreamAbortCB) (struct LogicalDecodingContext *ctx,
<title>Stream Prepare Callback</title>
<para>
The <function>stream_prepare_cb</function> callback is called to prepare
- a previously streamed transaction as part of a two-phase commit.
-<programlisting>
+ 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.
+ <programlisting>
typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
XLogRecPtr prepare_lsn);
@@ -969,8 +973,8 @@ typedef void (*LogicalDecodeStreamPrepareCB) (struct LogicalDecodingContext *ctx
<sect3 id="logicaldecoding-output-plugin-stream-commit">
<title>Stream Commit Callback</title>
<para>
- The <function>stream_commit_cb</function> callback is called to commit
- a previously streamed transaction.
+ The required <function>stream_commit_cb</function> callback is called to
+ commit a previously streamed transaction.
<programlisting>
typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
ReorderBufferTXN *txn,
@@ -982,8 +986,8 @@ typedef void (*LogicalDecodeStreamCommitCB) (struct LogicalDecodingContext *ctx,
<sect3 id="logicaldecoding-output-plugin-stream-change">
<title>Stream Change Callback</title>
<para>
- The <function>stream_change_cb</function> callback is called when sending
- a change in a block of streamed changes (demarcated by
+ The required <function>stream_change_cb</function> callback is called
+ when sending a change in a block of streamed changes (demarcated by
<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
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">
<title>Stream Message Callback</title>
<para>
- The <function>stream_message_cb</function> callback is called when sending
- a generic message in a block of streamed changes (demarcated by
+ The optional <function>stream_message_cb</function> callback is called when
+ sending a generic message in a block of streamed changes (demarcated by
<function>stream_start_cb</function> and <function>stream_stop_cb</function> 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
<sect3 id="logicaldecoding-output-plugin-stream-truncate">
<title>Stream Truncate Callback</title>
<para>
- The <function>stream_truncate_cb</function> callback is called for a
- <command>TRUNCATE</command> command in a block of streamed changes
+ The optional <function>stream_truncate_cb</function> callback is called
+ for a <command>TRUNCATE</command> command in a block of streamed changes
(demarcated by <function>stream_start_cb</function> and
<function>stream_stop_cb</function> calls).
<programlisting>
--
2.28.0.windows.1
Re: Adjust the description of OutputPluginCallbacks in pg-doc
On Thu, Jan 19, 2023 at 4:47 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Wed, Jan 11, 2023 at 4:20 PM wangw.fnst@fujitsu.com
<wangw.fnst@fujitsu.com> wrote:When I was reading the "Logical Decoding Output Plugins" chapter in pg-doc [1],
I think in the summary section, only the callback message_cb is not described
whether it is required or optional, and the description of callback
stream_prepare_cb seems inaccurate.And after the summary section, I think only the callback stream_xxx_cb section
and the callback truncate_cb section are not described this tag (are they
required or optional).I think we could improve these to be more reader friendly. So I tried to write
a patch for these and attach it.Any thoughts?
This looks mostly good to me. I have made minor adjustments in the
attached. Do those make sense to you?
I forgot to mention that I intend to commit this only on HEAD as this
is a doc improvement patch.
--
With Regards,
Amit Kapila.
RE: Adjust the description of OutputPluginCallbacks in pg-doc
On Thurs, Jan 19, 2023 at 19:18 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Wed, Jan 11, 2023 at 4:20 PM wangw.fnst@fujitsu.com
<wangw.fnst@fujitsu.com> wrote:When I was reading the "Logical Decoding Output Plugins" chapter in pg-doc
[1],
I think in the summary section, only the callback message_cb is not described
whether it is required or optional, and the description of callback
stream_prepare_cb seems inaccurate.And after the summary section, I think only the callback stream_xxx_cb
section
and the callback truncate_cb section are not described this tag (are they
required or optional).I think we could improve these to be more reader friendly. So I tried to write
a patch for these and attach it.Any thoughts?
This looks mostly good to me. I have made minor adjustments in the
attached. Do those make sense to you?
Thanks for your improvement.
It makes sense to me.
Regards,
Wang Wei
Re: Adjust the description of OutputPluginCallbacks in pg-doc
On Fri, Jan 20, 2023 at 8:03 AM wangw.fnst@fujitsu.com
<wangw.fnst@fujitsu.com> wrote:
On Thurs, Jan 19, 2023 at 19:18 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Wed, Jan 11, 2023 at 4:20 PM wangw.fnst@fujitsu.com
<wangw.fnst@fujitsu.com> wrote:When I was reading the "Logical Decoding Output Plugins" chapter in pg-doc
[1],
I think in the summary section, only the callback message_cb is not described
whether it is required or optional, and the description of callback
stream_prepare_cb seems inaccurate.And after the summary section, I think only the callback stream_xxx_cb
section
and the callback truncate_cb section are not described this tag (are they
required or optional).I think we could improve these to be more reader friendly. So I tried to write
a patch for these and attach it.Any thoughts?
This looks mostly good to me. I have made minor adjustments in the
attached. Do those make sense to you?Thanks for your improvement.
It makes sense to me.
Pushed.
--
With Regards,
Amit Kapila.