Horton

Thread

Commits

  1. ALTER SUBSCRIPTION / REFRESH docs: explain copy_data

  1. Documentation patch for ALTER SUBSCRIPTION

    David Christensen <david@endpoint.com> — 2020-01-23T20:35:11Z

    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.

Should apply back to Pg 10.

Best,

David

  2. Re: Documentation patch for ALTER SUBSCRIPTION

    Amit Kapila <amit.kapila16@gmail.com> — 2020-02-05T02:45:41Z

    On Fri, Jan 24, 2020 at 2:05 AM David Christensen <david@endpoint.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?

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

  3. Re: Documentation patch for ALTER SUBSCRIPTION

    David Christensen <david@endpoint.com> — 2020-02-05T03:14:30Z

    >> On Feb 4, 2020, at 8:45 PM, Amit Kapila <amit.kapila16@gmail.com> wrote:
>> 
>> On Fri, Jan 24, 2020 at 2:05 AM David Christensen <david@endpoint.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. 

Best,

David

  4. Re: Documentation patch for ALTER SUBSCRIPTION

    Amit Kapila <amit.kapila16@gmail.com> — 2020-02-05T08:19:20Z

    On Wed, Feb 5, 2020 at 8:44 AM David Christensen <david@endpoint.com> wrote:
>
> >> On Feb 4, 2020, at 8:45 PM, Amit Kapila <amit.kapila16@gmail.com> wrote:
> >>
> >> On Fri, Jan 24, 2020 at 2:05 AM David Christensen <david@endpoint.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

  5. Re: Documentation patch for ALTER SUBSCRIPTION

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-02-05T13:56:10Z

    On 2020-Feb-05, Amit Kapila wrote:

> 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.

For reference, the complete varlistentry is:

    <term><literal>REFRESH PUBLICATION</literal></term>
    <listitem>
     <para>
      Fetch missing table information from publisher.  This will start
      replication of tables that were added to the subscribed-to publications
      since the last invocation of <command>REFRESH PUBLICATION</command> or
      since <command>CREATE SUBSCRIPTION</command>. <!-- [2] -->
     </para>

     <para>
      <replaceable>refresh_option</replaceable> specifies additional options for the
      refresh operation.  The supported options are:

      <variablelist>
       <varlistentry>
        <term><literal>copy_data</literal> (<type>boolean</type>)</term>
        <listitem>
         <para>
          Specifies whether the existing data in the publications that are
          being subscribed to should be copied once the replication starts.
          The default is <literal>true</literal>. <!-- [1] -->
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </listitem>

I tend to agree with David that this is ambiguous enough to warrant a
few words.  Maybe his proposed wording is too verbose; how about just
adding "(Previously subscribed tables are not copied.)" where the [1]
appears?  Alternatively, we could add "Tables that were already present
in the subscription are not modified in any way." where [2] appears, but
that seems less clear to me.

An example would not be bad if it showed that existing data is not
copied.  But examples are actually just syntactical examples, so you'd
have to resort to a comment explaining that existing tables are not
copied by the shown syntax.  You might as well just add the words in the
reference docs ...

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

  6. Re: Documentation patch for ALTER SUBSCRIPTION

    David Christensen <david@endpoint.com> — 2020-02-05T14:35:30Z

    > On Feb 5, 2020, at 7:56 AM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote:
> 
> On 2020-Feb-05, Amit Kapila wrote:
> 
>> 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.
> 
> For reference, the complete varlistentry is:
> 
>    <term><literal>REFRESH PUBLICATION</literal></term>
>    <listitem>
>     <para>
>      Fetch missing table information from publisher.  This will start
>      replication of tables that were added to the subscribed-to publications
>      since the last invocation of <command>REFRESH PUBLICATION</command> or
>      since <command>CREATE SUBSCRIPTION</command>. <!-- [2] -->
>     </para>
> 
>     <para>
>      <replaceable>refresh_option</replaceable> specifies additional options for the
>      refresh operation.  The supported options are:
> 
>      <variablelist>
>       <varlistentry>
>        <term><literal>copy_data</literal> (<type>boolean</type>)</term>
>        <listitem>
>         <para>
>          Specifies whether the existing data in the publications that are
>          being subscribed to should be copied once the replication starts.
>          The default is <literal>true</literal>. <!-- [1] -->
>         </para>
>        </listitem>
>       </varlistentry>
>      </variablelist>
>     </para>
>    </listitem>
> 
> I tend to agree with David that this is ambiguous enough to warrant a
> few words.  Maybe his proposed wording is too verbose; how about just
> adding "(Previously subscribed tables are not copied.)" where the [1]
> appears?  Alternatively, we could add "Tables that were already present
> in the subscription are not modified in any way." where [2] appears, but
> that seems less clear to me.
> 
> An example would not be bad if it showed that existing data is not
> copied.  But examples are actually just syntactical examples, so you'd
> have to resort to a comment explaining that existing tables are not
> copied by the shown syntax.  You might as well just add the words in the
> reference docs …

I would be happy with the suggestion [1]; it would have clarified my specific question.

Thanks,

David

  7. Re: Documentation patch for ALTER SUBSCRIPTION

    Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-02-05T18:08:16Z

    OK, pushed that.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services