Bootstrap a Galera Cluster

Overview

This page describes the special procedure that is used to startup the first node in a Galera Cluster, which is known as bootstrapping.

Compatibility

  • MariaDB Enterprise Server 10.3

  • MariaDB Enterprise Server 10.4

  • MariaDB Enterprise Server 10.5

  • MariaDB Enterprise Server 10.6

Purpose

When a Galera Cluster node starts by default, it tries to establish a connection to the other cluster nodes configured in the wsrep_cluster_address system variable. The node does not become active until it connects to another cluster node that belongs to the Primary Component. Consequently, if all nodes in a cluster are offline, you must start the first node using a special method, so that it does not abort startup when it can't establish a connection with any other cluster nodes. The special method is known as bootstrapping the cluster.

To bootstrap the first node in a new cluster, the --wsrep-new-cluster command-line option is used. This option can be specified in a few different ways, depending on how you plan to start the process.

systemd

In environments that use systemd for service management, the galera_new_cluster utility is provided:

$ sudo galera_new_cluster

When the galera_new_cluster utility is executed, it starts the mariadb.service systemd unit with the --wsrep-new-cluster command-line option added to the mariadbd command.

Since this command starts the mariadb.service systemd unit, the service should be stopped prior to running this command.

Command-Line

In environments where mariadbd is started via the command-line, the --wsrep-new-cluster command-line option can be specified:

$ sudo mariadbd .. --wsrep-new-cluster ..

Configuration File

The --wsrep-new-cluster command-line option can also be specified in a configuration file:

[mariadb]
wsrep-new-cluster

When the --wsrep-new-cluster command-line option is specified in a configuration file that the node reads during startup, the node forms a new cluster. MariaDB recommends removing the option from the configuration file immediately for safety reasons. If the option is left in the configuration file, the node will form a new cluster every time it is restarted, even if the other cluster nodes are online.