Get started quickly with MariaDB Galera Cluster using these guides. Follow step-by-step instructions to deploy and configure a highly available, multi-master cluster for your applications.
MariaDB Galera Cluster quickstart guide
MariaDB Galera Cluster provides a multi-primary (active-active) cluster solution for MariaDB, enabling high availability, read/write scalability, and true synchronous replication. This means any node can handle read and write operations, with changes instantly replicated to all other nodes, ensuring no replica lag and no lost transactions. It's exclusively available on Linux.
Before starting, ensure you have:
At least three nodes: For redundancy and avoiding split-brain scenarios (bare-metal or virtual machines).
Linux Operating System: A compatible Debian-based (e.g., Ubuntu, Debian) or RHEL-based (e.g., CentOS, Fedora) distribution.
Synchronized Clocks: All nodes should have NTP configured for time synchronization.
SSH Access: Root or sudo access to all nodes for installation and configuration.
Network Connectivity: All nodes must be able to communicate with each other over specific ports (see Firewall section). Low latency between nodes is ideal.
rsync: Install rsync on all nodes, as it's commonly used for State Snapshot Transfers (SST).
sudo apt install rsync (Debian/Ubuntu)
sudo yum install rsync (RHEL/CentOS)
Install MariaDB Server and the Galera replication provider on all nodes of your cluster.
a. Add MariaDB Repository:
It's recommended to install from the official MariaDB repositories to get the latest stable versions. Use the MariaDB Repository Configuration Tool (search "MariaDB Repository Generator") to get specific instructions for your OS and MariaDB version.
Example for Debian/Ubuntu (MariaDB 10.11):
sudo apt update
sudo apt install dirmngr software-properties-common apt-transport-https ca-certificates curl -y
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash
sudo apt updateb. Install MariaDB Server and Galera:
sudo apt install mariadb-server mariadb-client galera-4 -y # For MariaDB 10.4+ or later, galera-4 is the provider.
# For older versions (e.g., 10.3), use galera-3.c. Secure MariaDB Installation:
Run the security script on each node to set the root password and remove insecure defaults.
sudo mariadb-secure-installationSet a strong root password.
Answer Y to remove anonymous users, disallow remote root login, remove test database, and reload privilege tables.
Open the necessary ports on each node's firewall to allow inter-node communication.
# Example for UFW (Ubuntu)
sudo ufw allow 3306/tcp # MariaDB client connections
sudo ufw allow 4567/tcp # Galera replication (multicast and unicast)
sudo ufw allow 4567/udp # Galera replication (multicast)
sudo ufw allow 4568/tcp # Incremental State Transfer (IST)
sudo ufw allow 4444/tcp # State Snapshot Transfer (SST)
sudo ufw reload
sudo ufw enable # If firewall is not already enabledAdjust for your firewall system (e.g., firewalld for RHEL-based systems).
galera.cnf on Each Node)Create a configuration file (e.g., /etc/mysql/conf.d/galera.cnf) on each node. The content will be largely identical, with specific changes for each node's name and address.
Example galera.cnf content:
[mysqld]
# Basic MariaDB settings
binlog_format=ROW
default_storage_engine=InnoDB
innodb_autoinc_lock_mode=2
bind-address=0.0.0.0 # Binds to all network interfaces. Adjust if you have a specific private IP for cluster traffic.
# Galera Provider Configuration
wsrep_on=ON
wsrep_provider=/usr/lib/galera/libgalera_smm.so # Adjust path if different (e.g., /usr/lib64/galera-4/libgalera_smm.so)
# Galera Cluster Configuration
wsrep_cluster_name="my_galera_cluster" # A unique name for your cluster
# IP addresses of ALL nodes in the cluster, comma-separated.
# Use private IPs if available for cluster communication.
wsrep_cluster_address="gcomm://node1_ip_address,node2_ip_address,node3_ip_address"
# This node's specific configuration
wsrep_node_name="node1" # Must be unique for each node (e.g., node1, node2, node3)
wsrep_node_address="node1_ip_address" # This node's own IP addressImportant:
wsrep_cluster_address: List the IP addresses of all nodes in the cluster on every node.
wsrep_node_name: Must be unique for each node (e.g., node1, node2, node3).
wsrep_node_address: Set to the specific IP address of the node you are configuring.
a. Bootstrapping the First Node:
Start MariaDB on the first node with the --wsrep-new-cluster option. This tells it to form a new cluster. Do this only once for the initial node of a new cluster.
sudo systemctl stop mariadb # Ensure it's stopped
sudo galera_new_cluster # This command often wraps the systemctl start --wsrep-new-cluster
# Alternatively: sudo systemctl start mariadb --wsrep-new-clusterb. Starting Subsequent Nodes:
For the second and third nodes, start the MariaDB service normally. They will discover and join the existing cluster using the wsrep_cluster_address specified in their configuration.
sudo systemctl start mariadbAfter all nodes are started, verify that they have joined the cluster.
a. Check Cluster Size (on any node):
Connect to MariaDB on any node and check the cluster status:
sudo mariadb -u root -pInside the MariaDB shell:
SHOW STATUS LIKE 'wsrep_cluster_size';The Value should match the number of nodes in your cluster (e.g., 3).
b. Test Replication:
On node1, create a new database and a table:
CREATE DATABASE test_db;
USE test_db;
CREATE TABLE messages (id INT AUTO_INCREMENT PRIMARY KEY, text VARCHAR(255));
INSERT INTO messages (text) VALUES ('Hello from node1!');On node2 (or node3), connect to MariaDB and check for the new database and table:
SHOW DATABASES; -- test_db should appear
USE test_db;
SELECT * FROM messages; -- 'Hello from node1!' should appearInsert data from node2:
INSERT INTO messages (text) VALUES ('Hello from node2!');Verify on node1 that the new data is present:
USE test_db;
SELECT * FROM messages; -- 'Hello from node2!' should appearThis confirms synchronous replication is working.
MariaDB Galera Cluster Replication quickstart guide
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.
Galera Replication is a multi-primary replication solution for database clustering. Unlike traditional asynchronous or semi-synchronous replication, Galera ensures that transactions are committed on all nodes (or fail on all) before the client receives a success confirmation. This mechanism eliminates data loss and minimizes replica lag, making all nodes active and capable of handling read and write operations.
The core of Galera Replication revolves around the concept of write sets and the wsrep API:
Write Set Broadcasting: When a client commits a transaction on any node in the cluster, that node (the "donor" for that specific transaction) captures the changes (the "write set") associated with that transaction. This write set is then broadcasted to all other nodes in the cluster.
Certification and Application: Each receiving node performs a "certification" test to ensure that the incoming write set does not conflict with any concurrent transactions being committed locally.
If the write set passes certification, it is applied to the local database, and the transaction is committed on that node.
If a conflict is detected, the conflicting transaction (usually the one that was executed locally) is aborted, ensuring data consistency across the cluster.
Virtually Synchronous: The term "virtually synchronous" means that while the actual data application might happen slightly after the commit on the initiating node, the commit order is globally consistent, and all successful transactions are guaranteed to be applied on all active nodes. A transaction is not truly considered committed until it has passed certification on all nodes.
wsrep API: This API defines the interface between the Galera replication library (the "wsrep provider") and the database server (MariaDB). It allows the database to expose hooks for Galera to capture and apply transaction write sets.
Multi-Primary (Active-Active): All nodes in a Galera Cluster can be simultaneously used for both read and write operations.
Synchronous Replication (Virtual): Data is consistent across all nodes at all times, preventing data loss upon node failures.
Automatic Node Provisioning (SST/IST): When a new node joins or an existing node rejoins, Galera automatically transfers the necessary state to bring it up to date.
State Snapshot Transfer (SST): A full copy of the database is transferred from an existing node to the joining node.
Incremental State Transfer (IST): Only missing write sets are transferred if the joining node is not too far behind.
Automatic Membership Control: Nodes automatically detect and manage cluster membership changes (nodes joining or leaving).
Galera Replication essentially transforms a set of individual MariaDB servers into a robust, highly available, and consistent distributed database system.
MariaDB Galera Cluster usage guide
This guide provides essential information for effectively using and interacting with a running MariaDB Galera Cluster. It covers connection methods, operational considerations, monitoring, and best practices for applications.
Since Galera Cluster is multi-primary, any node can accept read and write connections.
a. Using a Load Balancer (Recommended for Production):
Deploying a load balancer or proxy (like MariaDB MaxScale, ProxySQL, or HAProxy) is the recommended approach.
MariaDB MaxScale: Provides intelligent routing (e.g., readwritesplit, router), connection pooling, and advanced cluster awareness (e.g., binlogrouter for replication clients, switchover for failover).
Other Load Balancers: Configure them to distribute connections across your Galera nodes, typically using health checks on port 3306 or other cluster-specific checks.
b. Direct Connection:
You can connect directly to any individual node's IP address or hostname using standard MariaDB client tools or connectors (e.g., mariadb command-line client, MariaDB Connector/J, Connector/Python).
Example (Command-line):Bash
mariadb -h <node_ip_address> -u <username> -pWhile simple, this method lacks automatic failover; your application would need to handle connection retries and failover logic.
Active-Active: You can perform both read and write operations on any node in the cluster. All successful write operations are synchronously replicated to all other nodes.
Transactions: Standard SQL transactions (START TRANSACTION, COMMIT, ROLLBACK) work as expected. Galera handles the replication of committed transactions.
DDL operations (like CREATE TABLE, ALTER TABLE, DROP TABLE) require special attention in a synchronous multi-primary cluster to avoid conflicts and outages.
Total Order Isolation (TOI) - Default:
This is Galera's default DDL method.
The DDL statement is executed on all nodes in the same order, and it temporarily blocks other transactions on all nodes while it applies.
It ensures consistency but can cause brief pauses in application activity, especially on busy clusters.
Best Practice: Execute DDL during maintenance windows or low-traffic periods.
Rolling Schema Upgrade (RSU) / Percona's pt-online-schema-change:
For large tables or critical production systems, use tools like pt-online-schema-change (from Percona Toolkit) which performs DDL without blocking writes.
This tool works by creating a new table, copying data, applying changes, and then swapping the tables. It's generally preferred for minimizing downtime for ALTER TABLE operations.
wsrep_OSU_method:
This system variable controls how DDL operations are executed.
TOI (default): Total Order Isolation.
RSU: Rolling Schema Upgrade (requires manual steps with pt-online-schema-change).
NBO (Non-Blocking Operations): A newer method allowing non-blocking DDL for some operations, but not fully implemented for all DDL types. Use with caution and test thoroughly.
Regularly monitor your Galera Cluster to ensure its health and consistency.
wsrep_cluster_size: Number of nodes currently in the Primary Component.SQL
SHOW STATUS LIKE 'wsrep_cluster_size';Expected value: the total number of nodes configured (e.g., 3).
wsrep_local_state_comment / wsrep_local_state: The state of the current node.
Synced (4): Node is fully synchronized and operational.
Donor/Desync (2): Node is transferring state to another node.
Joining (1): Node is in the process of joining the cluster.
Donor/Stalled (1): Node is stalled.
wsrep_incoming_addresses: List of incoming connections from other cluster nodes.
wsrep_cert_deps_distance: Indicates flow control. A high value suggests that this node is falling behind and flow control may activate.
wsrep_flow_control_paused: Percentage of time the node was paused due to flow control. High values indicate a bottleneck.
wsrep_local_recv_queue / wsrep_local_send_queue: Size of the receive/send queue. Ideally, these should be close to 0. Sustained high values indicate replication lag or node issues.
Galera Cluster is designed for automatic recovery, but understanding the process is key.
Node Failure: If a node fails, the remaining nodes continue to operate as the Primary Component. The failed node will automatically attempt to rejoin when it comes back online.
Split-Brain Scenarios: If the network partitions the cluster, nodes will try to form a "Primary Component." The partition with the majority of nodes forms the new Primary Component. If no majority can be formed (e.g., a 2-node cluster splits), the cluster will become inactive. A 3-node or higher cluster is recommended to avoid this.
Manual Bootstrapping (Last Resort): If the entire cluster goes down or a split-brain occurs where no Primary Component forms, you might need to manually "bootstrap" a new Primary Component from one of the healthy nodes.
Choose the node that was most up-to-date.
Stop MariaDB on that node.
Start it with: sudo galera_new_cluster or sudo systemctl start mariadb --wsrep-new-cluster.
Start other nodes normally; they will rejoin the bootstrapped component.
Use Connection Pooling: Essential for managing connections efficiently in high-traffic applications.
Short Transactions: Keep transactions as short and concise as possible to minimize conflicts and improve throughput. Long-running transactions increase the risk of rollbacks due to certification failures.
Primary Keys: All tables should have a primary key. Galera relies on primary keys for efficient row-level replication. Tables without primary keys can cause performance degradation and issues.
Retry Logic: Implement retry logic in your application for failed transactions (e.g., due to certification failures, deadlock, or temporary network issues).
Connect to a Load Balancer: Always direct your application's connections through a load balancer or proxy to leverage automatic failover and intelligent routing.
By following these guidelines, you can effectively manage and operate your MariaDB Galera Cluster for high availability and performance.