Skip to content

Commit af41cb5

Browse files
vbwagnervbwagner
committed
Merge branch 'PGPROEE9_6' of gitlab.postgrespro.ru:pgpro-dev/postgrespro into PGPROEE9_6
2 parents 069b318 + 91c252f commit af41cb5

File tree

2 files changed

+115
-26
lines changed

2 files changed

+115
-26
lines changed

‎doc/src/sgml/high-availability.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,7 @@ protocol to make nodes agree on a serializable transactional order.
259259
Online Transaction Processing (<acronym>OLTP</acronym>) scalability
260260
for read transactions, as well as ensures high availability with
261261
automatic disaster recovery.
262+
For details, see <xref linkend="multimaster">.
262263
</para>
263264
</listitem>
264265
</varlistentry>

‎doc/src/sgml/multimaster.sgml

Lines changed: 114 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,23 @@
104104
</listitem>
105105
<listitem>
106106
<para>
107-
Sequence generation. To avoid conflicts between unique identifiers on different nodes, <filename>multimaster</filename> modifies the default behavior of sequence generators. For each node, ID generation is started with the node number and is incremented by the number of nodes. For example, in a three-node cluster, 1, 4, and 7 IDs are allocated to the objects written onto the first node, while 2, 5, and 8 IDs are reserved for the second node. If you change the number of nodes in the cluster, the incrementation interval for new IDs is adjusted accordingly. Thus, the generated sequence values are not monotonic.
107+
In a multi-master cluster, the <literal>ALTER SYSTEM</literal> command only affects the configuration of the current node.
108+
If you would like to change configuration parameters across the whole database cluster, you need to run this command on
109+
each node.
110+
</para>
111+
</listitem>
112+
<listitem>
113+
<para>
114+
Sequence generation. To avoid conflicts between unique identifiers on different nodes,
115+
<filename>multimaster</filename> modifies the default behavior of sequence generators.
116+
By default, ID generation on each node is started with this node number and is
117+
incremented by the number of nodes. For example, in a three-node cluster, 1, 4, and 7
118+
IDs are allocated to the objects written onto the first node, while 2, 5, and 8 IDs are reserved
119+
for the second node. If you change the number of nodes in the cluster, the incrementation
120+
interval for new IDs is adjusted accordingly. Thus, the generated sequence values are not
121+
monotonic. If it is cricital to get a monotonically increasing sequence cluster-wide, you can
122+
set the <link linkend="mtm-monotonic-sequences"><varname>multimaster.monotonic_sequences</varname></link>
123+
to <literal>true</literal>.
108124
</para>
109125
</listitem>
110126
<listitem>
@@ -228,8 +244,8 @@
228244
heartbeats to the node are lost in a row, this node is kicked out
229245
of the cluster to allow writes to the remaining alive nodes. You
230246
can configure the heartbeat frequency and the response timeout in
231-
the <literal>multimaster.heartbeat_send_timeout</literal> and
232-
<literal>multimaster.heartbeat_recv_timeout</literal> parameters,
247+
the <varname>multimaster.heartbeat_send_timeout</varname> and
248+
<varname>multimaster.heartbeat_recv_timeout</varname> parameters,
233249
respectively.
234250
</para>
235251
<para>
@@ -263,12 +279,12 @@
263279
If you try to access a disconnected node, <filename>multimaster</filename> returns an error
264280
message indicating the current status of the node. To prevent stale reads, read-only queries are also forbidden.
265281
Additionally, you can break connections between the disconnected node and the clients using the
266-
<link linkend="mtm-break-connection">multimaster.break_connection</link> variable.
282+
<link linkend="mtm-break-connection"><varname>multimaster.break_connection</varname></link> variable.
267283
</para>
268284
</note>
269285
<para>
270286
If required, you can override this behavior for one of the nodes using the
271-
<link linkend="mtm-major-node">multimaster.major_node</link> variable.
287+
<link linkend="mtm-major-node"><varname>multimaster.major_node</varname></link> variable.
272288
In this case, the node will continue working even if it is isolated.
273289
</para>
274290
<para>
@@ -374,7 +390,8 @@ where <replaceable>datadir</> is the directory containing the database cluster.
374390
shared_preload_libraries = 'multimaster'
375391
</programlisting>
376392
<tip>
377-
<para>If the <varname>shared_preload_libaries</varname> variable is already defined in <filename>postgresql.auto.conf</filename>, you will need to modify its value using the <literal>ALTER SYSTEM</literal> command. For details, see <xref linkend="config-setting-configuration-file">.
393+
<para>If the <varname>shared_preload_libaries</varname> variable is already defined in <filename>postgresql.auto.conf</filename>, you will need to modify its value using the <xref linkend="sql-altersystem"> command. For details, see <xref linkend="config-setting-configuration-file">.
394+
Note that in a multi-master cluster, the <literal>ALTER SYSTEM</literal> command only affects the configuration of the node from which it was run.
378395
</para>
379396
</tip>
380397
</listitem>
@@ -493,7 +510,7 @@ CREATE EXTENSION multimaster;</programlisting></para>
493510
the <structname>mtm.get_cluster_state()</structname> view:
494511
</para>
495512
<programlisting>
496-
mtm.get_cluster_state();
513+
SELECT mtm.get_cluster_state();
497514
</programlisting>
498515
<para>
499516
If <literal>liveNodes</literal> is equal to
@@ -604,7 +621,7 @@ mtm.get_cluster_state();
604621
</listitem>
605622
<listitem>
606623
<para>
607-
<link linkend="multimaster-excluding-nodes-from-the-cluster">Excluding Nodes
624+
<link linkend="multimaster-removing-nodes-from-the-cluster">Removing Nodes
608625
from the Cluster</link>
609626
</para>
610627
</listitem>
@@ -624,13 +641,13 @@ mtm.get_cluster_state();
624641
To check node-specific information, use <literal>mtm.get_nodes_state()</literal>:
625642
</para>
626643
<programlisting>
627-
mtm.get_nodes_state();
644+
SELECT mtm.get_nodes_state();
628645
</programlisting>
629646
<para>To check the status of the whole cluster, use the
630647
<literal>mtm.get_cluster_state()</literal> view:
631648
</para>
632649
<programlisting>
633-
mtm.get_cluster_state();
650+
SELECT mtm.get_cluster_state();
634651
</programlisting>
635652
<para>For details on all the returned information, see <xref linkend="multimaster-functions">.
636653
</para>
@@ -675,7 +692,7 @@ mtm.get_cluster_state();
675692
In <literal>psql</literal> connected to any alive node, run:
676693
</para>
677694
<programlisting>
678-
mtm.add_node('dbname=mydb user=myuser host=node4');
695+
SELECT mtm.add_node('dbname=mydb user=myuser host=node4');
679696
</programlisting>
680697
<para>
681698
This command changes the cluster configuration on all nodes
@@ -702,8 +719,10 @@ pg_basebackup -D <replaceable>datadir</replaceable> -h node1 -x
702719
</para>
703720
<programlisting>
704721
multimaster.node_id = 4
705-
multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,dbname=mydb user=myuser host=node2,
706-
dbname=mydb user=myuser host=node3,dbname=mydb user=myuser host=node4'
722+
multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,
723+
dbname=mydb user=myuser host=node2,
724+
dbname=mydb user=myuser host=node3,
725+
dbname=mydb user=myuser host=node4'
707726
</programlisting>
708727
</listitem>
709728
<listitem>
@@ -741,18 +760,22 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
741760
<para><link linkend="multimaster-monitoring-cluster-status">Monitoring Cluster
742761
Status</link></para>
743762
</sect3>
744-
<sect3 id="multimaster-excluding-nodes-from-the-cluster">
745-
<title>Excluding Nodes from the Cluster</title>
763+
<sect3 id="multimaster-removing-nodes-from-the-cluster">
764+
<title>Removing Nodes from the Cluster</title>
765+
<para>
766+
<filename>multimaster</filename> provides the <literal>mtm.stop_node()</literal>
767+
function that can temporarily or permanently remove nodes from the cluster.
768+
</para>
746769
<para>
747-
To exclude a node from the cluster, use the
748-
<literal>mtm.stop_node()</literal> function. For example, to
749-
exclude node 3, run the following command on any other node:
770+
To temporarily exclude a node from the cluster, run the
771+
<literal>mtm.stop_node()</literal> function specifying the node ID. For example, to
772+
exclude node 3, run the following command on any other node of the cluster:
750773
</para>
751774
<programlisting>
752775
SELECT mtm.stop_node(3);
753776
</programlisting>
754777
<para>
755-
This excludes node 3 from the cluster and stops replication to
778+
This command excludes node 3 from the cluster and stops replication to
756779
this node. While the WAL lag between the node and the current cluster state
757780
is less than the <varname>multimaster.max_recovery_lag</varname> value,
758781
you can restore the node using the <function>mtm.recover_node</function> function.
@@ -767,7 +790,7 @@ SELECT mtm.stop_node(3);
767790
</para>
768791
</note>
769792
<para>
770-
If you would like to permanently remove the node from the cluster, run the
793+
To permanently drop the node from the cluster, run the
771794
<literal>mtm.stop_node()</literal> function with the <literal>drop_slot</literal> parameter
772795
set to <literal>true</literal>:
773796
</para>
@@ -794,7 +817,7 @@ SELECT mtm.stop_node(3, drop_slot true);
794817
In <literal>psql</literal> connected to any alive node, create a new replication slot for the disconnected node with the following command:
795818
</para>
796819
<programlisting>
797-
mtm.recover_node(2);
820+
SELECT mtm.recover_node(2);
798821
</programlisting>
799822
<para>where 2 is the ID of the disconnected node specified in the <varname>multimaster.node_id</varname> variable.</para>
800823
</listitem>
@@ -938,8 +961,8 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
938961
<listitem>
939962
<para>Node with this flag continues working even if it cannot access the majority of other nodes.
940963
This is needed to break the symmetry if there is an even number of alive nodes in the cluster.
941-
For example, a cluster with three nodes continues working if one of the nodes has crashed.
942-
If connection between the remaining nodes is lost, the node with <varname>multimaster.major_node</varname> = <literal>true</literal> will continue working.
964+
For example, in a cluster of three nodes, if one of the nodes has crashed and
965+
the connection between the remaining nodes is lost, the node with <varname>multimaster.major_node</varname> = <literal>true</literal> will continue working.
943966
</para>
944967
<important>
945968
<para>This parameter should be used with caution. Only one node in the cluster
@@ -976,6 +999,40 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
976999
</para>
9771000
</listitem>
9781001
</varlistentry>
1002+
<varlistentry id="mtm-monotonic-sequences">
1003+
<term><varname>multimaster.monotonic_sequences</varname>
1004+
<indexterm><primary><varname>multimaster.monotonic_sequences</varname></primary>
1005+
</indexterm>
1006+
</term>
1007+
<listitem>
1008+
<para>Defines the sequence generation mode for unique identifiers. This variable can
1009+
take the following values:
1010+
<itemizedlist>
1011+
<listitem>
1012+
<para>
1013+
<literal>false</literal> (default) &mdash;
1014+
ID generation on each node is started with this node number and is incremented by
1015+
the number of nodes. For example, in a three-node cluster, 1, 4, and 7 IDs are allocated to the objects written onto
1016+
the first node, while 2, 5, and 8 IDs are reserved for the second node. If you
1017+
change the number of nodes in the cluster, the incrementation interval for new IDs is adjusted accordingly.
1018+
</para>
1019+
</listitem>
1020+
<listitem>
1021+
<para>
1022+
<literal>true</literal> &mdash;
1023+
the generated sequence increases monotonically cluster-wide.
1024+
ID generation on each node is started with this node number and is incremented by
1025+
the number of nodes, but the values are omitted if they are smaller than the already generated IDs on another node.
1026+
For example, in a three-node cluster, if 1, 4 and 7 IDs are already allocated to the objects on
1027+
the first node, 2 and 5 IDs will be omitted on the second node. In this case, the first ID on the second node is 8.
1028+
Thus, the next generated ID is always higher than the previous one, regardless of the cluster node.
1029+
</para>
1030+
</listitem>
1031+
</itemizedlist>
1032+
<para>Default: <literal>false</literal>
1033+
</para>
1034+
</listitem>
1035+
</varlistentry>
9791036
</variablelist>
9801037
</sect3>
9811038
<sect3 id="multimaster-functions"><title>Functions</title>
@@ -1108,9 +1165,9 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
11081165

11091166
<varlistentry>
11101167
<term>
1111-
<function>mtm.collect_cluster_state_info()</function>
1168+
<function>mtm.collect_cluster_info()</function>
11121169
<indexterm>
1113-
<primary><function>mtm.collect_cluster_state_info</></primary>
1170+
<primary><function>mtm.collect_cluster_info</></primary>
11141171
</indexterm>
11151172
</term>
11161173
<listitem>
@@ -1359,7 +1416,7 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
13591416
<itemizedlist>
13601417
<listitem>
13611418
<para>
1362-
<parameter>table_name</parameter> &mdash; The table you would like to
1419+
<parameter>table_name</parameter> &mdash; the table you would like to
13631420
exclude from the replication scheme.</para>
13641421
<para>Type: <literal>regclass</literal></para>
13651422
</listitem>
@@ -1368,6 +1425,37 @@ pg_ctl -D <replaceable>datadir</replaceable> -l <replaceable>pg.log</replaceable
13681425
<para>
13691426
</para>
13701427
</listitem>
1428+
</varlistentry>
1429+
<varlistentry>
1430+
<term>
1431+
<function>mtm.copy_table(<parameter>table_name</parameter> <type>regclass</type>, <parameter>node_id</parameter> <type>integer</type>)</function>
1432+
<indexterm>
1433+
<primary><function>mtm.copy_table</></primary>
1434+
</indexterm>
1435+
</term>
1436+
<listitem>
1437+
<para>Copies the specified table to another node. You can use this function to restore the corrupted data
1438+
on one or more nodes of the cluster. This function must be called on the node from which the table is copied.
1439+
</para>
1440+
<para>
1441+
Arguments:
1442+
<itemizedlist>
1443+
<listitem>
1444+
<para>
1445+
<parameter>table_name</parameter> &mdash; the table you would like to
1446+
copy.</para>
1447+
<para>Type: <literal>regclass</literal></para>
1448+
</listitem>
1449+
<listitem>
1450+
<para>
1451+
<parameter>node_id</parameter> &mdash; the node to copy the table to.</para>
1452+
<para>Type: <literal>integer</literal></para>
1453+
</listitem>
1454+
</itemizedlist>
1455+
</para>
1456+
<para>
1457+
</para>
1458+
</listitem>
13711459
</varlistentry>
13721460
</variablelist>
13731461
</sect3>

0 commit comments

Comments
 (0)