MariaDB starting with

Since , the MySQL-wsrep patch has been merged into MariaDB Server. Therefore, in and above, the functionality of MariaDB Galera Cluster can be obtained by installing the standard MariaDB Server packages and the Galera wsrep provider library package.

Beginning in , Galera Cluster ships with the MariaDB Server. Upgrading a Galera Cluster node is very similar to upgrading a server from to . For more information on that process as well as incompatibilities between versions, see the .

Performing a Rolling Upgrade

The following steps can be used to perform a rolling upgrade from to when using Galera Cluster. In a rolling upgrade, each node is upgraded individually, so the cluster is always operational. There is no downtime from the application's perspective.

First, before you get started:

1. First, take a look at to see what has changed between the major versions.

2. Check whether any system variables or options have been changed or removed. Make sure that your server's configuration is compatible with the new MariaDB version before upgrading.

3. Check whether replication has changed in the new MariaDB version in any way that could cause issues while the cluster contains upgraded and non-upgraded nodes.

4. Check whether any new features have been added to the new MariaDB version. If a new feature in the new MariaDB version cannot be replicated to the old MariaDB version, then do not use that feature until all cluster nodes have been upgrades to the new MariaDB version.

5. Next, make sure that the Galera version numbers are compatible.

6. If you are upgrading from the most recent release to , then the versions will be compatible. uses Galera 3 (i.e. Galera wsrep provider versions 25.3.x), and uses Galera 4 (i.e. Galera wsrep provider versions 26.4.x). This means that upgrading to also upgrades the system to Galera 4. However, Galera 3 and Galera 4 should be compatible for the purposes of a rolling upgrade, as long as you are using Galera 26.4.2 or later.

7. See What is MariaDB Galera Cluster? Galera wsrep provider Versions for information on which MariaDB releases uses which Galera wsrep provider versions.

8. Ideally, you want to have a large enough gcache to avoid a State Snapshot Transfer (SST) during the rolling upgrade. The gcache size can be configured by setting gcache.size For example:wsrep_provider_options="gcache.size=2G"

Before you upgrade, it would be best to take a backup of your database. This is always a good idea to do before an upgrade. We would recommend .

Then, for each node, perform the following steps:

sudo apt-get remove mariadb-server galera

sudo yum remove MariaDB-server galera

sudo zypper remove MariaDB-server galera

When this process is done for one node, move onto the next node.

_{This page is licensed: CC BY-SA / Gnu FDL}

Galera Cluster ships with the MariaDB Server. Upgrading a Galera Cluster node is very similar to upgrading a server from to . For more information on that process as well as incompatibilities between versions, see the .

Performing a Rolling Upgrade

The following steps can be used to perform a rolling upgrade from to when using Galera Cluster. In a rolling upgrade, each node is upgraded individually, so the cluster is always operational. There is no downtime from the application's perspective.

First, before you get started:

1. First, take a look at to see what has changed between the major versions.

2. Check whether any system variables or options have been changed or removed. Make sure that your server's configuration is compatible with the new MariaDB version before upgrading.

3. Check whether replication has changed in the new MariaDB version in any way that could cause issues while the cluster contains upgraded and non-upgraded nodes.

4. Check whether any new features have been added to the new MariaDB version. If a new feature in the new MariaDB version cannot be replicated to the old MariaDB version, then do not use that feature until all cluster nodes have been upgrades to the new MariaDB version.

5. Next, make sure that the Galera version numbers are compatible.

6. If you are upgrading from the most recent release to , then the versions will be compatible.

7. See What is MariaDB Galera Cluster?: Galera wsrep provider Version s for information on which MariaDB releases uses which Galera wsrep provider versions.

8. You want to have a large enough gcache to avoid a State Snapshot Transfer (SST) during the rolling upgrade. The gcache size can be configured by setting gcache.size For example:wsrep_provider_options="gcache.size=2G"

Before you upgrade, it would be best to take a backup of your database. This is always a good idea to do before an upgrade. We would recommend .

Then, for each node, perform the following steps:

sudo apt-get remove mariadb-server galera

sudo yum remove MariaDB-server galera

sudo zypper remove MariaDB-server galera

When this process is done for one node, move onto the next node.

_{This page is licensed: CC BY-SA / Gnu FDL}

Galera Cluster ships with the MariaDB Server. Upgrading a Galera Cluster node is very similar to upgrading a server from to . For more information on that process as well as incompatibilities between versions, see the .

Performing a Rolling Upgrade

The following steps can be used to perform a rolling upgrade from to when using Galera Cluster. In a rolling upgrade, each node is upgraded individually, so the cluster is always operational. There is no downtime from the application's perspective.

First, before you get started:

1. First, take a look at to see what has changed between the major versions.

2. Check whether any system variables or options have been changed or removed. Make sure that your server's configuration is compatible with the new MariaDB version before upgrading.

3. Check whether replication has changed in the new MariaDB version in any way that could cause issues while the cluster contains upgraded and non-upgraded nodes.

4. Check whether any new features have been added to the new MariaDB version. If a new feature in the new MariaDB version cannot be replicated to the old MariaDB version, then do not use that feature until all cluster nodes have been upgrades to the new MariaDB version.

5. Next, make sure that the Galera version numbers are compatible.

6. If you are upgrading from the most recent release to , then the versions will be compatible.

7. See What is MariaDB Galera Cluster?: Galera wsrep provider Versions for information on which MariaDB releases uses which Galera wsrep provider versions.

8. You want to have a large enough gcache to avoid a State Snapshot Transfer (SST) during the rolling upgrade. The gcache size can be configured by setting gcache.size for example:wsrep_provider_options="gcache.size=2G"

Before you upgrade, it would be best to take a backup of your database. This is always a good idea to do before an upgrade. We would recommend .

Then, for each node, perform the following steps:

sudo apt-get remove mariadb-server galera

sudo yum remove MariaDB-server galera

sudo zypper remove MariaDB-server galera

When this process is done for one node, move onto the next node.

_{This page is licensed: CC BY-SA / Gnu FDL}

Galera Cluster ships with the MariaDB Server. Upgrading a Galera Cluster node is very similar to upgrading a server from to . For more information on that process as well as incompatibilities between versions, see the .

Methods

• Stopping all nodes, upgrading all nodes, then starting the nodes

• Rolling upgrade with IST (however, see MDEV-33263)

• Note that rolling upgrade with SST does not work

Performing a Rolling Upgrade

The following steps can be used to perform a rolling upgrade from to when using Galera Cluster. In a rolling upgrade, each node is upgraded individually, so the cluster is always operational. There is no downtime from the application's perspective.

First, before you get started:

1. First, take a look at to see what has changed between the major versions.

2. Check whether any system variables or options have been changed or removed. Make sure that your server's configuration is compatible with the new MariaDB version before upgrading.

3. Check whether replication has changed in the new MariaDB version in any way that could cause issues while the cluster contains upgraded and non-upgraded nodes.

4. Check whether any new features have been added to the new MariaDB version. If a new feature in the new MariaDB version cannot be replicated to the old MariaDB version, then do not use that feature until all cluster nodes have been upgrades to the new MariaDB version.

5. Next, make sure that the Galera version numbers are compatible.

6. If you are upgrading from the most recent release to , then the versions will be compatible.

7. See What is MariaDB Galera Cluster?: Galera wsrep provider Versions for information on which MariaDB releases uses which Galera wsrep provider versions.

8. You want to have a large enough gcache to avoid a State Snapshot Transfer (SST) during the rolling upgrade. The gcache size can be configured by setting gcache.size For example:wsrep_provider_options="gcache.size=2G"

Before you upgrade, it would be best to take a backup of your database. This is always a good idea to do before an upgrade. We would recommend .

Then, for each node, perform the following steps:

sudo apt-get remove mariadb-server galera

sudo yum remove MariaDB-server galera

sudo zypper remove MariaDB-server galera

When this process is done for one node, move onto the next node.

_{This page is licensed: CC BY-SA / Gnu FDL}

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}

Overview

X509 cert in PEM format (implies --ssl).

Details

Parameters

The Basics

Q: What is the MariaDB Advanced Cluster?

MariaDB Advanced Cluster is a new high-availability (HA) database product exclusive to the MariaDB Enterprise portfolio. It replaces traditional synchronous replication (as used in Galera and Enterprise Cluster) with the Raft consensus algorithm. Instead of waiting for every node to acknowledge a write, a transaction is considered "committed" as soon as a majority (quorum) of the nodes safely store the log entry.

Q: What does RAFT stand for?

Technically, Raft is not an acronym. Its creators chose the name because it implies "logs" (as in a replicated log) floating safely together to survive failures. However, the engineering community often uses the backronym Reliable, Replicated, Redundant, And Fault-Tolerant to describe its core characteristics.

The MariaDB Cluster Landscape: Community vs. Enterprise

Q: How do the different clustering products fit into the MariaDB portfolio?

Following MariaDB's acquisition of Codership (the creators of Galera), our high-availability product offerings are clearly tiered between community-driven projects and commercial, mission-critical solutions:

• MariaDB Community Server (with Galera Cluster): The open-source community foundation for synchronous high availability. It provides a flexible growth path and standard HA for non-commercial or less rigorous deployments.

• MariaDB Enterprise Cluster: The production-hardened version of Galera, exclusive to the MariaDB Enterprise Platform. It includes (such as enhanced encryption, non-blocking backups, and comprehensive monitoring) and is optimized for rock-solid stability and zero data loss in mission-critical, localized commercial environments.

• : A fully managed DBaaS version of the Enterprise Cluster. Available on the new PowerPlus tier, it integrates Galera with MariaDB MaxScale for intelligent traffic routing, automated failover for app connections, and zero-data-loss protection without the operational overhead.

The Architecture Question

Q: Is MariaDB Advanced Cluster replacing Galera or MariaDB Enterprise Cluster?

MariaDB Advanced Cluster can be seen as the next evolution of Galera Clustering technology. It is aiming to solve the same problems while at the same time addressing some of the issues the existing Galera Cluster solution inherently has due to the nature of the technology. While Galera is the gold standard of local "High Availability", Advanced Cluster allows us to address more complex usage scenarios.

If you are running Community Server, you can continue to use standard Galera. If you are running Enterprise Server or MariaDB Cloud, you have the choice between the Galera-powered MariaDB Enterprise Cluster (for local zero-data-loss) or the Raft-powered MariaDB Advanced Cluster (for global WAN environments).

Real-World Scenarios: Handling Network Latency

Q: Can you provide an example of how MariaDB Advanced Cluster handles network latency compared to MariaDB Enterprise Cluster?

To understand the architectural difference, imagine running a mission-critical web application spanning three distinct geographic locations to ensure disaster recovery. You deploy a 7-node cluster:

• New York (NY): 3 Nodes (Primary App Region)

• London (LON): 2 Nodes (Secondary Region)

• Tokyo (TYO): 2 Nodes (DR Region, highest latency relative to NY)

Scenario A: The Traditional Galera Way (MariaDB Enterprise Cluster)

In a Galera-based cluster, data integrity is paramount. Because Galera's virtual synchrony messaging is multi-master and leaderless, all nodes must communicate to agree on the exact ordering of messages. There are three communication steps during which message exchange happens concurrently:

1. The Broadcast: The NY App writes to an NY node. That node immediately broadcasts the write-set to all 6 other nodes simultaneously (NY → LON and NY → TYO).

2. The Ordering Agreement: Because anyone could be writing at the same time, LON and TYO must also communicate with each other (LON → TYO and TYO → LON) to agree on the message order.

3. The Bottleneck: The initiating NY node must wait to receive acknowledgments from every single node in the cluster (LON → NY and TYO → NY). It is forced to wait for the slowest communication hops (Tokyo).

Result: Your application's write performance in New York is directly tied to your worst-case network latency and the complex ordering hops to Tokyo.

Scenario B: The MariaDB Advanced Cluster Way (Using Raft)

With the Advanced Cluster using Raft, the mechanics change to prioritize consensus over total unanimity.

1. The Quorum Calculation: In a 7-node cluster, a majority is 4 nodes.

2. The Write: The NY App sends the write to the cluster's elected Leader (in NY).

3. The Log & Broadcast: The Leader appends the data to its log and broadcasts it to the 6 Followers.

4. The Race: The Leader has the data (Count: 1). The 2 other NY nodes respond instantly (Count: 3).

Result: The Leader completely ignores the latency of the furthest outlier (Tokyo). Your application's write performance is decoupled from your worst-case network scenario.

Specification Comparison: Galera vs. Raft

Q: When should we use Galera vs. Advanced Cluster (Raft)?

Understanding the mechanical differences makes it clear why these technologies serve different environments.

Key Performance Advantages (Advanced Cluster Use Cases)

Because of these architectural differences, MariaDB Advanced Cluster clearly outperforms Enterprise Cluster in several specific scenarios:

1. Geo-Distributed Replicas: When nodes are spread across vast distances, Advanced Cluster is significantly faster. Why? Because its single-leader, log-based consensus model completely eliminates the need for the complex, multi-directional transaction certification and ordering agreements required by Galera.

2. Slower or Degrading Hardware: Advanced Cluster is highly resilient to localized performance degradation. Why? Because it only requires a majority to commit. If a single machine experiences a CPU spike, disk latency, or a degrading network link, the Leader simply commits using the faster majority, never waiting for the slowest machine to catch up.

Operations, Fault Tolerance, and Leader Election

Q: How does fault tolerance and recovery work in the Advanced Cluster?

Raft achieves fault tolerance through an automated leader election process. Because it relies on a quorum, a Raft cluster can safely tolerate the loss of up to $\frac{N-1}{2}$ nodes. For example, a 7-node cluster can lose 3 nodes and remain fully operational, with no risk of split-brain scenarios.

Q: Exactly how is a new Leader elected if the current one fails?

The Raft consensus algorithm handles leader elections automatically and rapidly using "heartbeats" and randomized timers:

1. The Trigger (Election Timeout): All Follower nodes expect constant, periodic "heartbeat" messages from the Leader. If a Follower stops receiving these heartbeats, it assumes the Leader has crashed.

2. The Campaign: That Follower immediately promotes itself to a "Candidate" state, votes for itself, and broadcasts a message to all other nodes asking for their votes.

3. The Vote: The other Follower nodes will evaluate the request. They will vote for the Candidate as long as that Candidate's data log is at least as up-to-date as their own, and they haven't already voted in this cycle.

The instructions on this page were used to create the galera package on the Ubuntu and Debian Linux distributions. This package contains the wsrep provider for MariaDB Galera Cluster.

The version of the wsrep provider is 25.3.5. We also provide 25.2.9 for those that need or want it. Prior to that, the wsrep version was 23.2.7.

1. Install prerequisites:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get -y install check debhelper libasio-dev libboost-dev libboost-program-options-dev libssl-dev scons

1. Clone from and checkout mariadb-3.x banch:

1. Build the packages by executing build.sh under scripts/ directory with -p switch:

When finished, you will have the Debian packages for galera library and arbitrator in the parent directory.

Running galera test suite

If you want to run the galera test suite (mysql-test-run --suite=galera), you need to install the galera library as either /usr/lib/galera/libgalera_smm.so or /usr/lib64/galera/libgalera_smm.so

_{This page is licensed: CC BY-SA / Gnu FDL}

URLs in Galera take a particular format:

<schema>://<cluster_address>[?option1=value1[&option2=value2]]

Schema

• gcomm⁣- This is the option to use for a working implementation.

• dummy⁣- Used for running tests and profiling, does not do any actual replication, and all following parameters are ignored.

Cluster address

• The cluster address shouldn't be empty like gcomm://. This should never be hardcoded into any configuration files.

• To connect the node to an existing cluster, the cluster address should contain the address of any member of the cluster you want to join.

• The cluster address can also contain a comma-separated list of multiple members of the cluster. It is good practice to list all possible members of the cluster, for example. ⁣gcomm:<node1 name or ip>,<node2 name or ip2>,<node3 name or ip>

Option list

• The variable is used to set a . These parameters can also be provided (and overridden) as part of the URL. Unlike options provided in a configuration file, they will not endure and need to be resubmitted with each connection.

A useful option to set is pc.wait_prim=noto ensure the server will start running even if it can't determine a primary node. This is useful if all members go down at the same time.

Port

By default, gcomm listens on all interfaces. The port is either provided in the cluster address or will default to 4567 if not set.

_{This page is licensed: CC BY-SA / Gnu FDL}

Hybrid replication leverages standard, asynchronous MariaDB Replication to copy data from a synchronous MariaDB Galera Cluster to an external server or another cluster. This configuration establishes a one-way data flow, where the entire Galera Cluster serves as the source (primary) for one or more asynchronous replicas. This advanced setup combines the strengths of both replication methods: synchronous replication ensures high availability within the primary site, while asynchronous replication caters to specific use cases, allowing for flexible data distribution.

Common Use Cases

Implementing a hybrid replication setup is a powerful technique for solving several common business needs:

Key Challenges and Considerations

Before implementing a hybrid setup, it is critical to understand the technical challenges:

_{This page is licensed: CC BY-SA / Gnu FDL}

Overview

Name for the cluster.

Details

This system variable specifies the logical name of the cluster. Every Cluster Node that connects to each other must have the same logical name in order to form a component or join the Primary Component.

Parameters

Examples

Configuration

Set the cluster name using an options file:

Show Configuration

To view the current cluster name, use the statement:

Quickstart Guide: About Galera Replication

Galera Replication is a core technology enabling MariaDB Galera Cluster to provide a highly available and scalable database solution. It is characterized by its virtually synchronous replication, ensuring strong data consistency across all cluster nodes.

To facilitate development and QA, we have created some test repositories for the Galera wsrep provider.

Galera Test Repositories for YUM

Replace ${dist} in the code below for the YUM-based distribution you are testing. Valid distributions are:

Auto-Eviction enhances cluster stability by automatically removing non-responsive or "unhealthy" in MariaDB Galera Cluster. This prevents a single problematic node from degrading the entire cluster's . In a Galera Cluster, each node monitors the network response times of other nodes. If a node becomes unresponsive due to reasons like memory swapping, network congestion, or a hung process, it can delay and potentially disrupt cluster operations. Auto-Eviction provides a deterministic method to isolate these misbehaving nodes effectively.

Auto-Eviction Process

The Auto-Eviction process is based on a consensus mechanism among the healthy cluster members.

The recommended strategy for creating a full, consistent backup of a MariaDB Galera Cluster is to perform the backup on a single . Because all nodes in a contain the same data, a complete backup from one node represents a snapshot of the entire cluster at a specific point in time.

The preferred tool for this is . mariadb-backup creates a "hot" backup without blocking the node from serving traffic for an extended period.

The Challenge of Consistency in a Live Cluster

Certification-based replication uses and transaction ordering techniques to achieve synchronous replication.

Transactions execute optimistically in a , or replica, and then at commit time, they run a coordinated certification process to enforce global consistency. It achieves global coordination with the help of a broadcast service that establishes a global total order among concurrent transactions.

Requirements for Certification-Based Replication

It is not possible to implement certification-based replication for all database systems. It requires certain features of the database in order to work:

While a client application can connect directly to any node in a MariaDB Galera Cluster, this is not a practical approach for a production environment. A direct connection creates a single point of failure and does not allow the application to take advantage of the cluster's high availability and read-scaling capabilities.

A load balancer or database proxy is an essential component that sits between your application and the cluster. Its primary responsibilities are:

• Provide a Single Endpoint: Your application connects to the load balancer's virtual IP address, not to the individual database nodes.

wsrep_sst_common Variables

The wsrep_sst_common script provides shared functionality used by various State Snapshot Transfer (SST) methods in Galera Cluster. It centralizes the handling of common configurations such as authentication credentials, SSL/TLS encryption parameters, and other security-related settings. This ensures consistent and secure communication between cluster nodes during the SST process.

Overview

State snapshot transfer method.

Overview

Explicitly enables TLS usage by the wsrep provider.

The wsrep_provider_options system variable applies to MariaDB Enterprise Cluster, powered by Galera and to Galera Cluster available with MariaDB Community Server. This page relates specifically to the socket.ssl wsrep_provider_options.

Controls whether the node performs application-level protocol version checks when joining a cluster.

The wsrep_provider_options system variable applies to MariaDB Enterprise Cluster, powered by Galera and to Galera Cluster available with MariaDB Community Server. This page relates specifically to the gcs.check_appl_proto wsrep_provider_options.

Details

Galera Cluster automatically uses the highest protocol version supported by all nodes. This prevents older nodes, which lack support for newer features, from joining or disrupting the cluster until an upgrade solution is available.

However, MySQL and MariaDB have evolved differently, and their internal protocol versions are incomparable. This incompatibility prevents a mixed-node cluster (MySQL nodes and MariaDB nodes) from forming, which blocks rolling migrations.

Migration Usage: When (e.g., Percona XtraDB Cluster) to MariaDB Galera Cluster, this parameter must be set to FALSE (OFF) on all nodes to disable the protocol check. Once the cluster is fully migrated to MariaDB, it should be set back to TRUE.

Examples

Display Current Value

wsrep_provider_options define optional settings the node passes to the wsrep provider.

To display current wsrep_provider_options values:

The expected output will display the option and the value. Options with no default value will not be displayed in the output.

Set in Configuration File

When changing a setting for a wsrep_provider_options in the config file, you must list EVERY option that is to have a value other than the default value. Options that are not explicitly listed are reset to the default value.

Options are set in the my.cnf configuration file. Use the ; delimiter to set multiple options.

The configuration file must be updated on each node. A restart to each node is needed for changes to take effect.

Use a quoted string that includes every option where you want to override the default value. Options that are not in the list will reset to their default value.

To set the option in the configuration file (example for migration):

Set Dynamically

The gcs.check_appl_proto option cannot be set dynamically. It can only be set in the configuration file.

Trying to change a non-dynamic option with SET results in an error:

Overview

Defines the path to the SSL certificate key.

The wsrep_provider_options system variable applies to MariaDB Enterprise Cluster, powered by Galera and to Galera Cluster available with MariaDB Community Server. This page relates specifically to the socket.ssl_key wsrep_provider_options.

Details

The node uses the certificate key, a self-signed private key, in encrypting replication traffic over SSL. You can use either an absolute path or one relative to the working directory. The file must use PEM format.

Examples

Display Current Value

wsrep_provider_options define optional settings the node passes to the wsrep provider.

To display current wsrep_provider_options values:

The expected output will display the option and the value. Options with no default value, for example SSL options, will not be displayed in the output.

Set in Configuration File

When changing a setting for a wsrep_provider_options in the config file, you must list EVERY option that is to have a value other than the default value. Options that are not explicitly listed are reset to the default value.

Options are set in the my.cnf configuration file. Use the ; delimiter to set multiple options.

The configuration file must be updated on each node. A restart to each node is needed for changes to take effect.

Use a quoted string that includes every option where you want to override the default value. Options that are not in the list will reset to their default value.

To set the option in the configuration file:

Set Dynamically

The socket.ssl_key option cannot be set dynamically. It can only be set in the configuration file.

Trying to change a non-dynamic option with SET results in an error:

Overview

Defines the path to the SSL certificate.

The wsrep_provider_options system variable applies to MariaDB Enterprise Cluster, powered by Galera and to Galera Cluster available with MariaDB Community Server. This page relates specifically to the socket.ssl_cert wsrep_provider_options.

Details

The node uses the certificate as a self-signed public key in encrypting replication traffic over SSL. You can use either an absolute path or one relative to the working directory. The file must use PEM format.

Examples

Display Current Value

wsrep_provider_options define optional settings the node passes to the wsrep provider.

To display current wsrep_provider_options values:

The expected output will display the option and the value. Options with no default value, for example SSL options, will not be displayed in the output.

Set in Configuration File

When changing a setting for a wsrep_provider_options in the config file, you must list EVERY option that is to have a value other than the default value. Options that are not explicitly listed are reset to the default value.

Options are set in the my.cnf configuration file. Use the ; delimiter to set multiple options.

The configuration file must be updated on each node. A restart to each node is needed for changes to take effect.

Use a quoted string that includes every option where you want to override the default value. Options that are not in the list will reset to their default value.

To set the option in the configuration file:

Set Dynamically

The socket.ssl_cert option cannot be set dynamically. It can only be set in the configuration file.

Trying to change a non-dynamic option with SET results in an error:

Overview

Defines the path to the SSL Certificate Authority (CA) file.

The wsrep_provider_options system variable applies to MariaDB Enterprise Cluster, powered by Galera and to Galera Cluster available with MariaDB Community Server. This page relates specifically to the socket.ssl_ca wsrep_provider_options.

Details

The node uses the CA file to verify the signature on the certificate. You can use either an absolute path or one relative to the working directory. The file must use PEM format.

Examples

Display Current Value

wsrep_provider_options define optional settings the node passes to the wsrep provider.

To display current wsrep_provider_options values:

The expected output will display the option and the value. Options with no default value, for example SSL options, will not be displayed in the output.

Set in Configuration File

When changing a setting for a wsrep_provider_options in the config file, you must list EVERY option that is to have a value other than the default value. Options that are not explicitly listed are reset to the default value.

Options are set in the my.cnf configuration file. Use the ; delimiter to set multiple options.

The configuration file must be updated on each node. A restart to each node is needed for changes to take effect.

Use a quoted string that includes every option where you want to override the default value. Options that are not in the list will reset to their default value.

To set the option in the configuration file:

Set Dynamically

The socket.ssl_ca option cannot be set dynamically. It can only be set in the configuration file.

Trying to change a non-dynamic option with SET results in an error:

Overview

Print warning about certificate expiration if the X509 certificate used for wsrep connections is about to expire in hours given as an argument. If the value is 0, warnings are not printed.

Usage

The wsrep_certificate_expiration_hours_warning system variable can be set in a configuration file:

The global value of the wsrep_certificate_expiration_hours_warning system variable can also be set dynamically at runtime by executing :

When the wsrep_certificate_expiration_hours_warning system variable is set dynamically at runtime, its value will be reset the next time the server restarts. To make the value persist on restart, set it in a configuration file too.

Details

The wsrep_certificate_expiration_hours_warning system variable can be used to configure certificate expiration warnings for MariaDB Enterprise Cluster, powered by Galera:

• When the wsrep_certificate_expiration_hours_warning system variable is set to 0, certificate expiration warnings are not printed to the .

• When the wsrep_certificate_expiration_hours_warning system variable is set to a value N, which is greater than 0, certificate expiration warnings are printed to the MariaDB Error Log when the node's certificate expires in N

Parameters

Overview

CA directory (check OpenSSL docs, implies --ssl).

Details

Parameters

Overview

X509 key in PEM format (implies --ssl).

Details

Parameters

Overview

CA file in PEM format (check OpenSSL docs, implies --ssl).

Details

Parameters

MariaDB Enterprise Cluster is a solution designed to handle high workloads exceeding the capacity of a single server. It is based on Galera Cluster technology integrated with MariaDB Enterprise Server and includes features like data-at-rest encryption for added security. This multi-primary replication alternative is ideal for maintaining data consistency across multiple servers, providing enhanced reliability and scalability.

Overview

MariaDB Enterprise Cluster, powered by Galera, is available with MariaDB Enterprise Server. MariaDB Galera Cluster is available with MariaDB Community Server.

There are binary installation packages available for RPM and Debian-based distributions, which will pull in all required Galera dependencies.

If these are not available, you will need to build Galera from source.

The wsrep API for Galera Cluster is included by default. Follow the usual instructions

Preparation

MariaDB Galera Cluster provides a powerful automation feature through the wsrep_notify_cmd . When this variable is configured, the MariaDB server will automatically execute a specified command or script in response to changes in the cluster's membership or the local node's state.

This is extremely useful for integrating the cluster with external systems:

MariaDB Galera Cluster is flexible and can be deployed in several different topologies to meet various business needs, from within a single data center to geographically distributed disaster recovery. The primary deployment patterns are designed for Local Area Networks (LAN) and Wide Area Networks (WAN).

Standard LAN Cluster (Single Data Center)

This is the most common deployment pattern for achieving high availability and read scaling within a single data center.

By default, Galera Cluster replicates data between each node without encrypting it. This is generally acceptable when the cluster nodes runs on the same host or in networks where security is guaranteed through other means. However, in cases where the cluster nodes exist on separate networks or they are in a high-risk network, the lack of encryption does introduce security concerns as a malicious actor could potentially eavesdrop on the traffic or get a complete copy of the data by .

To mitigate this concern, Galera Cluster allows you to encrypt data in transit as it is replicated between each cluster node using the Transport Layer Security (TLS) protocol. TLS was formerly known as Secure Socket Layer (SSL), but strictly speaking the SSL protocol is a predecessor to TLS and, that version of the protocol is now considered insecure. The documentation still uses the term SSL often and for compatibility reasons TLS-related server system and status variables still use the prefix ssl_, but internally, MariaDB only supports its secure successors.

In order to secure connections between the cluster nodes, you need to ensure that all servers were compiled with TLS support. See to determine how to check whether a server was compiled with TLS support.

When a network failure or a crash affects over half of your cluster nodes, the cluster might lose its . In such cases, the remaining nodes may return an Unknown command error for many queries. This behavior is a safeguard to prevent data inconsistency.

You can confirm this by checking the wsrep_cluster_status on all nodes:

If none of your nodes return a value of Primary, you must manually intervene to reset the Quorum and bootstrap a new Primary Component.

Sometimes it can be helpful to perform a "manual SST" when Galera's fail. This can be especially useful when the cluster's is very large, since a normal SST can take a long time to fail in that case.

A manual SST essentially consists of taking a backup of the donor, loading the backup on the joiner, and then manually editing the cluster state on the joiner node. This page will show how to perform this process with .

Process

MariaDB's are very useful when used with , which is primarily what that feature was developed for. , on the other hand, was developed by Codership for all MySQL and MariaDB variants, and the initial development of the technology pre-dated MariaDB's implementation. As a side effect, (at least until ) only partially supports MariaDB's implementation.

GTID Support for Write Sets Replicated by Galera Cluster

Galera Cluster has its own that is substantially different from

MariaDB Galera Cluster supports a weighted quorum, where each node can be assigned a weight in the range of 0 to 255, with which it will participate in quorum calculations. This provides fine-grained control over which nodes are most critical for forming a , especially in complex or .

By default, every has a weight of 1. You can customize a node's weight during runtime by setting the pc.weight :

Summary

In MariaDB Cluster, transactions are replicated using the wsrep API, synchronously ensuring consistency across nodes. Synchronous replication offers high availability and consistency but is complex and potentially slower compared to asynchronous replication. Due to these challenges, asynchronous replication is often preferred for database performance and scalability, as seen in popular systems like MySQL and PostgreSQL, which typically favor asynchronous or semi-synchronous solutions.

In MariaDB Cluster, the server replicates a transaction at commit time by broadcasting the write set associated with the transaction to every node in the cluster. The client connects directly to the DBMS and experiences behavior that is similar to native MariaDB in most cases. The wsrep API (write set replication API) defines the interface between Galera replication and MariaDB.

Synchronous vs. Asynchronous Replication

The basic difference between synchronous and asynchronous replication is that "synchronous" replication guarantees that if a change happened on one node in the cluster, then the change will happen on other nodes in the cluster "synchronously," or at the same time. "Asynchronous" replication gives no guarantees about the delay between applying changes on the "master" node and the propagation of changes to "slave" nodes. The delay with "asynchronous" replication can be short or long. This also implies that if a master node crashes in an "asynchronous" replication topology, then some of the latest changes may be lost.

Theoretically, synchronous replication has several advantages over asynchronous replication:

• Clusters utilizing synchronous replication are always highly available. If one of the nodes crashed, then there would be no data loss. Additionally, all cluster nodes are always consistent.

• Clusters utilizing synchronous replication allow transactions to be executed on all nodes in parallel.

• Clusters utilizing synchronous replication can guarantee causality across the whole cluster. This means that if a transactionSELECT is executed on one cluster node after a transaction is executed on another cluster node, it should see the effects of that transaction.

However, in practice, synchronous database replication has traditionally been implemented via the so-called "2-phase commit" or distributed locking, which proved to be very slow. Low performance and complexity of implementation of synchronous replication led to a situation where asynchronous replication remains the dominant means for database performance scalability and availability. Widely adopted open-source databases such as MySQL or PostgreSQL offer only asynchronous or semi-synchronous replication solutions.

Galera's replication is not completely synchronous. It is sometimes called virtually synchronous replication.

Certification-Based Replication Method

An alternative approach to synchronous replication that uses group communication and transaction ordering techniques was suggested by a number of researchers. For example:

Prototype implementations have shown a lot of promise. We combined our experience in synchronous database replication and the latest research in the field to create the Galera Replication library and the wsrep API.

Galera replication is a highly transparent, scalable, and virtually synchronous replication solution for database clustering to achieve high availability and improved performance. Galera-based clusters are:

• Highly available

• Highly transparent

• Highly scalable (near-linear scalability may be reached depending on the application)

Generic Replication Library

Galera replication functionality is implemented as a shared library and can be linked with any transaction processing system that implements the wsrep API hooks.

The Galera replication library is a protocol stack providing functionality for preparing, replicating, and applying transaction write sets. It consists of:

• wsrep API specifies the interface responsibilities for DBMS and replication provider

• wsrep hooks is the wsrep integration in the DBMS engine.

• Galera provider implements the wsrep API for Galera library

• certification layer takes care of preparing write sets and performing certification

Many components in the Galera replication library were redesigned and improved with the introduction of Galera 4.

Galera Slave Threads

Although the Galera provider certifies the write set associated with a transaction at commit time on each node in the cluster, this write set is not necessarily applied on that cluster node immediately. Instead, the write set is placed in the cluster node's receive queue on the node, and it is eventually applied by one of the cluster node's Galera slave threads.

The number of Galera slave threads can be configured with the system variable.

The Galera slave threads are able to determine which write sets are safe to apply in parallel. However, if your cluster nodes seem to have frequent consistency problems, then setting the value to 1 will probably fix the problem.

When a cluster node's state, as seen by , is⁣JOINED, then increasing the number of slave threads may help the cluster node catch up with the cluster more quickly. In this case, it may be useful to set the number of threads to twice the number of CPUs on the system.

Streaming Replication

Streaming replication was introduced in Galera 4.

In older versions of MariaDB Cluster, there was a 2GB limit on the size of the transaction you could run. The node waits on the transaction commit before performing replication and certification. With large transactions, long-running writes, and changes to huge datasets, there was a greater possibility of a conflict forcing a rollback on an expensive operation.

Using streaming replication, the node breaks huge transactions up into smaller and more manageable fragments; it then replicates these fragments to the cluster as it works instead of waiting for the commit. Once certified, the fragment can no longer be aborted by conflicting transactions. As this can have performance consequences both during execution and in the event of rollback, it is recommended that you only use it with large transactions that are unlikely to experience conflict.

For more information on streaming replication, see the documentation.

Group Commits

Group Commit support for MariaDB Cluster was introduced in Galera 4.

In MariaDB Group Commit, groups of transactions are flushed together to disk to improve performance. In previous versions of MariaDB, this feature was not available in MariaDB Cluster, as it interfered with the global ordering of transactions for replication. MariaDB Cluster can now take advantage of Group Commit.

For more information on Group Commit, see the documentation.

See Also

_{This page is licensed: CC BY-SA / Gnu FDL}

allows for the generation of unique integers independent of any specific table. While standard sequences function normally in a standalone MariaDB server, using them in a MariaDB Galera Cluster requires specific configurations to ensure conflict-free operation and optimal performance.

Configuring Sequences for Galera

Because Galera is a multi-primary system, multiple nodes may attempt to generate sequence values simultaneously. To prevent duplicate values and certification failures, the cluster utilizes an offset-based generation strategy.

Mandatory: INCREMENT BY 0

For a sequence to function correctly in a multi-node environment, it must be defined with INCREMENT BY 0.

This setting instructs the node to ignore the sequence's internal increment logic. Instead, the node applies the cluster-wide wsrep_auto_increment_control logic using the following formula:

Where:

• Node_Offset: The unique identifier for the specific node (e.g., 1, 2, or 3).

• Cluster_Size: The total number of nodes in the cluster.

• N: The iteration count (0, 1, 2, ...).

Visualizing the Offset Logic

The following diagram illustrates how two nodes in a 3-node cluster generate unique IDs simultaneously without communicating or locking.

This ensures that nodes generate interleaved, non-conflicting IDs preventing Certification Failures (Error 1213) without requiring network locks.

Cache Configuration Strategies

The CACHE option is the primary lever for balancing performance against data continuity. In Galera, replication introduces a "Flush-on-Sync" behavior: when any node commits a sequence update, other nodes must sync their state, discarding any unused values in their local cache.

Use Case: Active-Active Ticket Reservation System

A common requirement for Galera is a distributed system (e.g., ticket sales) where users in different regions must be able to book items simultaneously without "race conditions" or duplicate Booking IDs.

In this example, we configure a sequence to allow high-speed concurrent bookings from multiple nodes.

Troubleshooting

This page is licensed: CC BY-SA / Gnu FDL

MariaDB Galera Cluster provides a synchronous replication system that uses an approach often called eager replication. In this model, nodes in a cluster synchronize with all other nodes by applying replicated updates as a single transaction. This means that when a transaction COMMITs, all nodes currently part of the Primary Component are guaranteed to reach a consistent state by applying replicated updates in the same global serial order. This 'virtually synchronous' approach ensures that while the change is replicated immediately, nodes maintain logical consistency across the active majority of the cluster even if some individual nodes are temporarily lagging or offline.This process is accomplished using write-set replication through a group communication framework.

Core Architectural Components

The internal architecture of MariaDB Galera Cluster revolves around four primary components:

MariaDB Server (DBMS)

The foundation of the cluster is the standard MariaDB Server, typically using the InnoDB storage engine. This component serves clients that connect to it and executes queries as a normal database server would.

The wsrep API

The wsrep API is a generic replication plugin interface for databases. It defines a set of application callbacks and replication plugin calls that connect the MariaDB Server to the replication provider. It consists of two main elements:

• wsrep Hooks: These hooks integrate with the database server engine to enable write-set replication.

• dlopen(): This function is used to make the (the Galera Plugin) available to the wsrep hooks.

In this model, the wsrep API considers the database to have a "state." When clients modify the database content, its state changes. The API represents these changes as a series of atomic transactions. In a healthy cluster, all nodes always have the same because they synchronize by replicating and applying these state changes in the same serial order.

From a technical perspective, the process flow is as follows:

1. A state change (transaction) occurs on one node in the cluster.

2. Within the MariaDB Server, the wsrep hooks translate these changes into a write-set.

3. The dlopen() function makes the wsrep provider's functions available to the hooks.

Galera Replication Plugin

The Galera Replication Plugin implements the wsrep API and acts as the wsrep Provider. It handles the core replication service functionality. The plugin itself consists of the following components:

Group Communication (GComm) Framework

The Galera Replication Plugin uses a Group Communication (GComm) framework for its messaging layer. The GComm system implements a virtual synchrony Quality of Service (QoS), which unifies data delivery and cluster into a clear, formal model.

While virtual synchrony guarantees data consistency, it does not guarantee the temporal synchrony needed for smooth multi-primary operations. To address this, Galera Cluster implements its own runtime-configurable , which keeps nodes synchronized to within a fraction of a second.

The GComm framework also provides a total ordering of messages from multiple sources, which it uses to generate Global Transaction IDs in a multi-primary cluster.

Fundamental Concepts

Global Transaction ID (GTID)

To keep the database state identical across all nodes, the wsrep API uses a Global Transaction ID (GTID). This allows the cluster to uniquely identify every state change and to know the current state of any node in relation to others. An example GTID looks like this:

45eec521-2f34-11e0-0800-2a36050b826b:94530586304

It consists of two components:

• State UUID: A unique identifier for the database state and its sequence of changes.

• Ordinal Sequence Number (seqno): A 64-bit signed integer that denotes the position of the transaction in the sequence.

Read and Write Scaling

A direct benefit of Galera's multi-master architecture is the ability to scale both read and write operations.

• Write Scaling: Because every node in the cluster can accept write operations, you can distribute your application's write traffic across multiple nodes. This can increase write throughput, though it's important to remember that all writes must still be replicated and certified on all nodes, which can introduce .

• Read Scaling: This is the most significant performance advantage. Since all nodes are kept synchronized, they all contain the same data. This allows you to distribute read queries across all nodes in the cluster, providing excellent horizontal scaling for read-heavy applications. This architecture is ideal for use with a load balancer (like MariaDB MaxScale) that can perform read-write splitting.

This scaling is typically managed by a which distributes traffic intelligently across the cluster.

_{This page is licensed: CC BY-SA / Gnu FDL}

Streaming Replication optimizes replication of large or long-running transactions in MariaDB Galera Cluster. Typically, a node executes a transaction fully and replicates the complete write-set to other nodes at time. Although efficient for most workloads, this approach can be challenging for very large or lengthy transactions.

With Streaming Replication, the initiating node divides the transaction into smaller fragments. These fragments are certified and replicated to other nodes while the transaction is ongoing. Once a fragment is certified and applied to the replicas, it becomes immune to abortion by conflicting transactions, thus improving the chances of the entire transaction succeeding. This method also supports processing of transaction write-sets over two Gigabytes.

When to Use Streaming Replication

In most cases, the standard replication method is sufficient. Streaming Replication is a specialized tool for specific scenarios. The best practice is to enable it only at the session level for the specific transactions that require it.

Large Data Transactions

This is the primary use case. When performing a massive , , or , normal replication requires the originating node to hold the entire transaction locally and then send a very large write-set at commit time. This can cause two problems:

1. A significant replication lag, as the entire cluster waits for the large write-set to be transferred and applied.

2. The replica nodes, while busy applying the large transaction, cannot commit other transactions, which can trigger and throttle the entire cluster.

With Streaming Replication, the node replicates the data in fragments throughout the transaction's lifetime. This spreads the network load and allows replica nodes to apply other concurrent transactions between fragments, minimizing the impact on the overall

Long-Running Transactions

A transaction that remains open for a long time has a higher chance of that commits first. When this happens, the long-running transaction is aborted.

Streaming Replication mitigates this by committing the transaction in fragments. Once a fragment is , it is "locked in" and cannot be aborted by a new conflicting transaction.

High-Contention ("Hot") Records

For applications that frequently update the same row (e.g., a counter, a job queue, or a locking scheme), Streaming Replication can be used to force a critical update to replicate immediately. This effectively locks the , preventing other transactions from modifying it and increasing the chance that the critical transaction will commit successfully.

How to Enable and Use Streaming Replication

Streaming Replication should be enabled at the session level just for the transactions that need it. This is controlled by two session variables:

• defines what a "unit" of replication is.

• defines how many units make up a fragment.

To enable streaming, you set both variables:

In the above example, the node will create, certify, and replicate a fragment after every 10 SQL statements within the transaction.

The available fragment units for wsrep_trx_fragment_unit are:

To disable Streaming Replication, you can set wsrep_trx_fragment_size back to 0.

Managing a "Hot Record"

Consider an application that manages a work order queue. To prevent two users from getting the same queue position, you can use Streaming Replication for the single critical update.

1. Begin the transaction:

2. After reading necessary data, enable Streaming Replication for just the next statement:

3. Perform the critical update. This statement will be immediately fragmented and replicated:

4. Immediately disable Streaming Replication for the rest of the transaction:

This ensures the queue_position update is replicated and certified across the cluster before the rest of the transaction proceeds, preventing .

Limitations and Performance Considerations

Before using Streaming Replication, consider the following limitations:

Performance Overhead

When Streaming Replication is enabled, Galera records all write-sets to a log table () on every node to ensure persistence in case of a crash. This adds write overhead and can impact performance, which is why it should only be used when necessary.

Cost of Rollbacks

If a streaming transaction needs to be rolled back after some fragments have already been applied, the rollback operation consumes system resources on all nodes as they undo the previously applied fragments. Frequent rollbacks of streaming transactions can become a performance problem.

For these reasons, it is always a good application design policy to use shorter, smaller transactions whenever possible.

_{This page is licensed: CC BY-SA / Gnu FDL}

Quorum is essential for maintaining data consistency in a MariaDB Galera Cluster by safeguarding against network partitions or node failures. It ensures that the cluster processes database queries and transactions only when a majority of nodes are operational, healthy, and in communication.

Primary Component

This majority group is known as the Primary Component. Nodes not in this group switch to a non-primary state, halting queries and entering a read-only "safe mode" to prevent data discrepancies. The primary function of Quorum is to avoid "split-brain" scenarios, which occur when network partitions lead to parts of the cluster operating independently and accepting writes. By ensuring only the partition with a majority of nodes becomes the Primary Component, Quorum effectively prevents these inconsistencies.

Quorum Calculation

Quorum is achieved when more than 50% of the total nodes in the last known membership are in communication.

• Odd Number of Nodes (Recommended): In a 3-node cluster, a majority is 2. The cluster can tolerate the failure of 1 node and remain operational.

• Even Number of Nodes: In a 2-node cluster, a majority is also 2. If one node fails, the remaining node represents only 50% of the cluster, which is not a majority, and it will lose Quorum. This is why a 2-node cluster has no fault tolerance without an external .

The Galera Arbitrator (garbd)

The Galera Arbitrator (garbd) is the standard solution for clusters with an even number of nodes. It is a lightweight, stateless daemon that acts as a voting member in the cluster without being a full database node. It participates in Quorum calculations, effectively turning an even-numbered cluster into an odd-numbered one. In the diagram, in a 2-node cluster, adding garbd makes the total number of voting members 3, allowing the cluster to maintain Quorum if one database node fails.

Understanding and Recovering from a Split-Brain

A split-brain occurs when a network partition divides the cluster and no resulting group of nodes has a majority (e.g., a 4-node cluster splitting into two groups of 2). By design, both halves of the cluster will fail to achieve a majority, and all nodes will enter a non-Primary state.

If you need to restore service before the network issue is fixed, you must manually intervene:

1. Choose ONE side of the partition to become the new Primary Component.

2. On a single node within that chosen group, execute the following command:

The nodes in this group will now form a new Primary Component. When network connectivity is restored, the nodes from the other partition will automatically rejoin.

Advanced Quorum Control

As a more advanced alternative to garbd for fine-grained control, nodes can also be assigned a specific voting weight.

Monitoring Quorum and Cluster Membership

You can check the health of the cluster and its Quorum status at any time by querying the following .