How to create a MariaDB Galera cluster

A MariaDB Galera cluster keeps multiple database nodes in the same write-capable cluster, which reduces the impact of a single server failure and shortens maintenance windows. That matters when read and write traffic must stay available without waiting for an asynchronous replica to catch up after a failover.

Galera adds the wsrep replication provider to MariaDB so each node exchanges writesets with the others and certifies transactions before commit. One node is bootstrapped once to form the first Primary Component, then the remaining nodes join with normal service starts and synchronize by SST or IST until they reach Synced state.

These steps target MariaDB on Ubuntu or Debian using the distro packages mariadb-server and galera-4. Oracle MySQL uses Group Replication or InnoDB Cluster instead of Galera, so this package-and-helper workflow does not apply there. Keep all nodes on the same MariaDB major version, use private addresses for inter-node traffic, and allow TCP 3306, TCP+UDP 4567, TCP 4568, and TCP 4444 between cluster members.

1. Pick three Linux hosts with stable private IP addresses and empty or equivalent MariaDB datadirs.

   Joining a node by SST replaces its local data with a donor copy. Take a backup before reusing a standalone server with important data.

2. Install the MariaDB server, the Galera provider, and the default rsync SST tool on every node.

   $ sudo apt update
   $ sudo apt install mariadb-server galera-4 rsync

   On current Ubuntu and Debian packages, the Galera provider is delivered by the separate galera-4 package.

3. Create a dedicated Galera config file on the first node.

   $ sudoedit /etc/mysql/mariadb.conf.d/60-galera.cnf

4. Add cluster settings for the first node.

   [mariadb]
   bind-address = 192.0.2.31
   binlog_format = ROW
   default_storage_engine = InnoDB
   innodb_autoinc_lock_mode = 2
   
   wsrep_on = ON
   wsrep_provider = /usr/lib/galera/libgalera_smm.so
   wsrep_cluster_name = sg_cluster
   wsrep_cluster_address = gcomm://192.0.2.31,192.0.2.32,192.0.2.33
   wsrep_node_name = db1
   wsrep_node_address = 192.0.2.31
   wsrep_sst_method = rsync

   Keep wsrep_cluster_address pointed at the full node list on all nodes. Do not save it as plain gcomm:// in the config, because that bootstraps a new cluster instead of rejoining the existing one after a restart.

5. Copy the same settings to the second and third nodes, changing only the node-specific values.

   wsrep_node_name = db2
   wsrep_node_address = 192.0.2.32

   wsrep_node_name = db3
   wsrep_node_address = 192.0.2.33

   The wsrep_cluster_name and wsrep_cluster_address values must match on every node.

6. Stop MariaDB on all nodes before the first bootstrap so only one node creates the initial Primary Component.

   $ sudo systemctl stop mariadb

7. Bootstrap the first node into a new cluster.

   $ sudo galera_new_cluster

   Current Debian or Ubuntu mariadb-server packages install the galera_new_cluster helper and the related galera_recovery tool.

   If the entire cluster is later shut down, bootstrap only the most advanced node identified by galera_recovery or /var/lib/mysql/grastate.dat. Running galera_new_cluster on the wrong node can discard newer writes.

8. Verify that the bootstrap node is online and ready to accept cluster traffic.

   $ sudo mariadb --table -e "SHOW STATUS WHERE Variable_name IN ('wsrep_cluster_size','wsrep_cluster_status','wsrep_local_state_comment','wsrep_ready');"
   +---------------------------+---------+
   | Variable_name             | Value   |
   +---------------------------+---------+
   | wsrep_cluster_size        | 1       |
   | wsrep_cluster_status      | Primary |
   | wsrep_local_state_comment | Synced  |
   | wsrep_ready               | ON      |
   +---------------------------+---------+

9. Start MariaDB normally on the remaining nodes so they join the running cluster.

   $ sudo systemctl start mariadb

   The default rsync SST method blocks donor writes while the full copy runs. On larger datasets, join nodes one at a time and watch the error log until the joiner reaches Synced.

   Related: How to view the MySQL or MariaDB server error log
   Related: How to manage MySQL or MariaDB service in Linux

10. Check the cluster state on each node after both joiners finish syncing.

    $ sudo mariadb --table -e "SHOW STATUS WHERE Variable_name IN ('wsrep_cluster_size','wsrep_cluster_status','wsrep_local_state_comment');"
    +---------------------------+---------+
    | Variable_name             | Value   |
    +---------------------------+---------+
    | wsrep_cluster_size        | 3       |
    | wsrep_cluster_status      | Primary |
    | wsrep_local_state_comment | Synced  |
    +---------------------------+---------+

    A node that does not show Primary and Synced should not take application traffic yet.

11. Create a small test database and row on the first node.

    $ sudo mariadb -e "CREATE DATABASE IF NOT EXISTS galera_test; CREATE TABLE IF NOT EXISTS galera_test.t (id INT PRIMARY KEY AUTO_INCREMENT, note VARCHAR(64)) ENGINE=InnoDB; INSERT INTO galera_test.t (note) VALUES ('cluster-ok');"

    InnoDB is the supported storage engine for MariaDB Galera Cluster.

12. Query the test table from another node to confirm the write replicated across the cluster.

    $ sudo mariadb --table -e "SELECT * FROM galera_test.t;"
    +----+------------+
    | id | note       |
    +----+------------+
    |  1 | cluster-ok |
    +----+------------+

    A cluster still needs a load balancer, proxy, or VIP if applications require one stable connection endpoint. Galera provides node membership and data replication, not a built-in client router.