Fixes for create subscription page

On Wed, 2026-10-07 at 11:58 +0100, Thom Brown wrote:

I was looking through the new options for create subscription, and
found issues with some of the text, so I reviewed the whole page.
Attached are my proposed changes.

Thanks!

I agree with most of your changes, but have doubts about a few:

--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml

<para>
Since no connection is made when this option is
-          <literal>false</literal>, no tables and sequences are subscribed. To
+          <literal>false</literal>, no tables or sequences are subscribed. To

Hm. I think "and" would be the better conjunction here (although "or"
is not really wrong).

send and receive functions will be transferred in binary. Note that
the initial synchronization requires all data types to have binary
-          send and receive functions, otherwise the synchronization will fail
+          send and receive functions, otherwise synchronization will fail
(see <xref linkend="sql-createtype"/> for more about send/receive
functions). This parameter has no effect for sequences.

My feeling is that the article is correct here (disclaimer: I am not
a native speaker).

-           overall system performance. This option provides minimal performance
+           overall system performance. This option incurs minimal performance
overhead when applied appropriately. The following scenarios illustrate

I see your point, although you could argue that "minimal performance overhead"
is a feature, and you provide a feature rather than incur it.
How about "provides reduced performance overhead"?

c. Read-Only Subscribers:
In configurations involving single or multiple publisher nodes
performing concurrent write operations, read-only subscriber nodes may
-           replicate changes without seeing a performance impact if it does index
-           scan. However, if the subscriber is impacted due to replication lag or
-           scan performance (say due to sequential scans), it needs to follow one
+           replicate changes without performance degradation if performing index
+           scans. However, if the subscriber is affected due to replication lag or
+           scan performance (e.g. due to sequential scans), it needs to follow one
of the two previous strategies to distribute the workload on the
subscriber.

Your change clearly is an improvement (the original was grammatically wrong).
But "subscriber nodes may replicate changes without performance degradation
if performing index scans" still feels less than perfect. Shouldn't it be
"when performing index scans" or "when they perform index scans" or - even
better - "during index scans"?

See <xref linkend="logical-replication-security"/> for details on
how to configure access control between the subscription and the
-   publication instance.
+   publisher instance.

I think you should be consistent: "between the subscriber and the publisher
instance". But perhaps it would be best to retain the original, because
"publication" and "subscription" are the names of the PostgreSQL objects
involved. How about "between the database with the subscription and the
database with the publication"?

Yours,
Laurenz Albe

On Wed, 7 Oct 2026 at 15:32, Laurenz Albe <laurenz.albe@cybertec.at> wrote:

On Wed, 2026-10-07 at 11:58 +0100, Thom Brown wrote:

I was looking through the new options for create subscription, and
found issues with some of the text, so I reviewed the whole page.
Attached are my proposed changes.

Thanks!

I agree with most of your changes, but have doubts about a few:

--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml

<para>
Since no connection is made when this option is
-          <literal>false</literal>, no tables and sequences are subscribed. To
+          <literal>false</literal>, no tables or sequences are subscribed. To

Hm. I think "and" would be the better conjunction here (although "or"
is not really wrong).

I think an "or" after a "no" doesn't read well. I think, in order to
use "and", it would have to read "tables and sequences are not
subscribed."

send and receive functions will be transferred in binary. Note that
the initial synchronization requires all data types to have binary
-          send and receive functions, otherwise the synchronization will fail
+          send and receive functions, otherwise synchronization will fail
(see <xref linkend="sql-createtype"/> for more about send/receive
functions). This parameter has no effect for sequences.

My feeling is that the article is correct here (disclaimer: I am not
a native speaker).

I guess if we're specifically referring to the initial synchronisation
earlier in the sentence, my correction isn't an improvement.

-           overall system performance. This option provides minimal performance
+           overall system performance. This option incurs minimal performance
overhead when applied appropriately. The following scenarios illustrate

I see your point, although you could argue that "minimal performance overhead"
is a feature, and you provide a feature rather than incur it.
How about "provides reduced performance overhead"?

I'm not keen on "providing" any overhead, but we could just be
completely neutral about it:

"This option has minimal performance overhead when applied appropriately."

c. Read-Only Subscribers:
In configurations involving single or multiple publisher nodes
performing concurrent write operations, read-only subscriber nodes may
-           replicate changes without seeing a performance impact if it does index
-           scan. However, if the subscriber is impacted due to replication lag or
-           scan performance (say due to sequential scans), it needs to follow one
+           replicate changes without performance degradation if performing index
+           scans. However, if the subscriber is affected due to replication lag or
+           scan performance (e.g. due to sequential scans), it needs to follow one
of the two previous strategies to distribute the workload on the
subscriber.

Your change clearly is an improvement (the original was grammatically wrong).
But "subscriber nodes may replicate changes without performance degradation
if performing index scans" still feels less than perfect. Shouldn't it be
"when performing index scans" or "when they perform index scans" or - even
better - "during index scans"?

Yeah, fair enough. I would avoid "during index scans" as it makes it
about timing. But "when performing index scans" sounds right.

See <xref linkend="logical-replication-security"/> for details on
how to configure access control between the subscription and the
-   publication instance.
+   publisher instance.

I think you should be consistent: "between the subscriber and the publisher
instance". But perhaps it would be best to retain the original, because
"publication" and "subscription" are the names of the PostgreSQL objects
involved. How about "between the database with the subscription and the
database with the publication"?

Yeah, point taken. Maybe leave that as it is.

Thanks

Thom

On Wed, 2026-10-07 at 17:03 +0100, Thom Brown wrote:

On Wed, 7 Oct 2026 at 15:32, Laurenz Albe <laurenz.albe@cybertec.at> wrote:

On Wed, 2026-10-07 at 11:58 +0100, Thom Brown wrote:

I was looking through the new options for create subscription, and
found issues with some of the text, so I reviewed the whole page.
Attached are my proposed changes.

--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml

<para>
Since no connection is made when this option is
-          <literal>false</literal>, no tables and sequences are subscribed. To
+          <literal>false</literal>, no tables or sequences are subscribed. To

Hm. I think "and" would be the better conjunction here (although "or"
is not really wrong).

I think an "or" after a "no" doesn't read well. I think, in order to
use "and", it would have to read "tables and sequences are not
subscribed."

That sounds good to me.

send and receive functions will be transferred in binary. Note that
the initial synchronization requires all data types to have binary
-          send and receive functions, otherwise the synchronization will fail
+          send and receive functions, otherwise synchronization will fail
(see <xref linkend="sql-createtype"/> for more about send/receive
functions). This parameter has no effect for sequences.

My feeling is that the article is correct here (disclaimer: I am not
a native speaker).

I guess if we're specifically referring to the initial synchronisation
earlier in the sentence, my correction isn't an improvement.

Good, we are in agreement then.

-           overall system performance. This option provides minimal performance
+           overall system performance. This option incurs minimal performance
overhead when applied appropriately. The following scenarios illustrate

I see your point, although you could argue that "minimal performance overhead"
is a feature, and you provide a feature rather than incur it.
How about "provides reduced performance overhead"?

I'm not keen on "providing" any overhead, but we could just be
completely neutral about it:

"This option has minimal performance overhead when applied appropriately."

Well, picking nits, the option itself *is* not a minimal overhead, using it causes
minimal overhead. So perhaps

If this option is applied appropriately, the performance overhead will be minimal.

c. Read-Only Subscribers:
In configurations involving single or multiple publisher nodes
performing concurrent write operations, read-only subscriber nodes may
-           replicate changes without seeing a performance impact if it does index
-           scan. However, if the subscriber is impacted due to replication lag or
-           scan performance (say due to sequential scans), it needs to follow one
+           replicate changes without performance degradation if performing index
+           scans. However, if the subscriber is affected due to replication lag or
+           scan performance (e.g. due to sequential scans), it needs to follow one
of the two previous strategies to distribute the workload on the
subscriber.

Your change clearly is an improvement (the original was grammatically wrong).
But "subscriber nodes may replicate changes without performance degradation
if performing index scans" still feels less than perfect. Shouldn't it be
"when performing index scans" or "when they perform index scans" or - even
better - "during index scans"?

Yeah, fair enough. I would avoid "during index scans" as it makes it
about timing. But "when performing index scans" sounds right.

Great.

See <xref linkend="logical-replication-security"/> for details on
how to configure access control between the subscription and the
-   publication instance.
+   publisher instance.

I think you should be consistent: "between the subscriber and the publisher
instance". But perhaps it would be best to retain the original, because
"publication" and "subscription" are the names of the PostgreSQL objects
involved. How about "between the database with the subscription and the
database with the publication"?

Yeah, point taken. Maybe leave that as it is.

Fine!

Yours,
Laurenz Albe

Hi,

I've read the initial patch and the discussion so far.

FWIW, I think the patch with the changes discussed in this thread
looks good to me.

(I might have worded a couple of them differently, but that's only
personal preference, so I won't muddle your thread with noise)

Let's see an updated patch.

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

Hi,

On Wed, Oct 7, 2026 at 3:59 AM Thom Brown <thom@linux.com> wrote:

Hi,

I was looking through the new options for create subscription, and
found issues with some of the text, so I reviewed the whole page.
Attached are my proposed changes.

Thank you for the patch. The patch overall looks good to me. A one
minor comment:

-          be <literal>pg_conflict_detection</literal> as it is reserved for the
+          be <literal>pg_conflict_detection</literal> as it is reserved for
           conflict detection.

There are other places where we can apply this change. In func-admin.sgml:

The new slot name cannot be <literal>pg_conflict_detection</literal>,
as it is reserved for the conflict detection.

and

<literal>pg_conflict_detection</literal> as it is reserved for
the conflict detection. The copied logical slot starts from the same

In protocol.sgml:

The name cannot be <literal>pg_conflict_detection</literal> as it
is reserved for the conflict detection.

I think we can backpatch it to v19, where most of the touched text was
added. The remaining changes are wording improvements. What do you
think?

Regards,

--
Masahiko Sawada
Amazon Web Services: https://aws.amazon.com