Bootstrap a MariaDB Galera Cluster Safely with galera_new_cluster

You will start a new MariaDB Galera Primary Component from the node that is safest to use, then start the remaining nodes so they rejoin it. Allow about 15 minutes for a planned outage, assuming the nodes and their network are already configured. This is a recovery operation, not a normal way to start one database server.

The examples below match the installed Ubuntu package mariadb-server 1:10.11.14-0ubuntu0.24.04.1. Its galera_new_cluster command is a shell wrapper around systemd. You need root or sudo, access to every node, and a Galera configuration that is already complete.

1. Confirm that this is a cluster bootstrap

Use this command only when every node in the cluster is down or the existing Primary Component has been lost. Do not use it for a routine restart of one node that can still rejoin an existing component.

First check the local service state:

$ systemctl is-active mariadb
inactive

The result can instead be failed after a crash. Check every node before proceeding. If another node is still serving traffic as the Primary Component, stop and diagnose that situation instead of creating a second component.

2. Choose the node with the safest state

On an orderly shutdown, inspect the Galera state file on each node. The usual data directory is /var/lib/mysql:

$ sudo awk '/^(seqno|safe_to_bootstrap):/ {print}' /var/lib/mysql/grastate.dat
seqno: 15
safe_to_bootstrap: 1

Bootstrap from the node whose state contains safe_to_bootstrap: 1. That flag is normally written to the last node shut down, which should have the latest state after a graceful cluster stop. The exact sequence number is useful evidence, but do not casually choose a different node just because its number looks convenient.

If all nodes show safe_to_bootstrap: 0, treat this as a crash-recovery decision. Compare the recovered positions from every node using the MariaDB Galera recovery procedure, then choose the node with the highest position. Do not edit grastate.dat until you have made that comparison and accepted the risk. If you cannot identify the most advanced node, stop and obtain database-operator assistance.

Checkpoint: you should now have one named bootstrap node and a written record of why it was selected. All other nodes must remain stopped until the new Primary Component is ready.

3. Bootstrap the selected node

Run this elevated command on the selected node only:

$ sudo galera_new_cluster

With this installed version, the wrapper sets the temporary systemd environment variable _WSREP_NEW_CLUSTER=--wsrep-new-cluster, restarts the mariadb unit, clears that environment variable, and returns the restart status. It does not accept a cluster address or a node list on its command line.

A successful command normally returns to the shell without a success message. Check the service immediately:

$ systemctl is-active mariadb
active
$ sudo mariadb -e "SHOW GLOBAL STATUS LIKE 'wsrep_cluster_status'; SHOW GLOBAL STATUS LIKE 'wsrep_local_state_comment';"

The first command should report active. In the SQL result, look for Primary in wsrep_cluster_status and Synced in wsrep_local_state_comment. The table formatting varies by client version. If the wrapper fails, inspect the service log before retrying:

$ sudo journalctl -u mariadb -n 100 --no-pager

4. Start each remaining node normally

After the first node is Primary and Synced, start each other node one at a time with its ordinary service command:

$ sudo systemctl start mariadb
$ systemctl is-active mariadb
active

Wait for the node to complete its state transfer before starting the next one. Watch the bootstrap node's membership count:

$ sudo mariadb -e "SHOW GLOBAL STATUS LIKE 'wsrep_cluster_size';"

Use the expected cluster size for your deployment, not a guessed value. A joining node may need a state snapshot transfer, so its first start can take longer than a normal restart. Check its own MariaDB log if it does not become healthy.

5. Undo a mistaken start

If you started the wrong node or accidentally bootstrapped during a partition, stop the affected MariaDB services before any writes continue:

$ sudo systemctl stop mariadb

This is service-disrupting, so confirm the host and unit name before pressing Enter. Stopping the service does not merge divergent data or undo transactions. Preserve the logs, record which node was bootstrapped, and resolve the cluster state with the Galera recovery procedure before starting anything again. Do not repeatedly bootstrap nodes as a trial-and-error fix.