This is a read-only copy of the MariaDB Knowledgebase generated on 2025-05-01. For the latest, interactive version please visit https://mariadb.com/kb/.

Deploy Galera Cluster Topology

Overview

This procedure describes the deployment of the Galera Cluster topology with MariaDB Enterprise Server, and MariaDB MaxScale 25.01.

MariaDB Enterprise Cluster is powered by Galera.

MariaDB Enterprise Cluster provides read scalability and fault tolerance through virtually synchronous multi-primary certification-based write-set replication (wsrep).

This procedure has 6 steps, which are executed in sequence.

MariaDB products can be deployed in many different topologies to suit specific use cases. Enterprise Cluster can be deployed on its own, or integrated with MariaDB Replication to integrate with other clusters or topologies.

This procedure represents basic product capability with 3 Enterprise Cluster nodes and 1 MaxScale node.

This page provides an overview of the topology, requirements, and deployment procedures.

Please read and understand this procedure before executing.

Procedure Steps

Support

Customers can obtain support by submitting a support case.

Components

The following components are deployed during this procedure:

ComponentFunction
MariaDB Enterprise Server 10.5Modern SQL RDBMS with high availability, pluggable storage engines, hot online backups, and audit logging.
MariaDB MaxScale 25.01Database proxy that extends the availability, scalability, and security of MariaDB Enterprise Servers

MariaDB Enterprise Server Components

ComponentDescription
Enterprise Cluster• MariaDB Enterprise Server leverages the Galera Enterprise 4 wsrep provider plugin
• Provides virtually synchronous multi-primary replication for MariaDB Enterprise Server
• All nodes can handle both reads and writes
• Replicates write-sets to all other nodes in the cluster
• Supports data-at-rest encryption of the write-set cache
InnoDB• General purpose storage engine
• ACID-compliant
• Performance
• Required for Enterprise Cluster

MariaDB MaxScale Components

ComponentDescription
Galera MonitorTracks changes in the state of MariaDB Enterprise Servers operating as Enterprise Cluster nodes.
ListenerListens for client connections to MaxScale, then passes them to the router service associated with the listener
Read Connection RouterRoutes connections from the listener to any available Enterprise Cluster node
Read/Write Split RouterRoutes read operations from the listener to any available Enterprise Cluster node, and routes write operations from the listener to a specific server that MaxScale uses as the primary server
Server ModuleConnection configuration in MaxScale to an Enterprise Cluster node

Topology

es-galera-cluster-topology-no-title

MariaDB Enterprise Cluster topology provides read scalability through certification-based write-set replication (wsrep) that is multi-primary and virtually synchronous.

The Enterprise Cluster topology consists of:

  • 1 or more MaxScale nodes
  • 3 or more MariaDB Enterprise Servers (ES) configured as Enterprise Cluster nodes

The MaxScale nodes:

  • Monitor the health and availability of each Enterprise Cluster node using the Galera Monitor (galeramon)
  • Accept client and application connections
  • Route queries to the Enterprise Cluster nodes using the Read Connection (readconnroute) or the Read/Write Split (readwritesplit) routers.

The Enterprise Cluster nodes:

  • Receive queries from MaxScale
  • Store data locally using the InnoDB storage engine
  • Perform certification-based virtually synchronous replication to other Enterprise Cluster nodes
  • Provide State Snapshot Transfers (SST) to bring MariaDB Enterprise Server nodes into sync with the cluster

Requirements

These requirements are for the Galera Cluster topology when deployed with MariaDB Enterprise Server and MariaDB MaxScale 25.01.

  • Node Count
  • Operating System

Node Count

  • MaxScale nodes, 1 or more are required.
  • Enterprise Cluster nodes, 3 or more are required.

To avoid problems in establishing a quorum in the event of a network partition or outage, MariaDB recommends deploying an odd number of Enterprise Cluster nodes. When using multiple network switches, deploy across an odd number of switches, each with an odd number of nodes. When using multiple data centers, deploy across an odd number of data centers, each with an odd number of switches.

Operating System

In alignment to the enterprise lifecycle, the Galera Cluster topology with MariaDB Enterprise Server and MariaDB MaxScale 25.01 is provided for:

  • AlmaLinux 8 (x86_64, ARM64)
  • AlmaLinux 9 (x86_64, ARM64)
  • Debian 11 (x86_64, ARM64)
  • Debian 12 (x86_64, ARM64)
  • Red Hat Enterprise Linux 8 (x86_64, ARM64)
  • Red Hat Enterprise Linux 9 (x86_64, PPC64LE, ARM64)
  • Red Hat UBI 8 (x86_64, ARM64)
  • Rocky Linux 8 (x86_64, ARM64)
  • Rocky Linux 9 (x86_64, ARM64)
  • SUSE Linux Enterprise Server 15 (x86_64, ARM64)
  • Ubuntu 20.04 LTS (x86_64, ARM64)
  • Ubuntu 22.04 LTS (x86_64, ARM64)
  • Ubuntu 24.04 LTS (x86_64, ARM64)

Quick Reference

MariaDB Enterprise Server Configuration Management

MethodDescription
Configuration FileConfiguration files (such as /etc/my.cnf) can be used to set system-variables and options. The server must be restarted to apply changes made to configuration files.
Command-lineThe server can be started with command-line options that set system-variables and options.
SQLUsers can set system-variables that support dynamic changes on-the-fly using the SET statement.

MariaDB Enterprise Server packages are configured to read configuration files from different paths, depending on the operating system. Making custom changes to Enterprise Server default configuration files is not recommended because custom changes may be overwritten by other default configuration files that are loaded later.

To ensure that your custom changes will be read last, create a custom configuration file with the z- prefix in one of the include directories.

DistributionExample Configuration File Path
• CentOS
• Red Hat Enterprise Linux (RHEL)
• SUSE Linux Enterprise Server (SLES)
/etc/my.cnf.d/z-custom-mariadb.cnf
• Debian
• Ubuntu
/etc/mysql/mariadb.conf.d/z-custom-mariadb.cnf

MariaDB Enterprise Server Service Management

The systemctl command is used to start and stop the MariaDB Enterprise Server service. The galera_new_cluster and galera_recovery scripts are used for Enterprise Cluster-specific operations.

OperationCommand
Startsudo systemctl start mariadb
Stopsudo systemctl stop mariadb
Restartsudo systemctl restart mariadb
Enable during startupsudo systemctl enable mariadb
Disable during startupsudo systemctl disable mariadb
Statussudo systemctl status mariadb
Bootstrap a cluster nodesudo galera_new_cluster
Recover a cluster node's positionsudo galera_recovery

For additional information, see "Start and Stop Services".

MariaDB Enterprise Server Logs

MariaDB Enterprise Server produces log data that can be helpful in problem diagnosis.

Log filenames and locations may be overridden in the server configuration. The default location of logs is the data directory. The data directory is specified by the datadir system variable.

LogSystem Variable/OptionDefault Filename
MariaDB Error Loglog_error<hostname>.err
MariaDB Enterprise Audit Logserver_audit_file_pathserver_audit.log
Slow Query Logslow_query_log_file<hostname>-slow.log
General Query Loggeneral_log_file<hostname>.log
Binary Loglog_bin<hostname>-bin

MaxScale Configuration Management

MaxScale can be configured using several methods. These methods make use of MaxScale's REST API.

MethodBenefits
MaxCtrlCommand-line utility to perform administrative tasks through the REST API. See MaxCtrl Commands.
MaxGUIMaxGUI is a graphical utility that can perform administrative tasks through the REST API.
REST APIThe REST API can be used directly. For example, the curl utility could be used to make REST API calls from the command-line. Many programming languages also have libraries to interact with REST APIs.

The procedure on these pages configures MaxScale using MaxCtrl.

MaxScale Service Management

The systemctl command is used to start and stop the MaxScale service.>

OperationCommand
Startsudo systemctl start maxscale
Stopsudo systemctl stop maxscale
Restartsudo systemctl restart maxscale
Enable during startupsudo systemctl enable maxscale
Disable during startupsudo systemctl disable maxscale
Statussudo systemctl status maxscale

For additional information, "Start and Stop Services".

Next Step

Navigation in the procedure "Deploy Galera Cluster Topology":

Next: Step 1: Install MariaDB Enterprise Server

Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.