Enterprise Server 10.4
Enterprise Server 10.5
Enterprise Server 10.6
Enterprise Server 11.4
MariaDB Replication
Highly available
Asynchronous or semi-synchronous replication
Automatic failover via MaxScale
Manual provisioning of new nodes from backup
Scales reads via MaxScale
Enterprise Server 10.3+, MaxScale 2.5+
This procedure describes the deployment of the Primary/Replica topology with MariaDB Enterprise Server and MariaDB MaxScale.
Primary/Replica topology provides read scalability and fault tolerance through asynchronous or semi-synchronous single-primary replication.
This procedure has 7 steps, which are executed in sequence.
MariaDB products can be deployed in many different topologies to suit specific use cases. The Primary/Replica topology can be deployed on its own, or integrated with MariaDB Enterprise Cluster.
This procedure represents basic product capability with 3 Enterprise Server nodes and 1 MaxScale node.
This page provides an overview of the topology, requirements, and deployment procedure.
Please read and understand this procedure before executing.
Install MariaDB Enterprise Server
Start and Configure MariaDB Enterprise Server on Primary Server
Start and Configure MariaDB Enterprise Server on Replica Servers
Test MariaDB Enterprise Server
Install MariaDB MaxScale
Start and Configure MariaDB MaxScale
Test MariaDB MaxScale
The following components are deployed during this procedure:
MariaDB Enterprise Server
Modern SQL RDBMS with high availability, pluggable storage engines, hot online backups, and audit logging.
Database proxy that extends the availability, scalability, and security of MariaDB Enterprise Servers
General purpose storage engine
ACID-compliant
Performance
Listener
Listens for client connections to MaxScale, then passes them to the router service associated with the listener
MariaDB Monitor
Tracks changes in the state of MariaDB Enterprise Servers.
Read Connection Router
Routes connections from the listener to any available Enterprise Server node
Read/Write Split Router
Routes read operations from the listener to any available Enterprise Server node, and routes write operations from the listener to a specific server operating as the primary server
Server Module
Connection configuration in MaxScale to an Enterprise Server node
Primary/Replica topology provides read scalability and fault tolerance through asynchronous or semi-synchronous single-primary replication of MariaDB Enterprise Server 11.4
The Primary/Replica topology consists of:
1 or more MaxScale nodes
1 Enterprise Server node operating as the primary server
2 or more Enterprise Server nodes operating as replica servers.
The MaxScale nodes:
Monitor the health and availability of the Enterprise Server nodes
Route queries to Enterprise Server nodes using Read/Write Split (readwritesplit
) and Read Connection (readconnroute
) routers.
Promote replica servers in the event that the primary server fails.
The Enterprise Server node operating as the primary server:
Receives write queries from MaxScale, logging them to the Binary Log
Provides Binary Logs to replica servers for replication
The Enterprise Server nodes operating as replica servers:
Receive read queries from MaxScale
Replicate writes asynchronously or semi-synchronously from the primary server
These requirements are for the Primary/Replica topology when deployed with MariaDB Enterprise Server 11.4 and MariaDB MaxScale 25.01.
In alignment to the enterprise lifecycle, the Primary/Replica topology with MariaDB Enterprise Server 11.4 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)
Microsoft Windows (x86_64)
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)
maxscale
MaxScale process owner
mysql
Enterprise Server process owner
Configuration File
Configuration 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-line
The server can be started with command-line options that set system-variables and options.
SQL
Users 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.
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
The systemctl
command is used to start and stop the MariaDB Enterprise Server service.
Start
sudo systemctl start mariadb
Stop
sudo systemctl stop mariadb
Restart
sudo systemctl restart mariadb
Enable during startup
sudo systemctl enable mariadb
Disable during startup
sudo systemctl disable mariadb
Status
sudo systemctl status mariadb
For additional information, see "Starting and Stopping MariaDB".
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 https://app.gitbook.com/o/diTpXxF5WsbHqTReoBsS/s/SsmexDFPv2xG2OTyO5yV/~/changes/381/ha-and-performance/optimization-and-tuning/system-variables/server-system-variables#datadir system variable.
MaxScale can be configured using several methods. These methods make use of MaxScale's REST API.
Command-line utility to perform administrative tasks through the REST API. See MaxCtrl Commands.
MaxGUI is a graphical utility that can perform administrative tasks through the REST API.
The 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.
The systemctl
command is used to start and stop the MaxScale service.
Start
sudo systemctl start maxscale
Stop
sudo systemctl stop maxscale
Restart
sudo systemctl restart maxscale
Enable during startup
sudo systemctl enable maxscale
Disable during startup
sudo systemctl disable maxscale
Status
sudo systemctl status maxscale
For additional information, see "Starting and Stopping MariaDB".
Navigation in the procedure "Deploy Primary/Replica Topology":
This page is: Copyright © 2025 MariaDB. All rights reserved.\
This page details step 1 of the 7-step procedure "Deploy Primary/Replica Topology".
This step installs MariaDB Enterprise Server
The Primary/Replica topology requires 3 or more MariaDB Enterprise Server nodes for High Availability (HA). Nodes must meet requirements.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
MariaDB Corporation provides package repositories for CentOS / RHEL (YUM) and Debian / Ubuntu (APT). A download token is required to access the MariaDB Enterprise Repository.
Customer Download Tokens are customer-specific and are available through the MariaDB Customer Portal.
To retrieve the token for your account:
Navigate to https://customers.mariadb.com/downloads/token/
Log in.
Copy the Customer Download Token.
Substitute your token for CUSTOMER_DOWNLOAD_TOKEN
when configuring the package repositories.
On each Enterprise ColumnStore node, install the prerequisites for downloading the software from the Web. Install on CentOS / RHEL (YUM):
$ sudo yum install curl
Install on Debian / Ubuntu (APT):
$ sudo apt install curl apt-transport-https
On each Enterprise ColumnStore node, configure package repositories and specify Enterprise Server:
$ curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "4d483b4df193831a0101d3dfa7fb3e17411dda7fc06c31be4f9e089c325403c0 mariadb_es_repo_setup" \
| sha256sum -c -
$ chmod +x mariadb_es_repo_setup
$ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
--skip-maxscale \
--skip-tools \
--mariadb-server-version="11.4"
On each Enterprise Cluster node, install MariaDB Enterprise Server and MariaDB Enterprise Backup.
Install via CentOS / RHEL (YUM):
$ sudo yum install MariaDB-server MariaDB-backup
Install via Debian / Ubuntu (APT):
$ sudo apt update
$ sudo apt install mariadb-server mariadb-backup
Install via SLES (ZYpp):
$ sudo zypper install MariaDB-server MariaDB-backup
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 1 of 7.
Next: Step 2: Start and Configure MariaDB Enterprise Server on Primary Server
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 2 of the 7-step procedure "Deploy Primary/Replica Topology".
This step starts and configures a MariaDB Enterprise Server to operate as a primary server in MariaDB Replication.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
The installation process might have started the Enterprise Server service. The service should be stopped prior to making configuration changes.
Stop the MariaDB Enterprise Server service:
$ sudo systemctl stop mariadb
Enterprise Server nodes require that you set the following system variables and options:
The network socket Enterprise Server listens on for incoming TCP/IP client connections. On Debian or Ubuntu, this system variable must be set to override the 127.0.0.1 default configuration.
Set this option to the file you want to use for the Binary Log. Setting this option enables binary logging.
Sets the numeric Server ID for this MariaDB Enterprise Server. The value set on this option must be unique to each node.
MariaDB Enterprise Server also supports group commit.
Group commit can help performance by reducing I/O.
If you would like to configure parallel replication on replica servers, then you must also configure group commit on the primary server.
Sets the number of transactions that the server commits as a group to the binary log.
Sets the number of microseconds that the server waits for transactions to group commit before it commits the current group.
On each Enterprise Server node, edit a configuration file and set these system variables and options:
[mariadb]
bind_address = 0.0.0.0
log_bin = mariadb-bin.log
server_id = 1
Set the server_id option to a value that is unique for each Enterprise Server node.
Start MariaDB Enterprise Server. If the Enterprise Server process is already running, restart it to apply the changes from the configuration file.
$ systemctl start mariadb
For additional information, see "Starting and Stopping MariaDB".
The Primary/Replica topology requires several user accounts. Each user account should be created on the primary server, so that it is replicated to the replica servers.
Primary/Replica uses MariaDB Replication to replicate writes between the primary and replica servers. As MaxScale can promote a replica server to become a new primary in the event of node failure, all nodes must have a replication user.
The action is performed on the primary server.
Create the replication user and grant it the required privileges:
Use the CREATE USER statement to create replication user.
CREATE USER 'repl'@'192.0.2.%' IDENTIFIED BY 'repl_passwd';
Replace the referenced IP address with the relevant address for your environment.
Ensure that the user account can connect to the primary server from each replica.
Grant the user account the required privileges with the GRANT statement.
The following privileges are required:
GRANT REPLICATION SLAVE,
REPLICATION CLIENT
ON *.* TO repl@'%';
Use this username and password for the MASTER_USER and MASTER_PASSWORD
in the CHANGE MASTER TO statement when configuring replica servers in Step 3.
Primary/Replica uses MariaDB MaxScale 25.01 to load balance between the nodes. MaxScale requires a database user to connect to the primary server when routing queries and to promote replicas in the event that the primary server fails.
This action is performed on the primary server.
Use the CREATE USER statement to create the MaxScale user:
CREATE USER 'mxs'@'192.0.2.%'
IDENTIFIED BY 'mxs_passwd';
Replace the referenced IP address with the relevant address for your environment.
Ensure that the user account can connect from the IP address of the MaxScale instance.
Use the GRANT statement to grant the privileges required by the router:
GRANT SHOW DATABASES ON *.* TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.columns_priv TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.db TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.procs_priv TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.proxies_priv TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.roles_mapping TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.tables_priv TO 'mxs'@'192.0.2.%';
GRANT SELECT ON mysql.user TO 'mxs'@'192.0.2.%';
Use the GRANT statement to grant privileges required by the MariaDB Monitor.
The following privileges are required:
GRANT SUPER,
REPLICATION CLIENT,
RELOAD,
PROCESS,
SHOW DATABASES,
EVENT
ON *.* TO 'mxs'@'192.0.2.%';
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 2 of 7.
Next: Step 3: Start and Configure MariaDB Enterprise Server on Replica Servers
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 3 of the 7-step procedure "Deploy Primary/Replica Topology".
This page starts and configures a MariaDB Enterprise Server 11.4 to operate as a replica server in MariaDB Replication.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
The installation process might have started the Enterprise Server service. The service should be stopped prior to making configuration changes.
On each Enterprise Server node, stop the MariaDB Enterprise Server service:
$ sudo systemctl stop mariadb
Enterprise Server nodes require that you set the following system variables and options:
The network socket Enterprise Server listens on for incoming TCP/IP client connections. On Debian or Ubuntu, this system variable must be set to override the 127.0.0.1 default configuration.
Enables binary logging and sets the name of the binlog file.
Unique numeric identifier for each Enterprise Server node.
MariaDB Enterprise Server also supports group commit.
Writes to the primary server that are group committed or logged with a Global Transaction ID in different replication domains can be applied on the replica server using parallel threads to improve performance.
Sets the number of threads the replica server uses to apply replication events in parallel. Use a non-zero value to enable Parallel Replication.
Sets how the replica server applies replicated transactions.
On each Enterprise Server node, edit a configuration file and set these system variables and options:
[mariadb]
bind_address = 0.0.0.0
log_bin = mariadb-bin.log
server_id = 1
Set the server_id option to a value that is unique for each Enterprise Server node.
When deploying a new replica server to an existing system, back up the primary server and restore it on the replica server to initialize the database.
Use MariaDB Backup to back up the primary server.
On the primary server, take a full backup:
$ sudo mariadb-backup --backup \
--user=mariadb-backup_user \
--password=mariadb-backup_passwd \
--target-dir=/data/backup/replica_backup
Confirm successful completion of the backup operation.
On the primary server, prepare the backup:
$ sudo mariadb-backup --prepare \
--target-dir=/data/backup/replica_backup
Confirm successful completion of the prepare operation.
On the primary server, copy the backup directory to each replica server:
$ sudo rsync -av /data/backup/replica_backup 192.0.2.11:/data/backup/
On the replica server, move the default datadir to another location:
$ sudo mv /var/lib/mysql /var/lib/mysql_backup
On the replica server, use MariaDB Backup to restore the backup to the datadir:
$ sudo mariadb-backup --copy-back \
--target-dir=/data/backup/replica_backup
On the replica server, set the file permissions for the datadir:
$ sudo chown -R mysql:mysql /var/lib/mysql
Start MariaDB Enterprise Server. If the Enterprise Server process is already running, restart it to apply the changes from the configuration file.
$ systemctl start mariadb
For additional information, see "Starting and Stopping MariaDB".
If the replica server was restored from a backup of the primary, set the GTID position.
Get the GTID position that corresponds to the restored backup. This can be found in the xtrabackup_binlong_info file.
$ cat xtrabackup_binlog_info
mariadb-bin.000096 568 0-1-2001,1-2-5139
The GTID position from the above output is 0-1-2001,1-2-5139
.
Connect to the replica server:
$ sudo mariadb
Set the gtid_slave_pos system variable to the GTID position:
SET GLOBAL gtid_slave_pos='0-1-2001,1-2-5139';
Execute the CHANGE MASTER TO statement to configure the replica server to connect to the primary server at this position:
CHANGE MASTER TO
MASTER_USER = "repl",
MASTER_HOST = "192.0.2.10",
MASTER_PASSWORD = "repl_passwd",
MASTER_USE_GTID = slave_pos;
The above statement configures the replica server to connect to a primary server located at 192.0.2.10 using the repl user account. This account must first be configured on the primary server.
Use the START REPLICA statement to start replication:
START REPLICA;
Use SHOW REPLICA STATUS statement to confirm replication is running:
SHOW REPLICA STATUS\G
*************************** 1. row ***************************
Slave_IO_State: Waiting for master to send event
Master_Host: 192.0.2.10
Master_User: repl
Master_Port: 3306
Connect_Retry: 60
Master_Log_File: mariadb-bin.000001
Read_Master_Log_Pos: 645
Relay_Log_File: li282-189-relay-bin.000002
Relay_Log_Pos: 946
Relay_Master_Log_File: mariadb-bin.000001
Slave_IO_Running: Yes
Slave_SQL_Running: Yes
Replicate_Do_DB:
Replicate_Ignore_DB:
Replicate_Do_Table:
Replicate_Ignore_Table:
Replicate_Wild_Do_Table:
Replicate_Wild_Ignore_Table:
Last_Errno: 0
Last_Error:
Skip_Counter: 0
Exec_Master_Log_Pos: 645
Relay_Log_Space: 1259
Until_Condition: None
Until_Log_File:
Until_Log_Pos: 0
Master_SSL_Allowed: No
Master_SSL_CA_File:
Master_SSL_CA_Path:
Master_SSL_Cert:
Master_SSL_Cipher:
Master_SSL_Key:
Seconds_Behind_Master: 0
Master_SSL_Verify_Server_Cert: No
Last_IO_Errno: 0
Last_IO_Error:
Last_SQL_Errno: 0
Last_SQL_Error:
Replicate_Ignore_Server_Ids:
Master_Server_Id: 1
Master_SSL_Crl:
Master_SSL_Crlpath:
Using_Gtid: Slave_Pos
Gtid_IO_Pos: 0-1-2
Replicate_Do_Domain_Ids:
Replicate_Ignore_Domain_Ids:
Parallel_Mode: optimistic
SQL_Delay: 0
SQL_Remaining_Delay: NULL
Slave_SQL_Running_State: Slave has read all relay log; waiting for more updates
Slave_DDL_Groups: 2
Slave_Non_Transactional_Groups: 0
Slave_Transactional_Groups: 0
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 3 of 7.
Next: Step 4: Test MariaDB Enterprise Server
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 4 of the 7-step procedure "Deploy Primary/Replica Topology".
This step tests MariaDB Enterprise Server
Several actions require connection to MariaDB Enterprise Server. A command-line client (mariadb) was included with your ES installation. These instructions describe connection via Unix domain socket. Alternatively, a different client and connection method could be used.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
Use Systemd to test whether the MariaDB Enterprise Server service is running.
This action is performed on each Enterprise Server node.
Check if the MariaDB Enterprise Server service is running by executing the following:
$ systemctl status mariadb
If the service is not running on any node, start the service by executing the following on that node:
$ sudo systemctl start mariadb
Use mariadb Client to test the local connection to the Enterprise Server node.
This action is performed on each Enterprise Server node:
$ sudo mariadb
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 38
Server version: 11.4.5-3-MariaDB-Enterprise MariaDB Enterprise Server
Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]>
The sudo command is used here to connect to the Enterprise Server node using the root@localhost user account, which authenticates using the unix_socket authentication plugin. Other user accounts can be used by specifying the --user
and --password
command-line options.
Use SHOW REPLICA STATUS to check that replication is running properly on the replica servers.
This action is performed on each replica server.
Execute the following:
SHOW REPLICA STATUS\G
*************************** 1. row ***************************
Slave_IO_State: Waiting for master to send event
Master_Host: 192.0.2.1
Master_User: repl
Master_Port: 3306
Connect_Retry: 60
Master_Log_File: mariadb-bin.000001
Read_Master_Log_Pos: 645
Relay_Log_File: li282-189-relay-bin.000002
Relay_Log_Pos: 946
Relay_Master_Log_File: mariadb-bin.000001
Slave_IO_Running: Yes
Slave_SQL_Running: Yes
Replicate_Do_DB:
Replicate_Ignore_DB:
Replicate_Do_Table:
Replicate_Ignore_Table:
Replicate_Wild_Do_Table:
Replicate_Wild_Ignore_Table:
Last_Errno: 0
Last_Error:
Skip_Counter: 0
Exec_Master_Log_Pos: 645
Relay_Log_Space: 1259
Until_Condition: None
Until_Log_File:
Until_Log_Pos: 0
Master_SSL_Allowed: No
Master_SSL_CA_File:
Master_SSL_CA_Path:
Master_SSL_Cert:
Master_SSL_Cipher:
Master_SSL_Key:
Seconds_Behind_Master: 0
Master_SSL_Verify_Server_Cert: No
Last_IO_Errno: 0
Last_IO_Error:
Last_SQL_Errno: 0
Last_SQL_Error:
Replicate_Ignore_Server_Ids:
Master_Server_Id: 1
Master_SSL_Crl:
Master_SSL_Crlpath:
Using_Gtid: Slave_Pos
Gtid_IO_Pos: 0-1-2
Replicate_Do_Domain_Ids:
Replicate_Ignore_Domain_Ids:
Parallel_Mode: optimistic
SQL_Delay: 0
SQL_Remaining_Delay: NULL
Slave_SQL_Running_State: Slave has read all relay log; waiting for more updates
Slave_DDL_Groups: 2
Slave_Non_Transactional_Groups: 0
Slave_Transactional_Groups: 0
If Slave_IO_Running
column is not Yes
on any replica server, then check:
The network connectivity between the replica server and the primary server
The Last_IO_Error
column for details on any errors
If Slave_SQL_Running
column is not Yes on any replica server, then check:
The GTID position in gtid_slave_pos
The Last_SQL_Error
column for details on any errors
If both columns are not Yes
on any replica server, then check:
The replication configuration on the replica server.
If you need to make any corrections, the slave threads can be restarted with START REPLICA.
Use mariadb Client to test DDL.
On the primary server, use the mariadb Client to connect to the node:
$ sudo mariadb
Create a test database and table:
CREATE DATABASE IF NOT EXISTS test;
CREATE TABLE test.contacts (
id INT PRIMARY KEY AUTO_INCREMENT,
first_name VARCHAR(50),
last_name VARCHAR(50),
email VARCHAR(100)
);
On each replica server, use the mariadb Client to connect to the node:
$ sudo mariadb
Confirm that the database and table exist:
SHOW CREATE TABLE test.contacts\G;
If the database or table do not exist on any node, then check the replication status on the node.
Use mariadb Client to test DML.
On the primary server, use the MariaDB Client to connect to the node:
$ sudo mariadb
Insert sample data into the table created in the DDL test:
INSERT INTO test.contacts (first_name, last_name, email)
VALUES
("Kai", "Devi", "kai.devi@example.com"),
("Lee", "Wang", "lee.wang@example.com");
On each replica server, use the mariadb Client to connect to the node:
$ sudo mariadb
Execute a SELECT query to retrieve the data:
SELECT * FROM test.contacts;
+----+------------+-----------+----------------------+
| id | first_name | last_name | email |
+----+------------+-----------+----------------------+
| 1 | Kai | Devi | kai.devi@example.com |
| 2 | Lee | Wang | lee.wang@example.com |
+----+------------+-----------+----------------------+
If the data is not returned on any node, then check the replication status on the node.
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 4 of 7.
Next: Step 5: Install MariaDB MaxScale
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 5 of the 7-step procedure "Deploy Primary/Replica Topology".
This step install MariaDB MaxScale 25.01.
The MaxScale node must meet requirements.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
MariaDB Corporation provides package repositories for YUM (RHEL, CentOS), APT (Debian, Ubuntu), and ZYpp (SLES). A download token is required to access the MariaDB Enterprise Repository.
Customer Download Tokens are customer-specific and are available through the MariaDB Customer Portal.
To retrieve the token for your account:
Navigate to https://customers.mariadb.com/downloads/token/
Log in.
Copy the Customer Download Token.
Substitute your token for CUSTOMER_DOWNLOAD_TOKEN
when configuring the package repositories.
On the MaxScale node, install the prerequisites for downloading the software from the Web.
Install on CentOS / RHEL (YUM):
$ sudo yum install curl
Install on Debian / Ubuntu (APT):
$ sudo apt install curl apt-transport-https
Install on SLES (ZYpp):
$ sudo zypper install curl
On the MaxScale node, configure package repositories and specify MariaDB MaxScale 25.01:
$ curl -LsSO https://dlm.mariadb.com/enterprise-release-helpers/mariadb_es_repo_setup
$ echo "4d483b4df193831a0101d3dfa7fb3e17411dda7fc06c31be4f9e089c325403c0 mariadb_es_repo_setup" \
| sha256sum -c -
$ chmod +x mariadb_es_repo_setup
$ sudo ./mariadb_es_repo_setup --token="CUSTOMER_DOWNLOAD_TOKEN" --apply \
--skip-server \
--skip-tools \
--mariadb-maxscale-version="25.01"
On the MaxScale node, install MariaDB MaxScale.
Install on CentOS / RHEL (YUM):
$ sudo yum install maxscale
Install on Debian / Ubuntu (APT):
$ sudo apt install maxscale
Install on SLES (ZYpp):
$ sudo zypper install maxscale
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 5 of 7.
Next: Step 6: Start and Configure MariaDB MaxScale
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 6 of the 7-step procedure "Deploy Primary/Replica Topology".
This step starts and configures MariaDB MaxScale.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
MariaDB MaxScale installations include a configuration file with some example objects. This configuration file should be replaced.
On the MaxScale node, replace the default /etc/maxscale.cnf
with the following configuration:
[maxscale]
threads = auto
admin_host = 0.0.0.0
admin_secure_gui = false
For additional information, see "Global Settings".
On the MaxScale node, restart the MaxScale service to ensure that MaxScale picks up the new configuration:
$ sudo systemctl restart maxscale
For additional information, see "Starting and Stopping MariaDB".
On the MaxScale node, use maxctrl create server to create a server object for each MariaDB Enterprise Server:
$ maxctrl create server node1 192.0.2.101
$ maxctrl create server node2 192.0.2.102
$ maxctrl create server node3 192.0.2.103
MaxScale uses monitors to retrieve additional information from the servers. This information is used by other services in filtering and routing connections based on the current state of the node. For MariaDB Replication, use the MariaDB Monitor (mariadbmon).
On the MaxScale node, use maxctrl create monitor to create a MariaDB Monitor:
$ maxctrl create monitor mdb_monitor mariadbmon \
user=mxs \
password='MAXSCALE_USER_PASSWORD' \
replication_user=repl \
replication_password='REPLICATION_USER_PASSWORD' \
--servers node1 node2 node3
In this example:
mdb_monitor
is an arbitrary name that is used to identify the new monitor.
mariadbmon is the name of the module that implements the MariaDB Monitor.
user=MAXSCALE_USER
sets the user
parameter to the database user account that MaxScale uses to monitor the ES nodes.
password='MAXSCALE_USER_PASSWORD'
sets the password
parameter to the password used by the database user account that MaxScale uses to monitor the ES nodes.
replication_user=REPLICATION_USER
sets the replication_user
parameter to the database user account that MaxScale uses to setup replication.
replication_password='REPLICATION_USER_PASSWORD'
sets the replication_password
parameter to the password used by the database user account that MaxScale uses to setup replication.
--servers
sets the servers
parameter to the set of nodes that MaxScale should monitor. All non-option arguments after --servers
are interpreted as server names.
Other Module Parameters supported by mariadbmon
in MaxScale can also be specified.
Routers control how MaxScale balances the load between Enterprise Server nodes. Each router uses a different approach to routing queries. Consider the specific use case of your application and database load and select the router that best suits
Connection-based load balancing
Routes connections to Enterprise ColumnStore nodes designated as replica servers for a read-only pool
Routes connections to an Enterprise ColumnStore node designated as the primary server for a read-write pool.
Query-based load balancing
Routes write queries to an Enterprise ColumnStore node designated as the primary server
Routes read queries to Enterprise ColumnStore node designated as replica servers
Automatically reconnects after node failures
Automatically replays transactions after node failures
Optionally enforces causal reads
Use MaxScale Read Connection Router (readconnroute) to route connections to replica servers for a read-only pool.
On the MaxScale node, use maxctrl create service
to create a router:
$ maxctrl create service connection_router_service readconnroute \
user=mxs \
password='MAXSCALE_USER_PASSWORD' \
router_options=slave \
--servers node1 node2 node3
In this example:
connection_router_service
is an arbitrary name that is used to identify the new service.
readconnroute
is the name of the module that implements the Read Connection Router.
user=MAXSCALE_USER
sets the user
parameter to the database user account that MaxScale uses to connect to the ES nodes.
password=MAXSCALE_USER_PASSWORD
sets the password parameter to the password used by the database user account that MaxScale uses to connect to the ES nodes.
router_options=slave
sets the router_options
parameter to slave
, so that MaxScale only routes connections to the replica nodes.
--servers sets the servers
parameter to the set of nodes to which MaxScale should route connections. All non-option arguments after --servers
are interpreted as server names.
Other Module Parameters supported by readconnroute
in MaxScale 25.01 can also be specified.
These instructions reference TCP port 3308. You can use a different TCP port. The TCP port used must not be bound by any other listener.
On the MaxScale node, use the maxctrl create listener command to configure MaxScale to use a listener for the Read Connection Router (readconnroute):
$ maxctrl create listener connection_router_service connection_router_listener 3308 \
protocol=MariaDBClient
In this example:
connection_router_service
is the name of the readconnroute service that was previously created.
connection_router_listener
is an arbitrary name that is used to identify the new listener.
3308
is the TCP port.
protocol=MariaDBClient
sets the protocol parameter.
Other Module Parameters supported by listeners in MaxScale can also be specified.
MaxScale Read/Write Split Router (readwritesplit) performs query-based load balancing. The router routes write queries to the primary and read queries to the replicas.
On the MaxScale node, use the maxctrl create service command to configure MaxScale to use the Read/Write Split Router (readwritesplit):
$ maxctrl create service query_router_service readwritesplit \
user=mxs \
password='MAXSCALE_USER_PASSWORD' \
--servers node1 node2 node3
In this example:
query_router_service
is an arbitrary name that is used to identify the new service.
readwritesplit
is the name of the module that implements the Read/Write Split Router.
user=MAXSCALE_USER
sets the user
parameter to the database user account that MaxScale uses to connect to the ES nodes.
password=MAXSCALE_USER_PASSWORD
sets the password
parameter to the password used by the database user account that MaxScale uses to connect to the ES nodes.
--servers sets the servers
parameter to the set of nodes to which MaxScale should route queries. All non-option arguments after --servers
are interpreted as server names.
Other Module Parameters supported by readwritesplit
in MaxScale can also be specified.
These instructions reference TCP port 3307
. You can use a different TCP port. The TCP port used must not be bound by any other listener.
On the MaxScale node, use the maxctrl create listener
command to configure MaxScale to use a listener for the Read/Write Split Router (readwritesplit):
$ maxctrl create listener query_router_service query_router_listener 3307 \
protocol=MariaDBClient
In this example:
query_router_service
is the name of the readwritesplit
service that was previously created.
query_router_listener
is an arbitrary name that is used to identify the new listener.
3307 is the TCP port.
protocol=MariaDBClient
sets the protocol
parameter.
Other Module Parameters supported by listeners in MaxScale can also be specified.
To start the services and monitors, on the MaxScale node use maxctrl start services:
$ maxctrl start services
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 6 of 7.
Next: Step 7: Test MariaDB MaxScale
This page is: Copyright © 2025 MariaDB. All rights reserved.
This page details step 7 of the 7-step procedure "Deploy Primary/Replica Topology".
This step tests MariaDB MaxScale.
Interactive commands are detailed. Alternatively, the described operations can be performed using automation.
Use maxctrl show maxscale command to view the global MaxScale configuration.
This action is performed on the MaxScale node:
$ maxctrl show maxscale
┌──────────────┬───────────────────────────────────────────────────────┐
│ Version │ 25.01.2 │
├──────────────┼───────────────────────────────────────────────────────┤
│ Commit │ 3761fa7a52046bc58faad8b5a139116f9e33364c │
├──────────────┼───────────────────────────────────────────────────────┤
│ Started At │ Thu, 05 Aug 2021 20:21:20 GMT │
├──────────────┼───────────────────────────────────────────────────────┤
│ Activated At │ Thu, 05 Aug 2021 20:21:20 GMT │
├──────────────┼───────────────────────────────────────────────────────┤
│ Uptime │ 868 │
├──────────────┼───────────────────────────────────────────────────────┤
│ Config Sync │ null │
├──────────────┼───────────────────────────────────────────────────────┤
│ Parameters │ { │
│ │ "admin_auth": true, │
│ │ "admin_enabled": true, │
│ │ "admin_gui": true, │
│ │ "admin_host": "0.0.0.0", │
│ │ "admin_log_auth_failures": true, │
│ │ "admin_pam_readonly_service": null, │
│ │ "admin_pam_readwrite_service": null, │
│ │ "admin_port": 8989, │
│ │ "admin_secure_gui": false, │
│ │ "admin_ssl_ca_cert": null, │
│ │ "admin_ssl_cert": null, │
│ │ "admin_ssl_key": null, │
│ │ "admin_ssl_version": "MAX", │
│ │ "auth_connect_timeout": "10000ms", │
│ │ "auth_read_timeout": "10000ms", │
│ │ "auth_write_timeout": "10000ms", │
│ │ "cachedir": "/var/cache/maxscale", │
│ │ "config_sync_cluster": null, │
│ │ "config_sync_interval": "5000ms", │
│ │ "config_sync_password": "*****", │
│ │ "config_sync_timeout": "10000ms", │
│ │ "config_sync_user": null, │
│ │ "connector_plugindir": "/usr/lib64/mysql/plugin", │
│ │ "datadir": "/var/lib/maxscale", │
│ │ "debug": null, │
│ │ "dump_last_statements": "never", │
│ │ "execdir": "/usr/bin", │
│ │ "language": "/var/lib/maxscale", │
│ │ "libdir": "/usr/lib64/maxscale", │
│ │ "load_persisted_configs": true, │
│ │ "local_address": null, │
│ │ "log_debug": false, │
│ │ "log_info": false, │
│ │ "log_notice": true, │
│ │ "log_throttling": { │
│ │ "count": 10, │
│ │ "suppress": 10000, │
│ │ "window": 1000 │
│ │ }, │
│ │ "log_warn_super_user": false, │
│ │ "log_warning": true, │
│ │ "logdir": "/var/log/maxscale", │
│ │ "max_auth_errors_until_block": 10, │
│ │ "maxlog": true, │
│ │ "module_configdir": "/etc/maxscale.modules.d", │
│ │ "ms_timestamp": false, │
│ │ "passive": false, │
│ │ "persistdir": "/var/lib/maxscale/maxscale.cnf.d", │
│ │ "piddir": "/var/run/maxscale", │
│ │ "query_classifier": "qc_sqlite", │
│ │ "query_classifier_args": null, │
│ │ "query_classifier_cache_size": 289073971, │
│ │ "query_retries": 1, │
│ │ "query_retry_timeout": "5000ms", │
│ │ "rebalance_period": "0ms", │
│ │ "rebalance_threshold": 20, │
│ │ "rebalance_window": 10, │
│ │ "retain_last_statements": 0, │
│ │ "session_trace": 0, │
│ │ "skip_permission_checks": false, │
│ │ "sql_mode": "default", │
│ │ "syslog": true, │
│ │ "threads": 1, │
│ │ "users_refresh_interval": "0ms", │
│ │ "users_refresh_time": "30000ms", │
│ │ "writeq_high_water": 16777216, │
│ │ "writeq_low_water": 8192 │
│ │ } │
└──────────────┴───────────────────────────────────────────────────────┘
Output should align to the global MaxScale configuration in the new configuration file you created.
Use the maxctrl list servers and maxctrl show server commands to view the configured server objects.
This action is performed on the MaxScale node:
Obtain the full list of servers objects:
$ maxctrl list servers
┌────────┬─────────────┬──────┬─────────────┬─────────────────────────┬──────┐
│ Server │ Address │ Port │ Connections │ State │ GTID │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node1 │ 192.0.2.101 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node2 │ 192.0.2.102 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node3 │ 192.0.2.103 │ 3306 │ 0 │ Master, Synced, Running │ │
└────────┴─────────────┴──────┴─────────────┴─────────────────────────┴──────┘
For each server object, view the configuration:
$ maxctrl show server node3
┌─────────────────────┬───────────────────────────────────────────┐
│ Server │ node3 │
├─────────────────────┼───────────────────────────────────────────┤
│ Address │ 192.0.2.103 │
├─────────────────────┼───────────────────────────────────────────┤
│ Port │ 3306 │
├─────────────────────┼───────────────────────────────────────────┤
│ State │ Master, Synced, Running │
├─────────────────────┼───────────────────────────────────────────┤
│ Version │ 11.4.5-3-MariaDB-enterprise-log │
├─────────────────────┼───────────────────────────────────────────┤
│ Last Event │ master_up │
├─────────────────────┼───────────────────────────────────────────┤
│ Triggered At │ Thu, 05 Aug 2021 20:22:26 GMT │
├─────────────────────┼───────────────────────────────────────────┤
│ Services │ connection_router_service │
│ │ query_router_service │
├─────────────────────┼───────────────────────────────────────────┤
│ Monitors │ cluster_monitor │
├─────────────────────┼───────────────────────────────────────────┤
│ Master ID │ -1 │
├─────────────────────┼───────────────────────────────────────────┤
│ Node ID │ 1 │
├─────────────────────┼───────────────────────────────────────────┤
│ Slave Server IDs │ │
├─────────────────────┼───────────────────────────────────────────┤
│ Current Connections │ 1 │
├─────────────────────┼───────────────────────────────────────────┤
│ Total Connections │ 1 │
├─────────────────────┼───────────────────────────────────────────┤
│ Max Connections │ 1 │
├─────────────────────┼───────────────────────────────────────────┤
│ Statistics │ { │
│ │ "active_operations": 0, │
│ │ "adaptive_avg_select_time": "0ns", │
│ │ "connection_pool_empty": 0, │
│ │ "connections": 1, │
│ │ "max_connections": 1, │
│ │ "max_pool_size": 0, │
│ │ "persistent_connections": 0, │
│ │ "reused_connections": 0, │
│ │ "routed_packets": 0, │
│ │ "total_connections": 1 │
│ │ } │
├─────────────────────┼───────────────────────────────────────────┤
│ Parameters │ { │
│ │ "address": "192.0.2.103", │
│ │ "disk_space_threshold": null, │
│ │ "extra_port": 0, │
│ │ "monitorpw": null, │
│ │ "monitoruser": null, │
│ │ "persistmaxtime": "0ms", │
│ │ "persistpoolmax": 0, │
│ │ "port": 3306, │
│ │ "priority": 0, │
│ │ "proxy_protocol": false, │
│ │ "rank": "primary", │
│ │ "socket": null, │
│ │ "ssl": false, │
│ │ "ssl_ca_cert": null, │
│ │ "ssl_cert": null, │
│ │ "ssl_cert_verify_depth": 9, │
│ │ "ssl_cipher": null, │
│ │ "ssl_key": null, │
│ │ "ssl_verify_peer_certificate": false, │
│ │ "ssl_verify_peer_host": false, │
│ │ "ssl_version": "MAX" │
│ │ } │
└─────────────────────┴───────────────────────────────────────────┘
Output should align to the Server Object configuration you performed.
Use the maxctrl list monitors and maxctrl show monitor commands to view the configured monitors.
This action is performed on the MaxScale node:
Obtain the full list of monitors:
$ maxctrl list monitors
┌─────────────────┬─────────┬─────────────────────┐
│ Monitor │ State │ Servers │
├─────────────────┼─────────┼─────────────────────┤
│ cluster_monitor │ Running │ node1, node2, node3 │
└─────────────────┴─────────┴─────────────────────┘
For each monitor, view the monitor configuration:
$ maxctrl show monitor cluster_monitor
┌─────────────────────┬──────────────────────────────────────────────────────┐
│ Monitor │ cluster_monitor │
├─────────────────────┼──────────────────────────────────────────────────────┤
│ Module │ galeramon │
├─────────────────────┼──────────────────────────────────────────────────────┤
│ State │ Running │
├─────────────────────┼──────────────────────────────────────────────────────┤
│ Servers │ node1 │
│ │ node2 │
│ │ node3 │
├─────────────────────┼──────────────────────────────────────────────────────┤
│ Parameters │ { │
│ │ .. │
│ │ } │
├─────────────────────┼──────────────────────────────────────────────────────┤
│ Monitor Diagnostics │ { │
│ │ .. │
│ │ } │
└─────────────────────┴──────────────────────────────────────────────────────┘
Output should align to the Galera Monitor (galeramon) configuration you performed.
Use the maxctrl list services and maxctrl show service commands to view the configured routing services.
This action is performed on the MaxScale node:
Obtain the full list of routing services:
$ maxctrl list services
┌───────────────────────────┬────────────────┬─────────────┬───────────────────┬─────────────────────┐
│ Service │ Router │ Connections │ Total Connections │ Servers │
├───────────────────────────┼────────────────┼─────────────┼───────────────────┼─────────────────────┤
│ connection_router_service │ readconnroute │ 0 │ 0 │ node1, node2, node3 │
├───────────────────────────┼────────────────┼─────────────┼───────────────────┼─────────────────────┤
│ query_router_service │ readwritesplit │ 1 │ 1 │ node1, node2, node3 │
└───────────────────────────┴────────────────┴─────────────┴───────────────────┴─────────────────────┘
For each service, view the service configuration:
$ maxctrl show service query_router_service
┌─────────────────────┬─────────────────────────────────────────────────────────────┐
│ Service │ query_router_service │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Router │ readwritesplit │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ State │ Started │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Started At │ Thu Aug 5 20:23:38 2021 │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Current Connections │ 1 │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Total Connections │ 1 │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Max Connections │ 1 │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Cluster │ │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Servers │ node1 │
│ │ node2 │
│ │ node3 │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Services │ │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Filters │ │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Parameters │ { │
│ │ "auth_all_servers": false, │
│ │ "causal_reads": "false", │
│ │ "causal_reads_timeout": "10000ms", │
│ │ "connection_keepalive": "300000ms", │
│ │ "connection_timeout": "0ms", │
│ │ "delayed_retry": false, │
│ │ "delayed_retry_timeout": "10000ms", │
│ │ "disable_sescmd_history": false, │
│ │ "enable_root_user": false, │
│ │ "idle_session_pool_time": "-1000ms", │
│ │ "lazy_connect": false, │
│ │ "localhost_match_wildcard_host": true, │
│ │ "log_auth_warnings": true, │
│ │ "master_accept_reads": false, │
│ │ "master_failure_mode": "fail_instantly", │
│ │ "master_reconnection": false, │
│ │ "max_connections": 0, │
│ │ "max_sescmd_history": 50, │
│ │ "max_slave_connections": 255, │
│ │ "max_slave_replication_lag": "0ms", │
│ │ "net_write_timeout": "0ms", │
│ │ "optimistic_trx": false, │
│ │ "password": "*****", │
│ │ "prune_sescmd_history": true, │
│ │ "rank": "primary", │
│ │ "retain_last_statements": -1, │
│ │ "retry_failed_reads": true, │
│ │ "reuse_prepared_statements": false, │
│ │ "router": "readwritesplit", │
│ │ "session_trace": false, │
│ │ "session_track_trx_state": false, │
│ │ "slave_connections": 255, │
│ │ "slave_selection_criteria": "LEAST_CURRENT_OPERATIONS", │
│ │ "strict_multi_stmt": false, │
│ │ "strict_sp_calls": false, │
│ │ "strip_db_esc": true, │
│ │ "transaction_replay": false, │
│ │ "transaction_replay_attempts": 5, │
│ │ "transaction_replay_max_size": 1073741824, │
│ │ "transaction_replay_retry_on_deadlock": false, │
│ │ "type": "service", │
│ │ "use_sql_variables_in": "all", │
│ │ "user": "mxs", │
│ │ "version_string": null │
│ │ } │
├─────────────────────┼─────────────────────────────────────────────────────────────┤
│ Router Diagnostics │ { │
│ │ "avg_sescmd_history_length": 0, │
│ │ "max_sescmd_history_length": 0, │
│ │ "queries": 1, │
│ │ "replayed_transactions": 0, │
│ │ "ro_transactions": 0, │
│ │ "route_all": 0, │
│ │ "route_master": 0, │
│ │ "route_slave": 1, │
│ │ "rw_transactions": 0, │
│ │ "server_query_statistics": [ │
│ │ { │
│ │ "avg_selects_per_session": 0, │
│ │ "avg_sess_duration": "0ns", │
│ │ "id": "node2", │
│ │ "read": 1, │
│ │ "total": 1, │
│ │ "write": 0 │
│ │ } │
│ │ ] │
│ │ } │
└─────────────────────┴─────────────────────────────────────────────────────────────┘
Output should align to the Read Connection Router (readconnroute) or Read/Write Split Router (readwritesplit) configuration you performed.
Applications should use a dedicated user account. The user account must be created on the primary server.
When users connect to MaxScale, MaxScale authenticates the user connection before routing it to an Enterprise Server node. Enterprise Server authenticates the connection as originating from the IP address of the MaxScale node.
The application users must have one user account with the host IP address of the application server and a second user account with the host IP address of the MaxScale node.
The requirement of a duplicate user account can be avoided by enabling the proxy_protocol
parameter for MaxScale and the proxy_protocol_networks for Enterprise Server.
This action is performed on any Enterprise Cluster node:
Connect to the node:
$ sudo mariadb
Create the database user account for your MaxScale node:
CREATE USER 'app_user'@'192.0.2.104' IDENTIFIED BY 'app_user_passwd';
Replace 192.0.2.104 with the relevant IP address specification for your MaxScale node.
Passwords should meet your organization's password policies.
Grant the privileges required by your application to the database user account for your MaxScale node:
GRANT ALL ON test.* TO 'app_user'@'192.0.2.104';
The privileges shown are designed to allow the tests in the subsequent sections to work. The user account for your production application may require different privileges.
This action is performed on any Enterprise Cluster node:
Create the database user account for your application server:
CREATE USER 'app_user'@'192.0.2.11' IDENTIFIED BY 'app_user_passwd';
Replace 192.0.2.11 with the relevant IP address specification for your application server.
Passwords should meet your organization's password policies.
Grant the privileges required by your application to the database user account for your application server:
GRANT ALL ON test.* TO 'app_user'@'192.0.2.11';
The privileges shown are designed to allow the tests in the subsequent sections to work. The user account for your production application may require different privileges.
To test the connection, use the MariaDB Client from your application server to connect to an Enterprise Cluster node through MaxScale.
This action is performed on the application server:
$ mariadb --host 192.0.2.104 --port 3307
--user app_user --password
If you configured the Read Connection Router, confirm that MaxScale routes connections to the replica servers.
On the MaxScale node, use the maxctrl list listeners command to view the available listeners and ports:
$ maxctrl list listeners
┌────────────────────────────┬──────┬──────┬─────────┬───────────────────────────┐
│ Name │ Port │ Host │ State │ Service │
├────────────────────────────┼──────┼──────┼─────────┼───────────────────────────┤
│ connection_router_listener │ 3308 │ :: │ Running │ connection_router_service │
├────────────────────────────┼──────┼──────┼─────────┼───────────────────────────┤
│ query_router_listener │ 3307 │ :: │ Running │ query_router_service │
└────────────────────────────┴──────┴──────┴─────────┴───────────────────────────┘
Open multiple terminals connected to your application server, in each use MariaDB Client to connect to the listener port for the Read Connection Router (in the example 3308):
$ mariadb --host 192.0.2.104 --port 3308 \
--user app_user --password
Use the application user credentials you created for the --user
and --password
options.
In each terminal, query the hostname system variable to identify to which you're connected:
SELECT @@global.hostname;
+-------------------+
| @@global.hostname |
+-------------------+
| node2 |
+-------------------+
Different terminals should return different values since MaxScale routes the connections to different nodes.
Since the router was configured the slave router option, the Read Connection Router only routes connections to replica servers.
If you configured the Read/Write Split Router, confirm that readwritesplit correctly routes write queries.
This action is performed with multiple client connections to the MaxScale node.
On the MaxScale node, use the maxctrl list servers command to identify the Enterprise Cluster node currently operating as the primary server:
$ maxctrl list servers
┌────────┬─────────────┬──────┬─────────────┬─────────────────────────┬──────┐
│ Server │ Address │ Port │ Connections │ State │ GTID │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node1 │ 192.0.2.101 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node2 │ 192.0.2.102 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node3 │ 192.0.2.103 │ 3306 │ 0 │ Master, Synced, Running │ │
└────────┴─────────────┴──────┴─────────────┴─────────────────────────┴──────┘
The server listed as Master is currently operating as the primary server.
On the MaxScale node, use the maxctrl list listeners command to identify the correct listener port:
$ maxctrl list listeners galerarouter
┌────────────────────────────┬──────┬───────┬─────────┬───────────────────────────┐
│ Name │ Port │ Host │ State │ Service │
├────────────────────────────┼──────┼───────┼─────────┼───────────────────────────┤
│ connection_router_listener │ 3308 │ │ Running │ connection_router_service │
│ query_router_listener │ 3307 │ │ Running │ query_router_service │
└────────────────────────────┴──────┴───────┴─────────┴───────────────────────────┘
In the example, the listener port for the Read/Write Split router is 3307.
Use the MariaDB Client to establish multiple connections to the listener configured for the Read/Write Split routing service, query_router_listener
, on the MaxScale node:
$ mariadb --host=192.0.2.104 --port=3307 \
--user=app_user --password=app_user_passwd
The database user account for your application server should be specified by the --user
option.
Using any client connection, create a test table:
CREATE TABLE test.load_balancing_test (
id INT PRIMARY KEY AUTO_INCREMENT,
hostname VARCHAR(256)
);
Using each client connection, insert the values of the hostname system variable into the table using the INSERT statement to identify the node that executes the statement:
INSERT INTO test.load_balancing_test (hostname)
VALUES (@@global.hostname);
Using any client connection, query the table using the SELECT statement:
SELECT * FROM test.load_balancing_test;
+----+----------+
| id | hostname |
+----+----------+
| 1 | node3 |
| 4 | node3 |
| 7 | node3 |
+----+----------+
The output shows the hostname from the Enterprise Cluster node operating as the primary server. (Enterprise Cluster offsets auto-increment values by node to avoid write conflicts.)
Confirm that MaxScale is routing write queries to the Enterprise Cluster node operating as the primary server by checking that the test table only contains the hostname of the correct Enterprise Cluster node.
If you configured the Read/Write Split Router, confirm that readwritesplit properly routes read queries to multiple replica servers.
This action is performed with multiple clients connected to the MaxScale node.
On the MaxScale node, use maxctrl list servers to identify the Enterprise Cluster nodes that are currently operating as replica servers:
$ maxctrl list servers
┌────────┬─────────────┬──────┬─────────────┬─────────────────────────┬──────┐
│ Server │ Address │ Port │ Connections │ State │ GTID │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node1 │ 192.0.2.101 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node2 │ 192.0.2.102 │ 3306 │ 0 │ Slave, Synced, Running │ │
├────────┼─────────────┼──────┼─────────────┼─────────────────────────┼──────┤
│ node3 │ 192.0.2.103 │ 3306 │ 0 │ Master, Synced, Running │ │
└────────┴─────────────┴──────┴─────────────┴─────────────────────────┴──────┘
The servers listed as Slave are currently operating as replica servers.
On the MaxScale node, use the maxctrl list listeners command to identify the correct listener port:
$ maxctrl list listeners
┌────────────────────────────┬──────┬───────┬─────────┬───────────────────────────┐
│ Name │ Port │ Host │ State │ Service │
├────────────────────────────┼──────┼───────┼─────────┼───────────────────────────┤
│ connection_router_listener │ 3308 │ │ Running │ connection_router_service │
│ query_router_listener │ 3307 │ │ Running │ query_router_service │
└────────────────────────────┴──────┴───────┴─────────┴───────────────────────────┘
In the example, the listener port for the Read/Write Split router is 3307.
Use the MariaDB Client to establish multiple connections to query_router_listener
which is the listener configured for the Read/Write Split routing service on the MaxScale node:
$ mariadb --host=192.0.2.104 --port=3307 \
--user=app_user --password=app_user_passwd
The database user account for your application server should be specified by the --user option.
Using each client connection, query the hostname system variable to identify the node that executes the statement:
SELECT @@global.hostname;
+-------------------+
| @@global.hostname |
+-------------------+
| node2 |
+-------------------+
Confirm that MaxScale routes the SELECT statements to different replica servers.
For more information on different routing criteria, see slave_selection_criteria
Navigation in the procedure "Deploy Primary/Replica Topology":
This page was step 7 of 7.
This procedure is complete.
This page is: Copyright © 2025 MariaDB. All rights reserved.