Re: create subscription - improved warning message

On 2022-Oct-11, Peter Smith wrote:

> On Tue, Oct 11, 2022 at 2:46 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
> >
> > On Mon, Oct 10, 2022 at 8:14 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> > > It feels a little strange to me that we describe two steps rather
> > > vaguely and then give exact SQL for the third step. How about,
> > > say,
> > >
> > > HINT: To initiate replication, you must manually create the
> > > replication slot, enable the subscription, and refresh the
> > > subscription.
> >
> > LGTM.
>
> PSA patch v3-0001 where the message/hint is worded as suggested above

LGTM.

> > BTW, do we want to slightly adjust the documentation for the
> > connect option on CREATE SUBSCRIPTION page [1]? It says: "Since no
> > connection is made when this option is false, no tables are
> > subscribed, and so after you enable the subscription nothing will be
> > replicated. You will need to then run ALTER SUBSCRIPTION ... REFRESH
> > PUBLICATION for tables to be subscribed."
> >
> > It doesn't say anything about manually creating the slot and probably
> > the wording can be made similar.
>
> PSA patch v3-0002 which changes CREATE SUBSCRIPTION pgdocs to use the
> same wording as in the HINT message.

I think we want the documentation to explain in much more detail what is
meant. Users are going to need some help in determining which commands
to run for each of the step mentioned in the hint, so I don't think we
want the docs to say the same thing as the hint. How does the user know
the name of the slot, what options to use, what are the commands to run
afterwards. So I think we should aim to *expand* that text, not reduce
it.

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/