Reviewed descriptions of config variables

Author: Liudmila Mantrova

doc/configuration.md

@@ -1,22 +1,29 @@
-# `Configuration parameters`
+# `GUC Variables`
 
-```multimaster.node_id``` Multimaster node ID, unique number identifying this node. Nodes should be numbered by natural numbers starting from 1 without gaps (e.g. 1, 2, 3, ...). node_id is also used as an offset in ```multimaster.conn_strings```, thus i-th node's connection string expected to be on i-th position in ```multimaster.conn_strings```. Mandatory.
+```multimaster.node_id``` Node ID - a unique natural number identifying the node of a multi-master cluster. You must start node numbering from 1 and cannot have any gaps in numbering. For example, for a cluster of five nodes, set node IDs to 1, 2, 3, 4, and 5. 
 
-```multimaster.conn_strings``` Multimaster node connection strings separated by commas, i.e. 'dbname=mydb host=node1, dbname=mydb host=node2, dbname=mydb host=node3'. Order here is important and should be consistent with ```multimaster.node_id```. Multimaster allows to specify custom arbiter_port value for all connection strings. Also this parameter is expected to be identical on all nodes. Mandatory.
+```multimaster.conn_strings``` Connection strings for each node of a multi-master cluster, separated by commas. Each connection string must include the name of the database to replicate and the cluster node domain name. For example, 'dbname=mydb host=node1, dbname=mydb host=node2, dbname=mydb host=node3'. Connection strings must appear in the order of the node IDs specified in the ```multimaster.node_id``` variable. Connection string for the i-th node must be on the i-th position. This parameter must be identical on all nodes. You can specify a custom port for all connection strings using the `multimaster.arbiter_port` variable. 
 
-```multimaster.arbiter_port``` Port for arbiter process to listen on. Default to 5433.
+```multimaster.arbiter_port``` Port for the arbiter process to listen on. 
+Default: 5433
 
-```multimaster.heartbeat_send_timeout``` Period of broadcasting heartbeat messages by arbiter to all nodes. In milliseconds. Default to 1000.
+```multimaster.heartbeat_send_timeout``` Time interval between heartbeat messages, in milliseconds. An arbiter process broadcasts heartbeat messages to all nodes to detect connection problems. Default: 1000.
 
-```multimaster.heartbeat_recv_timeout``` If no heartbeat message is received from node within this period, it assumed to be dead. In milliseconds. Default to 10000.
+```multimaster.heartbeat_recv_timeout``` Timeout, in milliseconds. If no heartbeat message is received from the node within this timeframe, the node is excluded from the cluster. 
+Default: 10000
 
-```multimaster.min_recovery_lag``` Minimal lag of WAL-sender performing recovery after which cluster is locked until recovery is completed. When wal-sender almost catch-up WAL current position we need to stop 'Achilles tortile competition' and temporary stop commit of new transactions until node will be completely repared. In bytes. Default to 100000.
 
-```multimaster.max_recovery_lag``` Maximal lag of replication slot of failed node after which this slot is dropped to avoid transaction log overflow. Dropping slot makes it not possible to recover node using logical replication mechanism, it will be necessary to completely copy content of some alive node using pg_basebackup or similar tool. Zero value of parameter disable slot dropping. In bytes. Default to 100000000.
+```multimaster.min_recovery_lag``` Minimal WAL lag between the current cluster state and the node to be restored, in bytes. When this threshold is reached during node recovery, the cluster is locked for write transactions until the recovery is complete. 
+Default: 100000
+
+```multimaster.max_recovery_lag``` Maximal WAL lag size, in bytes. When a node is disconnected from the cluster, other nodes copy WALs for all new trasactions into the replication slot of this node. Upon reaching the `multimaster.max_recovery_lag` value, the replication slot for the disconnected node is deleted to avoid overflow. At this point, automatic recovery of the node is no longer possible. In this case, you can restore the node manually by cloning the data from one of the alive nodes using `pg_basebackup` or a similar tool. If you set this variable to zero, replication slot will not be deleted. 
+Default: 10000000
+
+```multimaster.ignore_tables_without_pk``` Boolean. This variable enables/disables replication of tables without primary keys. By default, replication of tables without primary keys is disabled because of the logical replication restrictions. To enable replication, you can set this variable to false. However, take into account that `multimaster` does not allow update operations on such tables. Default: true
+
+```multimaster.cluster_name``` Name of the cluster. If you set this variable, `multimaster` checks that the cluster name is the same for all the cluster nodes.
 
-```multimaster.ignore_tables_without_pk``` Do not replicate tables withpout primary key. Boolean.
 
-```multimaster.cluster_name``` Name of the cluster, desn't affect anything. Just in case. If set that mmts will check name correspondence.
 
 ## Questionable
 
@@ -38,8 +45,6 @@
 
 ```multimaster.gc_period``` Number of distributed transactions after which garbage collection is started. Multimaster is building xid->csn hash map which has to be cleaned to avoid hash overflow. This parameter specifies interval of invoking garbage collector for this map. default = MTM_HASH_SIZE/10
 
-```multimaster.max_node``` Maximal number of cluster nodes. This parameters allows to add new nodes to the cluster, default value 0 restricts number of nodes to one specified in multimaster.conn_strings (May be just set that to 64 and allow user to add node when trey need without restart?) default = 0
-
 ```multimaster.node_disable_delay``` Minimal amount of time (msec) between node status change. This delay is used to avoid false detection of node failure and to prevent blinking of node status node. default = 2000. (We can just increase heartbeat_recv_timeout)
 
 ```multimaster.connect_timeout``` Multimaster nodes connect timeout. Interval in milliseconds for establishing connection with cluster node. default = 10000, /* 10 seconds */