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.

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

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:

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.

What Does the Read/Write Split Router Support?

The supports:

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

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

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 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 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 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:

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 Read/Write Split Router select replica servers to load balance queries?

• How does the

• How does the

• How does the

Additional information is available

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

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

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:

1. Restart the server.

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:

1. Restart the MaxScale instance.

Enabling Causal Reads on MaxScale 2.4 and Before

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

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