Re: Documentation patch for ALTER SUBSCRIPTION

On Wed, Feb 5, 2020 at 8:44 AM David Christensen <david(at)endpoint(dot)com> wrote:
>
> >> On Feb 4, 2020, at 8:45 PM, Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
> >>
> >> On Fri, Jan 24, 2020 at 2:05 AM David Christensen <david(at)endpoint(dot)com> wrote:
> >> Greetings,
> >> Enclosed find a documentation patch that clarifies the behavior of ALTER SUBSCRIPTION … REFRESH PUBLICATION with new tables; I ran into a situation today where the docs were not clear that existing tables would not be re-copied, so remedying this situation.
> >
> > It seems this is already covered in REFRESH PUBLICATION, see "This
> > will start replication of tables that were added to the subscribed-to
> > publications since the last invocation of REFRESH PUBLICATION or since
> > CREATE SUBSCRIPTION.". As far as I understand, this text explains the
> > situation you were facing. Can you explain why the text quoted by me
> > is not sufficient?
>
> Hi Amit,
>
> From several reads of the text it was not explicitly clear to me that when you issued the copy_data that it would not effectively recopy existing tables in the existing publication, which I had been trying to confirm was not the case prior to running a refresh operation. I had to resort to reviewing the source code to get the answer I was looking for.
>
> If you are already familiar with the operation under the hood I am sure the ambiguity is not there but since I was recently confused by this I wanted to be more explicit in a way that would have helped me answer my original question.
>

It is possible that one might not understand how this option works by
reading the already existing text in docs, but I think writing in a
different language the same thing also doesn't seem advisable. I
think if we want to explain it better, then maybe a succinct example
at the end of the page might be helpful.

--
With Regards,
Amit Kapila.
EnterpriseDB: http://www.enterprisedb.com