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

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