PG Docs - CREATE SUBSCRIPTION option list order
Hi,
The CREATE SUBSCRIPTION documentation [1]= https://www.postgresql.org/docs/devel/sql-createsubscription.html includes a list of "WITH"
options, which are currently in some kind of quasi alphabetical /
random order which I found unnecessarily confusing.
I can't think of any good reason for the current ordering, so PSA my
patch which has identical content but just re-orders that option list
to be alphabetical.
------
[1]: = https://www.postgresql.org/docs/devel/sql-createsubscription.html
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-create-subscription-options-list-order.patchapplication/octet-stream; name=v1-0001-create-subscription-options-list-order.patchDownload
From a0d6c4ee19f9c594eb2ce52a57ecd2bd054dd2b0 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Mon, 19 Apr 2021 09:50:59 +1000
Subject: [PATCH v1] create subscription options list order.
Change the list to be alphabetical.
---
doc/src/sgml/ref/create_subscription.sgml | 123 +++++++++++++++---------------
1 file changed, 63 insertions(+), 60 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index e812bee..85d01fc 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -96,6 +96,57 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
following parameters are supported:
<variablelist>
+
+ <varlistentry>
+ <term><literal>binary</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether the subscription will request the publisher to
+ send the data in binary format (as opposed to text).
+ The default is <literal>false</literal>.
+ Even when this option is enabled, only data types that have
+ binary send and receive functions will be transferred in binary.
+ </para>
+
+ <para>
+ When doing cross-version replication, it could happen that the
+ publisher has a binary send function for some data type, but the
+ subscriber lacks a binary receive function for the type. In
+ such a case, data transfer will fail, and
+ the <literal>binary</literal> option cannot be used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>connect</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether the <command>CREATE SUBSCRIPTION</command>
+ should connect to the publisher at all. Setting this to
+ <literal>false</literal> will change default values of
+ <literal>enabled</literal>, <literal>create_slot</literal> and
+ <literal>copy_data</literal> to <literal>false</literal>.
+ </para>
+
+ <para>
+ It is not allowed to combine <literal>connect</literal> set to
+ <literal>false</literal> and <literal>enabled</literal>,
+ <literal>create_slot</literal>, or <literal>copy_data</literal>
+ set to <literal>true</literal>.
+ </para>
+
+ <para>
+ Since no connection is made when this option is set
+ to <literal>false</literal>, the tables are not subscribed, and so
+ after you enable the subscription nothing will be replicated.
+ It is required to run
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ for tables to be subscribed.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
@@ -148,6 +199,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</varlistentry>
<varlistentry>
+ <term><literal>streaming</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether streaming of in-progress transactions should
+ be enabled for this subscription. By default, all transactions
+ are fully decoded on the publisher, and only then sent to the
+ subscriber as a whole.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -179,66 +242,6 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>binary</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether the subscription will request the publisher to
- send the data in binary format (as opposed to text).
- The default is <literal>false</literal>.
- Even when this option is enabled, only data types that have
- binary send and receive functions will be transferred in binary.
- </para>
-
- <para>
- When doing cross-version replication, it could happen that the
- publisher has a binary send function for some data type, but the
- subscriber lacks a binary receive function for the type. In
- such a case, data transfer will fail, and
- the <literal>binary</literal> option cannot be used.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>connect</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether the <command>CREATE SUBSCRIPTION</command>
- should connect to the publisher at all. Setting this to
- <literal>false</literal> will change default values of
- <literal>enabled</literal>, <literal>create_slot</literal> and
- <literal>copy_data</literal> to <literal>false</literal>.
- </para>
-
- <para>
- It is not allowed to combine <literal>connect</literal> set to
- <literal>false</literal> and <literal>enabled</literal>,
- <literal>create_slot</literal>, or <literal>copy_data</literal>
- set to <literal>true</literal>.
- </para>
-
- <para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
- after you enable the subscription nothing will be replicated.
- It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
- for tables to be subscribed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>streaming</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether streaming of in-progress transactions should
- be enabled for this subscription. By default, all transactions
- are fully decoded on the publisher, and only then sent to the
- subscriber as a whole.
- </para>
- </listitem>
- </varlistentry>
</variablelist></para>
</listitem>
</varlistentry>
--
1.8.3.1
On Sun, Apr 18, 2021, at 8:59 PM, Peter Smith wrote:
The CREATE SUBSCRIPTION documentation [1] includes a list of "WITH"
options, which are currently in some kind of quasi alphabetical /
random order which I found unnecessarily confusing.I can't think of any good reason for the current ordering, so PSA my
patch which has identical content but just re-orders that option list
to be alphabetical.
AFAICS there is not reason to use a random order here. I think this parameter
list is in frequency of use. Your patch looks good to me.
--
Euler Taveira
EDB https://www.enterprisedb.com/
On Mon, Apr 19, 2021 at 6:32 AM Euler Taveira <euler@eulerto.com> wrote:
On Sun, Apr 18, 2021, at 8:59 PM, Peter Smith wrote:
The CREATE SUBSCRIPTION documentation [1] includes a list of "WITH"
options, which are currently in some kind of quasi alphabetical /
random order which I found unnecessarily confusing.I can't think of any good reason for the current ordering, so PSA my
patch which has identical content but just re-orders that option list
to be alphabetical.AFAICS there is not reason to use a random order here. I think this parameter
list is in frequency of use. Your patch looks good to me.
I also agree that the current order is quite random. One idea is to
keep them in alphabetical order as suggested by Peter and the other
could be to arrange parameters based on properties, for example, there
are few parameters like binary, streaming, copy_data which are in some
way related to the data being replicated and others are more of slot
properties (create_slot, slot_name). I see that few parameters among
these have some dependencies on other parameters as well. I noticed
that the other DDL commands like Create Table, Create Index doesn't
have the WITH clause parameters in any alphabetical order so it might
be better if the related parameters can be together here but if we
think it is not a good idea in this case due to some reason then
probably keeping them in alphabetical order makes sense.
--
With Regards,
Amit Kapila.
On Mon, Apr 19, 2021 at 2:09 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Mon, Apr 19, 2021 at 6:32 AM Euler Taveira <euler@eulerto.com> wrote:
On Sun, Apr 18, 2021, at 8:59 PM, Peter Smith wrote:
The CREATE SUBSCRIPTION documentation [1] includes a list of "WITH"
options, which are currently in some kind of quasi alphabetical /
random order which I found unnecessarily confusing.I can't think of any good reason for the current ordering, so PSA my
patch which has identical content but just re-orders that option list
to be alphabetical.AFAICS there is not reason to use a random order here. I think this parameter
list is in frequency of use. Your patch looks good to me.I also agree that the current order is quite random. One idea is to
keep them in alphabetical order as suggested by Peter and the other
could be to arrange parameters based on properties, for example, there
are few parameters like binary, streaming, copy_data which are in some
way related to the data being replicated and others are more of slot
properties (create_slot, slot_name). I see that few parameters among
these have some dependencies on other parameters as well. I noticed
that the other DDL commands like Create Table, Create Index doesn't
have the WITH clause parameters in any alphabetical order so it might
be better if the related parameters can be together here but if we
think it is not a good idea in this case due to some reason then
probably keeping them in alphabetical order makes sense.
Yes, if there were dozens of list items then I would agree that they
should be grouped somehow. But there aren't.
I think what may seem like a clever grouping to one reader may look
more like an over-complicated muddle to somebody else.
So I prefer just to apply the KISS Principle.
------
Kind Regards,
Peter Smith.
Fujitsu Australia.
On Mon, Apr 19, 2021 at 10:32 AM Peter Smith <smithpb2250@gmail.com> wrote:
On Mon, Apr 19, 2021 at 2:09 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Mon, Apr 19, 2021 at 6:32 AM Euler Taveira <euler@eulerto.com> wrote:
On Sun, Apr 18, 2021, at 8:59 PM, Peter Smith wrote:
The CREATE SUBSCRIPTION documentation [1] includes a list of "WITH"
options, which are currently in some kind of quasi alphabetical /
random order which I found unnecessarily confusing.I can't think of any good reason for the current ordering, so PSA my
patch which has identical content but just re-orders that option list
to be alphabetical.AFAICS there is not reason to use a random order here. I think this parameter
list is in frequency of use. Your patch looks good to me.I also agree that the current order is quite random. One idea is to
keep them in alphabetical order as suggested by Peter and the other
could be to arrange parameters based on properties, for example, there
are few parameters like binary, streaming, copy_data which are in some
way related to the data being replicated and others are more of slot
properties (create_slot, slot_name). I see that few parameters among
these have some dependencies on other parameters as well. I noticed
that the other DDL commands like Create Table, Create Index doesn't
have the WITH clause parameters in any alphabetical order so it might
be better if the related parameters can be together here but if we
think it is not a good idea in this case due to some reason then
probably keeping them in alphabetical order makes sense.Yes, if there were dozens of list items then I would agree that they
should be grouped somehow. But there aren't.
I think this list is going to grow in the future as we enhance this
subsystem. For example, the pending 2PC patch will add another
parameter to this list.
--
With Regards,
Amit Kapila.
v1 -> v2
Rebased.
------
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v2-0001-create-subscription-options-list-order.patchapplication/octet-stream; name=v2-0001-create-subscription-options-list-order.patchDownload
From 829fb5dfbf2343e27d52797776713345c71562f3 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Mon, 9 Aug 2021 12:28:39 +1000
Subject: [PATCH v2] create subscription options list order.
Change the WITH subscription parameter to be properly alphaetically ordered.
Otherwise it not very user-friending when looking for the option your are
interested in.
Currently it is mostly, but not fully alphabetical, so it looks like it was
always supposed to ordered but has evolved to be muddled.
---
doc/src/sgml/ref/create_subscription.sgml | 124 +++++++++++++++---------------
1 file changed, 63 insertions(+), 61 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 702934e..96a971d 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -96,6 +96,57 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
following parameters are supported:
<variablelist>
+
+ <varlistentry>
+ <term><literal>binary</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether the subscription will request the publisher to
+ send the data in binary format (as opposed to text).
+ The default is <literal>false</literal>.
+ Even when this option is enabled, only data types that have
+ binary send and receive functions will be transferred in binary.
+ </para>
+
+ <para>
+ When doing cross-version replication, it could happen that the
+ publisher has a binary send function for some data type, but the
+ subscriber lacks a binary receive function for the type. In
+ such a case, data transfer will fail, and
+ the <literal>binary</literal> option cannot be used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>connect</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether the <command>CREATE SUBSCRIPTION</command>
+ should connect to the publisher at all. Setting this to
+ <literal>false</literal> will change default values of
+ <literal>enabled</literal>, <literal>create_slot</literal> and
+ <literal>copy_data</literal> to <literal>false</literal>.
+ </para>
+
+ <para>
+ It is not allowed to combine <literal>connect</literal> set to
+ <literal>false</literal> and <literal>enabled</literal>,
+ <literal>create_slot</literal>, or <literal>copy_data</literal>
+ set to <literal>true</literal>.
+ </para>
+
+ <para>
+ Since no connection is made when this option is set
+ to <literal>false</literal>, the tables are not subscribed, and so
+ after you enable the subscription nothing will be replicated.
+ It is required to run
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ for tables to be subscribed.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
@@ -148,6 +199,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</varlistentry>
<varlistentry>
+ <term><literal>streaming</literal> (<type>boolean</type>)</term>
+ <listitem>
+ <para>
+ Specifies whether streaming of in-progress transactions should
+ be enabled for this subscription. By default, all transactions
+ are fully decoded on the publisher, and only then sent to the
+ subscriber as a whole.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
<listitem>
<para>
@@ -180,67 +243,6 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</varlistentry>
<varlistentry>
- <term><literal>binary</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether the subscription will request the publisher to
- send the data in binary format (as opposed to text).
- The default is <literal>false</literal>.
- Even when this option is enabled, only data types that have
- binary send and receive functions will be transferred in binary.
- </para>
-
- <para>
- When doing cross-version replication, it could happen that the
- publisher has a binary send function for some data type, but the
- subscriber lacks a binary receive function for the type. In
- such a case, data transfer will fail, and
- the <literal>binary</literal> option cannot be used.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>connect</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether the <command>CREATE SUBSCRIPTION</command>
- should connect to the publisher at all. Setting this to
- <literal>false</literal> will change default values of
- <literal>enabled</literal>, <literal>create_slot</literal> and
- <literal>copy_data</literal> to <literal>false</literal>.
- </para>
-
- <para>
- It is not allowed to combine <literal>connect</literal> set to
- <literal>false</literal> and <literal>enabled</literal>,
- <literal>create_slot</literal>, or <literal>copy_data</literal>
- set to <literal>true</literal>.
- </para>
-
- <para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
- after you enable the subscription nothing will be replicated.
- It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
- for tables to be subscribed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>streaming</literal> (<type>boolean</type>)</term>
- <listitem>
- <para>
- Specifies whether streaming of in-progress transactions should
- be enabled for this subscription. By default, all transactions
- are fully decoded on the publisher, and only then sent to the
- subscriber as a whole.
- </para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
<listitem>
<para>
--
1.8.3.1
Amit Kapila <amit.kapila16@gmail.com> writes:
On Mon, Apr 19, 2021 at 10:32 AM Peter Smith <smithpb2250@gmail.com> wrote:
Yes, if there were dozens of list items then I would agree that they
should be grouped somehow. But there aren't.
I think this list is going to grow in the future as we enhance this
subsystem. For example, the pending 2PC patch will add another
parameter to this list.
Well, we've got nine now; growing to ten wouldn't be a lot. However,
I think that grouping the options would be helpful because the existing
presentation seems extremely confusing. In particular, I think it might
help to separate the options that only determine what happens during
CREATE SUBSCRIPTION from those that control how replication behaves later.
(Are the latter set the same ones that are shared with ALTER
SUBSCRIPTION?)
Also, I think a lot of these descriptions desperately need copy-editing.
The grammar is shoddy and the markup is inconsistent.
regards, tom lane
On Sun, Sep 5, 2021 at 12:23 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Amit Kapila <amit.kapila16@gmail.com> writes:
On Mon, Apr 19, 2021 at 10:32 AM Peter Smith <smithpb2250@gmail.com> wrote:
Yes, if there were dozens of list items then I would agree that they
should be grouped somehow. But there aren't.I think this list is going to grow in the future as we enhance this
subsystem. For example, the pending 2PC patch will add another
parameter to this list.Well, we've got nine now; growing to ten wouldn't be a lot. However,
I think that grouping the options would be helpful because the existing
presentation seems extremely confusing. In particular, I think it might
help to separate the options that only determine what happens during
CREATE SUBSCRIPTION from those that control how replication behaves later.
+1. I think we can group them as (a) create_slot, slot_name, enabled,
connect, and (b) copy_data, synchronous_commit, binary, streaming,
two_phase. The first controls what happens during Create Subscription
and the later ones control the replication behavior later.
(Are the latter set the same ones that are shared with ALTER
SUBSCRIPTION?)
If we agree with the above categorization then not all of them fall
into the latter category.
--
With Regards,
Amit Kapila.
v2 --> v3
The subscription_parameter names are now split into 2 groups using
Amit's suggestion [1]/messages/by-id/CAA4eK1Kmu74xHk2jcHTmKq8HBj3xK6n=RfiJB6dfV5zVSqqiFg@mail.gmail.com on how to categorise them.
I also made some grammar improvements to their descriptions.
PSA.
------
[1]: /messages/by-id/CAA4eK1Kmu74xHk2jcHTmKq8HBj3xK6n=RfiJB6dfV5zVSqqiFg@mail.gmail.com
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v3-0001-PG-Docs-Create-Subscription-options-groupings.patchapplication/octet-stream; name=v3-0001-PG-Docs-Create-Subscription-options-groupings.patchDownload
From 1fae4072e5f045ca8d30fb7e42b6c8e63a9e1680 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Wed, 8 Sep 2021 14:30:09 +1000
Subject: [PATCH v3] PG Docs - Create Subscription - options groupings.
The subscription parameters are rearranged into two groups:
a) those that control what happens during Create Subscription
b) those that control the replication behavior
---
doc/src/sgml/ref/create_subscription.sgml | 127 ++++++++++++++++--------------
1 file changed, 70 insertions(+), 57 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 702934e..3c0bf37 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -92,17 +92,38 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
- This clause specifies optional parameters for a subscription. The
- following parameters are supported:
+ This clause specifies optional parameters for a subscription.
+ </para>
+ <para>
+ The following <replaceable class="parameter">subscription_parameter</replaceable> names control what happens during subscription creation:
<variablelist>
+
<varlistentry>
- <term><literal>copy_data</literal> (<type>boolean</type>)</term>
+ <term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the existing data in the publications that are
- being subscribed to should be copied once the replication starts.
- The default is <literal>true</literal>.
+ Specifies whether the <command>CREATE SUBSCRIPTION</command>
+ should connect to the publisher at all. Setting this to
+ <literal>false</literal> will change default values of
+ <literal>enabled</literal>, <literal>create_slot</literal> and
+ <literal>copy_data</literal> to <literal>false</literal>.
+ </para>
+
+ <para>
+ It is not allowed to combine <literal>connect</literal> set to
+ <literal>false</literal> and <literal>enabled</literal>,
+ <literal>create_slot</literal>, or <literal>copy_data</literal>
+ set to <literal>true</literal>.
+ </para>
+
+ <para>
+ Since no connection is made when this option is set
+ to <literal>false</literal>, the tables are not subscribed, and so
+ after you enable the subscription nothing will be replicated.
+ It is required to run
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ for tables to be subscribed.
</para>
</listitem>
</varlistentry>
@@ -147,37 +168,12 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- <varlistentry>
- <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
- <listitem>
- <para>
- The value of this parameter overrides the
- <xref linkend="guc-synchronous-commit"/> setting within this
- subscription's apply worker processes. The default value
- is <literal>off</literal>.
- </para>
+ </variablelist></para>
- <para>
- It is safe to use <literal>off</literal> for logical replication:
- If the subscriber loses transactions because of missing
- synchronization, the data will be sent again from the publisher.
- </para>
+ <para>
+ The following <replaceable class="parameter">subscription_parameter</replaceable> names control the replication behavior:
- <para>
- A different setting might be appropriate when doing synchronous
- logical replication. The logical replication workers report the
- positions of writes and flushes to the publisher, and when using
- synchronous replication, the publisher will wait for the actual
- flush. This means that setting
- <literal>synchronous_commit</literal> for the subscriber to
- <literal>off</literal> when the subscription is used for
- synchronous replication might increase the latency for
- <command>COMMIT</command> on the publisher. In this scenario, it
- can be advantageous to set <literal>synchronous_commit</literal>
- to <literal>local</literal> or higher.
- </para>
- </listitem>
- </varlistentry>
+ <variablelist>
<varlistentry>
<term><literal>binary</literal> (<type>boolean</type>)</term>
@@ -201,33 +197,16 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</varlistentry>
<varlistentry>
- <term><literal>connect</literal> (<type>boolean</type>)</term>
+ <term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the <command>CREATE SUBSCRIPTION</command>
- should connect to the publisher at all. Setting this to
- <literal>false</literal> will change default values of
- <literal>enabled</literal>, <literal>create_slot</literal> and
- <literal>copy_data</literal> to <literal>false</literal>.
- </para>
-
- <para>
- It is not allowed to combine <literal>connect</literal> set to
- <literal>false</literal> and <literal>enabled</literal>,
- <literal>create_slot</literal>, or <literal>copy_data</literal>
- set to <literal>true</literal>.
- </para>
-
- <para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
- after you enable the subscription nothing will be replicated.
- It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
- for tables to be subscribed.
+ Specifies whether the existing data in the publications that are
+ being subscribed to should be copied once the replication starts.
+ The default is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><literal>streaming</literal> (<type>boolean</type>)</term>
<listitem>
@@ -237,9 +216,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
are fully decoded on the publisher, and only then sent to the
subscriber as a whole.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
+ <listitem>
+ <para>
+ The value of this parameter overrides the
+ <xref linkend="guc-synchronous-commit"/> setting within this
+ subscription's apply worker processes. The default value
+ is <literal>off</literal>.
+ </para>
+
+ <para>
+ It is safe to use <literal>off</literal> for logical replication:
+ If the subscriber loses transactions because of missing
+ synchronization, the data will be sent again from the publisher.
+ </para>
+
+ <para>
+ A different setting might be appropriate when doing synchronous
+ logical replication. The logical replication workers report the
+ positions of writes and flushes to the publisher, and when using
+ synchronous replication, the publisher will wait for the actual
+ flush. This means that setting
+ <literal>synchronous_commit</literal> for the subscriber to
+ <literal>off</literal> when the subscription is used for
+ synchronous replication might increase the latency for
+ <command>COMMIT</command> on the publisher. In this scenario, it
+ can be advantageous to set <literal>synchronous_commit</literal>
+ to <literal>local</literal> or higher.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
<listitem>
@@ -267,6 +278,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
</variablelist></para>
+
+
</listitem>
</varlistentry>
</variablelist>
--
1.8.3.1
v3-0002-PG-Docs-Create-Subscription-options-rewording.patchapplication/octet-stream; name=v3-0002-PG-Docs-Create-Subscription-options-rewording.patchDownload
From 3833c5d48c65ff0bf8b6cb99f438d367feda799f Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Wed, 8 Sep 2021 16:19:51 +1000
Subject: [PATCH v3] PG Docs - Create Subscription - options rewording
Some rewording to improve grammar of the subscription_parameter
descriptions.
---
doc/src/sgml/ref/create_subscription.sgml | 42 +++++++++++++++----------------
1 file changed, 21 insertions(+), 21 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 3c0bf37..05f728c 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -111,18 +111,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- It is not allowed to combine <literal>connect</literal> set to
+ You are not allowed a combination of <literal>connect</literal> set to
<literal>false</literal> and <literal>enabled</literal>,
<literal>create_slot</literal>, or <literal>copy_data</literal>
set to <literal>true</literal>.
</para>
<para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
+ Since no connection is made when this option is
+ <literal>false</literal>, the tables are not subscribed, and so
after you enable the subscription nothing will be replicated.
It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal>
for tables to be subscribed.
</para>
</listitem>
@@ -142,8 +142,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>enabled</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the subscription should be actively replicating,
- or whether it should be just setup but not started yet. The default
+ Specifies whether the subscription should be actively replicating
+ or whether it should be just set up but not started yet. The default
is <literal>true</literal>.
</para>
</listitem>
@@ -158,10 +158,10 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- When <literal>slot_name</literal> is set to
- <literal>NONE</literal>, there will be no replication slot
- associated with the subscription. This can be used if the
- replication slot will be created later manually. Such
+ Setting <literal>slot_name</literal> to <literal>NONE</literal>
+ means there will be no replication slot
+ associated with the subscription. Use this when you will be
+ creating the replication slot later manually. Such
subscriptions must also have both <literal>enabled</literal> and
<literal>create_slot</literal> set to <literal>false</literal>.
</para>
@@ -182,14 +182,14 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
Specifies whether the subscription will request the publisher to
send the data in binary format (as opposed to text).
The default is <literal>false</literal>.
- Even when this option is enabled, only data types that have
+ Even when this option is enabled, only data types having
binary send and receive functions will be transferred in binary.
</para>
<para>
- When doing cross-version replication, it could happen that the
+ When doing cross-version replication, it could be that the
publisher has a binary send function for some data type, but the
- subscriber lacks a binary receive function for the type. In
+ subscriber lacks a binary receive function for that type. In
such a case, data transfer will fail, and
the <literal>binary</literal> option cannot be used.
</para>
@@ -200,8 +200,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the existing data in the publications that are
- being subscribed to should be copied once the replication starts.
+ Specifies whether to copy the existing data in the publications
+ subscribed to once the replication starts.
The default is <literal>true</literal>.
</para>
</listitem>
@@ -211,9 +211,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>streaming</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether streaming of in-progress transactions should
- be enabled for this subscription. By default, all transactions
- are fully decoded on the publisher, and only then sent to the
+ Specifies whether to enable streaming of in-progress transactions
+ for this subscription. By default, all transactions
+ are fully decoded on the publisher and only then sent to the
subscriber as a whole.
</para>
</listitem>
@@ -260,17 +260,17 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- When two-phase commit is enabled then the decoded transactions are sent
+ When two-phase commit is enabled the decoded transactions are sent
to the subscriber on the PREPARE TRANSACTION. By default, the transaction
prepared on the publisher is decoded as a normal transaction at commit.
</para>
<para>
The two-phase commit implementation requires that the replication has
- successfully passed the initial table synchronization phase. This means
+ successfully passed the initial table synchronization phase. So
even when two_phase is enabled for the subscription, the internal
two-phase state remains temporarily "pending" until the initialization
- phase is completed. See column
+ phase completes. See column
<literal>subtwophasestate</literal> of <xref linkend="catalog-pg-subscription"/>
to know the actual two-phase state.
</para>
--
1.8.3.1
On Wed, Sep 8, 2021 at 12:24 PM Peter Smith <smithpb2250@gmail.com> wrote:
v2 --> v3
The subscription_parameter names are now split into 2 groups using
Amit's suggestion [1] on how to categorise them.I also made some grammar improvements to their descriptions.
I have made minor edits to your first patch and it looks good to me. I
am not sure what exactly Tom has in mind related to grammatical
improvements, so it is better if he can look into that part of your
proposal (basically second patch
v4-0002-PG-Docs-Create-Subscription-options-rewording).
--
With Regards,
Amit Kapila.
Attachments:
v4-0001-Doc-Change-optional-parameters-grouping-in-Create.patchapplication/octet-stream; name=v4-0001-Doc-Change-optional-parameters-grouping-in-Create.patchDownload
From 6de70a4de83727f9f760ce1c38c4805455d8bc6d Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Thu, 9 Sep 2021 09:24:27 +0530
Subject: [PATCH v5 1/2] Doc: Change optional parameters grouping in Create
Subscription.
The subscription parameters are rearranged into two groups:
a) those that control what happens during Create Subscription
b) those that control the replication behavior
Author: Peter Smith
Reviewed-by: Amit Kapila
Discussion: https://postgr.es/m/CAHut+PtPJDSOxtuMGpO2yDrRPKxcYGL4n7HqJP9HernZE=Cj+g@mail.gmail.com
---
doc/src/sgml/ref/create_subscription.sgml | 132 +++++++++++++++++-------------
1 file changed, 73 insertions(+), 59 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 702934e..04a0fd7 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -92,17 +92,39 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
<listitem>
<para>
- This clause specifies optional parameters for a subscription. The
- following parameters are supported:
+ This clause specifies optional parameters for a subscription.
+ </para>
+
+ <para>
+ The following parameters control what happens during subscription creation:
<variablelist>
+
<varlistentry>
- <term><literal>copy_data</literal> (<type>boolean</type>)</term>
+ <term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the existing data in the publications that are
- being subscribed to should be copied once the replication starts.
- The default is <literal>true</literal>.
+ Specifies whether the <command>CREATE SUBSCRIPTION</command>
+ should connect to the publisher at all. Setting this to
+ <literal>false</literal> will change default values of
+ <literal>enabled</literal>, <literal>create_slot</literal> and
+ <literal>copy_data</literal> to <literal>false</literal>.
+ </para>
+
+ <para>
+ It is not allowed to combine <literal>connect</literal> set to
+ <literal>false</literal> and <literal>enabled</literal>,
+ <literal>create_slot</literal>, or <literal>copy_data</literal>
+ set to <literal>true</literal>.
+ </para>
+
+ <para>
+ Since no connection is made when this option is set
+ to <literal>false</literal>, the tables are not subscribed, and so
+ after you enable the subscription nothing will be replicated.
+ It is required to run
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ for tables to be subscribed.
</para>
</listitem>
</varlistentry>
@@ -146,38 +168,13 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
</listitem>
</varlistentry>
+ </variablelist>
+ </para>
- <varlistentry>
- <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
- <listitem>
- <para>
- The value of this parameter overrides the
- <xref linkend="guc-synchronous-commit"/> setting within this
- subscription's apply worker processes. The default value
- is <literal>off</literal>.
- </para>
-
- <para>
- It is safe to use <literal>off</literal> for logical replication:
- If the subscriber loses transactions because of missing
- synchronization, the data will be sent again from the publisher.
- </para>
+ <para>
+ The following parameters control the replication behavior:
- <para>
- A different setting might be appropriate when doing synchronous
- logical replication. The logical replication workers report the
- positions of writes and flushes to the publisher, and when using
- synchronous replication, the publisher will wait for the actual
- flush. This means that setting
- <literal>synchronous_commit</literal> for the subscriber to
- <literal>off</literal> when the subscription is used for
- synchronous replication might increase the latency for
- <command>COMMIT</command> on the publisher. In this scenario, it
- can be advantageous to set <literal>synchronous_commit</literal>
- to <literal>local</literal> or higher.
- </para>
- </listitem>
- </varlistentry>
+ <variablelist>
<varlistentry>
<term><literal>binary</literal> (<type>boolean</type>)</term>
@@ -201,33 +198,16 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</varlistentry>
<varlistentry>
- <term><literal>connect</literal> (<type>boolean</type>)</term>
+ <term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the <command>CREATE SUBSCRIPTION</command>
- should connect to the publisher at all. Setting this to
- <literal>false</literal> will change default values of
- <literal>enabled</literal>, <literal>create_slot</literal> and
- <literal>copy_data</literal> to <literal>false</literal>.
- </para>
-
- <para>
- It is not allowed to combine <literal>connect</literal> set to
- <literal>false</literal> and <literal>enabled</literal>,
- <literal>create_slot</literal>, or <literal>copy_data</literal>
- set to <literal>true</literal>.
- </para>
-
- <para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
- after you enable the subscription nothing will be replicated.
- It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
- for tables to be subscribed.
+ Specifies whether the existing data in the publications that are
+ being subscribed to should be copied once the replication starts.
+ The default is <literal>true</literal>.
</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><literal>streaming</literal> (<type>boolean</type>)</term>
<listitem>
@@ -237,9 +217,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
are fully decoded on the publisher, and only then sent to the
subscriber as a whole.
</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
+ <listitem>
+ <para>
+ The value of this parameter overrides the
+ <xref linkend="guc-synchronous-commit"/> setting within this
+ subscription's apply worker processes. The default value
+ is <literal>off</literal>.
+ </para>
+
+ <para>
+ It is safe to use <literal>off</literal> for logical replication:
+ If the subscriber loses transactions because of missing
+ synchronization, the data will be sent again from the publisher.
+ </para>
+ <para>
+ A different setting might be appropriate when doing synchronous
+ logical replication. The logical replication workers report the
+ positions of writes and flushes to the publisher, and when using
+ synchronous replication, the publisher will wait for the actual
+ flush. This means that setting
+ <literal>synchronous_commit</literal> for the subscriber to
+ <literal>off</literal> when the subscription is used for
+ synchronous replication might increase the latency for
+ <command>COMMIT</command> on the publisher. In this scenario, it
+ can be advantageous to set <literal>synchronous_commit</literal>
+ to <literal>local</literal> or higher.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><literal>two_phase</literal> (<type>boolean</type>)</term>
<listitem>
@@ -266,7 +278,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</listitem>
</varlistentry>
- </variablelist></para>
+ </variablelist>
+ </para>
+
</listitem>
</varlistentry>
</variablelist>
--
1.8.3.1
v4-0002-PG-Docs-Create-Subscription-options-rewording.patchapplication/octet-stream; name=v4-0002-PG-Docs-Create-Subscription-options-rewording.patchDownload
From 68fd9bf77d86e294009c900b5eb8e006adddea70 Mon Sep 17 00:00:00 2001
From: Amit Kapila <akapila@postgresql.org>
Date: Thu, 9 Sep 2021 09:36:04 +0530
Subject: [PATCH v5 2/2] PG Docs - Create Subscription - options rewording
Some rewording to improve grammar of the subscription_parameter
descriptions.
---
doc/src/sgml/ref/create_subscription.sgml | 42 +++++++++++++++----------------
1 file changed, 21 insertions(+), 21 deletions(-)
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 04a0fd7..2ce6b73 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -112,18 +112,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- It is not allowed to combine <literal>connect</literal> set to
+ You are not allowed a combination of <literal>connect</literal> set to
<literal>false</literal> and <literal>enabled</literal>,
<literal>create_slot</literal>, or <literal>copy_data</literal>
set to <literal>true</literal>.
</para>
<para>
- Since no connection is made when this option is set
- to <literal>false</literal>, the tables are not subscribed, and so
+ Since no connection is made when this option is
+ <literal>false</literal>, the tables are not subscribed, and so
after you enable the subscription nothing will be replicated.
It is required to run
- <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+ <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal>
for tables to be subscribed.
</para>
</listitem>
@@ -143,8 +143,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>enabled</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the subscription should be actively replicating,
- or whether it should be just setup but not started yet. The default
+ Specifies whether the subscription should be actively replicating
+ or whether it should be just set up but not started yet. The default
is <literal>true</literal>.
</para>
</listitem>
@@ -159,10 +159,10 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- When <literal>slot_name</literal> is set to
- <literal>NONE</literal>, there will be no replication slot
- associated with the subscription. This can be used if the
- replication slot will be created later manually. Such
+ Setting <literal>slot_name</literal> to <literal>NONE</literal>
+ means there will be no replication slot
+ associated with the subscription. Use this when you will be
+ creating the replication slot later manually. Such
subscriptions must also have both <literal>enabled</literal> and
<literal>create_slot</literal> set to <literal>false</literal>.
</para>
@@ -183,14 +183,14 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
Specifies whether the subscription will request the publisher to
send the data in binary format (as opposed to text).
The default is <literal>false</literal>.
- Even when this option is enabled, only data types that have
+ Even when this option is enabled, only data types having
binary send and receive functions will be transferred in binary.
</para>
<para>
- When doing cross-version replication, it could happen that the
+ When doing cross-version replication, it could be that the
publisher has a binary send function for some data type, but the
- subscriber lacks a binary receive function for the type. In
+ subscriber lacks a binary receive function for that type. In
such a case, data transfer will fail, and
the <literal>binary</literal> option cannot be used.
</para>
@@ -201,8 +201,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>copy_data</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether the existing data in the publications that are
- being subscribed to should be copied once the replication starts.
+ Specifies whether to copy the existing data in the publications
+ subscribed to once the replication starts.
The default is <literal>true</literal>.
</para>
</listitem>
@@ -212,9 +212,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>streaming</literal> (<type>boolean</type>)</term>
<listitem>
<para>
- Specifies whether streaming of in-progress transactions should
- be enabled for this subscription. By default, all transactions
- are fully decoded on the publisher, and only then sent to the
+ Specifies whether to enable streaming of in-progress transactions
+ for this subscription. By default, all transactions
+ are fully decoded on the publisher and only then sent to the
subscriber as a whole.
</para>
</listitem>
@@ -261,17 +261,17 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
- When two-phase commit is enabled then the decoded transactions are sent
+ When two-phase commit is enabled the decoded transactions are sent
to the subscriber on the PREPARE TRANSACTION. By default, the transaction
prepared on the publisher is decoded as a normal transaction at commit.
</para>
<para>
The two-phase commit implementation requires that the replication has
- successfully passed the initial table synchronization phase. This means
+ successfully passed the initial table synchronization phase. So
even when two_phase is enabled for the subscription, the internal
two-phase state remains temporarily "pending" until the initialization
- phase is completed. See column
+ phase completes. See column
<literal>subtwophasestate</literal> of <xref linkend="catalog-pg-subscription"/>
to know the actual two-phase state.
</para>
--
1.8.3.1
On Thu, Sep 9, 2021 at 9:50 AM Amit Kapila <amit.kapila16@gmail.com> wrote:
On Wed, Sep 8, 2021 at 12:24 PM Peter Smith <smithpb2250@gmail.com> wrote:
v2 --> v3
The subscription_parameter names are now split into 2 groups using
Amit's suggestion [1] on how to categorise them.I also made some grammar improvements to their descriptions.
I have made minor edits to your first patch and it looks good to me.
Pushed the first patch. I am not so sure about the second one so I
won't do anything for the same. I'll close this CF entry in a day or
two unless there is an interest in the second patch.
With Regards,
Amit Kapila.
Amit Kapila <amit.kapila16@gmail.com> writes:
Pushed the first patch. I am not so sure about the second one so I
won't do anything for the same. I'll close this CF entry in a day or
two unless there is an interest in the second patch.
Sorry for not reviewing this more promptly.
I made some further edits in the 0002 patch and pushed it.
regards, tom lane
On Mon, Sep 13, 2021 at 11:58 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Amit Kapila <amit.kapila16@gmail.com> writes:
Pushed the first patch. I am not so sure about the second one so I
won't do anything for the same. I'll close this CF entry in a day or
two unless there is an interest in the second patch.Sorry for not reviewing this more promptly.
I made some further edits in the 0002 patch and pushed it.
Thanks.
--
With Regards,
Amit Kapila.