Doc: Change optional parameters grouping in Create Subscription.

Amit Kapila · Amit Kapila · commit fee1040fe330 · 2021-09-13T08:29:10.000+05:30
The subscription parameters are rearranged into two groups: a) those that control what happens during Create Subscription b) those that control the replication behavior This makes the documentation of Create Subscription easier to follow. Author: Peter Smith Reviewed-by: Amit Kapila Discussion: https://postgr.es/m/CAHut+PtPJDSOxtuMGpO2yDrRPKxcYGL4n7HqJP9HernZE=Cj+g@mail.gmail.com
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
@@ -92,17 +92,39 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
     <term><literal>WITH ( <replaceable class="parameter">subscription_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
-      This clause specifies optional parameters for a subscription.  The
-      following parameters are supported:
+      This clause specifies optional parameters for a subscription.
+     </para>
+
+     <para>
+      The following parameters control what happens during subscription creation:
 
       <variablelist>
+
        <varlistentry>
-        <term><literal>copy_data</literal> (<type>boolean</type>)</term>
+        <term><literal>connect</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>.
+          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
+          <literal>copy_data</literal> to <literal>false</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
+          after you enable the subscription nothing will be replicated.
+          It is required to run
+          <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
+          for tables to be subscribed.
          </para>
         </listitem>
        </varlistentry>
@@ -146,38 +168,13 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
          </para>
         </listitem>
        </varlistentry>
+      </variablelist>
+     </para>
 
-       <varlistentry>
-        <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
-        <listitem>
-         <para>
-          The value of this parameter overrides the
-          <xref linkend="guc-synchronous-commit"/> setting within this
-          subscription's apply worker processes.  The default value
-          is <literal>off</literal>.
-         </para>
-
-         <para>
-          It is safe to use <literal>off</literal> for logical replication:
-          If the subscriber loses transactions because of missing
-          synchronization, the data will be sent again from the publisher.
-         </para>
+     <para>
+      The following parameters control the replication behavior:
 
-         <para>
-          A different setting might be appropriate when doing synchronous
-          logical replication.  The logical replication workers report the
-          positions of writes and flushes to the publisher, and when using
-          synchronous replication, the publisher will wait for the actual
-          flush.  This means that setting
-          <literal>synchronous_commit</literal> for the subscriber to
-          <literal>off</literal> when the subscription is used for
-          synchronous replication might increase the latency for
-          <command>COMMIT</command> on the publisher.  In this scenario, it
-          can be advantageous to set <literal>synchronous_commit</literal>
-          to <literal>local</literal> or higher.
-         </para>
-        </listitem>
-       </varlistentry>
+      <variablelist>
 
        <varlistentry>
         <term><literal>binary</literal> (<type>boolean</type>)</term>
@@ -201,33 +198,16 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
        </varlistentry>
 
        <varlistentry>
-        <term><literal>connect</literal> (<type>boolean</type>)</term>
+        <term><literal>copy_data</literal> (<type>boolean</type>)</term>
         <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
-          <literal>copy_data</literal> to <literal>false</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
-          after you enable the subscription nothing will be replicated.
-          It is required to run
-          <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order
-          for tables to be subscribed.
+          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>.
          </para>
         </listitem>
        </varlistentry>
+
        <varlistentry>
         <term><literal>streaming</literal> (<type>boolean</type>)</term>
         <listitem>
@@ -237,9 +217,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
           are fully decoded on the publisher, and only then sent to the
           subscriber as a whole.
          </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term><literal>synchronous_commit</literal> (<type>enum</type>)</term>
+        <listitem>
+         <para>
+          The value of this parameter overrides the
+          <xref linkend="guc-synchronous-commit"/> setting within this
+          subscription's apply worker processes.  The default value
+          is <literal>off</literal>.
+         </para>
+
+         <para>
+          It is safe to use <literal>off</literal> for logical replication:
+          If the subscriber loses transactions because of missing
+          synchronization, the data will be sent again from the publisher.
+         </para>
 
+         <para>
+          A different setting might be appropriate when doing synchronous
+          logical replication.  The logical replication workers report the
+          positions of writes and flushes to the publisher, and when using
+          synchronous replication, the publisher will wait for the actual
+          flush.  This means that setting
+          <literal>synchronous_commit</literal> for the subscriber to
+          <literal>off</literal> when the subscription is used for
+          synchronous replication might increase the latency for
+          <command>COMMIT</command> on the publisher.  In this scenario, it
+          can be advantageous to set <literal>synchronous_commit</literal>
+          to <literal>local</literal> or higher.
+         </para>
         </listitem>
        </varlistentry>
+
        <varlistentry>
         <term><literal>two_phase</literal> (<type>boolean</type>)</term>
         <listitem>
@@ -266,7 +278,9 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
 
         </listitem>
        </varlistentry>
-      </variablelist></para>
+      </variablelist>
+     </para>
+
     </listitem>
    </varlistentry>
   </variablelist>
