Starting the Cluster

When you finish installing and configuring Galera Cluster you have the databases ready for use, but they are not yet connected to each other to form a cluster. To do this, you will need to start mysqld on one node, using the --wsrep-new-cluster option. This initializes the new Primary Component for the cluster. Each node you start after this will connect to the component and begin replication.

Before you attempt to initialize the cluster, check that you have the following ready:

  • Database hosts with Galera Cluster installed, you will need a minimum of three hosts;

  • No firewalls between the hosts;

  • SELinux and AppArmor set to permit access to mysqld; and,

  • Correct path to libgalera_smm.so given to the wsrep_provider option. For example,

    wsrep_provider=/usr/lib64/libgalera_smm.so
    

With the hosts prepared, you are ready to initialize the cluster.

Note

See Also: When migrating from an existing, standalone instance of MySQL or MariaDB Galera Cluster, there are some additional steps that you must take. For more information on what you need to do, see Migrating to Galera Cluster.

Starting the First Cluster Node

By default, nodes do not start as part of the Primary Component. Instead, they assume that the Primary Component exists already somewhere in the cluster.

When nodes start, they attempt to establish network connectivity with the other nodes in the cluster. For each node they find, they check whether or not it is a part of the Primary Component. When they find the Primary Component, they request a state transfer to bring the local database into sync with the cluster. If they cannot find the Primary Component, they remain in a nonoperational state.

There is no Primary Component when the cluster starts. In order to initialize it, you need to explicitly tell one node to do so with the --wsrep-new-cluster argument. By convention, the node you use to initialize the Primary Component is called the first node, given that it is the first that becomes operational.

Note

See Also: When you start a new cluster, any node can serve as the first node, since all the databases are empty. When you migrate from MySQL to Galera Cluster, use the original master node as the first node. When restarting the cluster, use the most advanced node. For more information, see Migrating to Galera Cluster and Resetting the Quorum.

Bear in mind, the first node is only “first” in that it initializes the Primary Component. This node can fall behind and leave the cluster without necessarily affecting the Primary Component.

To start the first node, launch the database server on your first node. For systems that use init, run the following command:

# service mysql start --wsrep-new-cluster

For systems that use systemd, instead use this command:

# systemctl start mysql --wsrep-new-cluster

This starts mysqld on the node.

Note

Warning: Only use the --wsrep-new-cluster argument when initializing the Primary Component. Do not use it when you want the node to connect to an existing cluster.

Once the node starts the database server, check that startup was successful by checking wsrep_cluster_size. In the database client, run the following query:

SHOW STATUS LIKE 'wsrep_cluster_size';

+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| wsrep_cluster_size | 1     |
+--------------------+-------+

This status variable tells you the number of nodes that are connected to the cluster. Since you have just started your first node, the value is 1.

Note

Do not restart mysqld at this point.

Adding Additional Nodes to the Cluster

When you start the first node you initialize a new cluster. Once this is done, the procedure for adding all the other nodes is the same.

To add a node to an existing cluster, launch mysqld as you would normally. If your system uses init, run the following command:

# service mysql start

For systems that use systemd, instead run this command:

# systemctl start mysql

When the database server initializes as a new node, it connects to the cluster members as defined by the wsrep_cluster_address parameter. Using this parameter, it automatically retrieves the cluster map and connects to all other available nodes.

You can test that the node connection was successful using the wsrep_cluster_size status variable. In the database client, run the following query:

SHOW STATUS LIKE 'wsrep_cluster_size';

+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| wsrep_cluster_size | 2     |
+--------------------+-------+

This indicates that the second node is now connected to the cluster. Repeat this procedure to add the remaining nodes to your cluster.

When all nodes in the cluster agree on the membership state, they initiate state exchange. In state exchange, the new node checks the cluster state. If the node state differs from the cluster state, (which is normally the case), the new node requests a state snapshot transfer from the cluster and it installs it on the local database. After this is done, the new node is ready for use.