Re: Add publisher and subscriber to glossary documentation.

[Euler Taveira]

On Fri, Mar 15, 2024, at 1:14 AM, Amit Kapila wrote:
> I think node should mean instance for both physical and logical
> replication, otherwise, it would be confusing. We need both the usages
> as a particular publication/subscription is defined at the database
> level but the server on which we define those is referred to as a
> node/instance.

If you are creating a subscription that connects to the same instance
(replication between 2 databases in the same cluster), your definition is not
correct and Alvaro's definition is accurate. The node definition is closely
linked to the connection string. While the physical replication does not
specify a database (meaning "any database" referring to an instance), the
logical replication requires a database.


--
Euler Taveira
EDB   https://www.enterprisedb.com/

Re: Add publisher and subscriber to glossary documentation.

[Amit Kapila]

On Thu, Mar 14, 2024 at 7:51 PM Alvaro Herrera  wrote:
>
> On 2024-Mar-14, Shlok Kyal wrote:
>
> > Andrew Atkinson wrote:
> >
> > > Anyway, hopefully these examples show “node” and “database” are
> > > mixed and perhaps others agree using one consistently might help the
> > > goals of the docs.
> >
> > For me the existing content looks good, I felt let's keep it as it is
> > unless others feel differently.
>
> Actually it's these small terminology glitches that give me pause.  If
> we're going to have terms that are interchangeable (in this case "node"
> and "database"), then they should be always interchangeable, not just in
> some unspecified cases.  Maybe the idea of using "node" (which sounds
> like something that's instance-wide) is wrong for logical replication,
> which is necessarily something that happens database-locally.
>
> Then again, maybe defining "node" as something that exists at a
> database-local level when used in the context of logical replication is
> sufficient.  In that case, it would be better to avoid defining it as a
> synonym of "instance".  Then the terms are not always interchangeable,
> but it's clear when they are and when they aren't.
>
> "Node: in replication, each of the endpoints to which or
> from which data is replicated.  In the context of physical replication,
> each node is an instance.  In the context of logical replication, each
> node is a database".
>

I think node should mean instance for both physical and logical
replication, otherwise, it would be confusing. We need both the usages
as a particular publication/subscription is defined at the database
level but the server on which we define those is referred to as a
node/instance.

One of the usages pointed out by Andrew: "The subscriber database..."
[1] is unclear but I feel we can use node there as well instead of
database.

[1] - 
https://www.postgresql.org/docs/current/logical-replication-subscription.html

-- 
With Regards,
Amit Kapila.

Re: Add publisher and subscriber to glossary documentation.

[Alvaro Herrera]

On 2024-Mar-14, Shlok Kyal wrote:

> Andrew Atkinson wrote:
>
> > Anyway, hopefully these examples show “node” and “database” are
> > mixed and perhaps others agree using one consistently might help the
> > goals of the docs.
> 
> For me the existing content looks good, I felt let's keep it as it is
> unless others feel differently.

Actually it's these small terminology glitches that give me pause.  If
we're going to have terms that are interchangeable (in this case "node"
and "database"), then they should be always interchangeable, not just in
some unspecified cases.  Maybe the idea of using "node" (which sounds
like something that's instance-wide) is wrong for logical replication,
which is necessarily something that happens database-locally.

Then again, maybe defining "node" as something that exists at a
database-local level when used in the context of logical replication is
sufficient.  In that case, it would be better to avoid defining it as a
synonym of "instance".  Then the terms are not always interchangeable,
but it's clear when they are and when they aren't.

"Node: in replication, each of the endpoints to which or
from which data is replicated.  In the context of physical replication,
each node is an instance.  In the context of logical replication, each
node is a database".

Does that make sense?

I'd also look at altering "Primary" and "Standby" so that it's clearer
that they're about physical replication, and don't mention "database"
anymore, since that's the wrong level.  Maybe turn them into "Primary
(node)" and "Standby (node)" instead.

-- 
Álvaro Herrera PostgreSQL Developer  —  https://www.EnterpriseDB.com/

Re: Add publisher and subscriber to glossary documentation.

[Shlok Kyal]

Hi Andrew,

> If there's a movement towards "node" to refer to the database which has the 
> Subscription object, then perhaps the documentation for
>
> 31.2. Subscription, Chapter 31. Logical Replication should be updated as 
> well, since it uses both the "database" and "node" terms on the same page, 
> and to me referring to the same thing (I could be missing a subtlety).
>
>
> See:
>
>
> "The subscriber database..."
>
>
> "A subscriber node may..."
>
>
> Also, the word "database" in this sentence: "A subscription defines the 
> connection to another database" to me works, but I think using "node" there 
> could be more consistent if it’s referring to the server instance running the 
> database that holds the PUBLICATION. The connection string information 
> example later on the page shows "host" and "dbname" configured in the 
> CONNECTION value for the SUBSCRIPTION. This sentence seems like the use of 
> "database" in casual style to mean the "server instance" (or "node").
>
>
> Also, the "The node where a subscription is defined". That one actually feels 
> to me like "The database where a subscription is defined", but then that 
> contradicts what I just said, and "node" is fine here but I think "node" 
> should be on the preceding sentence too.
>
>
> Anyway, hopefully these examples show “node” and “database” are mixed and 
> perhaps others agree using one consistently might help the goals of the docs.

For me the existing content looks good, I felt let's keep it as it is
unless others feel differently.

Thanks and regards,
Shlok Kyal

Re: Add publisher and subscriber to glossary documentation.

[Andrew Atkinson]

If there's a movement towards "node" to refer to the database which has the
Subscription object, then perhaps the documentation for

31.2. Subscription, Chapter 31. Logical Replication

should be updated as well, since it uses both the "database" and "node"
terms on the same page, and to me referring to the same thing (I could be
missing a subtlety).

See:

"The subscriber database..."

"A subscriber node may..."

Also, the word "database" in this sentence: "A subscription defines the
connection to another database" to me works, but I think using "node" there
could be more consistent if it’s referring to the server instance running
the database that holds the PUBLICATION. The connection string information
example later on the page shows "host" and "dbname" configured in the
CONNECTION value for the SUBSCRIPTION. This sentence seems like the use of
"database" in casual style to mean the "server instance" (or "node").

Also, the "The node where a subscription is defined". That one actually
feels to me like "The database where a subscription is defined", but then
that contradicts what I just said, and "node" is fine here but I think
"node" should be on the preceding sentence too.

Anyway, hopefully these examples show “node” and “database” are mixed and
perhaps others agree using one consistently might help the goals of the
docs.


Thanks!



On Mon, Feb 26, 2024 at 1:08 AM Peter Smith  wrote:

> Hi, the patch v4 LGTM.
>
> ==
> Kind Regards,
> Peter Smith.
> Fujitsu Australia
>
>
>

Re: Add publisher and subscriber to glossary documentation.

[Peter Smith]

Hi, the patch v4 LGTM.

==
Kind Regards,
Peter Smith.
Fujitsu Australia

Re: Add publisher and subscriber to glossary documentation.

[Shlok Kyal]

> 1.
> +  
> +   Publication node
> +   
> +
> + A node where a
> +  linkend="glossary-publication">publication is defined
> + for logical
> replication.
> +
> +   
> +  
> +
>
> I felt the word "node" here should link to the glossary term "Node",
> instead of directly to the term "Instance".
>
> ~~
>
> 2.
> +  
> +   Subscription node
> +   
> +
> + A node where a
> +  linkend="glossary-subscription">subscription is defined
> + for logical
> replication.
> +
> +   
> +  
> +
>
> (same comment as above)
>
> I felt the word "node" here should link to the glossary term "Node",
> instead of directly to the term "Instance".

I have addressed the comments and have attached the updated version.

Thanks and Regards,
Shlok Kyal


v4-0001-Add-publisher-and-subscriber-to-glossary-document.patch
Description: Binary data

Re: Add publisher and subscriber to glossary documentation.

[Peter Smith]

Here are some comments for patch v3:

1.
+  
+   Publication node
+   
+
+ A node where a
+ publication is defined
+ for logical
replication.
+
+   
+  
+

I felt the word "node" here should link to the glossary term "Node",
instead of directly to the term "Instance".

~~

2.
+  
+   Subscription node
+   
+
+ A node where a
+ subscription is defined
+ for logical
replication.
+
+   
+  
+

(same comment as above)

I felt the word "node" here should link to the glossary term "Node",
instead of directly to the term "Instance".

~~

Apart from those links, it looks good to me. Let's see what others think.

==
Kind Regards,
Peter Smith.
Fujitsu Australia

Re: Add publisher and subscriber to glossary documentation.

[Shlok Kyal]

> Here are some comments for patch v2.
>
> ==
>
> 1. There are whitespace problems
>
> [postgres@CentOS7-x64 oss_postgres_misc]$ git apply
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:43:
> trailing whitespace.
>   A node where publication is defined for
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:45:
> trailing whitespace.
>   It replicates a set of changes from a table or a group of tables in
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:66:
> trailing whitespace.
>  A node where subscription is defined for
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:67:
> trailing whitespace.
>  logical 
> replication.
> ../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:68:
> trailing whitespace.
>  It subscribes to one or more publications on a publisher node and pulls
> warning: squelched 2 whitespace errors
> warning: 7 lines add whitespace errors.
>
> ~~~
> 2. Publisher node
>
> +  
> +   Publisher node
> +   
> +
> +  A node where publication is defined for
> +  logical
> replication.
> +  It replicates a set of changes from a table or a group of tables in
> +  publication to the subscriber node.
> +
> +
> + For more information, see
> + .
> +
> +   
> +  
> +
>
>
> 2a.
> I felt the term here should be "Publication node".
>
> Indeed, there should also be additional glossary terms like
> "Publisher" (i.e. it is the same as "Publication node") and
> "Subscriber" (i.e. it is the same as "Subscription node"). These
> definitions will then be consistent with node descriptions already in
> sections 30.1 and 30.2
>
>
> ~
>
> 2b.
> "node" should include a link to the glossary term. Same for any other
> terms mentioned
>
> ~
>
> 2c.
> /A node where publication is defined for/A node where a publication is
> defined for/
>
> ~
>
> 2d.
> "It replicates" is misleading because it is the PUBLICATION doing the
> replicating, not the node.
>
> IMO it will be better to include 2 more glossary terms "Publication"
> and "Subscription" where you can say this kind of information. Then
> the link "logical-replication-publication" also belongs under the
> "Publication" term.
>
>
> ~~~
>
> 3.
> +  
> +   Subscriber node
> +   
> +
> + A node where subscription is defined for
> + logical 
> replication.
> + It subscribes to one or more publications on a publisher node and pulls
> + a set of changes from a table or a group of tables in publications it
> + subscribes to.
> +
> +
> + For more information, see
> + .
> +
> +   
> +  
>
> All comments are similar to those above.
>
> ==
>
> In summary, IMO it should be a bit more like below:
>
> SUGGESTION (include all the necessary links etc)
>
> Publisher
> See "Publication node"
>
> Publication
> A publication replicates the changes of one or more tables to a
> subscription. For more information, see Section 30.1
>
> Publication node
> A node where a publication is defined for logical replication.
>
> Subscriber
> See "Subscription node"
>
> Subscription
> A subscription receives the changes of one or more tables from the
> publications it subscribes to. For more information, see Section 30.2
>
> Subscription node
> A node where a subscription is defined for logical replication.

I have addressed the comments and added an updated patch.

Thanks and Regards,
Shlok Kyal


v3-0001-Add-publisher-and-subscriber-to-glossary-document.patch
Description: Binary data

Re: Add publisher and subscriber to glossary documentation.

[Peter Smith]

Here are some comments for patch v2.

==

1. There are whitespace problems

[postgres@CentOS7-x64 oss_postgres_misc]$ git apply
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:43:
trailing whitespace.
  A node where publication is defined for
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:45:
trailing whitespace.
  It replicates a set of changes from a table or a group of tables in
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:66:
trailing whitespace.
 A node where subscription is defined for
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:67:
trailing whitespace.
 logical replication.
../patches_misc/v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch:68:
trailing whitespace.
 It subscribes to one or more publications on a publisher node and pulls
warning: squelched 2 whitespace errors
warning: 7 lines add whitespace errors.

~~~

2. Publisher node

+  
+   Publisher node
+   
+
+  A node where publication is defined for
+  logical
replication.
+  It replicates a set of changes from a table or a group of tables in
+  publication to the subscriber node.
+
+
+ For more information, see
+ .
+
+   
+  
+


2a.
I felt the term here should be "Publication node".

Indeed, there should also be additional glossary terms like
"Publisher" (i.e. it is the same as "Publication node") and
"Subscriber" (i.e. it is the same as "Subscription node"). These
definitions will then be consistent with node descriptions already in
sections 30.1 and 30.2


~

2b.
"node" should include a link to the glossary term. Same for any other
terms mentioned

~

2c.
/A node where publication is defined for/A node where a publication is
defined for/

~

2d.
"It replicates" is misleading because it is the PUBLICATION doing the
replicating, not the node.

IMO it will be better to include 2 more glossary terms "Publication"
and "Subscription" where you can say this kind of information. Then
the link "logical-replication-publication" also belongs under the
"Publication" term.


~~~

3.
+  
+   Subscriber node
+   
+
+ A node where subscription is defined for
+ logical replication.
+ It subscribes to one or more publications on a publisher node and pulls
+ a set of changes from a table or a group of tables in publications it
+ subscribes to.
+
+
+ For more information, see
+ .
+
+   
+  

All comments are similar to those above.

==

In summary, IMO it should be a bit more like below:

SUGGESTION (include all the necessary links etc)

Publisher
See "Publication node"

Publication
A publication replicates the changes of one or more tables to a
subscription. For more information, see Section 30.1

Publication node
A node where a publication is defined for logical replication.

Subscriber
See "Subscription node"

Subscription
A subscription receives the changes of one or more tables from the
publications it subscribes to. For more information, see Section 30.2

Subscription node
A node where a subscription is defined for logical replication.

==
Kind Regards,
Peter Smith.
Fujitsu Australia

Re: Add publisher and subscriber to glossary documentation.

[Shlok Kyal]

Hi,
I addressed the comments and updated the patch.

> Should these be "publisher node" and "subscriber node" instead?  Do we
> want to define the term "node"?  I think in everyday conversations we
> use "node" quite a lot, so maybe we do need an entry for it.  (Maybe
> just  suffices, plus add under instance
> "also called a node".)

Modified

> +   Publisher
> +   
> +
> +  A node where publication is defined.
> +  It replicates the publication changes to the subscriber node.
>
> Apart from deciding what to do with "node", what are "changes"?  This
> doesn't seem very specific.

Modified

> +   Subscriber
> +   
> +
> + A node where subscription is defined.
> + It subscribe to one or more publications on a publisher node and pull 
> the data
> + from the publications they subscribe to.
>
> Same issues as above, plus there are some grammar issues.

Modified

> I think these definitions should use the term "logical replication",
> which we don't currently define.  We do have "replication" where we
> provide an overview of "logical replication".  Maybe that's enough, but
> we should consider whether we want a separate definition of logical
> replication (I'm leaning towards not having one, but it's worth asking.)

Modified. Added the term "logical replication" in the definitions.
Used reference to "replication".

Thanks and Regards,
Shlok Kyal


v2-0001-Add-publisher-and-subscriber-to-glossary-document.patch
Description: Binary data

Re: Add publisher and subscriber to glossary documentation.

[Alvaro Herrera]

Hello

On 2024-Feb-12, Shlok Kyal wrote:

> There are several places where publisher and subscriber terms are used
> across the documentation. But the publisher and subscriber were
> missing in the documentation. I felt this should be added in the
> glossary.

I agree, but let's wordsmith those definitions first.

Should these be "publisher node" and "subscriber node" instead?  Do we
want to define the term "node"?  I think in everyday conversations we
use "node" quite a lot, so maybe we do need an entry for it.  (Maybe
just  suffices, plus add under instance
"also called a node".)

+   Publisher
+   
+
+  A node where publication is defined.
+  It replicates the publication changes to the subscriber node.

Apart from deciding what to do with "node", what are "changes"?  This
doesn't seem very specific.

+   Subscriber
+   
+
+ A node where subscription is defined.
+ It subscribe to one or more publications on a publisher node and pull the 
data
+ from the publications they subscribe to.

Same issues as above, plus there are some grammar issues.


I think these definitions should use the term "logical replication",
which we don't currently define.  We do have "replication" where we
provide an overview of "logical replication".  Maybe that's enough, but
we should consider whether we want a separate definition of logical
replication (I'm leaning towards not having one, but it's worth asking.)

-- 
Álvaro HerreraBreisgau, Deutschland  —  https://www.EnterpriseDB.com/
"But static content is just dynamic content that isn't moving!"
http://smylers.hates-software.com/2007/08/15/fe244d0c.html