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.

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:

1. Restart the MaxScale instance.

_{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.

The supports:

• deployments.

The 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.

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 replay in-progress transactions on a different server.

The 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.

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

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.

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:

1. Restart the MaxScale instance.

1. Disable the session command history by configuring the disable_sescmd_history 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.}

MaxScale's Read/Write Split Router (readwritesplit) 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 Read/Write Split Router route queries?

• 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.}

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.

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

For example:

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. If the replica servers are using asynchronous MariaDB replication, 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 statement:

The router will route this statement to the primary server.

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

The router will route this statement to a replica server.

In the above example, the replica server may not replicate and apply the statement immediately. If the 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 statement after the statement has been fully replicated and applied on the replica server.

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

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:

1. Restart the server.

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:

1. Restart the MaxScale instance.

1. Set the causal_reads and causal_reads_timeout 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.}

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.

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

MariaDB MaxScale offers a free Trial version with a flexible, license-key based evaluation period. This free version allows users to explore the latest GA features of MaxScale under a proprietary license.

Unlike previous versions, access to this trial is now managed via a specific license key. This key determines the duration of your evaluation period, providing a hands-on way to test MaxScale’s capabilities and performance within your environment before committing to an enterprise subscription.

The next section explains how to obtain your license key.

Getting the License Key

To use MaxScale 25.10.3 Trial mode, you must first obtain a trial license key from the MariaDB Customer Portal. This key validates your trial and determines the duration of your evaluation period.

1. Log in to MariaDB ID: Navigate to the . You will be prompted to sign in with your MariaDB ID. If you do not have an account, you can create one using your email, Google, GitHub, or LinkedIn credentials.

2. Generate the Key: Once logged in, follow the on-screen instructions to generate your unique MaxScale Trial license key.

3. Save the Key: Copy or download the generated key. You will need to provide this key during the MaxScale configuration process.

MaxScale Trial can be downloaded from the page. Choose the correct version for your OS.

The downloaded file is a tar-package that must be extracted. Create a directory and extract the package into that.

The filename will be different for different OSs.

The extracted tar contains 6 packages.

• maxscale-common_25.10.3~noble-1_amd64.deb

• maxscale-trial_25.10.3~noble-1_amd64.deb

• maxscale-maxctrl_25.10.3~noble-1_amd64.deb

Also these filenames will be different depending on the OS.

• maxscale-common contains common components used by the other packages, except for maxscale-maxctrl.

• maxscale-trial contains MaxScale itself.

• maxscale-maxctrl

NOTE If you have an earlier MaxScale Trial version, please uninstall it first.

Enter the directory where the tar-package was extracted and execute on a Debian based system

and on a RedHat based system

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 license key must be specified and the database users needed by MaxScale must be created.

Open /etc/maxscale.cnf and add a license_key entry to the [maxscale] section.

The value of license_key can either be the license key itself or the absolute path to a file containing the license.

NOTE If the license is read from a file, it must be readable by the user 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 , 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.

The command line utility maxctrl and the web UI MaxGUI communicate with MaxScale using a REST-API. By default, MaxGUI requires that TLS is enabled and it is configured as explained .

Alternatively, the requirement of TLS can be turned off by adding the entry

to the [maxscale] section in the MaxScale configuration file.

Please note that unless TLS is configured, your administrative credentials will be exposed in plain text over the network. Not using TLS should only be in a trial context in a controlled environment.

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

If TLS has been configured, the secure mode must be enabled with the flag --secure and the relevant parameters provided using the --tls... flags. Invoke maxctrl with the flag --help for the details.

After that the web-browser can be pointed to . Logging in is done using the username admin and the password mariadb. If TLS has not been disabled by the setting admin_secure_gui=false, https must be used.

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.

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

• Uninstall MaxScale Trial.

• Install MaxScale 25.10.3 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.\

The Read/Write Split Router (readwritesplit) uses well-defined rules to determine whether a statement can be routed to a replica server, or whether it needs to be routed to the primary server. Application designers must understand these rules to ensure that the router can properly load balance queries.

Statements Routed to the Primary Server

The following statements are routed to the primary server:

• Queries that write to the database. For example, this includes, but is not limited to, the following statements:

• Queries that modify the database (DDL) For example, this includes, but is not limited to, the following statements:

• Queries within open transactions If the application uses explicit transactions, then all queries within the transaction will be routed to the primary server. Explicit transactions are used in the following cases:

  • When is set to OFF.

  • When is executed.

For example, all queries will be routed to the primary server in this case:

And all queries will also be routed to the primary server in this case:

• Queries using stored procedures

• Queries using stored functions

• Queries using user-defined functions (UDF)

• Queries that use temporary tables

The following statements are routed to a replica server:

• Queries that are read-only For example, this includes, but is not limited to, the following statements:

• Queries that read system or user-defined variables For example, this includes, but is not limited to, the following statements:

For example, the following queries would be routed to a replica:

• Queries using built-in functions

The following statements are routed to all servers:

• statements, including those embedded in read-only statements

• statements

• statements that create prepared statements

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