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

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.

_{This page is: Copyright © 2026 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

Information about installing MariaDB MaxScale 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}

Overview

In MariaDB MaxScale, authenticators perform the following tasks:

• Authenticating clients that connect to MaxScale

• Authenticating connections to back-end MariaDB Enterprise Server nodes

• Deciding how authentication should be performed

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

Overview

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

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

The list is updated continuously. CVEs may be added retroactively to already-released versions, as vulnerabilities can be reported to and assigned by CVE Numbering Authorities (CNAs) after the corresponding fix has been released. As a result, a release may receive additional CVE entries over time even after it has been published.

List of Fixed Security Vulnerabilities

_{This page is: Copyright © 2026 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}

MariaDB MaxScale is an advanced, 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.

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.

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

• Intelligent Routing and Load Balancing:

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 MaxScale's REST API is used by both and .

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

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

• It does not use TLS by default.

• REST API

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

• Setting a server to maintenance mode.

• Reconfiguring monitors.

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.

There are two types of users:

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.

1. if the default configuration is not sufficient.

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.

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

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.

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

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

Quickstart Guide: MariaDB MaxScale Limitations

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

1. Configuration File Line Length

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

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

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

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

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

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

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

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

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

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

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

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

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

MariaDB MaxScale MaxGUI Guide

Introduction

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

Enabling MaxGUI

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

Securing the GUI

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

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

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

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

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

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

By default, the refresh interval is 10 seconds.

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

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

This page visualizes MaxScale configuration and clusters.

• Configuration: Visualizing MaxScale configuration.

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

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

This page shows and allows editing of MaxScale parameters.

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

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

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

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

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

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

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

Overview

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

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

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

Setting a Server to Maintenance Mode

1. Configure MaxScale for MaxGUI.

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

3. Enter your username and password to log in.

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

5. Click the server that you want to set to maintenance mode. This will bring up a page for the specific server.
6. Click the gear icon at the top left corner of the page next to the server name. This will show some options in a popup.
7. Click the wrench icon. This will open a popup window.
8. Click the "Set" button. If the specified server is a primary server, then MaxScale will allow open transactions to complete before closing any connections.

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

3. Enter your user and password to login.

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

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}

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

Configuring the Monitor

Define the monitor that monitors the servers.

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

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

Monitor User

The monitor user requires the REPLICA MONITOR privilege to do basic monitoring. To create a user with the proper grants, run:

CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'my_password';
GRANT REPLICA MONITOR ON *.* TO 'monitor_user'@'%';

If the automatic failover feature is used, the monitor user needs additional grants. See monitor documentation for more information.

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

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}

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.

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

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

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

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:

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

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.

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.

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

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

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

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

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

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

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

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.

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.

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

The following example registers the module command my_command for module_my_module_.

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 Comment filter requires one mandatory parameter to be defined.

• Type: string

• Mandatory: Yes

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.

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

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

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.

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.

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 (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 . The documentation for the contains an example of how to configure the user mapping.

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 the MariaDB package repository 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.

By default this also installs the maxscale-maxctrl package, if available, which is the command line client for administering MaxScale. If you do not want it to be installed, use the following:

• For RHEL/Rocky Linux/Alma Linux, use dnf install --setopt install_weak_deps=False maxscale.

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

In order to use the maxctrl command line client, you'll need to install Node.js. The minimum required version is Node.js 10 but we recommend using the latest LTS release of Node.js.

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.

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 .

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:

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 .

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

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.

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}

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, configure the REST API 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.

For example:

1. Ensure that the admin_gui global parameter is enable. It is enabled by default, so it will only be disabled if it was previously disabled manually.

2. Restart the MaxScale instance.

1. user with MaxCtrl:

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

1. named admin with MaxCtrl:

1. Visit MaxGUI in your web browser.

For example:

• If you were accessing it from local host with the default port, then you would visit this address:

• If you were accessing it with the above example configuration, then you would visit this address:

1. Enter your user and password to login.

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

MariaDB MaxScale does not require any external software at version-pinned ranges that you must track separately from the package itself. The platform packages (RPM, DEB) and the container image declare their runtime requirements through the standard packaging metadata, and your package manager resolves and installs the right versions for your operating system release.

This page describes how to enumerate those dependencies on each supported platform, so you can answer questions such as "Which exact libraries does MaxScale link against on this host?" or "What needs to be available before I can install or upgrade?" without guessing.

Debian and Ubuntu

Before installation, query the package's declared dependencies from the repository or a downloaded .deb file.

# From the configured MariaDB repository
apt-cache depends maxscale

# Recursive (the full transitive dependency tree)
apt-rdepends maxscale

# From a downloaded .deb file
dpkg-deb --info maxscale_*.deb | grep -E '^ (Depends|Recommends|Suggests):'

After installation, inspect the installed package metadata:

dpkg -s maxscale
dpkg -s maxscale-common

The Depends: and Recommends: lines list both the package-internal dependencies (for example, maxscale-common) and the system libraries pulled in by dpkg-shlibdeps at build time.

Before installation:

After installation:

The Requires: entries cover both the internal maxscale-common dependency and the system libraries that rpmbuild detected as needed at link time.

The commands match RHEL because SLES also uses RPM. The repository query uses zypper:

For MariaDB-published MaxScale container images, the dependencies are baked into the image layers. Use either the standard Docker tooling or a scanner that understands image layers:

syft and trivy produce CycloneDX 1.6 output covering all OS packages plus any bundled language-level dependencies (for example, the maxctrl and MaxGUI Node.js trees).

To see exactly which shared libraries the running MaxScale binary and its loaded modules link against on a given host, use ldd:

This is the most reliable way to answer "Does my host have everything MaxScale needs?" — ldd reports any unresolved symbols as not found.

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

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

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

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

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

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

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

For increased security, see .

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

For the last steps, please return to .

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

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

[Throttle]
type = filter
module = throttlefilter
max_qps = 500
throttling_duration = 60000
...

[Routing-Service]
type = service
filters = Throttle

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.

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

• Type:

• Mandatory: Yes

• Dynamic: Yes

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

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

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

Overview

Change Data Capture (CDC) is a new MaxScale protocol that allows compatible clients to authenticate and register for Change Data Capture events. The new protocol must be use in conjunction with AVRO router which currently converts MariaDB binlog events into AVRO records. Clients connect to CDC listener and authenticate using credentials provided in a format described in the CDC Protocol documentation.

Note: If no users are found in that file or if it doesn't exist, the only available user will be the service user:

[avro-service]
type=service
router=avrorouter
source=replication-service
user=cdc_user
password=cdc_password

Creating new CDC users

Starting with MaxScale 2.1, users can also be created through maxctrl:

maxctrl call command cdc add_user <service> <name> <password>

The should be the service name where the user is created. Older versions of MaxScale should use the cdc_users.py script.

bash$ cdc_users.py [-h] USER PASSWORD

The output of this command should be appended to the cdcusers file at/var/lib/maxscale/<service name>/.

Users can be deleted by removing the related rows in 'cdcusers' file. For more details on the format of the cdcusers file, read the .

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

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.

Before deploying MaxScale with Docker, ensure the following requirements are met:

• Docker installed and running on your system

• A MariaDB Enterprise subscription

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.

In versions 2.1.2 and earlier, the configuration files are limited to 1024 characters per line. This limitation was increased to 16384 characters in MaxScale 2.1.3. MaxScale 2.3.0 increased this limit to 16777216 characters.

In versions 2.2.12 and earlier, the section names in the configuration files were limited to 49 characters. This limitation was increased to 1023 characters in MaxScale 2.2.13.

Starting with MaxScale 2.4.0, on systems with Linux kernels 3.9 or newer due to the addition of SO_REUSEPORT support, it is possible for multiple MaxScale instances to listen on the same network port if the directories used by both instances are completely separate and there are no conflicts which can cause unexpected splitting of connections. This will only happen if users explicitly tell MaxScale to ignore the default directories and will not happen in normal use.

The parser of MaxScale correctly parses

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

Filters can be divided into a number of categories

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

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

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

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.

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

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

• Type: number

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

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

The next section explains how to obtain your license key.

Getting the License Key

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

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

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

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

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

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

The filename will be different for different OSs.

The extracted tar contains 6 packages.

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

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

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

Also these filenames will be different depending on the OS.

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

• maxscale-trial contains MaxScale itself.

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

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

and on a RedHat based system

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

Before starting MaxScale, the license key must be specified and the database users needed by MaxScale must be created.

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

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

NOTE If the license is read from a file, it must be readable by the user maxscale.

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

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

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

Service User

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

Monitor User

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

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

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

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

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

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

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

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

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

Smoketests

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

and with the following command that the service is running

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

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

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

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

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

• Uninstall MaxScale Trial.

• Install MaxScale 25.10.3 or higher.

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

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

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

Overview

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

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

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

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

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

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

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

Exclude queries that match the regex.

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

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

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

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

See the next entry, rewrite_dest, for more information.

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: None

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

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

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

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

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

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

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

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 ed25519auth plugin supports both alternatives.

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

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

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

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

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

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

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

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

MaxScale configuration:

/home/joe/mapping.json:

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

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

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

The key files can be generated with OpenSSL using the following commands.

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

Overview

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

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

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

Controlling the Filter with SQL Comments

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

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

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

The CCR filter has no mandatory parameters.

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: 60s

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

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

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

• Type: count

• Mandatory: No

• Dynamic: Yes

• Default: 0

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

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

• Type:

• Mandatory: No

• Dynamic: No

• Default: ""

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

• Type:

• Mandatory: No

• Dynamic: No

• Default: ""

See documentation for .

• Type:

• Mandatory: No

• Dynamic: No

• Values: ignorecase

Regular expression options for match and ignore.

• Type:

• Mandatory: No

• Dynamic: Yes

• Default: false

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

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

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

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

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

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

Overview

Hint Syntax

Note: If a query has more than one comment only the first comment is processed. Always place any MaxScale related comments first before any other comments that might appear in the query.

Comments and comment types

The client connection will need to have comments enabled. For example the mariadb and mysql command line clients have comments disabled by default and they need to be enabled by passing the --comments or -c option to it. Most, if not all, connectors keep all comments intact in executed queries.

# The --comments flag is needed for the command line client
mariadb --comments -u my-user -psecret -e "SELECT @@hostname -- maxscale route to server db1"

For comment types, use either -- (notice the whitespace after the double hyphen) or # after the semicolon or /* ... */ before the semicolon.

Inline comment blocks, i.e. /* .. */, do not require a whitespace character after the start tag or before the end tag but adding the whitespace is advised.

All hints must start with the maxscale tag.

The hints have two types, ones that define a server type and others that contain name-value pairs.

These hints will instruct the router to route a query to a certain type of a server.

Route to primary

A master value in a routing hint will route the query to a primary server. This can be used to direct read queries to a primary server for a up-to-date result with no replication lag.

Route to replica

A slave value will route the query to a replica server. Please note that the hints will override any decisions taken by the routers which means that it is possible to force writes to a replica server.

Route to named server

A server value will route the query to a named server. The value of<server name> needs to be the same as the server section name in maxscale.cnf. If the server is not used by the service, the hint is ignored.

Route to last used server

A last value will route the query to the server that processed the last query. This hint can be used to force certain queries to be grouped to the same server.

Name-value hints

These control the behavior and affect the routing decisions made by the router. Currently the only accepted parameter is the readwritesplit parametermax_slave_replication_lag. This will route the query to a server with a lower replication lag than this parameter's value.