MariaDB MaxScale is a database proxy that extends the high availability, scalability, and security of MariaDB Server while at the same time simplifying application development by decoupling it from underlying database infrastructure.

MariaDB MaxScale is engineered with an extensible architecture to support plugins, extending its functionality beyond transparent load balancing to become, for example, a database firewall. With built-in plugins for multiple routers, filters and protocols, MariaDB MaxScale can be configured to forward database requests and modify database responses based on business and technical requirements — for example, to mask sensitive data or scale reads.

About MariaDB MaxScale

MariaDB MaxScale is a database proxy that forwards database statements to one or more database servers.

The forwarding is performed using rules based on the semantic understanding of the database statements and on the roles of the servers within the backend cluster of databases.

MariaDB MaxScale is designed to provide, transparently to applications, load balancing and high availability functionality. MariaDB MaxScale has a scalable and flexible architecture, with plugin components to support different protocols and routing approaches.

MariaDB MaxScale makes extensive use of the asynchronous I/O capabilities of the Linux operating system, combined with a fixed number of worker threads. epoll is used to provide the event driven framework for the input and output via sockets.

Many of the services provided by MariaDB MaxScale are implemented as external shared object modules loaded at runtime. These modules support a fixed interface, communicating the entry points via a structure consisting of a set of function pointers. This structure is called the "module object". Additional modules can be created to work with MariaDB MaxScale.

Commonly used module types are protocol, router and filter. Protocol modules implement the communication between clients and MariaDB MaxScale, and between MariaDB MaxScale and backend servers. Routers inspect the queries from clients and decide the target backend. The decisions are usually based on routing rules and backend server status. Filters work on data as it passes through MariaDB MaxScale. Filter are often used for logging queries or modifying server responses.

A Google Group exists for MariaDB MaxScale. The Group is used to discuss ideas, issues and communicate with the MariaDB MaxScale community. Send email to maxscale@googlegroups.com or use the forum interface.

Bugs can be reported in the MariaDB Jira jira.mariadb.org

Installing MariaDB MaxScale

Information about installing MariaDB MaxScale, either from a repository or by building from source code, is included in the MariaDB MaxScale Installation Guide.

The same guide also provides basic information on running MariaDB MaxScale. More detailed information about configuring MariaDB MaxScale can be found in the Configuration Guide.

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

This document describes possible issues upgrading MariaDB MaxScale from version 2.1 to 2.2.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, we recommend you back up your current configuration file.

Administrative Users

The file format for the administrative users used by MaxScale has been changed. Old style files are automatically upgraded and a backup of the old file is stored in /var/lib/maxscale/passwd.backup.

Regular Expression Parameters

Modules may now use a built-in regular expression string parameter type instead of a normal string when accepting patterns. The modules that use the new regex parameter type are qlafilter and tee. When inputting pattern, enclose the string in slashes, e.g. match=/^select/ defines the pattern ^select.

Binlog Server

Binlog server automatically accepts GTID connection from MariaDB 10 slave servers by saving all incoming GTIDs into a SQLite map database.

MaxCtrl Included in Main Package

In the 2.2.1 beta version MaxCtrl was in its own package whereas in 2.2.2 it is in the main maxscale package. If you have a previous installation of MaxCtrl, please remove it before upgrading to MaxScale 2.2.2.

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

Overview

MariaDB MaxScale provides various administrative interfaces can be used to perform the following tasks:

• Setting a server to maintenance mode.

• Reconfiguring monitors.

• Reconfiguring routers.

• And much more.

Tools Supported by MaxScale

MaxScale supports different administrative interfaces for different kinds of environments and preferences:

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

Overview

When using MaxScale, it is often necessary to temporarily remove a server from the load balancing pool without actually shutting down the server. This is usually needed to perform maintenance on the server, such as when upgrading the server's software or when performing schema upgrades.

MaxScale allows users to set servers to "maintenance mode", which prevents MaxScale from routing traffic to the server and prevents it from being elected as the new primary server during failover or switchover.

MaxGUI is a graphical utility that can perform administrative tasks using MaxScale's MaxScale's REST API. It is available starting in . It can be used to set a server to maintenance mode.

Setting a Server to Maintenance Mode

1. Configure MaxScale for MaxGUI.

2. Visit MaxGUI in your web browser. For example, if you are accessing it from local host with the default port, then visit this address: 127.0.0.1:8989

3. Enter your username and password to log in.

4. On the dashboard, the "Servers" tab is shown by default.

5. Click the server that you want to set to maintenance mode. This will bring up a page for the specific server.

6. Click the gear icon at the top left corner of the page next to the server name. This will show some options in a popup.

7. Click the pause icon. This will open a popup window.

8. Click the "Maintain" button. If the specified server is a primary server, then MaxScale will allow open transactions to complete before closing any connections.

Forcing a Server to Maintenance Mode

1. Configure MaxScale for MaxGUI

2. Visit MaxGUI in your web browser. For example, if you are accessing it from local host with the default port, then visit this address: 127.0.0.1:8989

3. Enter your user and password to login.

4. On the dashboard, the "Servers" tab is shown by default.

5. Click the server that you want to set to maintenance mode. This will bring up a page for the specific server.

6. Click the gear icon at the top left corner of the page next to the server name. This will show some options in a popup.

7. Click the pause icon. This will open a popup window.

8. Check the "Force closing" checkbox.

9. Click the "Maintain" button. When the "Force closing" checkbox is specified, MaxScale immediately close all connections, even if the server is a primary server that has open transactions.

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

This document describes possible issues when upgrading MariaDB MaxScale from version 22.08 to 23.02.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, any existing configuration files should be backed up.

Removed Features

• The csmon and auroramon monitors have been removed.

• The obsolete maxctrl drain command has been removed.

• The maxctrl cluster commands have been removed.

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

This document describes possible issues when upgrading MariaDB MaxScale from version 6 to 22.08.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, any existing configuration files should be backed up.

Removed Features

• The support for legacy encryption keys generated with maxkeys from pre-2.5 versions has been removed. This feature was deprecated in MaxScale 2.5 when the new key storage format was introduced. To migrate to the new key storage format, create a new key file with maxkeys and re-encrypt the passwords withmaxpasswd.

• The deprecated Database Firewall filter has been removed.

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

This document describes possible issues when upgrading MariaDB MaxScale from version 2.5 to 6.

Note that the versioning scheme has changed and that version 6 immediately follows version 2.5. Effectively, the non-changing 2.-prefix has been dropped and henceforth at a major release, the major, instead of the minor version number, will be bumped. This change also affects how maintenance releases are versioned. For instance, 2.5.1, the first GA version of MaxScale 2.5, was followed by the maintenance release 2.5.2. 6.1, the first GA version of MaxScale 6, will be followed by the maintenance release 6.2.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, any existing configuration files should be backed up.

Duration Type Parameters

Using duration type parameters without an explicit suffix has been deprecated in MaxScale 2.4. In MaxScale 6 they are no longer allowed when used with the REST API or MaxCtrl. This means that any create or alter commands in MaxCtrl that use a duration type parameter must explicitly specify the suffix of the unit.

For example, the following command:

should be replaced with:

Duration type parameters can still be defined in the configuration file without an explicit suffix but this behavior is deprecated. The recommended approach is to add explicit suffixes to all duration type parameters when upgrading to MaxScale 6.

Changed Parameters

threads

The default value of threads was changed to auto.

Removed Parameters

Core Parameters

The following deprecated core parameters have been removed:

• thread_stack_size

Schemarouter

The deprecated aliases for the schemarouter parameters ignore_databases andignore_databases_regex have been removed. They can be replaced withignore_tables and ignore_tables_regex.

In addition, the preferred_server parameter that was deprecated in 2.5 has also been removed.

Session Command History

The prune_sescmd_history, max_sescmd_history and disable_sescmd_history have been made into generic service parameters that are shared between all routers that support it.

The default value of prune_sescmd_history was changed from false totrue. This was done as most MaxScale installations either benefit from it being enabled or are not affected by it.

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

This document describes particular issues to take into account when upgrading MariaDB MaxScale from version 2.0 to 2.1.

For more information about what has changed, please refer to the and to the .

Installation

Before starting the upgrade, we strongly recommend you back up your current configuration file.

IPv6 Support

MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to was changed from the IPv4 address 0.0.0.0 to the IPv6 address ::. To bind to the old IPv4 address, add address=0.0.0.0 to the listener definition.

Persisted Configuration Files

Starting with MaxScale 2.1, any changes made with the newly added will be persisted in a configuration file. These files are located in /var/lib/maxscale/maxscale.cnf.d/.

MaxScale Log Files

The name of the log file was changed from maxscaleN.log to maxscale.log. The default location for the log file is /var/log/maxscale/maxscale.log.

Rotating the log files will cause MaxScale to reopen the file instead of renaming them. This makes the MaxScale logging facility logrotate compatible.

ReadWriteSplit

The disable_sescmd_history option is now enabled by default. This means that slaves will not be recovered mid-session even if a replacement slave is available. To enable the legacy behavior, add the disable_sescmd_history=true parameter to the service definition.

Persistent Connections

The MariaDB session state is reset in MaxScale 2.1 for persistent connections. This means that any modifications to the session state (default database, user variable etc.) will not survive if the connection is put into the connection pool. For most users, this is the expected behavior.

User Data Cache

The location of the MariaDB user data cache was moved from/var/cache/maxscale/<Service> to /var/cache/maxscale/<Service>/<Listener>.

Galeramon Monitoring Algorithm

Galeramon will assign the master status only to the node which has awsrep_local_index value of 0. This will guarantee consistent writes with multiple MaxScales but it also causes slower changes of the master node.

To enable the legacy behavior, add root_node_as_master=false to the Galera monitor configuration.

MaxAdmin Editing Mode

The default editing mode was changed from vim to emacs mode. To start maxadmin in the legacy mode, use the -i option.

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

Overview

MaxScale's MaxScale's REST API is used by both and .

The REST API is enabled by default. However, the default configuration is not optimal for production systems, because:

• It only allows requests from the local host address by default.

• It does not use TLS by default.

• It used a hard-coded user (admin) and password (mariadb) by default.

Configuring MaxScale's REST API for Remote Connections

1. for remote connections by configuring several global parameters in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

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

Overview

When using MaxScale, it is often necessary to temporarily remove a server from the load balancing pool without actually shutting down the server. This is usually needed to perform maintenance on the server, such as when upgrading the server's software or when performing schema upgrades.

MaxScale allows users to set servers to "maintenance mode", which prevents MaxScale from routing traffic to the server and prevents it from being elected as the new primary server during failover or switchover.

MaxCtrl is a command-line utility that can perform administrative tasks using MaxScale's REST API. It can be used to set a server to maintenance mode.

Setting a Server to Maintenance Mode

1. Configure the REST API if the default configuration is not sufficient.

2. Use MaxCtrl to execute the set server command with the maintenance option:

Replace server1 with the name of the specific server.

1. If the specified server is a primary server, then MaxScale will allow open transactions to complete before closing any connections.

Forcing a Server to Maintenance Mode

1. Use MaxCtrl to execute the set server command with the maintenance --force option:

1. Replace server1 with the specific server name. When --force is used, MaxScale immediately closes all connections, even if the server is a primary server with open transactions.

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

This document describes how to configure a Galera cluster monitor.

Configuring the Monitor

Define the monitor that monitors the servers.

The mandatory parameters are the object type, the monitor module to use, the list of servers to monitor and the username and password to use when connecting to the servers. The monitor_interval parameter controls for how long the monitor waits between each monitoring loop.

This monitor module will assign one node within the Galera Cluster as the current primary and other nodes as replica. Only those nodes that are active members of the cluster are considered when making the choice of primary node. The primary node will be the node with the lowest value of wsrep_local_index.

Monitor User

The monitor user does not require any special grants to monitor a Galera cluster. To create a user for the monitor, execute the following SQL.

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

The routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a read-only query fails, then the router can retry the query on a different server.

Configuring Retries for Failed Reads

1. Configure retries for failed reads by configuring the retry_failed_reads parameter for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

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

Overview

In MariaDB MaxScale, authenticators perform the following tasks:

• Authenticating clients that connect to MaxScale

• Authenticating connections to back-end MariaDB Enterprise Server and MariaDB Xpand nodes

• Deciding how authentication should be performed

Authenticators Supported by MaxScale

The routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a server fails, then the router may need to retry failed queries on a different server. The retry may need to be delayed in some cases, such as when is in progress.

Configuring Delayed Retries for Failed Queries

1. Configure delayed retries for failed queries by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

For example:

1. Restart the MaxScale instance.

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

This document describes particular issues to take into account when upgrading MariaDB MaxScale from version 1.4 to 2.0.

For more information about what has changed, please refer to the and to the .

Installation

Before starting the upgrade, we strongly recommend you back up your current configuration file.

MaxAdmin

The default way the communication between MaxAdmin and MariaDB MaxScale is handled has been changed from an internet socket to a Unix domain socket. The former alternative is still available but has been deprecated.

If no arguments are given to MaxAdmin, it will attempt to connect to MariaDB MaxScale using a Unix domain socket. After the upgrade you will need to provide at least one internet socket related flag - -h, -P,-u or -p - to force MaxAdmin to use the internet socket approach.

E.g.

MySQL Monitor

The MySQL Monitor now assigns the stale state to the master server by default. In addition to this, the slave servers receive the stale slave state when they lose the connection to the master. This should not cause changes in behavior but the output of MaxAdmin will show new states when replication is broken.

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

MariaDB/MySQL Authenticator

The MariaDBAuth-module implements the client and backend authentication for the server plugin mysql_native_password. This is the default authentication plugin used by both MariaDB and MySQL.

Settings

The following settings may be given in the authenticator_options of the listener.

clear_pw_passthrough

Boolean, default value is "false". Activates passthrough-mode. In this mode, MaxScale does not check client credentials at all and defers authentication to the backend server. It may be useful in any situation where MaxScale cannot check the existence of client user account nor authenticate the client.

When a client connects to a listener with this setting enabled, MaxScale will change authentication method to "mysql_clear_password", causing the client to send their cleartext password to MaxScale. MaxScale will then attempt to use the password to authenticate to backends. The authentication result of the first backend to respond will be sent to the client. The backend may ask MaxScale for either cleartext password or standard ("mysql_native_password") authentication token. MaxScale can work with both backend plugins since it has the original password.

This feature is incompatible with service setting lazy_connect. Either leave it unspecified or set lazy_connect=false in the linked service. Also, multiple client authenticators are not allowed on the listener when passthrough-mode is on.

Because passwords are sent in cleartext, the listener should be configured for ssl.

log_password_mismatch

• Type:

• Mandatory: No

• Dynamic: No

• Default: false

The service setting log_auth_warnings must also be enabled for this setting to have effect. When both settings are enabled, password hashes are logged if a client gives a wrong password. This feature may be useful when diagnosing authentication issues. It should only be enabled on a secure system as the logging of password hashes may be a security risk.

cache_dir

Deprecated and ignored.

inject_service_user

Deprecated and ignored.

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

Overview

MaxScale's Native Authenticator is compatible with MariaDB Enterprise Server and MariaDB Xpand. It authenticates database users with the mysql_native_password .

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

This document describes possible issues when upgrading MariaDB MaxScale from version 23.02 to 23.08.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, any existing configuration files should be backed up.

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

This document describes possible issues when upgrading MariaDB MaxScale from version 2.4 to 2.5.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, any existing configuration files should be backed up.

MaxAdmin

The deprecated MaxAdmin interface has been removed in 2.5.0 in favor of the REST API and the MaxCtrl command line client. The cli and maxscaled modules can no longer be used.

Authentication

The credentials used by services now require additional grants. For a full list of required grants, refer to the .

MariaDB-Monitor

The settings detect_stale_master, detect_standalone_master anddetect_stale_slave are replaced by master_conditions andslave_conditions. The old settings may still be used, but will be removed in a later version.

Password encryption

The encrypted passwords feature has been updated to be more secure. Users are recommended to generate a new encryption key and re-encrypt their passwords using the maxkeys and maxpasswd utilities. Old passwords still work.

Default Server State

The default state of servers in 2.4 was Running and in 2.5 it is nowDown. This was done to prevent newly added servers from being accidentally used before they were monitored.

Columnstore Monitor

It is now mandatory to specify in the configuration what version the monitored Columnstore cluster is.

Please see the for details.

New binlog router

The binlog router delivered with MaxScale 2.5 is completely new and not 100% backward compatible with the binlog router delivered with earlier MaxScale versions. If you use the binlog router, carefully assess whether the functionality provided by the new one fulfills your requirements, before upgrading MaxScale.

Tee Filter

The tee filter parameter service has been deprecated in favor of the target parameter. All usages of service can be replaced with target.

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

Overview

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

The first step is to define the servers that make up the cluster. These servers will be used by the services and are monitored by the monitor.

The address and port parameters tell where the server is located.

Enabling TLS

To enable encryption for the MaxScale-to-MariaDB communication, add ssl=true to the server section. To enable server certificate verification, addssl_verify_peer_certificate=true.

The ssl and ssl_verify_peer_certificate parameters are similar to the--ssl and --ssl-verify-server-cert options of the mysql command line client.

For more information about TLS, refer to the .

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

Quickstart Guide: MariaDB MaxScale Authentication Modules

MariaDB MaxScale incorporates robust authentication modules to manage client access and ensure secure communication with your backend MariaDB servers. Understanding these modules is crucial for securing your database deployments when using MaxScale.

1. What are MaxScale Authentication Modules?

MaxScale's authentication modules (often referred to as "authenticator plugins") are components that handle client authentication. They determine how incoming clients verify their identity to MaxScale and, in turn, how MaxScale authenticates itself to the backend MariaDB servers. This process is similar to how authentication works directly with MariaDB Server using the MySQL protocol.

2. How Authentication Works in MaxScale

MaxScale employs a User Account Manager (UAM) for services that use a MariaDB protocol listener.

• The UAM is responsible for storing and managing user account information.

• It typically queries the mysql database on your backend MariaDB servers (usually the primary) to retrieve user account details.

• Using this information, the UAM authenticates connecting clients, verifies their passwords, and checks their database access rights.

• The user and password settings within your MaxScale service configuration define the credentials MaxScale uses to fetch these user accounts from the backend databases.

3. Available Authentication Plugins

MaxScale supports various authentication schemes through different plugins:

• Standard MySQL Password: This is the most common authentication method, verifying user credentials against those stored in the backend MariaDB server's mysql.user table (or similar).

• GSSAPI (Generic Security Service Application Programming Interface): Provides secure authentication methods, often used in enterprise environments with Kerberos or similar systems.

• PAM (Pluggable Authentication Modules): Allows MaxScale to integrate with PAM, enabling authentication against external systems like Unix system users, LDAP, or Active Directory.

4. Basic Configuration Concepts

Authentication options are primarily defined within the listener configuration of your MaxScale service in the maxscale.cnf file.

a. Specifying the Authenticator:

The authenticator parameter specifies which authentication plugin to use for a particular listener.

Example maxscale.cnf snippet (simplified):

Ini, TOML

[my_service]
type=service
router=readwritesplit
servers=server1,server2
user=maxscale_user # User MaxScale uses to connect to backend MariaDB for UAM
password=maxscale_password

[my_listener]
type=listener
service=my_service
protocol=MariaDBClient
port=3306
authenticator=MariaDBAuth # Example: Use the standard MariaDB password authentication
# authenticator=GSSAPIAuth # Or GSSAPI authentication
# authenticator=PAMAuth    # Or PAM authentication

b. Authenticator Options (authenticator_options):

Additional settings can be passed to the authenticator plugin using authenticator_options. These are comma-separated key-value pairs.

Common authenticator_options:

• skip_authentication=true: (Use with extreme caution, typically only for development/testing). This option bypasses password checks for connecting clients. Clients will still need a valid username in the backend database, but their password will not be verified.

• match_host=false: Disables host matching for user accounts. By default, MariaDB (and thus MaxScale's UAM) matches user accounts based on both username and host (e.g., 'user'@'localhost'). Setting this to false means only the username needs to match.

• lower_case_table_names=true/false: Controls how database names are matched during authentication, similar to the lower_case_table_names system variable in MariaDB Server.

Example with options:

Ini, TOML

[my_listener]
# ... other settings ...
authenticator=MariaDBAuth
authenticator_options=skip_authentication=true,match_host=false

By configuring these authentication modules, you can control how clients connect to your MariaDB through MaxScale, enforce security policies, and integrate with existing authentication infrastructure.

Further Resources:

• MariaDB MaxScale Authentication Modules Documentation

• MariaDB MaxScale Documentation

This document describes possible issues when upgrading MariaDB MaxScale from version 2.2 to 2.3.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, we recommend you back up your current configuration file.

Increased Memory Use

Starting with MaxScale 2.3.0 up to 40% of the memory can be used for caching parsed queries. The most noticeable change is that it improves performance in almost all cases where queries need to be parsed. Most of the time this happens when the readwritesplit router or filters are used.

The amount of memory that MaxScale uses can be controlled with thequery_classifier_cache_size parameter. For example, to limit the total memory to 1GB, add query_classifier_cache_size=1G to your configuration. To disable it, set the value to 0.

In addition to the aforementioned query classifier caching, the readwritesplit session command history is enabled by default in 2.3 but is limited to a maximum of 50 commands after which the history is disabled. This is unlikely to show in any metrics but it contributes to the increased memory footprint of MaxScale.

Unknown Global Parameters

All unknown parameters are now treated as errors. Check your configuration for errors if MaxScale fails to start after upgrading to 2.3.1.

passwd is deprecated

In the configuration file, passwords for monitors and services should be specified using password; the support for the deprecatedpasswd will be removed in the future. That is, the following

[The-Service]
type=service
passwd=some-service-password
...

[The-Monitor]
type=monitor
passwd=some-monitor-password
...

should be changed to

[The-Service]
type=service
password=some-service-password
...

[The-Monitor]
type=monitor
password=some-monitor-password
...

authenticator_options for servers is ignored

Authenticator options are now only used with listeners.

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

Overview

MaxCtrl is a command-line utility that can perform administrative tasks using MaxScale's REST API. It is possible to connect to MaxScale using TLS with MaxCtrl.

Connecting to MaxScale using TLS

1. Create a basic or admin user, depending on what kind of user you need:

$ maxctrl create user "maxscale_rest_admin" "maxscale_rest_admin_password" --type=admin

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

1. If you want to use MaxCtrl remotely, configure the REST API for remote connections. Several global parameters must be configured in maxscale.cnf.

For example:

[maxscale]
...
admin_host            = 0.0.0.0
admin_port            = 8443

1. . Several global parameters must be configured in maxscale.cnf.

For example:

[maxscale]
...
admin_ssl_key=/certs/server-key.pem
admin_ssl_cert=/certs/server-cert.pem
admin_ssl_ca_cert=/certs/ca-cert.pem

1. Ensure that the client also has a TLS certificate, a private key, and the CA certificate.

2. Use MaxCtrl to connect with TLS:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem

Replace maxscale_rest_admin and maxscale_rest_admin_password with the actual user and password.

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

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. If a replica server fails, then the router may need to create new connections to a different replica server for any existing client connections. The router takes certain steps to ensure that those new replica server connections have the same state as the old replica server connections.

Session Command History

The Read/Write Split Router (readwritesplit) maintains connection state on replica servers by keeping a session command history. If the router has to create a new connection, then it replays these session commands from the previous connection on the new connection.

Minimizing Memory Usage of Session Command History

The session command history can require a lot of memory if connections are long-lived. In these cases, there are two options to limit memory usage:

• Configure a maximum size for the session command history

• Disable the session command history. This option is not recommended, because you would lose out on the benefits of the session command history.

Configuring a Maximum Size of the Session Command History

1. Set the maximum size of the session command history by configuring some parameters for the Read/Write Split Router in maxscale.cnf.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
max_sescmd_history       = 1500
prune_sescmd_history     = true

1. Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Disabling the Session Command History

1. Disable the session command history by configuring the disable_sescmd_history parameter for the Read/Write Split Router in maxscale.cnf.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
disable_sescmd_history   = true

1. Restart the MaxScale instance.

$ sudo systemctl restart maxscale

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

MariaDB MaxScale MaxGUI Guide

Introduction

MaxGUI is a browser-based interface for MaxScale REST-API and query execution.

Enabling MaxGUI

To enable MaxGUI in a testing mode, add admin_host=0.0.0.0 andadmin_secure_gui=false under the [maxscale] section of the MaxScale configuration file. Once enabled, MaxGUI will be available on port 8989:http://127.0.0.1:8989/

Securing the GUI

To make MaxGUI secure, set admin_secure_gui=true and configure both theadmin_ssl_key and admin_ssl_cert parameters.

See Configuration Guide and Configuration and Hardening for instructions on how to harden your MaxScale installation for production use.

Authentication

MaxGUI uses the same credentials as maxctrl. The default username is admin with mariadb as the password.

Internally, MaxGUI uses JSON Web Tokens as the authentication method for persisting the user's session. If the Remember me checkbox is ticked, the session will persist for 24 hours. Otherwise, the session will expire as soon as MaxGUI is closed.

To log out, simply click the username section in the top right corner of the page header to access the logout menu.

Pages

Dashboard

This page provides an overview of MaxScale configuration which includes Monitors, Servers, Services, Sessions, Listeners, and Filters.

By default, the refresh interval is 10 seconds.

Detail

This page shows information on each MaxScale object and allow to edit its parameter, relationships and perform other manipulation operations.

Access this page by clicking on the MaxScale object name on the dashboard page

Visualization

This page visualizes MaxScale configuration and clusters.

• Configuration: Visualizing MaxScale configuration.

• Cluster: Visualizing a replication cluster into a tree graph and provides manual cluster manipulation operations such asswitchover, reset-replication, release-locks, failover, rejoin . At the moment, it supports only servers monitored by Monitor using mariadbmon module.

Access this page by clicking the graph icon on the sidebar navigation.

Settings

This page shows and allows editing of MaxScale parameters.

Access this page by clicking the gear icon on the sidebar navigation.

Logs Archive

Realtime MaxScale logs can be accessed by clicking the logs icon on the sidebar navigation.

Workspace

The "Workspace" page offers a versatile set of tools for effectively managing data and database interactions. It includes the following key tasks:

1. Run Queries

Execute queries on various servers, services, or listeners to retrieve data and perform database operations. Visualize query results using different graph types such as line, bar, or scatter graphs. Export query results in formats like CSV or JSON for further analysis and sharing.

2. Data Migration

The "Data Migration" feature facilitates seamless transitions from PostgreSQL to MariaDB. Transfer data and database structures between the two systems while ensuring data integrity and consistency throughout the process.

3. Create an ERD

Generating Entity-Relationship Diagrams (ERDs) to gain insights regarding data structure, optimizing database design for both efficiency and clarity.

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

Overview

MaxScale has a REST API, which can be configured to require authentication. When it is first installed, it has a single default admin user (admin) and password (mariadb). However, this user can be deleted, and other users can be created.

MaxCtrl is a command-line utility that can perform administrative tasks using MaxScale's REST API. It can be used to delete a user for the REST API.

Deleting a User

1. Configure the REST API if the default configuration is not sufficient.

2. Use MaxCtrl to execute the destroy user command:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   destroy user "admin"

Replace admin with the actual user.

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

The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If the primary server fails, then the router can automatically reconnect existing client connections to the new primary server.

Configuring Automatic Primary Server Re-connection

1. Configure automatic primary server re-connection by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
master_reconnection            = true
master_failure_mode            = fail_on_write

1. Restart the MaxScale instance.

$ sudo systemctl restart maxscale

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

The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a server fails, then the router may need to replay in-progress transactions on a different server.

Session Command History

The Read/Write Split Router (readwritesplit) maintains connection state on replica servers by keeping a session command history. If the router has to create a new connection, then it replays these session commands from the previous connection on the new connection.

Minimizing Memory Usage of Session Command History

The session command history can require a lot of memory if connections are long-lived. In these cases, there are two options to limit memory usage:

• Configure a maximum size for the session command history

• Disable the session command history. This option is not recommended, because you would lose out on the benefits of the session command history.

Configuring Transaction Replay

1. Configure transaction replay by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
transaction_replay                   = true
transaction_replay_max_size          = 10Mi
transaction_replay_attempts          = 10
transaction_replay_retry_on_deadlock = true

1. Restart the MaxScale instance.

$ sudo systemctl restart maxscale

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

Module commands

Introduced in MaxScale 2.1, the module commands are special, module-specific commands. They allow the modules to expand beyond the capabilities of the module API. Currently, only MaxCtrl implements an interface to the module commands.

All registered module commands can be shown with maxctrl list commands and they can be executed with maxctrl call command <module> <name> ARGS... whereis the name of the module and is the name of the command.ARGS is a command specific list of arguments.

Developer reference

The module command API is defined in the modulecmd.h header. It consists of various functions to register and call module commands. Read the function documentation in the header for more details.

The following example registers the module command my_command for modulemy_module.

#include <maxscale/modulecmd.hh>

bool my_simple_cmd(const MODULECMD_ARG *argv)
{
    printf("%d arguments given\n", argv->argc);
}

int main(int argc, char **argv)
{
    modulecmd_arg_type_t my_args[] =
    {
        {MODULECMD_ARG_BOOLEAN, "This is a boolean parameter"},
        {MODULECMD_ARG_STRING | MODULECMD_ARG_OPTIONAL, "This is an optional string parameter"}
    };

    // Register the command
    modulecmd_register_command("my_module", "my_command", my_simple_cmd, 2, my_args);

    // Find the registered command
    const MODULECMD *cmd = modulecmd_find_command("my_module", "my_command");

    // Parse the arguments for the command
    const void *arglist[] = {"true", "optional string"};
    MODULECMD_ARG *arg = modulecmd_arg_parse(cmd, arglist, 2);

    // Call the module command
    modulecmd_call_command(cmd, arg);

    // Free the parsed arguments
    modulecmd_arg_free(arg);
    return 0;
}

The array my_args of type modulecmd_arg_type_t is used to tell what kinds of arguments the command expects. The first argument is a boolean and the second argument is an optional string.

Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects.

When the module command is executed, the argv parameter for themy_simple_cmd contains the parsed arguments received from the caller of the command.

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

The goal of this tutorial is to configure a system that appears to the client as a single database. MariaDB MaxScale will split the statements such that write statements are sent to the primary server and read statements are balanced across the replica servers.

Setting up MariaDB MaxScale

This tutorial is a part of MariaDB MaxScale Tutorial. Please read it and follow the instructions. Return here once basic setup is complete.

Configuring the service

After configuring the servers and the monitor, we create a read-write-splitter service configuration. Create the following section in your configuration file. The section name is also the name of the service and should be meaningful. For this tutorial, we use the name Splitter-Service.

[Splitter-Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw

router defines the routing module used. Here we use readwritesplit for query-level read-write-splitting.

A service needs a list of servers where queries will be routed to. The server names must match the names of server sections in the configuration file and not the hostnames or addresses of the servers.

The user and password parameters define the credentials the service uses to populate user authentication data. These users were created at the start of the MaxScale Tutorial.

For increased security, see password encryption.

Configuring the Listener

To allow network connections to a service, a network ports must be associated with it. This is done by creating a separate listener section in the configuration file. A service may have multiple listeners but for this tutorial one is enough.

[Splitter-Listener]
type=listener
service=Splitter-Service
port=3306

The service parameter tells which service the listener connects to. For theSplitter-Listener we set it to Splitter-Service.

A listener must define the network port to listen on.

The optional address-parameter defines the local address the listener should bind to. This may be required when the host machine has multiple network interfaces. The default behavior is to listen on all network interfaces (the IPv6 address ::).

Starting MariaDB MaxScale

For the last steps, please return to MaxScale Tutorial.

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

Comment Filter

Overview

With the comment filter it is possible to define comments that are injected before the actual statements. These comments appear as sql comments when they are received by the server.

[MyComment]
type=filter
module=comment
inject="Comment to be injected"

[MyService]
type=service
router=readwritesplit
servers=server1
user=myuser
password=mypasswd
filters=MyComment

Settings

The Comment filter requires one mandatory parameter to be defined.

inject

• Type: string

• Mandatory: Yes

• Dynamic: Yes

A parameter that contains the comment injected before the statements. There is also defined variable $IP that can be used to comment the IP address of the client in the injected comment. Variables must be written in all caps.

Examples

Example 1 - Inject IP address of the connected client into statements

as comment.

The following configuration adds the IP address of the client to the comment.

[IPComment]
type=filter
module=comment
inject="IP=$IP"

[MyService]
type=service
router=readwritesplit
servers=server1
user=myuser
password=mypasswd
filters=IPComment

In this example when MaxScale receives statement like:

SELECT user FROM people;

It would look like

/* IP=::ffff:127.0.0.1 */SELECT user FROM people;

when received by server.

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

MaxScale CDC Connector

The C++ connector for the MariaDB MaxScaleCDC system.

Usage

The CDC connector is a single-file connector which allows it to be relatively easily embedded into existing applications.

To start using the connector, either download it from the MariaDB website or configure the MaxScale repository and install the maxscale-cdc-connector package.

API Overview

A CDC connection object is prepared by instantiating the CDC::Connection class. To create the actual connection, call the CDC::Connection::connect method of the class.

After the connection has been created, call the CDC::Connection::read method to get a row of data. The CDC::Row::length method tells how many values a row has and CDC::Row::value is used to access that value. The field name of a value can be extracted with the CDC::Row::key method and the current GTID of a row of data is retrieved with the CDC::Row::gtid method.

To close the connection, destroy the instantiated object.

Examples

The source code contains an example that demonstrates basic usage of the MaxScale CDC Connector.

Dependencies

The CDC connector depends on:

• OpenSSL

• Jansson

RHEL/CentOS 7

sudo yum -y install epel-release
sudo yum -y install jansson openssl-devel cmake make gcc-c++ git

Debian Stretch and Ubuntu Xenial

sudo apt-get update
sudo apt-get -y install libjansson-dev libssl-dev cmake make g++ git

Debian Jessie

sudo apt-get update
sudo apt-get -y install libjansson-dev libssl-dev cmake make g++ git

openSUSE Leap 42.3

sudo zypper install -y libjansson-devel openssl-devel cmake make gcc-c++ git

Building and Packaging

To build and package the connector as a library, follow MaxScale build instructions with the exception of adding -DTARGET_COMPONENT=devel to the CMake call.

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

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. It selects a replica server to execute a query using criteria configured by the slave_selection_criteria parameter.

Using Adaptive Routing

The Read/Write Split Router (readwritesplit) uses adaptive routing when the slave_selection_criteria parameter is set to ADAPTIVE_ROUTING.

In this mode, the router measures average server response times. When the router routes queries, it compares the response times of the different replica servers. It favors the faster servers for most queries, while still guaranteeing some traffic on the slowest servers.

Using Least Behind Primary

The Read/Write Split Router (readwritesplit) uses the replica server that is least behind the primary server when the slave_selection_criteria parameter is set to LEAST_BEHIND_MASTER. This mode is only compatible with .

In this mode, the router measures replica lag using the Seconds_Behind_Master column from SHOW REPLICA STATUS. The replica server that has the lowest value is considered to be the least behind the primary server.

Setting the Replica Selection Criteria

1. Set the replica selection criteria by configuring the slave_selection_criteria parameter for the Read/Write Split Router in maxscale.cnf:

[split-router]
type                     = service
router                   = readwritesplit
...
slave_selection_criteria = LEAST_GLOBAL_CONNECTIONS

1. Restart the MaxScale instance.

$ sudo systemctl restart maxscale

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

The goal of this tutorial is to configure a system that has two ports available, one for write connections and another for read connections. The read connections are load- balanced across replica servers.

Setting up MariaDB MaxScale

This tutorial is a part of the MariaDB MaxScale Tutorial. Please read it and follow the instructions. Return here once basic setup is complete.

Configuring services

We want two services and ports to which the client application can connect. One service routes client connections to the primary server, the other load balances between replica servers. To achieve this, we need to define two services in the configuration file.

Create the following two sections in your configuration file. The section names are the names of the services and should be meaningful. For this tutorial, we use the namesWrite-Service and Read-Service.

[Write-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw

[Read-Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw

router defines the routing module used. Here we use readconnroute for connection-level routing.

A service needs a list of servers to route queries to. The server names must match the names of server sections in the configuration file and not the hostnames or addresses of the servers.

The router_options-parameter tells the readconnroute-module which servers it should route a client connection to. For the write service we use the master-type and for the read service the slave-type.

The user and password parameters define the credentials the service uses to populate user authentication data. These users were created at the start of the MaxScale Tutorial.

For increased security, see password encryption.

Configuring the Listener

To allow network connections to a service, a network ports must be associated with it. This is done by creating a separate listener section in the configuration file. A service may have multiple listeners but for this tutorial one per service is enough.

[Write-Listener]
type=listener
service=Write-Service
port=3306

[Read-Listener]
type=listener
service=Read-Service
port=3307

The service parameter tells which service the listener connects to. For theWrite-Listener we set it to Write-Service and for the Read-Listener we set it to Read-Service.

A listener must define the network port to listen on.

The optional address-parameter defines the local address the listener should bind to. This may be required when the host machine has multiple network interfaces. The default behavior is to listen on all network interfaces (the IPv6 address ::).

Starting MariaDB MaxScale

For the last steps, please return to MaxScale Tutorial.

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

This document describes how to configure a MariaDB primary-replica cluster monitor to be used with MaxScale.

Configuring the Monitor

Define the monitor that monitors the servers.

[Replication-Monitor]
type=monitor
module=mariadbmon
servers=dbserv1, dbserv2, dbserv3
user=monitor_user
password=my_password
monitor_interval=2000ms

The mandatory parameters are the object type, the monitor module to use, the list of servers to monitor and the username and password to use when connecting to the servers. The monitor_interval parameter controls for how long the monitor waits between each monitoring loop.

Monitor User

The monitor user requires the REPLICATION CLIENT privileges to do basic monitoring. To create a user with the proper grants, execute the following SQL.

CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'my_password';
GRANT REPLICATION CLIENT ON *.* TO 'monitor_user'@'%';

Note: If the automatic failover of the MariaDB Monitor will used, the user will require additional grants. Execute the following SQL to grant them.

GRANT SUPER, RELOAD ON *.* TO 'monitor_user'@'%';

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

Quickstart Guide: MariaDB MaxScale Overview

MariaDB MaxScale is an advanced, open-source database proxy, router, and load balancer designed to enhance the scalability, high availability, and security of your MariaDB deployments. It acts as an intelligent intermediary between your applications and your MariaDB servers, abstracting the underlying database topology.

1. What is MariaDB MaxScale?

MaxScale is not a database itself, but a sophisticated gateway that understands the MariaDB protocol. It intercepts client connections and routes them to the appropriate backend MariaDB servers based on configured rules, health checks, and workload types. This allows for flexible and dynamic management of database traffic without requiring changes to the application code.

2. Core Functionalities and Benefits

MariaDB MaxScale provides several key functionalities that contribute to optimizing MariaDB environments:

• Intelligent Routing and Load Balancing:

  • ReadWriteSplit Router: This is a primary feature that automatically distinguishes between read (SELECT) and write (INSERT, UPDATE, DELETE, DDL) statements. It intelligently routes all write statements to the designated primary server and distributes read statements across multiple replica servers, significantly improving read scalability and reducing the load on the primary.

  • Other Routers: MaxScale offers various routers for different use cases, such as routing to specific databases, connection-based routing, or custom routing logic.

• High Availability and Automated Failover:

  • MaxScale constantly monitors the health of your MariaDB servers. In a replication setup (e.g., primary-replica or Galera Cluster), if the primary server fails, MaxScale can automatically detect the failure, promote a healthy replica to become the new primary, and seamlessly redirect client connections to the newly promoted server. This minimizes downtime and ensures continuous operation.

• Seamless Server Maintenance:

  • MaxScale provides built-in mechanisms to place backend servers into maintenance mode without interrupting connected applications or clients. This allows administrators to perform tasks like patching, upgrades, or reconfigurations on individual servers while MaxScale intelligently redirects traffic away from them. Management can be done via the maxctrl command-line interface, MaxGUI (web interface), or REST API.

• Security and Traffic Control:

  • MaxScale can implement granular security policies and traffic controls for database connections and queries. This includes features like firewalling, query filtering, and authentication proxying.

  • QLAfilter (Query Log Anonymizer Filter): This filter can be used to create an audit trail by logging all queries, with options to anonymize sensitive data, aiding in security audits and performance analysis.

• Protocol Compatibility: MaxScale is designed to be compatible with standard MariaDB and MySQL client protocols, making it transparent to most applications.

By abstracting the database topology and intelligently managing connections, MariaDB MaxScale helps organizations achieve higher availability, better performance, and enhanced security for their MariaDB deployments.

Further Resources:

Building MariaDB MaxScale from Source Code

MariaDB MaxScale can be built on any system that meets the requirements. The main requirements are as follows:

• CMake version 3.16 or later (Packaging requires CMake 3.25.1 or later)

• GCC version 4.9 or later

• OpenSSL version 1.0.1 or later

• GNUTLS

• Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl

• PAM

• SASL2 (cyrus-sasl)

• SQLite3 version 3.3 or later

• Tcl

• git

• jansson

• libatomic

• libcurl

• libmicrohttpd

• libuuid

• libxml2

• libssh

• pcre2

• zstd

This is the minimum set of requirements that must be met to build the MaxScale core package. Some modules in MaxScale require optional extra dependencies.

• libuuid (binlogrouter)

• boost (binlogrouter)

• Bison 2.7 or later (dbfwfilter)

• Flex 2.5.35 or later (dbfwfilter)

• librdkafka (kafkacdc, kafkaimporter and mirror)

• memcached (storage_memcached for the cache filter)

• hiredis (storage_redis for the cache filter)

Some of these dependencies are not available on all operating systems and are downloaded automatically during the build step. To skip the building of modules that need automatic downloading of the dependencies, use -DBUNDLE=N when configuring CMake.

Quickstart

This installs MaxScale as if it was installed from a package. Install git before running the following commands.

Required Packages

For a definitive list of packages, consult the script.

Configuring the Build

The tests and other parts of the build can be controlled via CMake arguments.

Here is a small table with the names of the most common parameters and what they control. These should all be given as parameters to the -D switch inNAME=VALUE format (e.g. -DBUILD_TESTS=Y).

Note: You can look into for a list of the CMake variables.

Running unit tests

To run the MaxScale unit test suite, configure the build with -DBUILD_TESTS=Y, compile and then run the make test command.

Building MariaDB MaxScale packages

If you wish to build packages, just add -DPACKAGE=Y to the CMake invocation and build the package with make package instead of installing MaxScale withmake install. This process will create a RPM/DEB package depending on your system.

To build a tarball, add -DTARBALL=Y to the cmake invocation. This will create a maxscale-x.y.z.tar.gz file where x.y.z is the version number.

Some Debian and Ubuntu systems suffer from a bug where make package fails with errors from dpkg-shlibdeps. This can be fixed by running make beforemake package and adding the path to the libmaxscale-common.so library to the LD_LIBRARY_PATH environment variable.

Installing optional components

The MaxScale build system is split into multiple components. The main component is the core MaxScale package which contains MaxScale and all the modules. This is the default component that is build, installed and packaged. There is also the experimental component that contains all experimental modules which are not considered as part of the core MaxScale package and are either alpha or beta quality modules.

To build the experimental modules along with the MaxScale core components, invoke CMake with -DTARGET_COMPONENT=core,experimental.

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

Installing MariaDB MaxScale using a tarball

MariaDB MaxScale is also made available as a tarball, which is named likemaxscale-x.y.z.OS.tar.gz where x.y.z is the same as the corresponding version and OS identifies the operating system, e.g. maxscale-2.5.6.centos.7.tar.gz.

In order to use the tarball, the following libraries are required:

• libcurl

• libaio

• OpenSSL

• gnutls

• libatomic

• unixODBC

The tarball has been built with the assumption that it will be installed in /usr/local. However, it is possible to install it in any directory, but in that case MariaDB MaxScale must be invoked with a flag.

Installing as root in /usr/local

If you have root access to the system you probably want to install MariaDB MaxScale under the user and group maxscale.

The required steps are as follows:

Creating the symbolic link is necessary, since MariaDB MaxScale has been built with the assumption that the plugin directory is /usr/local/maxscale/lib/maxscale.

The symbolic link also makes it easy to switch between different versions of MariaDB MaxScale that have been installed side by side in /usr/local; just make the symbolic link point to another installation.

In addition, the first time you install MariaDB MaxScale from a tarball you need to create the following directories:

and make maxscale the owner of them:

The following step is to create the MariaDB MaxScale configuration file /etc/maxscale.cnf. The file etc/maxscale.cnf.template can be used as a base. Please refer to for details.

When the configuration file has been created, MariaDB MaxScale can be started.

The -d flag causes maxscale not to turn itself into a daemon, which is advisable the first time MariaDB MaxScale is started, as it makes it easier to spot problems.

If you want to place the configuration file somewhere else but in /etc you can invoke MariaDB MaxScale with the --config flag, for instance, --config=/usr/local/maxscale/etc/maxscale.cnf.

Note also that if you want to keep everything under /usr/local/maxscale you can invoke MariaDB MaxScale using the flag --basedir.

That will cause MariaDB MaxScale to look for its configuration file in/usr/local/maxscale/etc and to store all runtime files under /usr/local/maxscale/var.

Installing in any Directory

Enter a directory where you have the right to create a subdirectory. Then do as follows.

The next step is to create the MaxScale configuration file maxscale-x.y.z/etc/maxscale.cnf. The file maxscale-x.y.z/etc/maxscale.cnf.template can be used as a base. Please refer to for details.

When the configuration file has been created, MariaDB MaxScale can be started.

With the flag --basedir, MariaDB MaxScale is told where the lib, etc and var directories are found. Unless it is specified, MariaDB MaxScale assumes the lib directory is found in /usr/local/maxscale, and the var and etc directories in /.

It is also possible to specify the directories and the location of the configuration file individually. Invoke MaxScale like

to find out the appropriate flags.

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

Quickstart Guide: MariaDB MaxScale Limitations

While MariaDB MaxScale is a powerful tool for managing MariaDB deployments, it's essential to be aware of its limitations to ensure proper configuration and avoid unexpected behavior. This guide highlights key considerations when deploying and using MaxScale.

1. Configuration File Line Length

• Limitation: Older versions of MaxScale (2.1.2 and earlier) had a strict line length limit of 1024 characters in the configuration file (maxscale.cnf).

• Consideration: Ensure your MaxScale configuration lines do not exceed this limit for older versions. Modern versions (e.g., 2.3.0 and later) have significantly increased this limit (to 16,777,216 characters), making it less of a concern for current deployments. Always check the documentation for your specific MaxScale version.

2. Assumptions about MariaDB Server Configuration

• Limitation: MaxScale operates under the assumption that certain MariaDB Server configuration parameters are set to their default values. A critical example is the assumption that autocommit is enabled for new connections.

• Consideration: If your backend MariaDB servers deviate from default autocommit settings or other assumed defaults, it could lead to unexpected behavior in how MaxScale manages connections and routes queries, particularly with transaction handling. Always verify that your MariaDB server configurations align with MaxScale's expectations as outlined in its documentation.

3. Transaction Boundary Detection and XA Transactions

• Limitation: MaxScale uses a custom SQL parser to deduce transaction boundaries. This parser may not fully comprehend or correctly classify highly complex SQL statements or certain edge cases. This can lead to a mismatch between MaxScale's understanding of a connection's transaction state and the actual state on the backend database.

• Specific Issue with XA Transactions: If a START TRANSACTION command fails internally on the backend due to an already open XA transaction (e.g., using XA START), MaxScale's parser might not correctly detect this failure. It could mistakenly assume a new transaction has started, leading to discrepancies in transaction state awareness, especially with the readwritesplit router.

• Consideration: Be cautious with overly complex SQL or when using XA transactions in conjunction with MaxScale's transaction-aware routers. Thoroughly test your application's transaction logic through MaxScale to identify and mitigate any potential inconsistencies.

4. ETL Feature Dependency

• Limitation: The ETL (Extract, Transform, Load) feature within MaxScale relies on the MariaDB Connector/ODBC driver for its functionality.

• Consideration: To ensure stability and avoid potential crashes or memory leaks when using MaxScale's ETL capabilities, it is highly recommended to use MariaDB Connector/ODBC driver version 3.1.18 or later. Always ensure all components are compatible.

Important General Considerations:

• Query Classification: MaxScale's ability to route queries correctly relies on its query classification. If queries are ambiguous or use non-standard SQL, they might be misrouted.

• Prepared Statements: While supported, complex interactions with prepared statements can sometimes expose nuances in parsing or routing.

• Protocol Specifics: MaxScale aims for broad compatibility, but subtle differences in client or server protocol implementations might arise.

• Monitoring and Filters: Be aware that specific monitor or filter modules might have their own inherent limitations or performance impacts.

Understanding these limitations helps in designing a robust MaxScale deployment and troubleshooting potential issues effectively.

Further Resources:

Overview

MaxScale has a , which can be configured to require authentication. When first installed, it has a single default admin user (admin) and password (mariadb). However, this user can be deleted, and other users can be created.

is a command-line utility that can perform administrative tasks using MaxScale's . It can create a user for the REST API.

User Types

There are two types of users:

Creating a Basic User

1. Configure the if the default configuration is not sufficient.

2. Use to execute the create user command:

Replace maxscale_rest and maxscale_rest_password with the desired user and password.

Creating an Admin User

1. Configure the if the default configuration is not sufficient.

2. Use to execute the create user command with the --type=admin option:

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

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

The output of the maxctrl create report command produces a JSON payload that contains the current state of MaxScale. This includes the runtime configuration and the status all objects in MaxScale.

The maxctrl create report command was added in MaxScale 2.5.20.

Creating a MaxCtrl Report

The report can be created with:

After the command completes, the data is in maxctrl-report.json.

The file in which the output is stored is the only argument to this command. Recent versions of maxctrl pipe the output to the standard output if no filename is given. This can be useful for environments where copying files may be difficult (e.g. docker).

Using jq

The easiest way to inspect the JSON output is to use the jq program:

It is usually available as a package in most operating systems.

List servers

List services

List monitors

List listeners

List filters

List keys of objects

This can be combined with the object field access to list the fields of sub-objects. The following lists the keys in the first server object.

Get a specific service

Change the RW-Split-Router to the name of the service you're looking for.

Get a specific monitor

Change the MariaDB-Monitor to the name of the monitor you're looking for.

Get a specific server

Change the DB-1 to the name of the server you're looking for.

Find the monitor for a server

Change DB-1 to the name of the server you're looking for.

Memory used by the query classifier cache

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

This document describes possible issues when upgrading MariaDB MaxScale from version 2.3 to 2.4.

For more information about what has changed, please refer to the and to the .

Before starting the upgrade, we recommend you back up your current configuration file.

Section Names

Reserved Names

Section and object names starting with @@ are now reserved for internal use by MaxScale.

In case such names have been used, they must manually be changed in all configuration files of MaxScale, before MaxScale 2.4 is started.

Those files are:

• The main configuration file; typically /etc/maxscale.cnf.

• All nested configuration files; typically /etc/maxscale.cnf.d/*.

• All dynamic configuration files; typically /var/lib/maxscale/maxscale.cnd.d/*.

Whitespace in Names

Whitespace in section names that was deprecated in MaxScale 2.2 will now be rejected, which will cause the startup of MaxScale to fail.

To prevent that, section names like

must be changed, for instance, to

Durations

Durations can now be specified using one of the suffixes h, m, s and ms for specifying durations in hours, minutes, seconds and milliseconds, respectively.

Not providing an explicit unit has been deprecated in MaxScale 2.4, so it is advisable to add suffixes to durations. For instance,

Improved Admin User Encryption

MaxScale 2.4 will use a SHA2-512 hash for new admin user passwords. To upgrade a user to use the better hashing algorithm, either recreate the user or use themaxctrl alter user command.

MariaDB-Monitor

The following settings have been removed and cause a startup error if defined:

• mysql51_replication

• multimaster

• allow_cluster_recovery.

ReadWriteSplit

• If multiple masters are available for a readwritesplit service, the one with the lowest connection count is selected.

• If a master server is placed into maintenance mode, all open transactions are allowed to gracefully finish before the session is closed. To forcefully close the connections, use the --force option for maxctrl set server.

• The lazy_connect feature can be used as a workaround to . It also reduces the overall load on the system when connections are rapidly opened and closed.

• Transaction replays now have a limit on how many times a replay is attempted. The default values is five attempts and is controlled by thetransaction_replay_attempts parameter.

• If transaction replay is enabled and a deadlock occurs (SQLSTATE 40XXX), the transaction is automatically retried.

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

Encrypting Passwords

Note: The password encryption format changed in MaxScale 2.5. All encrypted passwords created with MaxScale 2.4 or older need to be re-encrypted.

There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys, use the maxkeys command.

By default the key file will be generated in /var/lib/maxscale. If a different directory is required, it can be given as the first argument to the program. For more information, see maxkeys --help.

Once the keys have been created the maxpasswd command can be used to generate the encrypted password.

The username and password, either encrypted or plain text, are stored in the service section using the user and password parameters.

If a custom location was used for the key file, give it as the first argument tomaxpasswd and pass the password to be encrypted as the second argument. For more information, see maxkeys --help.

Here is an example configuration that uses an encrypted password.

If the key file is not in the default location, the parameter must be set to the directory that contains it.

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

Maxrows

Overview

The Maxrows filter is capable of restricting the amount of rows that a SELECT, a prepared statement or stored procedure could return to the client application.

If a resultset from a backend server has more rows than the configured limit or the resultset size exceeds the configured size, an empty result will be sent to the client.

Configuration

The Maxrows filter is easy to configure and to add to any existing service.

Settings

The Maxrows filter has no mandatory parameters. Optional parameters are:

max_resultset_rows

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: (no limit)

Specifies the maximum number of rows a resultset can have in order to be returned to the user.

If a resultset is larger than this an empty result will be sent instead.

max_resultset_size

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: 64Ki

Specifies the maximum size a resultset can have in order to be sent to the client. A resultset larger than this, will not be sent: an empty resultset will be sent instead.

max_resultset_return

• Type:

• Mandatory: No

• Dynamic: Yes

• Values: empty, error, ok

• Default: empty

Specifies what the filter sends to the client when the rows or size limit is hit, possible values:

• an empty result set

• an error packet with input SQL

• an OK packet

Example output with ERR packet:

debug

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

An integer value, using which the level of debug logging made by the Maxrows filter can be controlled. The value is actually a bitfield with different bits denoting different logging.

• 0 (0b00000) No logging is made.

• 1 (0b00001) A decision to handle data form server is logged.

• 2 (0b00010) Reached max_resultset_rows or max_resultset_size is logged.

To log everything, give debug a value of 3.

Example Configuration

Here is an example of filter configuration where the maximum number of returned rows is 10000 and maximum allowed resultset size is 256KB

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

MaxScale 25.01 GSSAPI Client Authenticator

GSSAPI Client Authenticator

GSSAPI is an authentication protocol that is commonly implemented with Kerberos on Unix or Active Directory on Windows. This document describes GSSAPI authentication in MaxScale. The authentication module name in MaxScale isGSSAPIAuth.

Preparing the GSSAPI system

For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short guide on how to set up Kerberos for MaxScale.

The first step is to configure MariaDB to use GSSAPI authentication. The MariaDB documentation for the is a good example on how to set it up.

The next step is to copy the keytab file from the server where MariaDB is installed to the server where MaxScale is located. The keytab file must be placed in the configured default location which almost always is/etc/krb5.keytab. Alternatively, the keytab filepath can be given as an authenticator option.

The location of the keytab file can be changed with the KRB5_KTNAME environment variable:

To take GSSAPI authentication into use, add the following to the listener.

The principal name should be the same as on the MariaDB servers.

Settings

principal_name

• Type: string

• Mandatory: No

• Dynamic: No

• Default: mariadb/localhost.localdomain

The service principal name to send to the client. This parameter is a string parameter which is used by the client to request the token.

This parameter must be the same as the principal name that the backend MariaDB server uses.

gssapi_keytab_path

• Type: path

• Mandatory: No

• Dynamic: No

• Default: Kerberos Default

Keytab file location. This should be an absolute path to the file containing the keytab. If not defined, Kerberos will search from a default location, usually/etc/krb5.keytab. This path is set to an environment variable. This means that multiple listeners with GSSAPIAuth will override each other. If using multiple GSSAPI authenticators, either do not set this option or use the same value for all listeners.

Implementation details

Read the document for more details on how authentication modules work in MaxScale.

GSSAPI authentication

The GSSAPI plugin authentication starts when the database server sends the service principal name in the AuthSwitchRequest packet. The principal name will usually be in the form service@REALM.COM.

The client searches its local cache for a token for the service or may request it from the GSSAPI server. If found, the client sends the token to the database server. The database server verifies the authenticity of the token using its keytab file and sends the final OK packet to the client.

Building the module

The GSSAPI authenticator modules require the GSSAPI development libraries (krb5-devel on CentOS 7).

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

Optimistic Transaction Execution Filter

The optimistictrx filter implements optimistic transaction execution. The filter is designed for a use-case where most of the transactions are read-only and writes happen rarely but each set of read-only statements is still grouped into a read-write transaction (i.e. START TRANSACTION, BEGIN orSET autocommit=0).

This filter will replace the BEGIN and START TRANSACTION SQL commands withSTART TRANSACTION READ ONLY. If the transaction is fully read-only, the transaction completes normally. However, if a write happens in the middle of a transaction, the filter issues a ROLLBACK command and then replays the read-only part of the transaction, including the original BEGIN statement. If the results of the replayed read-only part of the transaction is identical to the one that was returned to the client, the transaction proceeds normally. If the result checksum does not match, the connection is closed to prevent a write with the wrong transaction state from happening.

Configuration

To add the filter to a service, define an instance of the filter and then add it to a service's filters list:

This can also be done at runtime with:

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

performs query-based load balancing. For each client connected to MaxScale, it opens up connections to multiple back-end database servers. When the client sends a write query to MaxScale, it routes the query to the connection opened with the primary server. When the client sends a read query to MaxScale, it routes the query to a connection opened with one of the replicas.

This page contains topics that need to be considered when designing applications that use the Read/Write Split Router.

• How does the

• How does the

• How does the

• How does the

• How does the

Additional information is available .

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

MaxScale's performs query-based load balancing. For each client connected to MaxScale, it opens up connections to multiple back-end database servers. When the client sends a write query to MaxScale, it routes the query to the connection opened with the primary server. When the client sends a read query to MaxScale, it routes the query to a connection opened with one of the replicas.

What Does the Read/Write Split Router Support?

The supports:

• deployments

• deployments

• deployments

When to Use the Read/Write Split Router?

The allows you to:

• Perform query-based load balancing.

• Route client connections to multiple servers simultaneously.

• Route write queries to primary and read queries to replicas.

• Automatically reconnect clients to the new primary after failover or switchover.

• Automatically replay transactions on the new primary after failover or switchover.

• Automatically retry failed queries.

• Enforce causal reads to avoid reading stale data caused by slave lag.

Deploying Read/Write Split Router

• Deploy Xpand Topology

• write-split-router-usageDeploy MaxScale with MariaDB Monitor and Read/Write Split Router

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

Overview

MariaDB MaxScale is an advanced proxy, router, and load balancer:

• MaxScale performs automated failover for MariaDB replication. When the primary server fails, MaxScale promotes a replica to be the new primary and redirects the remaining replicas to it.

• MaxScale's ReadWriteSplit router performs query-based load balancing. ReadWriteSplit routes each write statement to the current primary server and load balances read statements by routing them to the replica servers.

• MaxScale's ReadConnRoute router performs connection-based load balancing. ReadConnRoute routes each connection to a single primary or replica node, depending on configuration.

• MaxScale can import data from Kafka and export data into Kafka. MaxScale's KafkaCDC router streams data from MariaDB database products to a Kafka broker. MaxScale's KafkaImporter router streams data from Kafka to MariaDB database products.

• MaxScale provides built-in mechanisms to perform server maintenance without disrupting applications or clients. Servers can be set to maintenance mode using the command-line interface with MaxCtrl, a web browser with MaxGUI, or REST API.

• MaxScale's Cache filter can improve SELECT performance by caching and reusing results.

• Security and traffic controls for database connections and queries can be implemented with MaxScale. MaxScale's QLAfilter can be used to create an audit trail by logging all queries. MaxScale's RegexFilter can also perform audit logging or protect against SQL injection by matching queries against a regular expression and performing various actions on the query, such as logging it, modifying it, or routing it to a specific server.

MariaDB MaxScale can be deployed in the cloud or on-premises.

Scheduled Releases

MariaDB MaxScale follows the MariaDB Enterprise release schedule, which can be found here.

Latest Software Releases

Available Documentation

Security

• Authentication with MariaDB MaxScale

Architecture

What's New

• See the MariaDB MaxScale 24.02 Changelog for a list of what's new in MaxScale 24.02 and prior versions.

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

MariaDB MaxScale Installation Guide

We recommend to install MaxScale on a separate server, to ensure that there can be no competition of resources between MaxScale and a MariaDB Server that it manages.

Install MariaDB MaxScale From MariaDB Repositories

The recommended approach is to use to install MaxScale. After enabling the repository by following the instructions, MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install maxscale.

• For Debian and Ubuntu, run apt update followed by apt install maxscale.

• For SLES, use zypper install maxscale.

Install MariaDB MaxScale From a RPM/DEB Package

Download the correct MaxScale package for your CPU architecture and operating system from the MariaDB Downloads page. MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install /path/to/maxscale-*.rpm

• For Debian and Ubuntu, use apt install /path/to/maxscale-*.deb.

• For SLES, use zypper install /path/to/maxscale-*.rpm.

Install MariaDB MaxScale Using a Tarball

MaxScale can also be installed using a tarball. This may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer to Install MariaDB MaxScale using a Tarball.

Building MariaDB MaxScale From Source Code

Alternatively, you may download the MariaDB MaxScale source and build your own binaries. To do this, refer to the separate document Building MariaDB MaxScale from Source Code.

Assumptions

Memory allocation behavior

MaxScale assumes that memory allocations always succeed and in general does not check for memory allocation failures. This assumption is compatible with the Linux kernel parameter vm.overcommit_memory having the value 0, which is also the default on most systems.

With vm.overcommit_memory being 0, memory allocations made by an application never fail, but instead the application may be killed by the so-called OOM (out-of-memory) killer if, by the time the application actually attempts to use the allocated memory, there is not available free memory on the system.

If the value is 2, then a memory allocation made by an application may fail and unless the application is prepared for that possibility, it will likely crash with a SIGSEGV. As MaxScale is not prepared to handle memory allocation failures, it will crash in this situation.

The current value of vm.overcommit_memory can be checked with this command:

sysctl vm.overcommit_memory

Alternatively, use this command:

cat /proc/sys/vm/overcommit_memory

Configuring MariaDB MaxScale

The MaxScale Tutorial covers the first steps in configuring your MariaDB MaxScale installation. Follow this tutorial to learn how to configure and start using MaxScale.

For a detailed list of all configuration parameters, refer to the Configuration Guide and the module specific documents listed in the Documentation Contents.

Encrypting Passwords

Read the Encrypting Passwords section of the configuration guide to set up password encryption for the configuration file.

Administration Of MariaDB MaxScale

There are various administration tasks that may be done with MariaDB MaxScale. A command line tools is available, maxctrl, that interacts with a running MariaDB MaxScale and allows the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality.

The administration tutorial covers the common administration tasks that need to be done with MariaDB MaxScale.

Copying or Backing Up MaxScale

The main configuration file for MaxScale is in /etc/maxscale.cnf and additional user-created configuration files are in/etc/maxscale.cnf.d/. Objects created or modified at runtime are stored in/var/lib/maxscale/maxscale.cnf.d/. Some modules also store internal data in/var/lib/maxscale/ named after the module or the configuration object.

The simplest way to back up the configuration and runtime data of a MaxScale installation is to create an archive from the following files and directories:

• /etc/maxscale.cnf

• /etc/maxscale.cnf.d/

• /var/lib/maxscale/

This can be done with the following command:

tar -caf maxscale-backup.tar.gz /etc/maxscale.cnf /etc/maxscale.cnf.d/ /var/lib/maxscale/

If MaxScale is configured to store data in custom locations, these should be included in the backup as well.

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

Consistent Critical Read Filter

Overview

The Consistent Critical Read (CCR) filter allows consistent critical reads to be done through MaxScale while still allowing scaleout of non-critical reads.

When the filter detects a statement that would modify the database, it attaches a routing hint to all following statements done by that connection. This routing hint guides the routing module to route the statement to the primary server where data is guaranteed to be in an up-to-date state. Writes from one session do not, by default, propagate to other sessions.

Note: This filter does not work with prepared statements. Only text protocol queries are handled by this filter.

Controlling the Filter with SQL Comments

The triggering of the filter can be limited further by adding MaxScale supported comments to queries and/or by using regular expressions. The query comments take precedence: if a comment is found it is obeyed even if a regular expression parameter might give a different result. Even a comment cannot cause a SELECT-query to trigger the filter. Such a comment is considered an error and ignored.

The comments must follow the MaxScale hint syntax and the HintFilter needs to be in the filter chain before the CCR-filter. If a query has a MaxScale supported comment line which defines the parameter ccr, that comment is caught by the CCR-filter. Parameter values match and ignore are supported, causing the filter to trigger (match) or not trigger (ignore) on receiving the write query. For example, the query

INSERT INTO departments VALUES ('d1234', 'NewDepartment'); -- maxscale ccr=ignore

would normally cause the filter to trigger, but does not because of the comment. The match-comment typically has no effect, since write queries by default trigger the filter anyway. It can be used to override an ignore-type regular expression that would otherwise prevent triggering.

Settings

The CCR filter has no mandatory parameters.

time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

The time window during which queries are routed to the primary. The duration can be specified as documented here but the value will always be rounded to the nearest second. If no explicit unit has been specified, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. The default value for this parameter is 60 seconds.

When a data modifying SQL statement is processed, a timer is set to the value oftime. Once the timer has elapsed, all statements are routed normally. If a new data modifying SQL statement is processed within the time window, the timer is reset to the value of time.

Enabling this parameter in combination with the count parameter causes both the time window and number of queries to be inspected. If either of the two conditions are met, the query is re-routed to the primary.

count

• Type: count

• Mandatory: No

• Dynamic: Yes

• Default: 0

The number of SQL statements to route to primary after detecting a data modifying SQL statement. This feature is disabled by default.

After processing a data modifying SQL statement, a counter is set to the value of count and all statements are routed to the primary. Each executed statement after a data modifying SQL statement cause the counter to be decremented. Once the counter reaches zero, the statements are routed normally. If a new data modifying SQL statement is processed, the counter is reset to the value ofcount.

match

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

These regular expression settings control which statements trigger statement re-routing. Only non-SELECT statements are inspected. For CCRFilter, the exclude-parameter is instead named ignore, yet works similarly.

match=.*INSERT.*
ignore=.*UPDATE.*
options=case,extended

ignore

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

See documentation for match.

options

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: ignorecase, case, extended

• Default: ignorecase

Regular expression options for match and ignore.

global

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

global is a boolean parameter that when enabled causes writes from one connection to propagate to all other connections. This can be used to work around cases where one connection writes data and another reads it, expecting the write done by the other connection to be visible.

This parameter only works with the time parameter. The use of global andcount at the same time is not allowed and will be treated as an error.

Example Configuration

Here is a minimal filter configuration for the CCRFilter which should solve most problems with critical reads after writes.

[CCRFilter]
type=filter
module=ccrfilter
time=5

With this configuration, whenever a connection does a write, all subsequent reads done by that connection will be forced to the primary for 5 seconds.

This prevents read scaling until the modifications have been replicated to the replicas. For best performance, the value of time should be slightly greater than the actual replication lag between the primary and its replicas. If the number of critical read statements is known, the count parameter could be used to control the number reads that are sent to the primary.

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

This document is designed as a quick introduction to setting up MariaDB MaxScale.

The installation and configuration of the MariaDB Server is not covered in this document. See the following MariaDB articles for more information on setting up a primary-replica-cluster or a Galera-cluster: and .

This tutorial assumes that one of the standard MaxScale binary distributions is used and that MaxScale is installed using default options.

Building from source code in GitHub is covered in .

Installing MaxScale

The precise installation process varies from one distribution to another. Details on package installation can be found in the .

Creating a user account for MaxScale

MaxScale checks that incoming clients are valid. To do this, MaxScale needs to retrieve user authentication information from the backend databases. Create a special user account for this purpose by executing the following SQL commands on the primary server of your database cluster. The following tutorials will use these credentials.

MariaDB versions 10.2.2 to 10.2.10 also require GRANT SELECT ON mysql.* TO 'maxscale'@'%';

Creating client user accounts

Because MariaDB MaxScale sits between the clients and the backend databases, the backend databases will see all clients as if they were connecting from MaxScale's address. This usually means that two sets of grants for each user are required.

For example, assume that the user 'jdoe'@'client-host' exists and MaxScale is located at maxscale-host. If 'jdoe'@'client-host' needs to be able to connect through MaxScale, another user, 'jdoe'@'maxscale-host', must be created. The second user must have the same password and similar grants as 'jdoe'@'client-host'.

The quickest way to do this is to first create the new user:

Then do a SHOW GRANTS query:

Then copy the same grants to the 'jdoe'@'maxscale-host' user.

An alternative to generating two separate accounts is to use one account with a wildcard host ('jdoe'@'%') which covers both hosts. This is more convenient but less secure than having specific user accounts as it allows access from all hosts.

Creating the configuration file

MaxScale reads its configuration from /etc/maxscale.cnf. A template configuration is provided with the MaxScale installation.

A global maxscale section is included in every MaxScale configuration file. This section sets the values of various global parameters, such as the number of threads MaxScale uses to handle client requests. To set thread count to the number of available cpu cores, set the following.

Configuring the servers

Read the mini-tutorial for server configuration instructions.

Configuring the monitor

The type of monitor used depends on the type of cluster used. For a primary-replica cluster read . For a Galera cluster read .

Configuring the services and listeners

This part is covered in two different tutorials. For a fully automated read-write-splitting setup, read the . For a simple connection based setup, read the .

Starting MaxScale

After configuration is complete, MariaDB MaxScale is ready to start. For systems that use systemd, use the systemctl command.

For older SysV systems, use the service command.

If MaxScale fails to start, check the error log in /var/log/maxscale/maxscale.log to see if any errors are detected in the configuration file.

Checking MaxScale status with MaxCtrl

The maxctrl-command can be used to confirm that MaxScale is running and the services, listeners and servers have been correctly configured. The following shows expected output when using a read-write-splitting configuration.

MariaDB MaxScale is now ready to start accepting client connections and route queries to the backend cluster.

More options can be found in the , and .

For more information about MaxCtrl and how to secure it, see the .

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

With the release of MaxScale 25.01 under a proprietary license, MariaDB has introduced MaxScale Trial, a free version that lets users explore the latest GA features in 24-hour increments, up to one week from install. MaxScale Trial offers limited performance capacity, providing a hands-on way to evaluate MaxScale’s capabilities before committing to an enterprise subscription

Installing MaxScale Trial

When the MaxScale Trial package has been installed, a template MaxScale configuration file will be copied to /etc/maxscale.cnf.template and /etc/maxscale.cnf; the former for reference and the latter for actual use. The configuration file has been written with the assumption that a MariaDB server is running on the same machine where MaxScale is installed.

Before starting MaxScale, the database users needed by MaxScale must be created.

Database Users used by MaxScale

MaxScale needs two database users for its own use; one user used by a MaxScale for fetching user account information and another user used by the MaxScale for monitoring the health of the MariaDB server and for performing operations on it. The same user can be used for both purposes, provided the user has all the grants needed by services and monitors.

In the following, the host is specified using '%', which means that MaxScale can access the server from anywhere. In a non-trial context, it is advisable to use the specific IP where MaxScale is running.

If you use the same user names and passwords - that is, service_user/service_pw and monitor_user/monitor_pw - you do not need to modify /etc/maxscale.cnf. Otherwise the user names and passwords must be updated accordingly.

Service User

The service user can be created with the following commands, executed using the mariadb command line utility.

Monitor User

Creating the monitor user is more complicated, because the required GRANTs depend both on what monitor is used and on the exact server version. The GRANTs needed by the MariaDB Monitor, used for monitoring a regular MariaDB primary/replica cluster can be found here, but for initial testing the user can be given blanket rights:

In a non-trial context, the monitor user should be granted only the GRANTs it really needs.

Starting MaxScale Trial

Once the database users have been created, MaxScale Trial can be started.

If no errors are shown by the command, which indicates that MaxScale started, the error log of MaxScale should be checked.

If there are no error entries, MaxScale is running and can be used.

Smoketests

With the following command it can be checked that MaxScale can connect to the server

and with the following command that the service is running

After that the web-browser can be pointed to . Logging in is done using the username admin and the password mariadb.

Note that by default MaxScale listens only on the interface 127.0.0.1, which means that you must access MaxScale from the same machine on which MaxScale is running. If you want to access MaxScale over the network, you need to add

to the [maxscale] section in /etc/maxscale.cnf.

Limitations of MaxScale Trial

Apart from the following limitations, MaxScale Trial is identical to MaxScale.

At startup, if any of the limitations on the number of filters, servers or services is exceeded, MaxScale will not start and an error like the following will be logged:

If the limit is exceeded at runtime with maxctrl, the operation will fail with an error like the following:

If the limit is exceeded at runtime using MaxGUI, the operation will fail with the following error message.

If the connection limit is exceeded, the connection attempt will fail, and note that no error message will be displayed.

An attempt to explicitly raise beyond the maximum of 15, will prevent MaxScale from running at startup and at runtime fail with a runtime error.

If the configured capture or exceeds the maximum limit of MaxScale Trial, the value will be adjusted down to the allowed maximum value and an error will be logged.

Upgrading to MaxScale

The configuration file of MaxScale Trial is 100% compatible with MaxScale. To replace MaxScale Trial with MaxScale, only the following steps are needed:

• Uninstall MaxScale Trial.

• Install MaxScale 25.01 or higher.

Although the uninstallation of MaxScale Trial will not cause the configuration file to be erased, it is recommended to make a backup of it before the operation.

It is not possible to have MaxScale Trial and MaxScale installed simultaneously on the same machine.

MaxScale configurations are not guaranteed to work in MaxScale Trial as MaxScale Trial has restrictions based on the documented limitations above which would block startup.\

What Are Filters?

The filter mechanism in MariaDB MaxScale is a means by which processing can be inserted into the flow of requests and responses between the client connection to MariaDB MaxScale and the MariaDB MaxScale connection to the backend database servers. The path from the client side of MariaDB MaxScale out to the actual database servers can be considered a pipeline, filters can then be placed in that pipeline to monitor, modify, copy or block the content that flows through that pipeline.

Types Of Filter

Filters can be divided into a number of categories

Logging filters

Logging filters do not in any way alter the statement or results of the statements that are passed through MariaDB MaxScale. They merely log some information about some or all of the statements and/or result sets.

Two examples of logging filters are contained within the MariaDB MaxScale, a filter that will log all statements and another that will log only a number of statements, based on the duration of the execution of the query.

Statement rewriting filters

Statement rewriting filters modify the statements that are passed through the filter. This allows a filter to be used as a mechanism to alter the statements that are seen by the database, an example of the use of this might be to allow an application to remain unchanged when the underlying database changes or to compensate for the migration from one database schema to another.

Result set manipulation filters

A result set manipulation filter is very similar to a statement rewriting but applies to the result set returned rather than the statement executed. An example of this may be obfuscating the values in a column.

Routing hint filters

Routing hint filters are filters that embed hints in the request that can be used by the router onto which the query is passed. These hints include suggested destinations as well as metric that may be used by the routing process.

Firewall filters

A firewall filter is a mechanism that allows queries to be blocked within MariaDB MaxScale before they are sent on to the database server for execution. They allow constructs or individual queries to be intercepted and give a level of access control that is more flexible than the traditional database grant mechanism.

Pipeline control filters

A pipeline filter is one that has an affect on how the requests are routed within the internal MariaDB MaxScale components. The most obvious version of this is the ability to add a "tee" connector in the pipeline, duplicating the request and sending it to a second MariaDB MaxScale service for processing.

Filter Definition

Filters are defined in the configuration file, typically maxscale.cnf, using a section for each filter instance. The content of the filter sections in the configuration file various from filter to filter, however there are always to entries present for every filter, the type and module.

The type is used by the configuration manager within MariaDB MaxScale to determine what this section is defining and the module is the name of the plugin that implements the filter.

When a filter is used within a service in MariaDB MaxScale the entry filters= is added to the service definition in the ini file section for the service. Multiple filters can be defined using a syntax akin to the Linux shell pipe syntax.

The names used in the filters= parameter are the names of the filter definition sections in the ini file. The same filter definition can be used in multiple services and the same filter module can have multiple instances, each with its own section in the ini file.

Filter Examples

The filters that are bundled with the MariaDB MaxScale are documented separately, in this section a short overview of how these might be used for some simple tasks will be discussed. These are just examples of how these filters might be used, other filters may also be easily added that will enhance the MariaDB MaxScale functionality still further.

Log The 30 Longest Running Queries

The top filter can be used to measure the execution time of every statement within a connection and log the details of the longest running statements.

The first thing to do is to define a filter entry in the ini file for the top filter. In this case we will call it "top30". The type is filter and the module that implements the filter is called topfilter.

In the definition above we have defined two filter specific parameters, the count of the number of statement to be logged and a filebase that is used to define where to log the information. This filename is a stem to which a session id is added for each new connection that uses the filter.

The filter keeps track of every statement that is executed, monitors the time it takes for a response to come back and uses this as the measure of execution time for the statement. If the time is longer than the other statements that have been recorded, then this is added to the ordered list within the filter. Once 30 statements have been recorded those statements that have been recorded with the least time are discarded from the list. The result is that at any time the filter has a list of the 30 longest running statements in each session.

When the session ends a report will be written for the session into the logfile defined. That report will include the top 30 longest running statements, plus summary data for the session;

• The time the connection was opened.

• The host the connection was from.

• The username used in the connection.

• The duration of the connection.

• The total number of statements executed in the connection.

• The average execution time for a statement in this connection.

Duplicate Data From Your Application Into Cassandra

The scenario we are using in this example is one in which you have an online gaming application that is designed to work with a MariaDB database. The database schema includes a high score table which you would like to have access to in a Cassandra cluster. The application is already using MariaDB MaxScale to connect to a MariaDB Galera cluster, using a service names BubbleGame. The definition of that service is as follows

The table you wish to store in Cassandra in called HighScore and will contain the same columns in both the MariaDB table and the Cassandra table. The first step is to install a MariaDB instance with the Cassandra storage engine to act as a bridge server between the relational database and Cassandra. In this bridge server add a table definition for the HighScore table with the engine type set to Cassandra. See for details. Add this server into the MariaDB MaxScale configuration and create a service that will connect to this server.

Next add a filter definition for the tee filter that will duplication insert statements that are destined for the HighScore table to this new service.

The above filter definition will cause all statements that match the regular expression inset.*HighScore.*values to be duplication and sent not just to the original destination, via the router but also to the service named Cassandra.

The final step is to add the filter to the BubbleGame service to enable the use of the filter.

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

Binlog Filter

Overview

The binlogfilter can be combined with a binlogrouter service to selectively replicate the binary log events to replica servers.

The filter uses two settings, match and exclude, to determine which events are replicated. If a binlog event does not match or is excluded, the event is replaced with an empty data event. The empty event is always 35 bytes which translates to a space reduction in most cases.

When statement-based replication is used, any query events that are filtered out are replaced with a SQL comment. This causes the query event to do nothing and thus the event will not modify the contents of the database. The GTID position of the replicating database will still advance which means that downstream servers replicating from it keep functioning correctly.

The filter works with both row based and statement based replication but we recommend using row based replication with the binlogfilter. This guarantees that there are no ambiguities in the event filtering.

Settings

match

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

Include queries that match the regex. See next entry, exclude, for more information.

exclude

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

Exclude queries that match the regex.

If neither match nor exclude are defined, the filter does nothing and all events are replicated. This filter does not accept regular expression options as a separate setting, such settings must be defined in the patterns themselves. See the for more information.

The two settings are matched against the database and table name concatenated with a period. For example, the string the patterns are matched against for the database test and table t1 is test.t1.

For statement based replication, the pattern is matched against all the tables in the statements. If any of the tables matches the match pattern, the event is replicated. If any of the tables matches the exclude pattern, the event is not replicated.

rewrite_src

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

See the next entry, rewrite_dest, for more information.

rewrite_dest

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

rewrite_src and rewrite_dest control the statement rewriting of the binlogfilter. The rewrite_src setting is a PCRE2 regular expression that is matched against the default database and the SQL of statement based replication events (query events). rewrite_dest is the replacement string which supports the normal PCRE2 backreferences (e.g the first capture group is $1, the second is $2, etc.).

Both rewrite_src and rewrite_dest must be defined to enable statement rewriting.

When statement rewriting is enabled must be used. The filter will disallow replication for all replicas that attempt to replicate with traditional file-and-position based replication.

The replacement is done both on the default database as well as the SQL statement in the query event. This means that great care must be taken when defining the rewriting rules. To prevent accidental modification of the SQL into a form that is no longer valid, use database and table names that never occur in the inserted data and is never used as a constant value.

Example Configuration

With the following configuration, only events belonging to database customers are replicated. In addition to this, events for the table orders are excluded and thus are not replicated.

For more information about the binlogrouter and how to use it, refer to the .

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

Ed25519 Authenticator

Ed25519 is a highly secure authentication method based on public key cryptography. It is used with the auth_ed25519-plugin of MariaDB Server.

When a client authenticates via ed25519, MaxScale first sends them a random message. The client signs the message using their password as private key and sends the signature back. MaxScale then checks the signature using the public key fetched from the mysql.user-table. The client password or an equivalent token is never exposed. For more information, see .

The security of this authentication scheme presents a problem for a proxy such as MaxScale since MaxScale needs to log in to backend servers on behalf of the client. Since each server will generate their own random messages, MaxScale cannot simply forward the original signature. Either the real password is required, or a different authentication scheme must be used between MaxScale and backends. The MaxScale ed25519auth-plugin supports both alternatives.

Configuration

To begin, add "ed25519auth" to the list of authenticators for a listener.

MaxScale will now authenticate incoming clients with ed25519 if their user account has plugin set to "ed25519" in the mysql.user-table. However, routing queries will fail since MaxScale cannot authenticate to backends. To continue, either use a mapping file or enable sha256-mode. Sha256-mode is enabled with the following settings.

ed_mode

This setting defines the authentication mode used. Two values are supported:

• ed25519 (default) Digital signature based authentication. Requires mapping for backend support.

• sha256 Authenticate client with caching_sha2_password-plugin instead. Requires either SSL or configured RSA-keys.

ed_rsa_privkey_path and ed_rsa_pubkey_path

Defines the RSA-keys used for encrypting the client password if SSL is not in use. Should point to files with the private and public keys.

Using a mapping file

To enable MaxScale to authenticate to backends, can be used. The mapping and backend passwords are given in a json-file. The client can map to an identical username or to another user, and the backend authentication scheme can be something else than ed25519.

The following example maps user "alpha" to "beta" and MaxScale then uses standard authentication to log into backends as "beta". User "alpha" authenticates to MaxScale using whatever method configured in the server. User "gamma" does not map to another user, just the password is given.

MaxScale configuration:

/home/joe/mapping.json:

Using sha256-authentication

The mapping-based solution requires the DBA to maintain a file with user passwords, which has security and upkeep implications. To avoid this, MaxScale can instead use the caching_sha2_password-plugin to authenticate the client. This authentication scheme transmits the client password to MaxScale in full, allowing MaxScale to log into backends using ed25519. MaxScale effectively lies to the client about its authentication plugin and then uses the correct plugin with the backends. Enable sha256-authentication by setting authentication option ed_mode to "sha256".

sha256-authentication is best used with encrypted connections. The example below shows a listener configured for sha256-mode and SSL.

If SSL is not in use, caching_sha2_password transmits the password using RSA-encryption. In this case, MaxScale needs the public and private RSA-keys. MaxScale sends the public key to the client if they don't already have it and the client uses it to encrypt the password. MaxScale then uses the private key to decrypt the password. The example below shows a listener configured for sha256-mode without SSL.

The keyfiles can be generated with OpenSSL using the following commands.

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

This tutorial is a short introduction to the Avrorouter, how to set it up and how it interacts with the binlogrouter.

The first part configures the services and sets them up for the binary log to Avro file conversion. The second part of this tutorial uses the client listener interface for the avrorouter and shows how to communicate with the service over the network.

Configuration

Preparing the primary server

The primary server where we will be replicating from needs to have binary logging enabled, binlog_format set to row and binlog_row_image set tofull. These can be enabled by adding the two following lines to the my.cnf file of the primary.

binlog_format=row
binlog_row_image=full

You can find out more about replication formats from the

Configuring MaxScale

We start by adding two new services into the configuration file. The first service is the binlogrouter service which will read the binary logs from the primary server. The second service will read the binlogs as they are streamed from the primary and convert them into Avro format files.

# The Replication Proxy service
[replication-service]
type=service
router=binlogrouter
server_id=4000
master_id=3000
filestem=binlog
user=maxuser
password=maxpwd

# The Avro conversion service
[avro-service]
type=service
router=avrorouter
source=replication-service
filestem=binlog
start_index=15

# The listener for the replication-service
[replication-listener]
type=listener
service=replication-service
port=3306

# The client listener for the avro-service
[avro-listener]
type=listener
service=avro-service
protocol=CDC
port=4001

The source parameter in the avro-service points to the replication-service we defined before. This service will be the data source for the avrorouter. Thefilestem is the prefix in the binlog files and start_index is the binlog number to start from. With these parameters, the avrorouter will start reading events from binlog binlog.000015.

Note that the filestem and start_index must point to the file that is the first binlog that the binlogrouter will replicate. For example, if the first file you are replicating is my-binlog-file.001234, set the parameters tofilestem=my-binlog-file and start_index=1234.

For more information on the avrorouter options, read the Avrorouter Documentation.

Preparing the data in the primary server

Before starting the MaxScale process, we need to make sure that the binary logs of the primary server contain the DDL statements that define the table layouts. What this means is that the CREATE TABLE statements need to be in the binary logs before the conversion process is started.

If the binary logs contain data modification events for tables that aren't created in the binary logs, the Avro schema of the table needs to be manually created. There are multiple ways to do this:

• Dump the database to a replica, configure it to replicate from the primary and point MaxScale to this replica (this is the recommended method as it requires no extra steps)

• Use the cdc_schema Go utility and copy the generated .avsc files to the avrodir

• Use the Python version of the schema generator and copy the generated .avsc files to the avrodir

If you used the schema generator scripts, all Avro schema files for tables that are not created in the binary logs need to be in the location pointed to by theavrodir parameter. The files use the following naming:<database>.<table>.<schema_version>.avsc. For example, the schema file name of the test.t1 table would be test.t1.0000001.avsc.

Starting MariaDB MaxScale

The next step is to start MariaDB MaxScale and set up the binlogrouter. We do that by connecting to the MySQL listener of the replication_router service and executing a few commands.

CHANGE MASTER TO MASTER_HOST='172.18.0.1',
       MASTER_PORT=3000,
       MASTER_LOG_FILE='binlog.000015',
       MASTER_LOG_POS=4,
       MASTER_USER='maxuser',
       MASTER_PASSWORD='maxpwd';

START SLAVE;

NOTE: GTID replication is not currently supported and file-and-position replication must be used.

This will start the replication of binary logs from the primary server at 172.18.0.1 listening on port 3000. The first file that the binlogrouter replicates is binlog.000015. This is the same file that was configured as the starting file in the avrorouter.

For more details about the SQL commands, refer to the Binlogrouter documentation.

After the binary log streaming has started, the avrorouter will automatically start processing the binlogs.

Creating and Processing Data

Next, create a simple test table and populated it with some data by executing the following statements.

CREATE TABLE test.t1 (id INT);
INSERT INTO test.t1 VALUES (1), (2), (3), (4), (5), (6), (7), (8), (9), (10);

To use the cdc.py command line client to connect to the CDC service, we must first create a user. This can be done via maxctrl by executing the following command.

maxctrl call command cdc add_user avro-service maxuser maxpwd

This will create the maxuser:maxpwd credentials which can then be used to request a JSON data stream of the test.t1 table that was created earlier.

cdc.py -u maxuser -p maxpwd -h 127.0.0.1 -P 4001 test.t1

The output is a stream of JSON events describing the changes done to the database.

{"namespace": "MaxScaleChangeDataSchema.avro", "type": "record", "name": "ChangeRecord", "fields": [{"name": "domain", "type": "int"}, {"name": "server_id", "type": "int"}, {"name": "sequence", "type": "int"}, {"name": "event_number", "type": "int"}, {"name": "timestamp", "type": "int"}, {"name": "event_type", "type": {"type": "enum", "name": "EVENT_TYPES", "symbols": ["insert", "update_before", "update_after", "delete"]}}, {"name": "id", "type": "int", "real_type": "int", "length": -1}]}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 1, "timestamp": 1537429419, "event_type": "insert", "id": 1}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 2, "timestamp": 1537429419, "event_type": "insert", "id": 2}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 3, "timestamp": 1537429419, "event_type": "insert", "id": 3}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 4, "timestamp": 1537429419, "event_type": "insert", "id": 4}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 5, "timestamp": 1537429419, "event_type": "insert", "id": 5}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 6, "timestamp": 1537429419, "event_type": "insert", "id": 6}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 7, "timestamp": 1537429419, "event_type": "insert", "id": 7}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 8, "timestamp": 1537429419, "event_type": "insert", "id": 8}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 9, "timestamp": 1537429419, "event_type": "insert", "id": 9}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 10, "timestamp": 1537429419, "event_type": "insert", "id": 10}

The first record is always the JSON format schema for the table describing the types and names of the fields. All records that follow it represent the changes that have happened on the database.

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

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. If the replica servers are using asynchronous , then the data on the replica servers can sometimes lag behind the primary server. When this occurs, read-only queries that are executed on the replica servers can return stale results if they are not executed in a causally consistent manner. Causal consistency is the act of ensuring that interdependent operations maintain consistency by performing them in the same order on all servers.

To prevent this, the Read/Write Split Router can be configured to enable "causal reads", which ensures causal consistency for read-only queries. When causal reads is enabled, the Read/Write Split Router ensures that load balanced read-only queries are only executed on the replica server after all write statements previously executed on the primary server are fully replicated and applied on that specific replica server.

Multiple MaxScale Nodes

Starting with MaxScale 22.08, the Read/Write Split Router's causal reads functionality can be used with multiple MaxScale nodes.

Example of a Causal Read Let's say that a client does the following:

1. The client executes an INSERT statement:

INSERT INTO hq_sales.invoices
   (customer_id, invoice_date, invoice_total, payment_method)
VALUES
   (1, '2020-05-10 12:35:10', 1087.23, 'CREDIT_CARD');

The router will route this statement to the primary server.

1. The client executes a SELECT statement that reads the inserted row:

SELECT * FROM hq_sales.invoices
   WHERE customer_id = 1
   AND invoice_date = '2020-05-10 12:35:10';

The router will route this statement to a replica server.

In the above example, the replica server may not replicate and apply the INSERT statement immediately. If the SELECT statement is executed before this happens, then the results of the query will not be causally consistent.

However, if causal reads is enabled, then the Read/Write Split Router will only execute the SELECT statement after the INSERT statement has been fully replicated and applied on the replica server.

Enabling Causal Reads

Causal reads requires configuration changes on both the back-end MariaDB Servers and on the MaxScale instance.

Enabling Causal Reads on MariaDB Server

Perform the following procedure on all MariaDB Servers used by MaxScale:

1. Choose a configuration file in which to configure your system variables and options. It is not recommended to make custom changes to one of the bundled configuration files. Instead, it is recommended to create a custom configuration file in one of the included directories. Configuration files in included directories are read in alphabetical order. If you want your custom configuration file to override the bundled configuration files, then it is a good idea to prefix the custom configuration file's name with a string that will be sorted last, such as z-.

• On RHEL, CentOS, Rocky Linux, and SLES, a good custom configuration file would be: /etc/my.cnf.d/z-custom-my.cnf

• On Debian and Ubuntu, a good custom configuration file would be: /etc/mysql/mariadb.conf.d/z-custom-my.cnf

1. Set the system variable to last_gtid, so that the server will track session-level changes to the value of the system variable.

It needs to be set in the configuration file in a group that will be read by , such as [mariadb] or [server].

For example:

[mariadb]
...
session_track_system_variables=last_gtid

1. Restart the server.

$ sudo systemctl restart mariadb

Enabling Causal Reads on MaxScale 2.5

1. Set the causal_reads and causal_reads_timeout parameters for the Read/Write Split Router in maxscale.cnf. The causal_reads parameter can be set to the following values:

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
causal_reads             = local
causal_reads_timeout     = 15
The unit for the causal_reads_timeout parameter is seconds, and the default value is 10.