Add publisher and subscriber to glossary documentation.

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 <glossssee otherterm="instance"> suffices, plus add under instance
"also called a node".)

+   <glossterm>Publisher</glossterm>
+   <glossdef>
+    <para>
+      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.

+   <glossterm>Subscriber</glossterm>
+   <glossdef>
+    <para>
+     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 Herrera Breisgau, 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

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 <glossssee otherterm="instance"> suffices, plus add under instance
"also called a node".)

Modified

+   <glossterm>Publisher</glossterm>
+   <glossdef>
+    <para>
+      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

+   <glossterm>Subscriber</glossterm>
+   <glossdef>
+    <para>
+     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

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.
<glossterm linkend="glossary-replication">logical replication</glossterm>.
../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

+  <glossentry id="glossary-publisher">
+   <glossterm>Publisher node</glossterm>
+   <glossdef>
+    <para>
+      A node where publication is defined for
+      <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+      It replicates a set of changes from a table or a group of tables in
+      publication to the subscriber node.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="logical-replication-publication"/>.
+    </para>
+   </glossdef>
+  </glossentry>
+

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.
+  <glossentry id="glossary-subscriber">
+   <glossterm>Subscriber node</glossterm>
+   <glossdef>
+    <para>
+     A node where subscription is defined for
+     <glossterm linkend="glossary-replication">logical replication</glossterm>.
+     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.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="logical-replication-subscription"/>.
+    </para>
+   </glossdef>
+  </glossentry>

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

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.
<glossterm linkend="glossary-replication">logical replication</glossterm>.
../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

+  <glossentry id="glossary-publisher">
+   <glossterm>Publisher node</glossterm>
+   <glossdef>
+    <para>
+      A node where publication is defined for
+      <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+      It replicates a set of changes from a table or a group of tables in
+      publication to the subscriber node.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="logical-replication-publication"/>.
+    </para>
+   </glossdef>
+  </glossentry>
+

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.
+  <glossentry id="glossary-subscriber">
+   <glossterm>Subscriber node</glossterm>
+   <glossdef>
+    <para>
+     A node where subscription is defined for
+     <glossterm linkend="glossary-replication">logical replication</glossterm>.
+     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.
+    </para>
+    <para>
+     For more information, see
+     <xref linkend="logical-replication-subscription"/>.
+    </para>
+   </glossdef>
+  </glossentry>

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

Here are some comments for patch v3:

1.
+  <glossentry id="glossary-publication-node">
+   <glossterm>Publication node</glossterm>
+   <glossdef>
+    <para>
+     A <glossterm linkend="glossary-instance">node</glossterm> where a
+     <glossterm
linkend="glossary-publication">publication</glossterm> is defined
+     for <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+

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

~~

2.
+  <glossentry id="glossary-subscription-node">
+   <glossterm>Subscription node</glossterm>
+   <glossdef>
+    <para>
+     A <glossterm linkend="glossary-instance">node</glossterm> where a
+     <glossterm
linkend="glossary-subscription">subscription</glossterm> is defined
+     for <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+

(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

1.
+  <glossentry id="glossary-publication-node">
+   <glossterm>Publication node</glossterm>
+   <glossdef>
+    <para>
+     A <glossterm linkend="glossary-instance">node</glossterm> where a
+     <glossterm
linkend="glossary-publication">publication</glossterm> is defined
+     for <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+

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

~~

2.
+  <glossentry id="glossary-subscription-node">
+   <glossterm>Subscription node</glossterm>
+   <glossdef>
+    <para>
+     A <glossterm linkend="glossary-instance">node</glossterm> where a
+     <glossterm
linkend="glossary-subscription">subscription</glossterm> is defined
+     for <glossterm linkend="glossary-replication">logical
replication</glossterm>.
+    </para>
+   </glossdef>
+  </glossentry>
+

(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

Hi, the patch v4 LGTM.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

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
<https://www.postgresql.org/docs/current/logical-replication-subscription.html&gt;
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 <smithpb2250@gmail.com> wrote:

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

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 <glossterm>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/

On Thu, Mar 14, 2024 at 7:51 PM Alvaro Herrera <alvherre@alvh.no-ip.org> 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 <glossterm>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]: https://www.postgresql.org/docs/current/logical-replication-subscription.html
database.

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

--
With Regards,
Amit Kapila.

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/