Doc: improve documentation of CREATE/ALTER SUBSCRIPTION.

Improve the descriptions of some options.  Fix sloppy grammar and markup.

Peter Smith and Tom Lane

Discussion: https://postgr.es/m/CAHut+PtPJDSOxtuMGpO2yDrRPKxcYGL4n7HqJP9HernZE=Cj+g@mail.gmail.com

diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 835be0d2a433d08ba20787562d339f06f971c7a9..9e51395a612fa5407c7ce5e4b7e342cad1c5061b 100644 (file)
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -50,14 +50,14 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    (Currently, all subscription owners must be superusers, so the owner checks
    will be bypassed in practice.  But this might change in the future.)
   </para>
-  
+
   <para>
    When refreshing a publication we remove the relations that are no longer
    part of the publication and we also remove the table synchronization slots
    if there are any. It is necessary to remove these slots so that the resources
    allocated for the subscription on the remote host are released. If due to
    network breakdown or some other error, <productname>PostgreSQL</productname>
-   is unable to remove the slots, an ERROR will be reported. To proceed in this
+   is unable to remove the slots, an error will be reported. To proceed in this
    situation, the user either needs to retry the operation or disassociate the
    slot from the subscription and drop the subscription as explained in
    <xref linkend="sql-dropsubscription"/>.
@@ -69,9 +69,11 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
    option as true cannot be executed inside a transaction block.
 
    These commands also cannot be executed when the subscription has
-   <literal>two_phase</literal> commit enabled, unless <literal>copy_data = false</literal>.
-   See column <literal>subtwophasestate</literal> of
-   <xref linkend="catalog-pg-subscription"/> to know the actual two-phase state.
+   <literal>two_phase</literal> commit enabled,
+   unless <literal>copy_data</literal> is <literal>false</literal>.
+   See column <structfield>subtwophasestate</structfield> of
+   <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
+   to know the actual two-phase state.
   </para>
  </refsect1>
 
@@ -92,7 +94,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
-      This clause alters the connection property originally set by
+      This clause replaces the connection string originally set by
       <xref linkend="sql-createsubscription"/>.  See there for more
       information.
      </para>
@@ -105,7 +107,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     <term><literal>DROP PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
     <listitem>
      <para>
-      Changes the list of subscribed publications.  <literal>SET</literal>
+      These forms change the list of subscribed publications.
+      <literal>SET</literal>
       replaces the entire list of publications with a new list,
       <literal>ADD</literal> adds additional publications to the list of
       publications, and <literal>DROP</literal> removes the publications from
@@ -143,8 +146,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
      <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>.
+      since <command>CREATE SUBSCRIPTION</command> or
+      the last invocation of <command>REFRESH PUBLICATION</command>.
      </para>
 
      <para>
@@ -156,9 +159,9 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
         <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>.  (Previously subscribed
+          Specifies whether to copy pre-existing data in the publications
+          that are being subscribed to when the replication starts.
+          The default is <literal>true</literal>.  (Previously-subscribed
           tables are not copied.)
          </para>
         </listitem>
@@ -171,8 +174,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     <term><literal>ENABLE</literal></term>
     <listitem>
      <para>
-      Enables the previously disabled subscription, starting the logical
-      replication worker at the end of transaction.
+      Enables a previously disabled subscription, starting the logical
+      replication worker at the end of the transaction.
      </para>
     </listitem>
    </varlistentry>
@@ -181,8 +184,8 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
     <term><literal>DISABLE</literal></term>
     <listitem>
      <para>
-      Disables the running subscription, stopping the logical replication
-      worker at the end of transaction.
+      Disables a running subscription, stopping the logical replication
+      worker at the end of the transaction.
      </para>
     </listitem>
    </varlistentry>

diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 04a0fd7fba37e5723ed6f438a6a2b05602d66c59..990a41f1a1ba716564f4152ce3a609a333d329ba 100644 (file)
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -32,20 +32,21 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
   <title>Description</title>
 
   <para>
-   <command>CREATE SUBSCRIPTION</command> adds a new subscription for the
-   current database.  The subscription name must be distinct from the name of
-   any existing subscription in the database.
+   <command>CREATE SUBSCRIPTION</command> adds a new logical-replication
+   subscription.  The subscription name must be distinct from the name of
+   any existing subscription in the current database.
   </para>
 
   <para>
-   The subscription represents a replication connection to the publisher.  As
-   such this command does not only add definitions in the local catalogs but
-   also creates a replication slot on the publisher.
+   A subscription represents a replication connection to the publisher.
+   Hence, in addition to adding definitions in the local catalogs, this
+   command normally creates a replication slot on the publisher.
   </para>
 
   <para>
    A logical replication worker will be started to replicate data for the new
-   subscription at the commit of the transaction where this command is run.
+   subscription at the commit of the transaction where this command is run,
+   unless the subscription is initially disabled.
   </para>
 
   <para>
@@ -73,14 +74,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     <term><literal>CONNECTION '<replaceable class="parameter">conninfo</replaceable>'</literal></term>
     <listitem>
      <para>
-      The connection string to the publisher.  For details
-      see <xref linkend="libpq-connstring"/>.
+      The <application>libpq</application> connection string defining how
+      to connect to the publisher database.  For details see
+      <xref linkend="libpq-connstring"/>.
      </para>
     </listitem>
    </varlistentry>
 
    <varlistentry>
-    <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable></literal></term>
+    <term><literal>PUBLICATION <replaceable class="parameter">publication_name</replaceable> [, ...]</literal></term>
     <listitem>
      <para>
       Names of the publications on the publisher to subscribe to.
@@ -105,25 +107,23 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         <listitem>
          <para>
           Specifies whether the <command>CREATE SUBSCRIPTION</command>
-          should connect to the publisher at all.  Setting this to
-          <literal>false</literal> will change default values of
-          <literal>enabled</literal>, <literal>create_slot</literal> and
+          command should connect to the publisher at all.  The default
+          is <literal>true</literal>.  Setting this to
+          <literal>false</literal> will force the values of
+          <literal>create_slot</literal>, <literal>enabled</literal> and
           <literal>copy_data</literal> to <literal>false</literal>.
+          (You cannot combine setting <literal>connect</literal>
+          to <literal>false</literal> with
+          setting <literal>create_slot</literal>, <literal>enabled</literal>,
+          or <literal>copy_data</literal> to <literal>true</literal>.)
          </para>
 
          <para>
-          It is not allowed to combine <literal>connect</literal> set to
-          <literal>false</literal> and <literal>enabled</literal>,
-          <literal>create_slot</literal>, or <literal>copy_data</literal>
-          set to <literal>true</literal>.
-         </para>
-
-         <para>
-          Since no connection is made when this option is set
-          to <literal>false</literal>, the tables are not subscribed, and so
+          Since no connection is made when this option is
+          <literal>false</literal>, no tables are subscribed, and so
           after you enable the subscription nothing will be replicated.
-          It is required to run
-          <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+          You will need to then run
+          <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal>
           for tables to be subscribed.
          </para>
         </listitem>
@@ -135,6 +135,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
          <para>
           Specifies whether the command should create the replication slot on
           the publisher.  The default is <literal>true</literal>.
+          If set to <literal>false</literal>, you are responsible for
+          creating the publisher's slot in some other way.
          </para>
         </listitem>
        </varlistentry>
@@ -143,8 +145,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         <term><literal>enabled</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
-          Specifies whether the subscription should be actively replicating,
-          or whether it should be just setup but not started yet.  The default
+          Specifies whether the subscription should be actively replicating
+          or whether it should just be set up but not started yet.  The default
           is <literal>true</literal>.
          </para>
         </listitem>
@@ -154,15 +156,15 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         <term><literal>slot_name</literal> (<type>string</type>)</term>
         <listitem>
          <para>
-          Name of the replication slot to use.  The default behavior is to
-          use the name of the subscription for the slot name.
+          Name of the publisher's replication slot to use.  The default is
+          to use the name of the subscription for the slot name.
          </para>
 
          <para>
-          When <literal>slot_name</literal> is set to
-          <literal>NONE</literal>, there will be no replication slot
-          associated with the subscription.  This can be used if the
-          replication slot will be created later manually.  Such
+          Setting <literal>slot_name</literal> to <literal>NONE</literal>
+          means there will be no replication slot
+          associated with the subscription.  Use this when you will be
+          creating the replication slot later manually.  Such
           subscriptions must also have both <literal>enabled</literal> and
           <literal>create_slot</literal> set to <literal>false</literal>.
          </para>
@@ -172,7 +174,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
      </para>
 
      <para>
-      The following parameters control the replication behavior:
+      The following parameters control the subscription's replication
+      behavior after it has been created:
 
       <variablelist>
 
@@ -183,14 +186,14 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
           Specifies whether the subscription will request the publisher to
           send the data in binary format (as opposed to text).
           The default is <literal>false</literal>.
-          Even when this option is enabled, only data types that have
+          Even when this option is enabled, only data types having
           binary send and receive functions will be transferred in binary.
          </para>
 
          <para>
-          When doing cross-version replication, it could happen that the
+          When doing cross-version replication, it could be that the
           publisher has a binary send function for some data type, but the
-          subscriber lacks a binary receive function for the type.  In
+          subscriber lacks a binary receive function for that type.  In
           such a case, data transfer will fail, and
           the <literal>binary</literal> option cannot be used.
          </para>
@@ -201,8 +204,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         <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.
+          Specifies whether to copy pre-existing data in the publications
+          that are being subscribed to when the replication starts.
           The default is <literal>true</literal>.
          </para>
         </listitem>
@@ -212,9 +215,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
         <term><literal>streaming</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
-          Specifies whether streaming of in-progress transactions should
-          be enabled for this subscription.  By default, all transactions
-          are fully decoded on the publisher, and only then sent to the
+          Specifies whether to enable streaming of in-progress transactions
+          for this subscription.  By default, all transactions
+          are fully decoded on the publisher and only then sent to the
           subscriber as a whole.
          </para>
         </listitem>
@@ -261,18 +264,22 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
          </para>
 
          <para>
-          When two-phase commit is enabled then the decoded transactions are sent
-          to the subscriber on the PREPARE TRANSACTION. By default, the transaction
-          prepared on the publisher is decoded as a normal transaction at commit.
+          When two-phase commit is enabled, prepared transactions are sent
+          to the subscriber at the time of <command>PREPARE
+          TRANSACTION</command>, and are processed as two-phase
+          transactions on the subscriber too.  Otherwise, prepared
+          transactions are sent to the subscriber only when committed, and
+          are then processed immediately by the subscriber.
          </para>
 
          <para>
-          The two-phase commit implementation requires that the replication has
-          successfully passed the initial table synchronization phase. This means
-          even when two_phase is enabled for the subscription, the internal
-          two-phase state remains temporarily "pending" until the initialization
-          phase is completed. See column
-          <literal>subtwophasestate</literal> of <xref linkend="catalog-pg-subscription"/>
+          The implementation of two-phase commit requires that replication
+          has successfully finished the initial table synchronization
+          phase. So even when <literal>two_phase</literal> is enabled for a
+          subscription, the internal two-phase state remains
+          temporarily <quote>pending</quote> until the initialization phase
+          completes. See column <structfield>subtwophasestate</structfield>
+          of <link linkend="catalog-pg-subscription"><structname>pg_subscription</structname></link>
           to know the actual two-phase state.
          </para>