DOC: fixed instructions for adding nodes

Author: Liudmila Mantrova

doc/src/sgml/multimaster.sgml

@@ -430,11 +430,11 @@ multimaster.conn_strings = 'dbname=mydb user=myuser host=node1, dbname=mydb user
                            # of connection strings 
                            # to neighbor nodes
 </programlisting>
-<para>The <literal>multimaster.max_nodes</literal> variable defines the maximum cluster size. If you plan to add new nodes to your cluster, the <literal>multimaster.max_nodes</literal> value should exceed the initial number of nodes. In this case, you can add new nodes without restarting <productname>&productname;</productname>.
+<para>The <literal>multimaster.max_nodes</literal> variable defines the maximum cluster size. If you plan to add new nodes to your cluster, the <literal>multimaster.max_nodes</literal> value should exceed the initial number of nodes. In this case, you can add new nodes without restarting <productname>&productname;</productname> until the specified number of nodes is reached.
 </para>
 <para>In most cases, three cluster nodes are enough to ensure high availability. Since the data on all cluster nodes is the same, you do not typically need more than five cluster nodes.
 </para>
-<para>If you would like to change the default connection settings for a cluster node, you can add other <link linkend="libpq-paramkeywords"> connection parameters</link> to the corresponding connection string in the <varname>multimaster.conn_strings</varname> variable. Additionally, you can specify the <literal>arbiter_process</literal> parameter to change the port used by the arbiter process to connect to the nodes. For details, see <xref linkend="multimaster-conn-strings"> and <xref linkend="multimaster-arbiter-port">.</para>
+<para>If you would like to change the default connection settings for a cluster node, you can add other <link linkend="libpq-paramkeywords"> connection parameters</link> to the corresponding connection string in the <varname>multimaster.conn_strings</varname> variable. If you change the default port on which the arbiter process listens for connections, you must specify this port in the <literal>arbiter_port</literal> parameter. For details, see <xref linkend="multimaster-arbiter-port"> and <xref linkend="multimaster-conn-strings">.</para>
                 <important><para>The
                 <literal>multimaster.node_id</literal> variable takes natural
                 numbers starting from 1, without any gaps in numbering.
@@ -480,7 +480,7 @@ CREATE EXTENSION multimaster;</programlisting></para>
       the <structname>mtm.get_cluster_state()</structname> view:
     </para>
     <programlisting>
-SELECT * FROM mtm.get_cluster_state();
+mtm.get_cluster_state();
 </programlisting>
     <para>
       If <literal>liveNodes</literal> is equal to
@@ -611,22 +611,24 @@ SELECT * FROM mtm.get_cluster_state();
       To check node-specific information, use <literal>mtm.get_nodes_state()</literal>:
     </para>
     <programlisting>
-SELECT * FROM mtm.get_nodes_state();
+mtm.get_nodes_state();
 </programlisting>
       <para>To check the status of the whole cluster, use the
       <literal>mtm.get_cluster_state()</literal> view:
     </para>
     <programlisting>
-SELECT * FROM mtm.get_cluster_state();
+mtm.get_cluster_state();
 </programlisting>
       <para>For details on all the returned information, see <xref linkend="multimaster-functions">.
     </para>
   </sect3>
   <sect3 id="multimaster-adding-new-nodes-to-the-cluster">
     <title>Adding New Nodes to the Cluster</title>
+    <para>With the <filename>multimaster</filename> extension, you can add or drop cluster nodes without
+      stopping the database service.
+    </para>
     <para>
-      With multimaster, you can add or drop cluster nodes without a
-      restart. To add a new node, you need to change the cluster
+      To add a new node, you need to change the cluster
       configuration on alive nodes, load all the data to the new node using
       <application>pg_basebackup</application>, and start the node.
     </para>
@@ -637,21 +639,30 @@ SELECT * FROM mtm.get_cluster_state();
       <literal>node4</literal>, follow these steps:
     </para>
     <orderedlist>
+      <listitem>
+        <para>Check whether the current number of cluster nodes has reached the value specified in the
+        <varname>multimaster.max_nodes</varname> variable. If this value is reached, increase
+        the <varname>multimaster.max_nodes</varname> value on each node and restart all nodes.
+        You can restart the nodes one by one, without stopping the database.
+        If the maximum number of nodes is not reached, proceed to the next step. 
+        </para>
+      </listitem>
       <listitem>
         <para>
           Figure out the required connection string to
           access the new node. For example, for the database
           <literal>mydb</literal>, user <literal>myuser</literal>, and
           the new node <literal>node4</literal>, the connection string
-          is <literal>&quot;dbname=mydb user=myuser host=node4&quot;</literal>.
+          can be <literal>&quot;dbname=mydb user=myuser host=node4&quot;</literal>.
+          For details, see <xref linkend="multimaster-conn-strings">.
         </para>
       </listitem>
       <listitem>
         <para>
           In <literal>psql</literal> connected to any alive node, run:
         </para>
         <programlisting>
-SELECT * FROM mtm.add_node('dbname=mydb user=myuser host=node4');
+mtm.add_node('dbname=mydb user=myuser host=node4');
 </programlisting>
         <para>
           This command changes the cluster configuration on all nodes
@@ -757,7 +768,7 @@ SELECT mtm.stop_node(3);
           In <literal>psql</literal> connected to any alive node, create a new replication slot for the disconnected node with the following command:
         </para>
         <programlisting>
-SELECT * FROM mtm.recover_node(2);
+mtm.recover_node(2);
 </programlisting>
 <para>where 2 is the ID of the disconnected node specified in the <varname>multimaster.node_id</varname> variable.</para>
       </listitem>
@@ -814,19 +825,18 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
     Connection strings must appear in the order of the node IDs
     specified in the <varname>multimaster.node_id</varname> variable.
     Connection string for the i-th node must be on the i-th position.
-    You can also specify a
-    custom port for the arbiter to listen on using the <literal>arbiter_port</literal>
-    parameter. The provided value must be the same as the <varname>multimaster.arbiter_port</varname>
-    value specified for this node.
+    If you specify a custom port in the <varname>multimaster.arbiter_port</varname>, 
+    you must provide this value in the <literal>arbiter_port</literal>
+    parameter in the connection string for the corresponding node.
   </para></listitem></varlistentry>
   <varlistentry><term><varname>multimaster.max_nodes</varname><indexterm><primary><varname>multimaster.max_nodes</varname></primary></indexterm></term><listitem><para>
-    The maximum number of nodes allowed in the cluster. If you plan to add new nodes to your cluster, the <literal>multimaster.max_nodes</literal> value should exceed the initial number of nodes. In this case, you can add new nodes without restarting <productname>&productname;</productname>. In most cases, three cluster nodes are enough to ensure high availability. Since the data on all cluster nodes is the same, you do not typically need more than five cluster nodes. The maximum possible number of nodes is limited to 64.</para>
+    The maximum number of nodes allowed in the cluster. If you plan to add new nodes to your cluster, the <literal>multimaster.max_nodes</literal> value should exceed the initial number of nodes. In this case, you can add new nodes without restarting <productname>&productname;</productname> until the specified number of nodes is reached. In most cases, three cluster nodes are enough to ensure high availability. Since the data on all cluster nodes is the same, you do not typically need more than five cluster nodes. The maximum possible number of nodes is limited to 64.</para>
     <para>Default: the number of nodes specified in the <varname>multimaster.conn_strings</varname> variable
   </para></listitem></varlistentry>
   <varlistentry id="multimaster-arbiter-port">
   <term><varname>multimaster.arbiter_port</varname><indexterm><primary><varname>multimaster.arbiter_port</varname></primary></indexterm></term><listitem><para>
     Port for the arbiter process to listen on. If you change the default value, you must specify this value in the <literal>arbiter_port</literal>
-    parameter in the connection string of the corresponding node.</para>
+    parameter in the connection string for the corresponding node.</para>
     <para>Default: 5433
   </para></listitem></varlistentry>
   <varlistentry><term><varname>multimaster.heartbeat_send_timeout</varname><indexterm><primary><varname>multimaster.heartbeat_send_timeout</varname></primary></indexterm></term><listitem><para>
@@ -873,7 +883,7 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
   </para></listitem></varlistentry>
   <varlistentry><term><varname>multimaster.cluster_name</varname><indexterm><primary><varname>multimaster.cluster_name</varname></primary></indexterm></term><listitem><para>
     Name of the cluster. If
-    you set this variable, <filename>multimaster</filename> checks that
+    you define this variable when setting up the cluster, <filename>multimaster</filename> checks that
     the cluster name is the same for all the cluster nodes.
   </para></listitem></varlistentry>
   <varlistentry>