PG Docs - CREATE SUBSCRIPTION option list order

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

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

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.

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.