Re: Documentation patch for ALTER SUBSCRIPTION - Mailing list pgsql-hackers

From Alvaro Herrera
Subject Re: Documentation patch for ALTER SUBSCRIPTION
Date
Msg-id 20200205135610.GA9721@alvherre.pgsql
Whole thread Raw
In response to Re: Documentation patch for ALTER SUBSCRIPTION  (Amit Kapila <amit.kapila16@gmail.com>)
Responses Re: Documentation patch for ALTER SUBSCRIPTION
List pgsql-hackers
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



pgsql-hackers by date:

Previous
From: Kirill Bychik
Date:
Subject: WAL usage calculation patch
Next
From: Robert Haas
Date:
Subject: Re: [Proposal] Global temporary tables