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

From David Christensen
Subject Re: Documentation patch for ALTER SUBSCRIPTION
Date
Msg-id 7A097672-69DA-4F4A-80FC-CCB143273C51@endpoint.com
Whole thread Raw
In response to Re: Documentation patch for ALTER SUBSCRIPTION  (Alvaro Herrera <alvherre@2ndquadrant.com>)
Responses Re: Documentation patch for ALTER SUBSCRIPTION
List pgsql-hackers
> 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

Attachment

pgsql-hackers by date:

Previous
From: Julien Rouhaud
Date:
Subject: Re: Feature improvement: can we add queryId for pg_catalog.pg_stat_activityview?
Next
From: Tom Lane
Date:
Subject: Re: Is custom MemoryContext prohibited?