Re: Fixes for create subscription page - Mailing list pgsql-docs

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