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 .

Software Releases

The supported MaxScale versions can be found in the latest .

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

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}

• REST API

  • Configuring the REST-API

  • Creating a REST API User

• TLS

• MaxGUI

• Operations

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

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

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.

MariaDB MaxScale MaxGUI Guide

Introduction

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

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.

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 . It can be used to set a server to maintenance mode.

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.

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

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.

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.

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:

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

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}

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

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

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

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.

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

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

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 .

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

Alternatively, use this command:

Configuring MariaDB MaxScale

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 and the module specific documents found in the .

Encrypting Passwords

Read the 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, , 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 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:

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}

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 retry failed queries on a different server. The retry may need to be delayed in some cases, such as when automatic failover 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.}

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

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

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

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.

Enabling this feature will increase memory usage of a session. The amount of memory stored per prepared statement is proportional to the length of the prepared SQL statement and the number of parameters the statement has.

Configuration

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

Limitations

• If the SQL in the prepared statement is larger than 1677723 bytes, the prepared statement will not be cached.

• If the same SQL is prepared more than once at the same time, only one of them will succeed. This happens as the prepared statement reuse uses the SQL string in the comparison to detect if a statement is already prepared.

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

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.

Configuration

This filter is an implicit filter and has no configuration parameters and does not need its own configuration section. To enable it, simply add it to the service using the module name.

Limitations

The filter prevents writes in two ways: by parsing the SQL and detecting writes and by setting the default mode of transactions to read-only. The parsing will prevent any writes that are detected from reaching the database and the read-only mode of transactions will prevent writes in stored procedures and user functions as well as act as a backup method in case the parsing is ineffective in detecting a write.

The SET TRANSACTION READ WRITE and START TRANSACTION READ WRITE statements are blocked by this filter. This is done as a safeguard against accidental removal of the read-only transaction mode. However, if the client disables the read-only mode directly via SET tx_read_only=0, the change is not detected by the filter and writes are possible.

Given that the detection of writes is based on parsing and that parsing is not 100% effective in detecting all possible permutations of this statement (e.g. PREPARE and EXECUTE from user variables is not detected), this cannot be used to prevent a mischievous user from being able to turn off the read-only mode.

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

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.

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)

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 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, add

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

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 parameter controls how long the monitor waits between each monitor tick.

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.

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

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

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:

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

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.

This authentication plugin is intended to be used with MariaDB version 12 or later and requires that the service user has the SET USER grant.

MariaDB versions 11.6 or later that include the PARSEC authentication plugin are supported but the passwords for the users must be provided via the

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

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.

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.

This document describes general MySQL protocol authentication in MaxScale. For REST-api authentication, see the configuration guide and the REST-api guide.

Similar to the MariaDB Server, MaxScale uses authentication plugins to implement different authentication schemes for incoming clients. The same plugins also handle authenticating the clients to backend servers. The authentication plugins available in MaxScale are standard MySQL password, GSSAPI, ed25519, PARSEC and pluggable authentication modules (PAM).

Most of the authentication processing is performed on the protocol level, before handing it over to one of the plugins. This shared part is described in this document. For information on an individual plugin, see its documentation.

User account management

Every MaxScale service with a MariaDB protocol listener requires knowledge of the user accounts defined on the backend databases. The service maintains this information in an internal component called the user account manager (UAM). The UAM queries relevant data from the mysql-database of the backends and stores it. Typically, only the current primary server is queried, as all servers are assumed to have the same users. The service settings user and password define the credentials used when fetching user accounts.

The service uses the stored data when authenticating clients, checking their passwords and database access rights. This results in an authentication process very similar to the MariaDB Server itself. Unauthorized users are generally detected already at the MaxScale level instead of the backend servers. This may not apply in some cases, for example if MaxScale is using old user account data.

If authentication fails, the UAM updates its data from a backend. MaxScale may attempt authenticating the client again with the refreshed data without communicating the first failure to the client. This transparent user data update does not always work, in which case the client should try to log in again.

As the UAM is shared between all listeners of a service, its settings are defined in the service configuration. For more information, search the for users_refresh_time, users_refresh_interval and auth_all_servers. Other settings which affect how the UAM connects to backends are the global settings auth_connect_timeout and local_address, and the various server-level ssl-settings.

Required grants

To properly fetch user account information, the MaxScale service user must be able to read from various tables in the mysql-database: user, db, tables_priv, columns_priv, procs_priv, proxies_priv, global_priv and roles_mapping. The user should also have the SHOW DATABASES-grant.

The SET USER grant is optional but recommended if MaxScale is used with MariaDB version 12 or newer. Granting it to the service user allows the backend authentication to use the service credentials to log in after which the final user account is selected using the SET SESSION AUTHORIZATION command. For more information, refer to the documentation of the setting.

If using MariaDB ColumnStore, the following grant is required:

Limitations and troubleshooting

When a client logs in to MaxScale, MaxScale sees the client's IP address. When MaxScale then connects the client to backends (using the client's username and password), the backends see the connection coming from the IP address of MaxScale. If the client user account is to a wildcard host ('alice'@'%'), this is not an issue. If the host is restricted ('alice'@'123.123.123.123'), authentication to backends will fail.

There are two primary ways to deal with this:

1. Duplicate user accounts. For every user account with a restricted hostname an equivalent user account for MaxScale is added ('alice'@'maxscale-ip').

2. Use .

Option 1 limits the passwords for user accounts with shared usernames. Such accounts must use the same password since they will effectively share the MaxScale-to-backend user account. Option 2 requires server support.

See for additional information on how to solve authentication issues.

Wildcard database grants

MaxScale supports wildcards _ and % for database-level grants. As with MariaDB Server, grant select on test_.* to 'alice'@'%'; gives access to test_ as well as test1, test2 and so on. If the GRANT command escapes the wildcard (grant select on \test_`.* to 'alice'@'%';) both MaxScale and the MariaDB Server interpret it as only allowing access to _test\__. _and%are only interpreted as wildcards when the grant is to a database:grant select on `test_`.t1 to 'alice'@'%';` only grants access to the test_.t1-table, not to test1.t1.

Settings

The listener configuration defines authentication options which only affect the listener. authenticator defines the authentication plugins to use. authenticator_options sets various options. These options may affect an individual authentication plugin or the authentication as a whole. The latter are explained below. Multiple options can be given as a comma-separated list.

skip_authentication

• Type:

• Mandatory: No

• Dynamic: No

• Default: false

If enabled, MaxScale will not check the passwords of incoming clients and just assumes that they are correct. Wrong passwords are instead detected when MaxScale tries to authenticate to the backend servers.

This setting is mainly meant for failure tolerance in situations where the password check is performed outside of MaxScale. If, for example, MaxScale cannot use an LDAP-server but the backend databases can, enabling this setting allows clients to log in. Even with this setting enabled, a user account matching the incoming client username and IP must exist on the backends for MaxScale to accept the client.

This setting is incompatible with standard MariaDB/MySQL authentication plugin (MariaDBAuth in MaxScale). If enabled, MaxScale cannot authenticate clients to backend servers using standard authentication.

match_host

• Type:

• Mandatory: No

• Dynamic: No

• Default: true

If disabled, MaxScale does not require that a valid user account entry for incoming clients exists on the backends. Specifically, only the client username needs to match a user account, hostname/IP is ignored.

This setting may be used to force clients to connect through MaxScale. Normally, creating the user jdoe@% will allow the user jdoe to connect from any IP-address. By disabling match_host and replacing the user with_jdoe@maxscale-IP_, the user can still connect from any client IP but will be forced to go through MaxScale.

lower_case_table_names

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 0

Controls database name matching for authentication when an incoming client logs in to a non-empty database. The setting functions similar to the MariaDB Server setting and should be set to the value used by the backends.

The setting accepts the values 0, 1 or 2:

• 0: case-sensitive matching (default)

• 1: convert the requested database name to lower case before using case-insensitive matching. Assumes that database names on the server are stored in lower case.

• 2: use case-insensitive matching.

true and false are also accepted for backwards compatibility. These map to 1 and 0, respectively.

The identifier names are converted using an ASCII-only function. This means that non-ASCII characters will retain their case-sensitivity.

Starting with MaxScale versions 2.5.25, 6.4.6, 22.08.5 and 23.02.2, the behavior of lower_case_table_names=1 is identical with how the MariaDB server behaves. In older releases the comparisons were done in a case-sensitive manner after the requested database name was converted into lowercase. Using lower_case_table_names=2 will behave identically in all versions which makes it a safe alternative to use when a mix of older and newer MaxScale versions is being used.

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

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.

maxkeys

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}

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 names_Write-Service_ and Read-Service.

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 .

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 per service is enough.

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

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

1. Restart the MaxScale instance.

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:

1. Restart the MaxScale instance.

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

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.

Configuration

Basic Configuration

This configuration states that the query frequency will be throttled to around 500 qps, and that the time limit a query is allowed to stay at the maximum frequency is 60 seconds. All values involving time are configured in milliseconds. With the basic configuration the throttling will be nearly immediate, i.e. a session will only be allowed very short bursts of high frequency querying.

When a session has been continuously throttled for throttling_duration milliseconds, or 60 seconds in this example, MaxScale will disconnect the session.

Allowing high frequency bursts

The two parameters max_qps and sampling_duration together define how a session is throttled.

Suppose max qps is 400 qps and sampling duration is 10 seconds. Since QPS is not an instantaneous measure, but one could say it has a granularity of 10 seconds, we see that over the 10 seconds 10*400 = 4000 queries are allowed before throttling kicks in.

With these values, a fresh session can start off with a speed of 2000 qps, and maintain that speed for 2 seconds before throttling starts.

If the client continues to query at high speed and throttling duration is set to 10 seconds, Maxscale will disconnect the session 12 seconds after it started.

Settings

max_qps

• Type: number

• Mandatory: Yes

• Dynamic: Yes

Maximum queries per second.

This is the frequency to which a session will be limited over a given time period. QPS is not measured as an instantaneous value but over a configurable sampling duration (see sampling_duration).

throttling_duration

• Type:

• Mandatory: Yes

• Dynamic: Yes

This defines how long a session is allowed to be throttled before MaxScale disconnects the session.

sampling_duration

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: 250ms

Sampling duration defines the window of time over which QPS is measured. This parameter directly affects the amount of time that high frequency queries are allowed before throttling kicks in.

The lower this value is, the more strict throttling becomes. Conversely, the longer this time is, the longer bursts of high frequency querying is allowed.

continuous_duration

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: 2s

This value defines what continuous throttling means. Continuous throttling starts as soon as the filter throttles the frequency. Continuous throttling ends when no throttling has been performed in the past continuous_duration time.

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

Securing Your MaxScale Deployment

The following hardening steps are recommended before going into production:

• Encrypt plaintext passwords

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

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

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

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

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.

Settings

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.

Further Resources:

Overview

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

Enabling MaxGUI

1. If you want to use MaxGUI remotely, for remote connections.

Several global parameters must be configured in maxscale.cnf.

For example:

1. MaxGUI requires TLS, so you must Several global parameters must be configured in maxscale.cnf.