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.

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

Overview

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

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

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:

• REST API

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.

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

Overview

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

• Setting a server to maintenance mode.

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:

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.

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.

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

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 transparent 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 an 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. Filters 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 an email to or use the interface.

Bugs can be reported in the MariaDB Jira

Installing MariaDB MaxScale

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

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

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

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 how to configure a Galera cluster monitor.

Configuring the Monitor

Define the monitor that monitors the servers.

[Galera-Monitor]
type=monitor
module=galeramon
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.

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}

Overview

MaxScale has a REST API, 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.

MaxCtrl is a command-line utility that can perform administrative tasks using MaxScale's REST API. 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 MaxCtrl 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 MaxCtrl 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 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.

[dbserv1]
type=server
address=192.168.2.1
port=3306

[dbserv2]
type=server
address=192.168.2.2
port=3306

[dbserv3]
type=server
address=192.168.2.3
port=3306

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}

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

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.

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.

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.

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.

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.

When operating MariaDB MaxScale in dynamic environments—such as Kubernetes, where nodes are frequently provisioned and deleted—it is critical to cleanly remove decommissioned servers from your MaxScale configuration. To delete a server using maxctrl, one has to unlink the server from any services or monitors beforehand. This step-by-step guide walks you through the safe removal process, following the recommended teardown sequence: Listener ➔ Service ➔ Monitor ➔ Server.

Overview

MaxScale has a , 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.

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

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.

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.

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

MariaDB MaxScale MaxGUI Guide

Introduction

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

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.1.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)

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 in NAME=VALUE format (e.g. -DBUILD_TESTS=Y).

Note: You can look into defaults.cmake 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}

Introduction

After MaxScale has been installed, test that MaxScale starts by executing sudo systemctl start maxscale, followed by sudo systemctl status maxscale.

Stop MaxScale with sudo systemctl stop maxscale. The log file is written at /var/log/maxscale/maxscale.log. If the startup failed, the log should explain why. With the default configuration file, MaxScale does not yet do anything interesting.

A functional configuration of MaxScale should include a listener, a service, a monitor and one or more servers. An incoming client connects to a listener port. Once the connection is established, the listener passes the client to a service. The service then handles all client traffic, from authentication to disconnection. Client queries are routed to servers and query results from servers back to the client. A monitor regularly checks the status of the servers.

MaxScale configuration files use the common file format. The files contain sections and each section can contain multiple key-value pairs. The MaxScale installer creates an example configuration file to /etc/maxscale.cnf.

Configure a Read-Write Service

Let's modify the example configuration file to include a service that routes all queries to one server. For this, you will need to have a running MariaDB Server accessible in the network. One option is to run a MariaDB Server . Once the server is running, log in to it with an administrative account and create a user account for MaxScale itself to use when monitoring the server and fetching user accounts. The following example creates user maxscale with all privileges.

Next, edit /etc/maxscale.cnf. Perform the following modifications:

1. In the section [server1], set correct address and port. These should match the running MariaDB Server.

2. In the section [MariaDB-Monitor], set user to maxscale and password to maxscale_passwd (or whatever user/password was created earlier).

The configuration file should now have the following effective contents.

Then, start MaxScale. If MaxScale started successfully, run maxctrl list servers in the terminal. If MaxScale can successfully connect to the server, the output should be approximately:

Next, check the log file at /var/log/maxscale/maxscale.log. It should have a message like:

If the monitor cannot connect to the server, the State is Down. In this case, check the log for error messages. Similarly, if the service cannot load user account information, an error is logged.

If everything is working properly, connect as client to the MaxScale listener port, configured to 4006.

Other user accounts on the server should work as well if their host patterns allow connections from MaxScale's IP address.

Extend Read-Write Service

The Read-Write Service configured above only uses one server. To enable read-write splitting, a replication cluster with a primary server and one or more replicas is required. Setting up such a cluster is outside the scope of this document, see for more information.

Once the replicas are set up, add them to the MaxScale configuration file as separate sections: [server2], [server3] etc., similar to [server1]. Remember to set the addresses and ports. Then, add the server names to the servers-settings of the monitor:

Then, restart MaxScale to take the configuration into use and run maxctrl list servers once more. If replication is working and MaxScale can connect to all the servers, the output should be as below. If this is not the case, check the log again for error messages.

Run maxctrl show servers to get more detailed information about the servers such as connection and query counts, and maxctrl show monitors to see monitor-related information such as replication status.

Connect to the listener port again with mariadb -h127.0.0.1 -P4006 -umaxscale -pmaxscale_passwd and run the query select @@server_id; a few times. It should give the server id of a replica, alternating if multiple are available. This demonstrates that read queries are sent to the replicas. Writes and other queries that depend on the primary are sent to the primary only, e.g. select @@last_insert_id,@@server_id;. Reads inside transactions are also ran on the primary to maintain transaction consistency.

Add a filter

Filters are components added to the query processing chain that can act on the query. A typical use-case is logging. To add a log filter, add the following to the configuration file:

Then, add the filter to the service:

Again, restart MaxScale to take the configuration into use. MaxScale will now log any client queries passing through MaxScale to /var/log/maxscale/query_log.unified.

Test the GUI

Add admin_secure_gui=false to the [maxscale]-section of the configuration file and restart MaxScale. This allows access to the GUI without configuring SSL certificates. Then, open a web browser and navigate to http://127.0.0.1:8989. A login screen should open, use username admin and password mariadb to access the GUI. The GUI can show MaxScale and server status, show and modify MaxScale configuration, perform SQL queries and much more. See for more information on the GUI.

Further reading

The lists all global configuration parameters. The explains the ReadWriteSplit-router and its features, such as transaction replay and causal reads. The explains monitor features such as failover and switchover.

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. or , depending on what kind of user you need:

Replace maxscale\_rest\_admin and maxscale\_rest\_admin\_password with the desired user and password.

1. If you want to use MaxCtrl remotely, . Several global parameters must be configured in maxscale.cnf.

For example:

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

For example:

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

2. Use to connect with TLS:

Replace maxscale_rest_admin and maxscale_rest_admin_password with the actual user and password.

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

Overview

This guide explains how to deploy MariaDB MaxScale using the official Docker image available via the MariaDB Enterprise Registry. MaxScale is a database proxy that offers load balancing, high availability, and security between MariaDB database servers and your applications.

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

Overview

MaxGUI is a graphical utility that can perform administrative tasks using . It is available starting in MaxScale 2.5. It supports many different operations.

MaxGUI is not available out-of-the box. MaxScale requires some configuration before MaxGUI can be used.

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.

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

PARSEC Authenticator

The (Password Authentication using Response Signed with Elliptic Curve) authentication plugin uses salted passwords, key derivation, extensible password storage format, and both server-side and client-side scrambles.

Similarly to the ed25519 authentication plugin, it signs the response with a ed25519 digital signature, but unlike the ed25519 authentication plugin, it uses the stock unmodified ed25519 as provided by OpenSSL.

Overview

The psreuse filter reuses identical prepared statements inside the same client connection. This filter only works with binary protocol prepared statements and not with text protocol prepared statements executed with the PREPARE SQL command.

When this filter is enabled and the connection prepares an identical prepared statement multiple times, instead of preparing it on the server the existing prepared statement handle is reused. This also means that whenever prepared statements are closed by the client, they will be left open by readwritesplit.

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.

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

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: Setting Up Replication and Getting Started With MariaDB Galera Cluster

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 Building from Source.

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}

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.

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 .

For increased security, see .

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.

The service parameter tells which service the listener connects to. For the_Splitter-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 .

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

Overview

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

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

Overview

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 changes the 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 is 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:

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

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}

Quickstart Guide: MariaDB MaxScale

MariaDB MaxScale is an advanced, open-source database proxy that provides intelligent routing, load balancing, high availability, and security features for your MariaDB and MySQL deployments. It acts as an intermediary, forwarding database statements to one or more backend database servers based on configured rules and server roles, all transparently to your applications.

Limitations and Known Issues within MariaDB MaxScale

This document lists known issues and limitations in MariaDB MaxScale and its plugins. Since limitations are related to specific plugins, this document is divided into several sections.

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.

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.

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 . Please read it and follow the instructions. Return here once basic setup is complete.

Overview

The throttle filter is used to limit the maximum query frequency (QPS - queries per second) of a database session to a configurable value. The main use cases are to prevent a rogue session (client side error) and a DoS attack from overloading the system.

The throttling is dynamic. The query frequency is not limited to an absolute value. Depending on the configuration the throttle will allow some amount of high frequency queries, or especially short bursts with no frequency limitation.

Overview

This filter prevents writes from being done and returns a read-only error if one is attempted. The error that is returned is ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION, error number 1792 with SQLSTATE 25006 and the message Cannot execute statement in a READ ONLY transaction.