From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Thom Brown <thom@linux.com>
To: pgsql-docs@lists.postgresql.org
Subject: Re: Fixes for create subscription page
Date: Wed, 07 Oct 2026 16:32:34 +0200
Message-ID: <5e6ffc6412da6fb68718a4c123e875f8d423dcad.camel@cybertec.at> (raw)
In-Reply-To: <CAA-aLv4tAU6yY=OUa7Fisy+Kk_4bS-mJreQUJjU-HhJOA9TB-w@mail.gmail.com>
References: <CAA-aLv4tAU6yY=OUa7Fisy+Kk_4bS-mJreQUJjU-HhJOA9TB-w@mail.gmail.com>
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients from your mail client; the link fills in
the headers below: reply via email
Some clients, webmail especially, drop In-Reply-To and References from
a link, and the reply then starts a new thread: use the mbox below.
To: pgsql-docs@postgresql.org
Cc: laurenz.albe@cybertec.at, thom@linux.com
Subject: Re: Fixes for create subscription page
In-Reply-To: <5e6ffc6412da6fb68718a4c123e875f8d423dcad.camel@cybertec.at>
References: <CAA-aLv4tAU6yY=OUa7Fisy+Kk_4bS-mJreQUJjU-HhJOA9TB-w@mail.gmail.com> <5e6ffc6412da6fb68718a4c123e875f8d423dcad.camel@cybertec.at>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox