1 of 100

MaxScale

MariaDB MaxScale

Discover MaxScale, an advanced database proxy for high availability, scalability, and security. Learn how it intelligently routes connections and balances loads for optimal database performance.

Quickstart Guides

Get started with MariaDB MaxScale, the advanced database proxy. These guides provide a quick path to installing, configuring, and leveraging key features.

MariaDB MaxScale Guide

Quickstart guide for MariaDB MaxScale

Quickstart Guide: MariaDB MaxScale Overview

MariaDB MaxScale is an advanced, open-source database proxy, router, and load balancer designed to enhance the scalability, high availability, and security of your MariaDB deployments. It acts as an intelligent intermediary between your applications and your MariaDB servers, abstracting the underlying database topology.

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.
High Availability and Automated Failover:
- MaxScale constantly monitors the health of your MariaDB servers. In a replication setup (e.g., primary-replica or Galera Cluster), if the primary server fails, MaxScale can automatically detect the failure, promote a healthy replica to become the new primary, and seamlessly redirect client connections to the newly promoted server. This minimizes downtime and ensures continuous operation.
Seamless Server Maintenance:
- MaxScale provides built-in mechanisms to place backend servers into maintenance mode without interrupting connected applications or clients. This allows administrators to perform tasks like patching, upgrades, or reconfigurations on individual servers while MaxScale intelligently redirects traffic away from them. Management can be done via the maxctrl command-line interface, MaxGUI (web interface), or REST API.
Security and Traffic Control:
- MaxScale can implement granular security policies and traffic controls for database connections and queries. This includes features like firewalling, query filtering, and authentication proxying.
- QLAfilter (Query Log Anonymizer Filter): This filter can be used to create an audit trail by logging all queries, with options to anonymize sensitive data, aiding in security audits and performance analysis.
Protocol Compatibility: MaxScale is designed to be compatible with standard MariaDB and MySQL client protocols, making it transparent to most applications.

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:

MariaDB MaxScale Installation Guide

MariaDB MaxScale installation quickstart guide

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.

Key concepts

To understand MaxScale, familiarize yourself with these core components:

Servers: These are your backend MariaDB or MySQL instances that MaxScale will manage traffic to.
Monitors: Plugins that observe the health and state of your backend servers (e.g., primary, replica, down).
Routers: Plugins that determine how client queries are directed to backend servers (e.g., readwritesplit router for directing writes to a primary and reads to replicas).
Services: Define a combination of a router and a set of servers, along with any filters.
Listeners: Define how clients connect to MaxScale (port, protocol) and which service they connect to.
Filters: Optional components that can inspect, modify, or log queries as they pass through MaxScale (e.g., qlafilter for auditing).

Installation

MariaDB MaxScale is typically installed from the official MariaDB repositories.

Add MariaDB Repository:

Use the MariaDB Repository Configuration Tool (search "MariaDB Repository Generator") to get specific instructions for your OS and MaxScale version.

Installation for Debian/Ubuntu:

sudo apt update
sudo apt install -y curl
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash
sudo apt install -y maxscale

Installation for RHEL/Rocky Linux/Alma Linux:

curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash
sudo dnf install -y maxscale

Basic configuration

MaxScale's configuration is primarily done in its main configuration file in /etc/maxscale.cnf.

Define Servers:

Add a section for each of your backend MariaDB servers.

[server1]
type=server
# IP address or hostname of your first MariaDB server
address=192.168.1.101

[server2]
type=server
# IP address or hostname of your second MariaDB server
address=192.168.1.102
# Set the port if MariaDB is listening on a non-default port
port=3307

Define a Monitor:

This section tells MaxScale how to monitor your backend servers' health and roles and groups them into a cluster of servers.

[MariaDB-Cluster]
type=monitor
# The  MariaDB asynchronous replication monitoring module
module=mariadbmon
# List of servers to monitor
servers=server1,server2
# The user used for monitoring
user=maxscale_monitor
password=monitor_password
# Check every 5 seconds
monitor_interval=5s

Important: Create the maxscale_monitor user on your backend MariaDB servers with appropriate privileges:

CREATE USER 'maxscale_monitor'@'%' IDENTIFIED BY 'monitor_password';
GRANT 
  BINLOG ADMIN, BINLOG MONITOR, 
  CONNECTION ADMIN, READ_ONLY ADMIN,
  REPLICATION SLAVE ADMIN, SLAVE MONITOR,
  RELOAD, PROCESS, SUPER, EVENT, SET USER,
  SHOW DATABASES
  ON *.* 
  TO `maxscale_monitor`@`%`
GRANT SELECT ON mysql.global_priv TO 'maxscale_monitor'@'%';

Define a Service (e.g., Read-Write Split):

This configures how MaxScale routes queries. The readwritesplit router is very common for replication setups as it load balances read while routing writes to the primary node.

[Read-Write-Service]
type=service
# The readwritesplit router module load balances reads and routes writes to the primary node
router=readwritesplit
# Servers available for this service
cluster=MariaDB-Cluster
# The user account used to fetch the user information from MariaDB
user=maxscale_user
password=maxscale_password

Important: Create the maxscale_user on your backend MariaDB servers with the following privileges:

CREATE USER 'maxscale_user'@'%' IDENTIFIED BY 'maxscale_password';
GRANT SELECT ON mysql.user TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.db TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.columns_priv TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.procs_priv TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.proxies_priv TO 'maxscale_user'@'%';
GRANT SELECT ON mysql.roles_mapping TO 'maxscale_user'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale_user'@'%';

Define a Listener:

This specifies the port and protocol MaxScale will listen on for incoming client connections and which service to direct them to.

[Read-Write-Listener]
type=listener
# The service that this listener connects to
service=Read-Write-Service
# The port that MaxScale will listen on for client applications
port=3306

Global MaxScale Configuration (usually at the top of maxscale.cnf):

[maxscale]
# Select the number of worker threads automatically based on the CPU thread count
threads=auto

Complete configuration

Your /etc/maxscale.cnf should now look like this:

[maxscale]
threads=auto

[server1]
type=server
address=192.168.1.101

[server2]
type=server
address=192.168.1.102
port=3307

[MariaDB-Cluster]
type=monitor
module=mariadbmon
servers=server1,server2
user=maxscale_monitor
password=monitor_password
monitor_interval=5s

[Read-Write-Service]
type=service
router=readwritesplit
cluster=MariaDB-Cluster
user=maxscale_user
password=maxscale_password

[Read-Write-Listener]
type=listener
service=Read-Write-Service
port=3306

Start and enable MaxScale

After configuring maxscale.cnf, start and enable the MaxScale service.

sudo systemctl start maxscale
sudo systemctl enable maxscale
sudo systemctl status maxscale # Check status

Basic usage and verification

Once MaxScale is running, configure your applications to connect to MaxScale's listener port instead of directly to a MariaDB server.

Example (Connect with mariadb client from the MaxScale server):

mariadb -h 127.0.0.1 -P 3306 -u my-user -p

Verify Read-Write Split (if configured):

Connect to MaxScale (127.0.0.1:3306).
Execute a WRITE query (e.g., INSERT INTO your_table ...). This should be routed to the primary server.
Execute a READ query (e.g., SELECT * FROM your_table). This should be load-balanced across your replica servers.
You can use maxctrl list servers and maxctrl show servers to observe routing in action.

Further Resources:

MariaDB MaxScale Authenticators Guide

Quickstart guide for MariaDB MaxScale authentication modules

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.

1. What are MaxScale Authentication Modules?

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.

2. How Authentication Works in MaxScale

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.
It typically queries the mysql database on your backend MariaDB servers (usually the primary) to retrieve user account details.
Using this information, the UAM authenticates connecting clients, verifies their passwords, and checks their database access rights.
The user and password settings within your MaxScale service configuration define the credentials MaxScale uses to fetch these user accounts from the backend databases.

3. Available Authentication Plugins

MaxScale supports various authentication schemes through different plugins:

Standard MySQL Password: This is the most common authentication method, verifying user credentials against those stored in the backend MariaDB server's mysql.user table (or similar).
GSSAPI (Generic Security Service Application Programming Interface): Provides secure authentication methods, often used in enterprise environments with Kerberos or similar systems.
PAM (Pluggable Authentication Modules): Allows MaxScale to integrate with PAM, enabling authentication against external systems like Unix system users, LDAP, or Active Directory.

4. Basic Configuration Concepts

Authentication options are primarily defined within the listener configuration of your MaxScale service in the maxscale.cnf file.

a. Specifying the Authenticator:

The authenticator parameter specifies which authentication plugin to use for a particular listener.

Example maxscale.cnf snippet (simplified):

Ini, TOML

[my_service]
type=service
router=readwritesplit
servers=server1,server2
user=maxscale_user # User MaxScale uses to connect to backend MariaDB for UAM
password=maxscale_password

[my_listener]
type=listener
service=my_service
protocol=MariaDBClient
port=3306
authenticator=MariaDBAuth # Example: Use the standard MariaDB password authentication
# authenticator=GSSAPIAuth # Or GSSAPI authentication
# authenticator=PAMAuth    # Or PAM authentication

b. Authenticator Options (authenticator_options):

Additional settings can be passed to the authenticator plugin using authenticator_options. These are comma-separated key-value pairs.

Common authenticator_options:

skip_authentication=true: (Use with extreme caution, typically only for development/testing). This option bypasses password checks for connecting clients. Clients will still need a valid username in the backend database, but their password will not be verified.
match_host=false: Disables host matching for user accounts. By default, MariaDB (and thus MaxScale's UAM) matches user accounts based on both username and host (e.g., 'user'@'localhost'). Setting this to false means only the username needs to match.
lower_case_table_names=true/false: Controls how database names are matched during authentication, similar to the lower_case_table_names system variable in MariaDB Server.

Example with options:

Ini, TOML

[my_listener]
# ... other settings ...
authenticator=MariaDBAuth
authenticator_options=skip_authentication=true,match_host=false

By configuring these authentication modules, you can control how clients connect to your MariaDB through MaxScale, enforce security policies, and integrate with existing authentication infrastructure.

Further Resources:

MariaDB MaxScale Authentication Modules Documentation
MariaDB MaxScale Documentation

MariaDB MaxScale Limitations Guide

MariaDB MaxScale limitations quickstart guide

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.

2. Assumptions about MariaDB Server Configuration

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.

3. Transaction Boundary Detection and XA Transactions

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.
Consideration: Be cautious with overly complex SQL or when using XA transactions in conjunction with MaxScale's transaction-aware routers. Thoroughly test your application's transaction logic through MaxScale to identify and mitigate any potential inconsistencies.

4. ETL Feature Dependency

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.

Important General Considerations:

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.
Monitoring and Filters: Be aware that specific monitor or filter modules might have their own inherent limitations or performance impacts.

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

Further Resources:

MaxScale Architecture

Understand MariaDB MaxScale's architecture. Explore its components, including monitors, routers, and filters, and how they work together to provide advanced database proxy capabilities.

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, transparently 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 the 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. Filter 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 email to maxscale@googlegroups.com or use the forum interface.

Bugs can be reported in the MariaDB Jira jira.mariadb.org

Installing MariaDB MaxScale

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

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

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

MariaDB MaxScale Overview

Get an overview of MariaDB MaxScale. This section introduces its core functionalities, including intelligent routing, load balancing, and high availability, for managing and optimizing deployment.

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

Latest Software Releases

Release Series

Latest Release Date

Latest Release

24.02

2024-12-09

23.08

2024-12-09

MariaDB MaxScale 23.08.8

23.02

2024-12-09

22.08

2024-12-09

MariaDB MaxScale 22.08.15

2024-03-11

2.5

2023-10-25

2.4

2022-01-10

Available Documentation

Security

Authentication with MariaDB MaxScale

Architecture

What's New

See the MariaDB MaxScale 24.02 Changelog for a list of what's new in MaxScale 24.02 and prior versions.

MaxScale Management

Manage MariaDB MaxScale efficiently. This section covers configuration, monitoring, and administration tasks to ensure optimal performance and reliability of your database proxy.

Installation & Configuration

This is your starting point for MariaDB MaxScale. Find essential guides for installation, learn how to configure MaxScale for your needs, and explore tutorials to get up and running.

MaxScale Installation Guide

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

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 listed 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 will interact with a running MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality.

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}

Building MaxScale From Source

Building MariaDB MaxScale from Source Code

MariaDB MaxScale can be built on any system that meets the requirements. The main requirements are as follows:

CMake version 3.16 or later (Packaging requires CMake 3.25.1 or later)
GCC version 4.9 or later
OpenSSL version 1.0.1 or later
GNUTLS
Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl
PAM
SASL2 (cyrus-sasl)
SQLite3 version 3.3 or later
Tcl
git
jansson
libatomic
libcurl
libmicrohttpd
libuuid
libxml2
libssh
pcre2
zstd

This is the minimum set of requirements that must be met to build the MaxScale core package. Some modules in MaxScale require optional extra dependencies.

libuuid (binlogrouter)
boost (binlogrouter)
Bison 2.7 or later (dbfwfilter)
Flex 2.5.35 or later (dbfwfilter)
librdkafka (kafkacdc, kafkaimporter and mirror)
memcached (storage_memcached for the cache filter)
hiredis (storage_redis for the cache filter)

Some of these dependencies are not available on all operating systems and are downloaded automatically during the build step. To skip the building of modules that need automatic downloading of the dependencies, use -DBUNDLE=N when configuring CMake.

Quickstart

This installs MaxScale as if it was installed from a package. Install git before running the following commands.

Required Packages

For a definitive list of packages, consult the script.

Configuring the Build

The tests and other parts of the build can be controlled via CMake arguments.

Here is a small table with the names of the most common parameters and what they control. These should all be given as parameters to the -D switch inNAME=VALUE format (e.g. -DBUILD_TESTS=Y).

Argument Name

Explanation

Note: You can look into for a list of the CMake variables.

Running unit tests

To run the MaxScale unit test suite, configure the build with -DBUILD_TESTS=Y, compile and then run the make test command.

Building MariaDB MaxScale packages

If you wish to build packages, just add -DPACKAGE=Y to the CMake invocation and build the package with make package instead of installing MaxScale withmake install. This process will create a RPM/DEB package depending on your system.

To build a tarball, add -DTARBALL=Y to the cmake invocation. This will create a maxscale-x.y.z.tar.gz file where x.y.z is the version number.

Some Debian and Ubuntu systems suffer from a bug where make package fails with errors from dpkg-shlibdeps. This can be fixed by running make beforemake package and adding the path to the libmaxscale-common.so library to the LD_LIBRARY_PATH environment variable.

Installing optional components

The MaxScale build system is split into multiple components. The main component is the core MaxScale package which contains MaxScale and all the modules. This is the default component that is build, installed and packaged. There is also the experimental component that contains all experimental modules which are not considered as part of the core MaxScale package and are either alpha or beta quality modules.

To build the experimental modules along with the MaxScale core components, invoke CMake with -DTARGET_COMPONENT=core,experimental.

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

Installing MaxScale Using a Tarball

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
libatomic
unixODBC

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}

MaxScale MaxGUI Guide

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 andadmin_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 Configuration Guide and Configuration and Hardening for instructions on how to harden your MaxScale installation for production use.

Authentication

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

Internally, MaxGUI uses JSON Web Tokens 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.

Pages

Dashboard

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.

Detail

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

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

Visualization

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

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

Settings

This page shows and allows editing of MaxScale parameters.

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

Logs Archive

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

Workspace

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

1. Run Queries

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.

2. Data Migration

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.

3. Create an ERD

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}

Configuring MaxScale's REST API

Overview

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

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

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

for remote connections by configuring several global parameters in maxscale.cnf.

Parameter

Description

For example:

Restart the MaxScale instance.

Operating MaxScale

Overview

Configuring the REST API

Creating a REST API User

Deleting a REST API User

Using TLS

* • •

Configuring MaxScale for MaxGUI

Setting a Server to Maintenance Mode

Understanding MaxScale's Administrative Interfaces

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:

Interface

Description

MaxCtrl

Use MaxCtrl for MariaDB MaxScale administration. This section introduces the command-line tool for managing MaxScale instances, configurations, and monitoring their status efficiently.

Connecting to MaxScale using TLS with MaxCtrl

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

Create a basic or admin user, depending on what kind of user you need:

$ maxctrl create user "maxscale_rest_admin" "maxscale_rest_admin_password" --type=admin

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

If you want to use MaxCtrl remotely, configure the REST API for remote connections. Several global parameters must be configured in maxscale.cnf.

Parameter

Description

• This parameter defines the network address that the REST API listens on.• The default value is 127.0.0.1.

• This parameter defines the network port that the REST API listens on.• The default value is 8989.

For example:

[maxscale]
...
admin_host            = 0.0.0.0
admin_port            = 8443

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

Parameter

Description

* This parameter defines the private key used by the REST API.

* This parameter defines the certificate used by the REST API.

*This parameter defines the CA certificate that signed the REST API's certificate.

For example:

[maxscale]
...
admin_ssl_key=/certs/server-key.pem
admin_ssl_cert=/certs/server-cert.pem
admin_ssl_ca_cert=/certs/ca-cert.pem

Ensure that the client also has a TLS certificate, a private key, and the CA certificate.
Use MaxCtrl to connect with TLS:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem

Replace maxscale_rest_admin and maxscale_rest_admin_password with the actual user and password.

Creating a REST API User for MaxScale with MaxCtrl

Overview

MaxScale has a REST API, which can be configured to require authentication. When first installed, it has a single default admin user (admin) and password (mariadb). However, this user can be deleted, and other users can be created.

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

User Types

There are two types of users:

User Type

Description

Basic

The user has read-only access

Admin

The user can change global MaxScale parameters and reconfigure modules.

Creating a Basic User

Configure the REST API if the default configuration is not sufficient.
Use MaxCtrl to execute the create user command:

$ maxctrl --secure \
   --user=admin \
   --password=mariadb \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   create user "maxscale_rest" "maxscale_rest_password"

Replace maxscale_rest and maxscale_rest_password with the desired user and password.

Creating an Admin User

Configure the REST API if the default configuration is not sufficient.
Use MaxCtrl to execute the create user command with the --type=admin option:

$ maxctrl --secure \
   --user=admin \
   --password=mariadb \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   create user "maxscale_rest_admin" "maxscale_rest_admin_password" --type=admin

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

Deleting a REST API User for MaxScale with MaxCtrl

Overview

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

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

Deleting a User

Configure the REST API if the default configuration is not sufficient.
Use MaxCtrl to execute the destroy user command:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   destroy user "admin"

Replace admin with the actual user.

MaxScale will refuse to delete the last remaining admin user.

Setting a Server to Maintenance Mode in MaxScale with MaxCtrl

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

Configure the REST API if the default configuration is not sufficient.
Use MaxCtrl to execute the set server command with the maintenance option:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   set server server1 maintenance

Replace server1 with the name of the specific server.

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

Use MaxCtrl to execute the set server command with the maintenance --force option:

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \

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.

MaxGUI

Manage MariaDB MaxScale with MaxGUI. This section introduces the graphical user interface for easy configuration, monitoring, and administration of your MaxScale instances.

Configuring MaxScale for MaxGUI

Overview

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

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

Enabling MaxGUI

If you want to use MaxGUI remotely, for remote connections. Several global parameters must be configured in maxscale.cnf.

Parameter

Description

For example:

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

Parameter

Description

For example:

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.
Restart the MaxScale instance.

user with MaxCtrl:

Replace maxscale_rest_admin and maxscale_rest_admin_password with the desired user and password.

named admin with MaxCtrl:

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:

Enter your user and password to login.

Setting a Server to Maintenance Mode in MaxScale with MaxGUI

Overview

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

Setting a Server to Maintenance Mode

.
Visit MaxGUI in your web browser. For example, if you are accessing it from local host with the default port, then visit this address:
Enter your username and password to log in.
On the dashboard, the "Servers" tab is shown by default.
Click the server that you want to set to maintenance mode. This will bring up a page for the specific server.
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.
Click the pause icon. This will open a popup window.
Click the "Maintain" button. 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

Visit MaxGUI in your web browser. For example, if you are accessing it from local host with the default port, then visit this address:
Enter your user and password to login.
On the dashboard, the "Servers" tab is shown by default.
Click the server that you want to set to maintenance mode. This will bring up a page for the specific server.
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.
Click the pause icon. This will open a popup window.
Check the "Force closing" checkbox.
Click the "Maintain" button. When the "Force closing" checkbox is specified, MaxScale immediately close all connections, even if the server is a primary server that has open transactions.

MaxScale Security

Secure MariaDB MaxScale deployments. This section covers essential security practices, including user authentication, SSL/TLS configuration, and access control, to protect your database proxy.

MaxScale Authentication

Learn about authentication in MariaDB MaxScale. This section covers configuring user authentication for clients connecting through MaxScale and securing access to your database instances.

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

Native Authenticator

Overview

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

MaxScale Use Cases

Discover common use cases for MariaDB MaxScale. This section highlights how MaxScale enhances high availability, scalability, security, and performance for various database deployments.

MaxScale Overview

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.

Read/Write Split Router Usage

This router sends write queries to a single primary server while load-balancing read queries across replica servers. Learn how to configure this for scaling out read workloads.

Delayed Retrying of Failed Queries with MaxScale's Read/Write Split Router

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

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

Parameter

Description

delayed_retry

• When this parameter is enabled, failed queries will not immediately return an error to the client. Instead, the router will retry the query if a different server becomes available before the timeout is reached. • This parameter is disabled by default.

delayed_retry_timeout

• The maximum amount of time to wait until returning an error if a query fails. • The value can be followed by any of the following units: h, m, s, and ms, for specifying durations in hours, minutes, seconds, and milliseconds. • The default value is 10 seconds.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
delayed_retry            = true
delayed_retry_timeout    = 30s

Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Designing for MaxScale's Read/Write Split Router

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 Write Split Router reconnect client connections to the new primary server after automatic failover?
How does the Read/Write Split Router retry failed reads?
How does the Read/Write Split Router retry failed queries during automatic failover?

Additional information is available here.

Ensuring Causal Consistency with MaxScale's Read/Write Split Router

The load balances read-only queries between one or more replica servers. If the replica servers are using asynchronous , then the data on the replica servers can sometimes lag behind the primary server. When this occurs, read-only queries that are executed on the replica servers can return stale results if they are not executed in a causally consistent manner. Causal consistency is the act of ensuring that interdependent operations maintain consistency by performing them in the same order on all servers.

To prevent this, the Read/Write Split Router can be configured to enable "causal reads", which ensures causal consistency for read-only queries. When causal reads is enabled, the Read/Write Split Router ensures that load balanced read-only queries are only executed on the replica server after all write statements previously executed on the primary server are fully replicated and applied on that specific replica server.

Multiple MaxScale Nodes

Starting with MaxScale 22.08, the Read/Write Split Router's causal reads functionality can be used with multiple MaxScale nodes.

Example of a Causal Read Let's say that a client does the following:

The client executes an statement:

The router will route this statement to the primary server.

The client executes a statement that reads the inserted row:

The router will route this statement to a replica server.

In the above example, the replica server may not replicate and apply the statement immediately. If the statement is executed before this happens, then the results of the query will not be causally consistent.

However, if causal reads is enabled, then the Read/Write Split Router will only execute the statement after the statement has been fully replicated and applied on the replica server.

Enabling Causal Reads

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

Enabling Causal Reads on MariaDB Server

Perform the following procedure on all MariaDB Servers used by MaxScale:

Choose a configuration file in which to configure your system variables and options. It is not recommended to make custom changes to one of the bundled configuration files. Instead, it is recommended to create a custom configuration file in one of the included directories. Configuration files in included directories are read in alphabetical order. If you want your custom configuration file to override the bundled configuration files, then it is a good idea to prefix the custom configuration file's name with a string that will be sorted last, such as z-.

On RHEL, CentOS, Rocky Linux, and SLES, a good custom configuration file would be: /etc/my.cnf.d/z-custom-my.cnf
On Debian and Ubuntu, a good custom configuration file would be: /etc/mysql/mariadb.conf.d/z-custom-my.cnf

Set the system variable to last_gtid, so that the server will track session-level changes to the value of the system variable.

It needs to be set in the configuration file in a group that will be read by , such as [mariadb] or [server].

For example:

Restart the server.

Enabling Causal Reads on MaxScale 2.5

Set the causal_reads and causal_reads_timeout parameters for the Read/Write Split Router in maxscale.cnf. The causal_reads parameter can be set to the following values:

Value

Description

For example:

Restart the MaxScale instance.

Enabling Causal Reads on MaxScale 2.4 and Before

Set the causal_reads and causal_reads_timeout parameters for the Read/Write Split Router in maxscale.cnf.

For example:

Restart the MaxScale instance.

Maintaining Connection State on Replica Servers with MaxScale's Read/Write Split Router

The load balances read-only queries between one or more replica servers. If a replica server fails, then the router may need to create new connections to a different replica server for any existing client connections. The router takes certain steps to ensure that those new replica server connections have the same state as the old replica server connections.

Session Command History

The maintains connection state on replica servers by keeping a session command history. If the router has to create a new connection, then it replays these session commands from the previous connection on the new connection.

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

Set the maximum size of the session command history by configuring some parameters for the Read/Write Split Router in maxscale.cnf.

Parameter

Description

For example:

Restart the MaxScale instance.

Disabling the Session Command History

Disable the session command history by configuring the disable_sescmd_history parameter for the Read/Write Split Router in maxscale.cnf.

For example:

Restart the MaxScale instance.

Reconnecting to the Primary Server with MaxScale's Read/Write Split Router

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

Configure automatic primary server re-connection by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

Parameter

Description

master_reconnection

• When this parameter is enabled, if the primary server fails and if master_failure_mode is not set to fail_instantly, then existing client connections will be automatically reconnected to the new primary server. • This parameter is disabled by default.

master_failure_mode

• This parameter defines how client connections are handled when the primary server fails. • This parameter must be set to either fail_on_write or error_on_write to allow automatic primary server reconnection. • When this parameter is set to fail_on_write, the client connection is closed if a write query is received when no primary is available. • When this parameter is set to error_on_write, if no primary server is available and a write query is received, an error is returned stating that the connection is in read-only mode.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
master_reconnection            = true
master_failure_mode            = fail_on_write

Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Replaying Transactions with MaxScale's Read/Write Split Router

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

Configure transaction replay by configuring several parameters for the Read/Write Split Router in maxscale.cnf.

Parameter

Description

transaction_replay

• When this parameter is enabled, transactions will be replayed if they are interrupted. It also implicitly enables the delayed_retry and master_reconnection parameters. • When this parameter is disabled, interrupted transactions will cause the client connection to be closed. • This parameter is disabled by default.

transaction_replay_max_size

• The maximum size of the transaction cache for each client connection. The unit is bytes, but EIC binary prefixes (Ki, Mi, Gi, and Ti) and SI prefixes (k, M, G, and T) can also be specified. • The default value is 1 MiB.

transaction_replay_attempts

• The maximum number of attempts to make when replaying a transaction. • The default value is 5.

transaction_replay_retry_on_deadlock

• When this parameter is enabled, transactions will be replayed if a deadlock occurs. • When this parameter is disabled, the client will receive an error if a deadlock occurs. • This parameter is disabled by default.

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
transaction_replay                   = true
transaction_replay_max_size          = 10Mi
transaction_replay_attempts          = 10
transaction_replay_retry_on_deadlock = true

Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Retrying Failed Reads with MaxScale's Read/Write Split Router

The Read/Write Split Router (readwritesplit) routes write queries to the primary server and load balances read-only queries between one or more replica servers. If a read-only query fails, then the router can retry the query on a different server.

Configuring Retries for Failed Reads

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

For example:

[split-router]
type                     = service
router                   = readwritesplit
...
retry_failed_reads       = true

Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Selecting Replica Servers with MaxScale's Read/Write Split Router

The Read/Write Split Router (readwritesplit) load balances read-only queries between one or more replica servers. It selects a replica server to execute a query using criteria configured by the slave_selection_criteria parameter.

Criterion

Description

ADAPTIVE_ROUTING

Selects using average response times

LEAST_BEHIND_MASTER

Selects based on replication lag

LEAST_CURRENT_OPERATIONS

Selects based on number of active operations (the default)

LEAST_GLOBAL_CONNECTIONS

Selects based on number of connections from MariaDB MaxScale

LEAST_ROUTER_CONNECTIONS

Selects based on number of connections from the service

Using Adaptive Routing

The Read/Write Split Router (readwritesplit) uses adaptive routing when the slave_selection_criteria parameter is set to ADAPTIVE_ROUTING.

In this mode, the router measures average server response times. When the router routes queries, it compares the response times of the different replica servers. It favors the faster servers for most queries, while still guaranteeing some traffic on the slowest servers.

Using Least Behind Primary

The Read/Write Split Router (readwritesplit) uses the replica server that is least behind the primary server when the slave_selection_criteria parameter is set to LEAST_BEHIND_MASTER. This mode is only compatible with .

In this mode, the router measures replica lag using the Seconds_Behind_Master column from SHOW REPLICA STATUS. The replica server that has the lowest value is considered to be the least behind the primary server.

Setting the Replica Selection Criteria

Set the replica selection criteria by configuring the slave_selection_criteria parameter for the Read/Write Split Router in maxscale.cnf:

[split-router]
type                     = service
router                   = readwritesplit
...
slave_selection_criteria = LEAST_GLOBAL_CONNECTIONS

Restart the MaxScale instance.

$ sudo systemctl restart maxscale

Understanding MaxScale's Read/Write Split Router

What Does the Read/Write Split Router Support?

The Read/Write Split Router (readwritesplit) supports:

deployments
Galera Cluster deployments
Multi-Node Enterprise ColumnStore deployments

When to Use the Read/Write Split Router?

The Read/Write Split Router (readwritesplit) allows you to:

Perform query-based load balancing.
Route client connections to multiple servers simultaneously.
Route write queries to primary and read queries to replicas.
Automatically reconnect clients to the new primary after failover or switchover.
Automatically replay transactions on the new primary after failover or switchover.
Automatically retry failed queries.
Enforce causal reads to avoid reading stale data caused by slave lag.

Deploying Read/Write Split Router

Deploy ColumnStore Object Storage Topology
Deploy ColumnStore Shared Local Storage Topology
Deploy Galera Cluster Topology
Deploy Primary/Replica Topology
Deploy Xpand Topology
write-split-router-usageDeploy MaxScale with MariaDB Monitor and Read/Write Split Router
Deploy MaxScale with Galera Monitor and Read/Write Split Router

Tutorials

Learn MariaDB MaxScale with practical tutorials. These guides provide step-by-step instructions for various MaxScale features, helping you implement advanced database proxy solutions.

Setting up MariaDB MaxScale

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

The precise installation process varies from one distribution to another. Details on package installation can be found in the .

Creating a user account for MaxScale

MaxScale checks that incoming clients are valid. To do this, MaxScale needs to retrieve user authentication information from the backend databases. Create a special user account for this purpose by executing the following SQL commands on the primary server of your database cluster. The following tutorials will use these credentials.

MariaDB versions 10.2.2 to 10.2.10 also require GRANT SELECT ON mysql.* TO 'maxscale'@'%';

Creating client user accounts

Because MariaDB MaxScale sits between the clients and the backend databases, the backend databases will see all clients as if they were connecting from MaxScale's address. This usually means that two sets of grants for each user are required.

For example, assume that the user 'jdoe'@'client-host' exists and MaxScale is located at maxscale-host. If 'jdoe'@'client-host' needs to be able to connect through MaxScale, another user, 'jdoe'@'maxscale-host', must be created. The second user must have the same password and similar grants as 'jdoe'@'client-host'.

The quickest way to do this is to first create the new user:

Then do a SHOW GRANTS query:

Then copy the same grants to the 'jdoe'@'maxscale-host' user.

An alternative to generating two separate accounts is to use one account with a wildcard host ('jdoe'@'%') which covers both hosts. This is more convenient but less secure than having specific user accounts as it allows access from all hosts.

Creating the configuration file

MaxScale reads its configuration from /etc/maxscale.cnf. A template configuration is provided with the MaxScale installation.

A global maxscale section is included in every MaxScale configuration file. This section sets the values of various global parameters, such as the number of threads MaxScale uses to handle client requests. To set thread count to the number of available cpu cores, set the following.

Configuring the servers

Read the mini-tutorial for server configuration instructions.

Configuring the monitor

The type of monitor used depends on the type of cluster used. For a primary-replica cluster read . For a Galera cluster read .

Configuring the services and listeners

This part is covered in two different tutorials. For a fully automated read-write-splitting setup, read the . For a simple connection based setup, read the .

Starting MaxScale

After configuration is complete, MariaDB MaxScale is ready to start. For systems that use systemd, use the systemctl command.

For older SysV systems, use the service command.

If MaxScale fails to start, check the error log in /var/log/maxscale/maxscale.log to see if any errors are detected in the configuration file.

Checking MaxScale status with MaxCtrl

The maxctrl-command can be used to confirm that MaxScale is running and the services, listeners and servers have been correctly configured. The following shows expected output when using a read-write-splitting configuration.

MariaDB MaxScale is now ready to start accepting client connections and route queries to the backend cluster.

More options can be found in the , and .

For more information about MaxCtrl and how to secure it, see the .

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

Analyzing MaxCtrl Create Report Output

The output of the maxctrl create report command produces a JSON payload that contains the current state of MaxScale. This includes the runtime configuration and the status all objects in MaxScale.

The maxctrl create report command was added in MaxScale 2.5.20.

Creating a MaxCtrl Report

The report can be created with:

After the command completes, the data is in maxctrl-report.json.

The file in which the output is stored is the only argument to this command. Recent versions of maxctrl pipe the output to the standard output if no filename is given. This can be useful for environments where copying files may be difficult (e.g. docker).

Using `jq`

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

It is usually available as a package in most operating systems.

List servers

List services

List monitors

List listeners

List filters

List keys of objects

This can be combined with the object field access to list the fields of sub-objects. The following lists the keys in the first server object.

Get a specific service

Change the RW-Split-Router to the name of the service you're looking for.

Get a specific monitor

Change the MariaDB-Monitor to the name of the monitor you're looking for.

Get a specific server

Change the DB-1 to the name of the server you're looking for.

Find the monitor for a server

Change DB-1 to the name of the server you're looking for.

Memory used by the query classifier cache

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

Configuring Servers

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

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

Configuring the Galera Monitor

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

Configuring the MariaDB Monitor

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.

Monitor User

The monitor user requires the REPLICATION CLIENT privileges to do basic monitoring. To create a user with the proper grants, execute the following SQL.

Note: If the automatic failover of the MariaDB Monitor will used, the user will require additional grants. Execute the following SQL to grant them.

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

Connection Routing with MariaDB MaxScale

The goal of this tutorial is to configure a system that has two ports available, one for write connections and another for read connections. The read connections are load- balanced across replica servers.

Setting up MariaDB MaxScale

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

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 namesWrite-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 theWrite-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}

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.

maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484

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.

[My-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=96F99AA1315BDC3604B006F427DD9484

If the key file is not in the default location, the datadir parameter must be set to the directory that contains it.

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

Filters

What Are Filters?

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.

Types Of Filter

Filters can be divided into a number of categories

Logging filters

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

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.

Result set manipulation filters

A result set manipulation filter is very similar to a statement rewriting but applies to the result set returned rather than the statement executed. An example of this may be obfuscating the values in a column.

Routing hint filters

Routing hint filters are filters that embed hints in the request that can be used by the router onto which the query is passed. These hints include suggested destinations as well as metric that may be used by the routing process.

Firewall filters

A firewall filter is a mechanism that allows queries to be blocked within MariaDB MaxScale before they are sent on to the database server for execution. They allow constructs or individual queries to be intercepted and give a level of access control that is more flexible than the traditional database grant mechanism.

Pipeline control filters

A pipeline filter is one that has an affect on how the requests are routed within the internal MariaDB MaxScale components. The most obvious version of this is the ability to add a "tee" connector in the pipeline, duplicating the request and sending it to a second MariaDB MaxScale service for processing.

Filter Definition

Filters are defined in the configuration file, typically maxscale.cnf, using a section for each filter instance. The content of the filter sections in the configuration file various from filter to filter, however there are always to entries present for every filter, the type and module.

The type is used by the configuration manager within MariaDB MaxScale to determine what this section is defining and the module is the name of the plugin that implements the filter.

When a filter is used within a service in MariaDB MaxScale the entry filters= is added to the service definition in the ini file section for the service. Multiple filters can be defined using a syntax akin to the Linux shell pipe syntax.

The names used in the filters= parameter are the names of the filter definition sections in the ini file. The same filter definition can be used in multiple services and the same filter module can have multiple instances, each with its own section in the ini file.

Filter Examples

The filters that are bundled with the MariaDB MaxScale are documented separately, in this section a short overview of how these might be used for some simple tasks will be discussed. These are just examples of how these filters might be used, other filters may also be easily added that will enhance the MariaDB MaxScale functionality still further.

Log The 30 Longest Running Queries

The top filter can be used to measure the execution time of every statement within a connection and log the details of the longest running statements.

The first thing to do is to define a filter entry in the ini file for the top filter. In this case we will call it "top30". The type is filter and the module that implements the filter is called topfilter.

In the definition above we have defined two filter specific parameters, the count of the number of statement to be logged and a filebase that is used to define where to log the information. This filename is a stem to which a session id is added for each new connection that uses the filter.

The filter keeps track of every statement that is executed, monitors the time it takes for a response to come back and uses this as the measure of execution time for the statement. If the time is longer than the other statements that have been recorded, then this is added to the ordered list within the filter. Once 30 statements have been recorded those statements that have been recorded with the least time are discarded from the list. The result is that at any time the filter has a list of the 30 longest running statements in each session.

When the session ends a report will be written for the session into the logfile defined. That report will include the top 30 longest running statements, plus summary data for the session;

The time the connection was opened.
The host the connection was from.
The username used in the connection.
The duration of the connection.
The total number of statements executed in the connection.
The average execution time for a statement in this connection.

Duplicate Data From Your Application Into Cassandra

The scenario we are using in this example is one in which you have an online gaming application that is designed to work with a MariaDB database. The database schema includes a high score table which you would like to have access to in a Cassandra cluster. The application is already using MariaDB MaxScale to connect to a MariaDB Galera cluster, using a service names BubbleGame. The definition of that service is as follows

The table you wish to store in Cassandra in called HighScore and will contain the same columns in both the MariaDB table and the Cassandra table. The first step is to install a MariaDB instance with the Cassandra storage engine to act as a bridge server between the relational database and Cassandra. In this bridge server add a table definition for the HighScore table with the engine type set to Cassandra. See for details. Add this server into the MariaDB MaxScale configuration and create a service that will connect to this server.

Next add a filter definition for the tee filter that will duplication insert statements that are destined for the HighScore table to this new service.

The above filter definition will cause all statements that match the regular expression inset.*HighScore.*values to be duplication and sent not just to the original destination, via the router but also to the service named Cassandra.

The final step is to add the filter to the BubbleGame service to enable the use of the filter.

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

Read-Write Splitting

The goal of this tutorial is to configure a system that appears to the client as a single database. MariaDB MaxScale will split the statements such that write statements are sent to the primary server and read statements are balanced across the replica servers.

Setting up MariaDB MaxScale

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

Configuring the service

After configuring the servers and the monitor, we create a read-write-splitter service configuration. Create the following section in your configuration file. The section name is also the name of the service and should be meaningful. For this tutorial, we use the name Splitter-Service.

[Splitter-Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw

router defines the routing module used. Here we use readwritesplit for query-level read-write-splitting.

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

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

For increased security, see password encryption.

Configuring the Listener

[Splitter-Listener]
type=listener
service=Splitter-Service
port=3306

The service parameter tells which service the listener connects to. For theSplitter-Listener we set it to Splitter-Service.

A listener must define the network port to listen on.

Starting MariaDB MaxScale

For the last steps, please return to MaxScale Tutorial.

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

Reference

Access the comprehensive MariaDB MaxScale reference. This section provides detailed documentation on its configuration parameters, modules, and API, essential for advanced deployments.

MaxScale Module Commands

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.

Developer reference

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

The array my_args of type modulecmd_arg_type_t is used to tell what kinds of arguments the command expects. The first argument is a boolean and the second argument is an optional string.

Arguments are passed to the parsing function as an array of void pointers. They are interpreted as the types the command expects.

When the module command is executed, the argv parameter for themy_simple_cmd contains the parsed arguments received from the caller of the command.

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

MaxScale Authenticators

Secure your MariaDB MaxScale deployment with authenticators. These modules manage client authentication with backend servers, supporting diverse mechanisms for enhanced security.

MaxScale GSSAPI Client Authenticator

MaxScale 25.01 GSSAPI Client Authenticator

GSSAPI Client Authenticator

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

Preparing the GSSAPI system

For Unix systems, the usual GSSAPI implementation is Kerberos. This is a short guide on how to set up Kerberos for MaxScale.

The first step is to configure MariaDB to use GSSAPI authentication. The MariaDB documentation for the is a good example on how to set it up.

The next step is to copy the keytab file from the server where MariaDB is installed to the server where MaxScale is located. The keytab file must be placed in the configured default location which almost always is/etc/krb5.keytab. Alternatively, the keytab filepath can be given as an authenticator option.

The location of the keytab file can be changed with the KRB5_KTNAME environment variable: keytab_def.html

To take GSSAPI authentication into use, add the following to the listener.

authenticator=GSSAPIAuth
authenticator_options=principal_name=mariadb/localhost.localdomain@EXAMPLE.COM

The principal name should be the same as on the MariaDB servers.

Settings

`principal_name`

Type: string
Mandatory: No
Dynamic: No
Default: mariadb/localhost.localdomain

The service principal name to send to the client. This parameter is a string parameter which is used by the client to request the token.

This parameter must be the same as the principal name that the backend MariaDB server uses.

`gssapi_keytab_path`

Type: path
Mandatory: No
Dynamic: No
Default: Kerberos Default

Keytab file location. This should be an absolute path to the file containing the keytab. If not defined, Kerberos will search from a default location, usually/etc/krb5.keytab. This path is set to an environment variable. This means that multiple listeners with GSSAPIAuth will override each other. If using multiple GSSAPI authenticators, either do not set this option or use the same value for all listeners.

authenticator_options=principal_name=mymariadb@EXAMPLE.COM,gssapi_keytab_path=/home/user/mymariadb.keytab

Implementation details

Read the Authentication Modules document for more details on how authentication modules work in MaxScale.

GSSAPI authentication

The GSSAPI plugin authentication starts when the database server sends the service principal name in the AuthSwitchRequest packet. The principal name will usually be in the form service@REALM.COM.

The client searches its local cache for a token for the service or may request it from the GSSAPI server. If found, the client sends the token to the database server. The database server verifies the authenticity of the token using its keytab file and sends the final OK packet to the client.

Building the module

The GSSAPI authenticator modules require the GSSAPI development libraries (krb5-devel on CentOS 7).

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

MaxScale MariaDB/MySQL Authenticator

MariaDB/MySQL Authenticator

The MariaDBAuth-module implements the client and backend authentication for the server plugin mysql_native_password. This is the default authentication plugin used by both MariaDB and MySQL.

Settings

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

`clear_pw_passthrough`

Boolean, default value is "false". Activates passthrough-mode. In this mode, MaxScale does not check client credentials at all and defers authentication to the backend server. It may be useful in any situation where MaxScale cannot check the existence of client user account nor authenticate the client.

When a client connects to a listener with this setting enabled, MaxScale will change authentication method to "mysql_clear_password", causing the client to send their cleartext password to MaxScale. MaxScale will then attempt to use the password to authenticate to backends. The authentication result of the first backend to respond will be sent to the client. The backend may ask MaxScale for either cleartext password or standard ("mysql_native_password") authentication token. MaxScale can work with both backend plugins since it has the original password.

This feature is incompatible with service setting lazy_connect. Either leave it unspecified or set lazy_connect=false in the linked service. Also, multiple client authenticators are not allowed on the listener when passthrough-mode is on.

Because passwords are sent in cleartext, the listener should be configured for ssl.

`log_password_mismatch`

Type:
Mandatory: No
Dynamic: No
Default: false

The service setting log_auth_warnings must also be enabled for this setting to have effect. When both settings are enabled, password hashes are logged if a client gives a wrong password. This feature may be useful when diagnosing authentication issues. It should only be enabled on a secure system as the logging of password hashes may be a security risk.

`cache_dir`

Deprecated and ignored.

`inject_service_user`

Deprecated and ignored.

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

MaxScale Connectors

Explore the connectors available for MariaDB MaxScale 25.01. This section details the MaxScale CDC Connector, a C++ API allowing applications to consume a stream of database change events.

MaxScale CDC Connector

The C++ connector for the MariaDB MaxScale CDC system.

Usage

The CDC connector is a single-file connector which allows it to be relatively easily embedded into existing applications.

To start using the connector, either download it from the MariaDB website or configure the MaxScale repository and install the maxscale-cdc-connector package.

API Overview

A CDC connection object is prepared by instantiating the CDC::Connection class. To create the actual connection, call the CDC::Connection::connect method of the class.

After the connection has been created, call the CDC::Connection::read method to get a row of data. The CDC::Row::length method tells how many values a row has and CDC::Row::value is used to access that value. The field name of a value can be extracted with the CDC::Row::key method and the current GTID of a row of data is retrieved with the CDC::Row::gtid method.

To close the connection, destroy the instantiated object.

Examples

The source code contains an example that demonstrates basic usage of the MaxScale CDC Connector.

Dependencies

The CDC connector depends on:

OpenSSL
Jansson

RHEL/CentOS 7

sudo yum -y install epel-release
sudo yum -y install jansson openssl-devel cmake make gcc-c++ git

Debian Stretch and Ubuntu Xenial

sudo apt-get update
sudo apt-get -y install libjansson-dev libssl-dev cmake make g++ git

Debian Jessie

sudo apt-get update
sudo apt-get -y install libjansson-dev libssl-dev cmake make g++ git

openSUSE Leap 42.3

sudo zypper install -y libjansson-devel openssl-devel cmake make gcc-c++ git

Building and Packaging

To build and package the connector as a library, follow MaxScale build instructions with the exception of adding -DTARGET_COMPONENT=devel to the CMake call.

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

MaxScale Filters

Filters in MariaDB MaxScale intercept and modify database traffic. Use them to transform, block, or log queries, enabling fine-grained control over your database workload and security.

MaxScale Comment Filter

Comment Filter

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

The Comment filter requires one mandatory parameter to be defined.

`inject`

Type: string
Mandatory: Yes
Dynamic: Yes

A parameter that contains the comment injected before the statements. There is also defined variable $IP that can be used to comment the IP address of the client in the injected comment. Variables must be written in all caps.

Examples

Example 1 - Inject IP address of the connected client into statements

as comment.

The following configuration adds the IP address of the client to the comment.

In this example when MaxScale receives statement like:

It would look like

when received by server.

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

MaxScale Consistent Critical Read Filter

Consistent Critical Read Filter

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 MaxScale hint syntax 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

INSERT INTO departments VALUES ('d1234', 'NewDepartment'); -- maxscale ccr=ignore

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.

Settings

The CCR filter has no mandatory parameters.

`time`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 60s

The time window during which queries are routed to the primary. The duration can be specified as documented here but the 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 oftime. 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.

`count`

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

`match`

Type: regex
Mandatory: No
Dynamic: No
Default: ""

These regular expression settings 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.

match=.*INSERT.*
ignore=.*UPDATE.*
options=case,extended

`ignore`

Type: regex
Mandatory: No
Dynamic: No
Default: ""

See documentation for match.

`options`

Type: enum
Mandatory: No
Dynamic: No
Values: ignorecase, case, extended
Default: ignorecase

Regular expression options for match and ignore.

`global`

Type: boolean
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.

Example Configuration

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

[CCRFilter]
type=filter
module=ccrfilter
time=5

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}

MaxScale Maxrows Filter

Maxrows

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.

Configuration

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

[MaxRows]
type=filter
module=maxrows

[MaxRows-Routing-Service]
type=service
...
filters=MaxRows

Settings

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

`max_resultset_rows`

Type: number
Mandatory: No
Dynamic: Yes
Default: (no limit)

Specifies the maximum number of rows a resultset can have in order to be returned to the user.

If a resultset is larger than this an empty result will be sent instead.

max_resultset_rows=1000

`max_resultset_size`

Type: size
Mandatory: No
Dynamic: Yes
Default: 64Ki

Specifies the maximum size a resultset can have in order to be sent to the client. A resultset larger than this, will not be sent: an empty resultset will be sent instead.

max_resultset_size=128Ki

`max_resultset_return`

Type: enum
Mandatory: No
Dynamic: Yes
Values: empty, error, ok
Default: empty

Specifies what the filter sends to the client when the rows or size limit is hit, possible values:

an empty result set
an error packet with input SQL
an OK packet

Example output with ERR packet:

MariaDB [(test)]> select * from test.t4;
ERROR 1415 (0A000): Row limit/size exceeded for query: select * from test.t4

`debug`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

An integer value, using which the level of debug logging made by the Maxrows filter can be controlled. The value is actually a bitfield with different bits denoting different logging.

0 (0b00000) No logging is made.
1 (0b00001) A decision to handle data form server is logged.
2 (0b00010) Reached max_resultset_rows or max_resultset_size is logged.

To log everything, give debug a value of 3.

debug=2

Example Configuration

Here is an example of filter configuration where the maximum number of returned rows is 10000 and maximum allowed resultset size is 256KB

[MaxRows]
type=filter
module=maxrows
max_resultset_rows=10000
max_resultset_size=256000

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

MaxScale Optimistic Transaction Execution Filter

Optimistic Transaction Execution Filter

The optimistictrx filter implements optimistic transaction execution. The filter is designed for a use-case where most of the transactions are read-only and writes happen rarely but each set of read-only statements is still grouped into a read-write transaction (i.e. START TRANSACTION, BEGIN orSET autocommit=0).

This filter will replace the BEGIN and START TRANSACTION SQL commands withSTART TRANSACTION READ ONLY. If the transaction is fully read-only, the transaction completes normally. However, if a write happens in the middle of a transaction, the filter issues a ROLLBACK command and then replays the read-only part of the transaction, including the original BEGIN statement. If the results of the replayed read-only part of the transaction is identical to the one that was returned to the client, the transaction proceeds normally. If the result checksum does not match, the connection is closed to prevent a write with the wrong transaction state from happening.

Configuration

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

This can also be done at runtime with:

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

MaxScale Psreuse Filter

Psreuse

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}

MaxScale Regex Filter

Overview

The Regex filter is a filter module for MariaDB MaxScale that is able to rewrite query content using regular expression matches and text substitution. The regular expressions use the PCRE2 syntax.

PCRE2 library uses a different syntax than POSIX to refer to capture groups in the replacement string. The main difference is the usage of the dollar character instead of the backslash character for references e.g. $1 instead of\1. For more details about the replacement string differences, please read the Creating a new string with substitutions chapter in the PCRE2 manual.

Configuration

The following demonstrates a minimal configuration.

[MyRegexFilter]
type=filter
module=regexfilter
match=some string
replace=replacement string

[MyService]
type=service
router=readconnroute
servers=server1
user=myuser
password=mypasswd
filters=MyRegexfilter

Settings

The Regex filter has two mandatory parameters: match and replace.

`match`

Type: regex
Mandatory: Yes
Dynamic: Yes

Defines the text in the SQL statements that is replaced.

match=TYPE[ ]*=
options=case

`options`

Type: enum
Mandatory: No
Dynamic: Yes
Values: ignorecase, case, extended
Default: ignorecase

The options-parameter affects how the patterns are compiled as usual.

`replace`

Type: string
Mandatory: Yes
Dynamic: Yes

This is the text that should replace the part of the SQL-query matching the pattern defined in match.

replace=ENGINE =

`source`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The optional source parameter defines an address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this address will have the match and replacement applied to them.

source=127.0.0.1

`user`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The optional user parameter defines a username that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username will have the match and replacement applied to them.

user=john

`log_file`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The optional log_file parameter defines a log file in which the filter writes all queries that are not matched and matching queries with their replacement queries. All sessions will log to this file so this should only be used for diagnostic purposes.

log_file=/tmp/regexfilter.log

`log_trace`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The optional log_trace parameter toggles the logging of non-matching and matching queries with their replacements into the log file on the info level. This is the preferred method of diagnosing the matching of queries since the log level can be changed at runtime. For more details about logging levels and session specific logging, please read the Configuration Guide.

log_trace=true

Examples

Example 1 - Replace MySQL 5.1 create table syntax with that for later versions

MySQL 5.1 used the parameter TYPE = to set the storage engine that should be used for a table. In later versions this changed to be ENGINE =. Imagine you have an application that you cannot change for some reason, but you wish to migrate to a newer version of MySQL. The regexfilter can be used to transform the create table statements into the form that could be used by MySQL 5.5

[CreateTableFilter]
type=filter
module=regexfilter
options=ignorecase
match=TYPE\s*=
replace=ENGINE=

[MyService]
type=service
router=readconnroute
servers=server1
user=myuser
password=mypasswd
filters=CreateTableFilter

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

MaxScale Throttle Filter

Throttle

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.

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: duration
Mandatory: Yes
Dynamic: Yes

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

`sampling_duration`

Type: duration
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: duration
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}

MaxScale Transaction Performance Monitoring Filter

Transaction Performance Monitoring Filter

Note: This module is experimental and must be built from source. The module is deprecated in MaxScale 23.08 and might be removed in a future release.

Overview

The Transaction Performance Monitoring (TPM) filter is a filter module for MaxScale that monitors every SQL statement that passes through the filter. The filter groups a series of SQL statements into a transaction by detecting 'commit' or 'rollback' statements. It logs all committed transactions with necessary information, such as timestamp, client, SQL statements, latency, etc., which can be used later for transaction performance analysis.

Configuration

The configuration block for the TPM filter requires the minimal filter options in it's section within the maxscale.cnf file, stored in /etc/maxscale.cnf.

The TPM filter does not support any filter options currently.

Settings

The TPM filter accepts a number of optional parameters.

Filename

The name of the output file created for performance logging. The default filename is tpm.log.

Source

The optional source parameter defines an address that is used to match against the address from which the client connection to MaxScale originates. Only sessions that originate from this address will be logged.

User

The optional user parameter defines a user name that is used to match against the user from which the client connection to MaxScale originates. Only sessions that are connected using this username are logged.

Delimiter

The optional delimiter parameter defines a delimiter that is used to distinguish columns in the log. The default delimiter is :::.

Query_delimiter

The optional query_delimiter defines a delimiter that is used to distinguish different SQL statements in a transaction. The default query delimiter is @@@.

Named_pipe

named_pipe is the path to a named pipe, which TPM filter uses to communicate with 3rd-party applications (e.g., ). Logging is enabled when the router receives the character '1' and logging is disabled when the router receives the character '0' from this named pipe. The default named pipe is /tmp/tpmfilter and logging is disabled by default.

For example, the following command enables the logging:

Similarly, the following command disables the logging:

Log Output Format

For each transaction, the TPM filter prints its log in the following format:

Examples

Example 1 - Log Transactions for Performance Analysis

You want to log every transaction with its SQL statements and latency for future transaction performance analysis.

Add a filter with the following definition:

After the filter reads the character '1' from its named pipe, the following is an example log that is generated from the above TPM filter with the above configuration:

Note that 3 and 6 are latencies of each transaction in milliseconds, while 0.165 and 0.123 are latencies of the first statement of each transaction in milliseconds.

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

MaxScale Monitors

Monitors are essential for high availability, tracking the status of backend servers. They detect failures, promote replicas, and enable automatic failover, ensuring service continuity.

#include <maxscale/modulecmd.hh>

bool my_simple_cmd(const MODULECMD_ARG *argv)
{
    printf("%d arguments given\n", argv->argc);
}

int main(int argc, char **argv)
{
    modulecmd_arg_type_t my_args[] =
    {
        {MODULECMD_ARG_BOOLEAN, "This is a boolean parameter"},
        {MODULECMD_ARG_STRING | MODULECMD_ARG_OPTIONAL, "This is an optional string parameter"}
    };

    // Register the command
    modulecmd_register_command("my_module", "my_command", my_simple_cmd, 2, my_args);

    // Find the registered command
    const MODULECMD *cmd = modulecmd_find_command("my_module", "my_command");

    // Parse the arguments for the command
    const void *arglist[] = {"true", "optional string"};
    MODULECMD_ARG *arg = modulecmd_arg_parse(cmd, arglist, 2);

    // Call the module command
    modulecmd_call_command(cmd, arg);

    // Free the parsed arguments
    modulecmd_arg_free(arg);
    return 0;
}

git clone https://github.com/mariadb-corporation/MaxScale
mkdir build
cd build
../MaxScale/BUILD/install_build_deps.sh
cmake ../MaxScale -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install
sudo ./postinst

$ sudo groupadd maxscale
$ sudo useradd -g maxscale maxscale
$ cd /usr/local
$ sudo tar -xzvf maxscale-x.y.z.OS.tar.gz
$ sudo ln -s maxscale-x.y.z.OS maxscale
$ cd maxscale
$ sudo chown -R maxscale var

[CassandraDB]
type=server
address=192.168.4.28
port=3306

[Cassandra]
type=service
router=readconnroute
router_options=running
servers=CassandraDB
user=maxscale
password=6628C50E07CCE1F0392EDEEB9D1203F3

[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

[PerformanceLogger]
type=filter
module=tpmfilter
delimiter=:::
query_delimiter=@@@
filename=/var/logs/tpm/perf.log
named_pipe=/tmp/tpmfilter

[Product-Service]
type=service
router=readconnroute
servers=server1
user=myuser
password=mypasswd
filters=PerformanceLogger

1484086477::::server1::::root::::3::::0.165@@@@0.108@@@@0.102@@@@0.092@@@@0.121@@@@0.122@@@@0.110@@@@2.081::::UPDATE WAREHOUSE SET W_YTD = W_YTD + 3630.48  WHERE W_ID = 2 @@@@SELECT W_STREET_1, W_STREET_2, W_CITY, W_STATE, W_ZIP, W_NAME FROM WAREHOUSE WHERE W_ID = 2@@@@UPDATE DISTRICT SET D_YTD = D_YTD + 3630.48 WHERE D_W_ID = 2 AND D_ID = 9@@@@SELECT D_STREET_1, D_STREET_2, D_CITY, D_STATE, D_ZIP, D_NAME FROM DISTRICT WHERE D_W_ID = 2 AND D_ID = 9@@@@SELECT C_FIRST, C_MIDDLE, C_LAST, C_STREET_1, C_STREET_2, C_CITY, C_STATE, C_ZIP, C_PHONE, C_CREDIT, C_CREDIT_LIM, C_DISCOUNT, C_BALANCE, C_YTD_PAYMENT, C_PAYMENT_CNT, C_SINCE FROM CUSTOMER WHERE C_W_ID = 2 AND C_D_ID = 9 AND C_ID = 1025@@@@UPDATE CUSTOMER SET C_BALANCE = 1007749.25, C_YTD_PAYMENT = 465215.47, C_PAYMENT_CNT = 203 WHERE C_W_ID = 2 AND C_D_ID = 9 AND C_ID = 1025@@@@INSERT INTO HISTORY (H_C_D_ID, H_C_W_ID, H_C_ID, H_D_ID, H_W_ID, H_DATE, H_AMOUNT, H_DATA)  VALUES (9,2,1025,9,2,'2017-01-10 17:14:37',3630.48,'locfljbe    xtnfqn')
1484086477::::server1::::root::::6::::0.123@@@@0.087@@@@0.091@@@@0.098@@@@0.078@@@@0.106@@@@0.094@@@@0.074@@@@0.089@@@@0.073@@@@0.098@@@@0.073@@@@0.088@@@@0.072@@@@0.087@@@@0.071@@@@0.085@@@@0.078@@@@0.088@@@@0.098@@@@0.081@@@@0.076@@@@0.082@@@@0.073@@@@0.077@@@@0.070@@@@0.105@@@@0.093@@@@0.088@@@@0.089@@@@0.087@@@@0.087@@@@0.086@@@@1.883::::SELECT C_DISCOUNT, C_LAST, C_CREDIT, W_TAX  FROM CUSTOMER, WAREHOUSE WHERE W_ID = 2 AND C_W_ID = 2 AND C_D_ID = 10 AND C_ID = 1267@@@@SELECT D_NEXT_O_ID, D_TAX FROM DISTRICT WHERE D_W_ID = 2 AND D_ID = 10 FOR UPDATE@@@@UPDATE DISTRICT SET D_NEXT_O_ID = D_NEXT_O_ID + 1 WHERE D_W_ID = 2 AND D_ID = 10@@@@INSERT INTO OORDER (O_ID, O_D_ID, O_W_ID, O_C_ID, O_ENTRY_D, O_OL_CNT, O_ALL_LOCAL) VALUES (286871, 10, 2, 1267, '2017-01-10 17:14:37', 7, 1)@@@@INSERT INTO NEW_ORDER (NO_O_ID, NO_D_ID, NO_W_ID) VALUES ( 286871, 10, 2)@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 24167@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 24167 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 96982@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 96982 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 40679@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 40679 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 31459@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 31459 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 6143@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 6143 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 12001@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 12001 AND S_W_ID = 2 FOR UPDATE@@@@SELECT I_PRICE, I_NAME , I_DATA FROM ITEM WHERE I_ID = 40407@@@@SELECT S_QUANTITY, S_DATA, S_DIST_01, S_DIST_02, S_DIST_03, S_DIST_04, S_DIST_05,        S_DIST_06, S_DIST_07, S_DIST_08, S_DIST_09, S_DIST_10 FROM STOCK WHERE S_I_ID = 40407 AND S_W_ID = 2 FOR UPDATE@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,1,24167,2,7,348.31998,'btdyjesowlpzjwnmxdcsion')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,2,96982,2,1,4.46,'kudpnktydxbrbxibbsyvdiw')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,3,40679,2,7,528.43,'nhcixumgmosxlwgabvsrcnu')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,4,31459,2,9,341.82,'qbglbdleljyfzdpfbyziiea')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,5,6143,2,3,152.67,'tmtnuupaviimdmnvmetmcrc')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,6,12001,2,5,304.3,'ufytqwvkqxtmalhenrssfon')@@@@INSERT INTO ORDER_LINE (OL_O_ID, OL_D_ID, OL_W_ID, OL_NUMBER, OL_I_ID, OL_SUPPLY_W_ID,  OL_QUANTITY, OL_AMOUNT, OL_DIST_INFO) VALUES (286871,10,2,7,40407,2,1,30.32,'hvclpfnblxchbyluumetcqn')@@@@UPDATE STOCK SET S_QUANTITY = 65 , S_YTD = S_YTD + 7, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 24167 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 97 , S_YTD = S_YTD + 1, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 96982 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 58 , S_YTD = S_YTD + 7, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 40679 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 28 , S_YTD = S_YTD + 9, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 31459 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 86 , S_YTD = S_YTD + 3, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 6143 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 13 , S_YTD = S_YTD + 5, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 12001 AND S_W_ID = 2@@@@UPDATE STOCK SET S_QUANTITY = 44 , S_YTD = S_YTD + 1, S_ORDER_CNT = S_ORDER_CNT + 1, S_REMOTE_CNT = S_REMOTE_CNT + 0  WHERE S_I_ID = 40407 AND S_W_ID = 2
...

$ maxctrl --secure \
   --user=admin \
   --password=mariadb \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   create user "maxscale_rest_admin" "maxscale_rest_admin_password" --type=admin

$ maxctrl --secure \
   --user=maxscale_rest_admin \
   --password=maxscale_rest_admin_password \
   --hosts=192.0.2.100:8443
   --tls-key=/certs/client-key.pem \
   --tls-cert=/certs/client-cert.pem \
   --tls-ca-cert=/certs/ca.pem \
   destroy user "admin"

[split-router]
type                     = service
router                   = readwritesplit
...
causal_reads             = local
causal_reads_timeout     = 15
The unit for the causal_reads_timeout parameter is seconds, and the default value is 10.

[split-router]
type                     = service
router                   = readwritesplit
...
causal_reads             = ON
causal_reads_timeout     = 15
The unit for the causal_reads_timeout parameter is seconds, and the default value is 10.

CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.columns_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.procs_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.proxies_priv TO 'maxscale'@'%';
GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';

SHOW GRANTS FOR 'jdoe'@'client-host';
+-----------------------------------------------------------------------+
| Grants for jdoe@client-host                                           |
+-----------------------------------------------------------------------+
| GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'client-host'   |
+-----------------------------------------------------------------------+
1 row in set (0.01 sec)

% sudo maxctrl list services

┌──────────────────┬────────────────┬─────────────┬───────────────────┬───────────────────────────┐
│ Service          │ Router         │ Connections │ Total Connections │ Servers                   │
├──────────────────┼────────────────┼─────────────┼───────────────────┼───────────────────────────┤
│ Splitter-Service │ readwritesplit │ 1           │ 1                 │ dbserv1, dbserv2, dbserv3 │
└──────────────────┴────────────────┴─────────────┴───────────────────┴───────────────────────────┘

% sudo maxctrl list servers

┌─────────┬─────────────┬──────┬─────────────┬─────────────────┬───────────┐
│ Server  │ Address     │ Port │ Connections │ State           │ GTID      │
├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤
│ dbserv1 │ 192.168.2.1 │ 3306 │ 0           │ Master, Running │ 0-3000-62 │
├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤
│ dbserv2 │ 192.168.2.2 │ 3306 │ 0           │ Slave, Running  │ 0-3000-62 │
├─────────┼─────────────┼──────┼─────────────┼─────────────────┼───────────┤
│ dbserv3 │ 192.168.2.3 │ 3306 │ 0           │ Slave, Running  │ 0-3000-62 │
└─────────┴─────────────┴──────┴─────────────┴─────────────────┴───────────┘

% sudo maxctrl list listeners Splitter-Service

┌───────────────────┬──────┬──────┬─────────┐
│ Name              │ Port │ Host │ State   │
├───────────────────┼──────┼──────┼─────────┤
│ Splitter-Listener │ 3306 │      │ Running │
└───────────────────┴──────┴──────┴─────────┘

MaxScale Trial

With the release of MaxScale 25.01 under a proprietary license, MariaDB has introduced MaxScale Trial, a free version that lets users explore the latest GA features in 24-hour increments, up to one week from install. MaxScale Trial offers limited performance capacity, providing a hands-on way to evaluate MaxScale’s capabilities before committing to an enterprise subscription

Installing MaxScale Trial

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

Before starting MaxScale, the database users needed by MaxScale must be created.

Database Users used by MaxScale

MaxScale needs two database users for its own use; one user used by a MaxScale service for fetching user account information and another user used by the MaxScale monitor 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.

CREATE USER 'service_user'@'%' IDENTIFIED BY 'service_pw';
GRANT SELECT ON mysql.user TO 'service_user'@'%';
GRANT SELECT ON mysql.db TO 'service_user'@'%';
GRANT SELECT ON mysql.tables_priv TO 'service_user'@'%';
GRANT SELECT ON mysql.columns_priv TO 'service_user'@'%';
GRANT SELECT ON mysql.procs_priv TO 'service_user'@'%';
GRANT SELECT ON mysql.proxies_priv TO 'service_user'@'%';
GRANT SELECT ON mysql.roles_mapping TO 'service_user'@'%';
GRANT SHOW DATABASES ON *.* TO 'service_user'@'%';

Monitor User

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

CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'monitor_pw';
GRANT ALL ON *.* TO 'monitor_user'@'%';

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

Starting MaxScale Trial

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

sudo service maxscale start

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

cat /var/log/maxscale/maxscale.log

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

maxctrl list servers

and with the following command that the service is running

maxctrl list services

After that the web-browser can be pointed to http://127.0.0.1:8989. Logging in is done using the username admin and the password mariadb.

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

admin_host=0.0.0.0

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

Limitations of MaxScale Trial

Apart from the following limitations, MaxScale Trial is identical to MaxScale.

#filters

#servers

#services

#connections

Capture

Capture size limited to 10MB and capture duration to 5 minutes.

Process lifetime

24 hours after which the MaxScale Trial process will exit.

Trial period

1 week from installation date.

At startup, if any of the limitations on the number of filters, servers or services is exceeded, MaxScale will not start and an error like the following will be logged:

2025-03-25 12:17:34   error  : (Read-Only-Service); The maximum limit of 1 services in MaxScale Trial has been reached. If insufficient, consider upgrading to MaxScale Enterprise: https://mariadb.com/maxscale-contact/
2025-03-25 12:17:34   error  : (Read-Only-Service); Service 'Read-Only-Service' creation failed.
2025-03-25 12:17:34   error  : 1 errors were encountered while processing configuration.
2025-03-25 12:17:34   alert  : Failed to process the MaxScale configuration file /etc/maxscale.cnf.

If the limit is exceeded at runtime with maxctrl, the operation will fail with an error like the following:

maxctrl create service Read-Only-Service router=readconnroute user=service_users
Error: Server at http://127.0.0.1:8989 responded with 400 Bad Request to `POST services`
{
    "errors": [
        {
            "detail": "The maximum limit of 1 services in MaxScale Trial has been reached. If insufficient, consider upgrading to MaxScale Enterprise: https://mariadb.com/maxscale-contact/"
        },
        {
            "detail": "Could not create service 'Read-Only-Service' with module 'router=readconnroute'"
        }
    ]
}

If the limit is exceeded at runtime using MaxGUI, the operation will fail with the following error message.

If the connection limit is exceeded, the connection attempt will fail, and note that no error message will be displayed.

An attempt to explicitly raise max_connections beyond the maximum of 15, will prevent MaxScale from running at startup and at runtime fail with a runtime error.

If the configured capture size or duration exceeds the maximum limit of MaxScale Trial, the value will be adjusted down to the allowed maximum value and an error will be logged.

Upgrading to MaxScale

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

Uninstall MaxScale Trial.
Install MaxScale 25.01 or higher.

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

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

MaxScale configurations are not guaranteed to work in MaxScale Trial as MaxScale Trial has restrictions based on the documented limitations above which would block startup.\

MaxScale Binlog Filter

Binlog Filter

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.

Settings

`match`

Type: regex
Mandatory: No
Dynamic: Yes
Default: None

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

`exclude`

Type: regex
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 PCRE2 api documentation 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.

`rewrite_src`

Type: regex
Mandatory: No
Dynamic: Yes
Default: None

See the next entry, rewrite_dest, for more information.

`rewrite_dest`

Type: regex
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.

Example Configuration

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.

[BinlogFilter]
type=filter
module=binlogfilter
match=/customers[.]/
exclude=/[.]orders/

[BinlogServer]
type=service
router=binlogrouter
server_id=33
filters=BinlogFilter

[BinlogListener]
type=listener
service=BinlogServer
port=4000

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

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

Securing Your MaxScale Deployment

There are five main components that you need to make sure are completed before you go into production:

Encrypting Plaintext Passwords
Securing the GUI Interface
Managing Users & Passwords
Enabling Audit Logging
Encrypting Database Connections

Encrypting Plaintext Passwords

Ensuring the security of your MaxScale setup involves stringent control over the key file permissions. Utilizing is an effective approach to generate a secure key file.

This generates a keyfile in /var/lib/maxscale

See for more information about maxkeys.

Once generated, this key file can be relocated to a secure location. This key file serves a dual purpose: it enables the encryption of passwords and facilitates MaxScale in decrypting those encrypted passwords.

To maintain confidentiality, it is crucial to adjust the ownership and permissions of the key file appropriately using chown. This step ensures that the key file remains secure and inaccessible to unauthorized users.

Following the secure setup of the key file, you can proceed to encrypt the plaintext passwords of users already created in your databases.

These encrypted passwords can then replace the plaintext passwords in your MaxScale configuration (CNF) files. This enhances the overall security of your database system by reducing the risk that passwords are accidentally shared.

Securing the GUI Interface

To enhance the security of your MaxScale environment, it’s crucial to configure the GUI host address properly. The default setting, 0.0.0.0, allows unrestricted access from any network, which poses a significant security risk. Instead, you should set the admin_host to a more secure address. Additionally, you can change the default port (8989) to another port for added security. For example, you can restrict access to the localhost by setting:

Alternatively, you can specify an internal network IP address to limit access within your internal network, such as:

If you need to allow external access, ensure that the network is adequately secured and that only authorized users can access the MaxScale interface. Consult with your network administrator to determine the most appropriate and secure configuration.

Enabling TLS Encryption

To further secure your MaxScale setup, enable TLS encryption for data in transit. Follow these steps to configure SSL:

1. Set Up SSL Keys and Certificates:

Generate SSL keys and certificates. See
Add them to the MaxScale configuration file.

2. Update the MaxScale Configuration:

Enable secure connections by setting admin_secure_gui to true.
Specify the paths to the SSL certificate and key files in your CNF file:

3. Verify Encryption:

Use the Maxctrl command to verify that TLS encryption is functioning correctly:

4. Update Default Credentials:

It’s essential to change the default admin passwords. Create a new user with a strong password and remove the default admin user for enhanced security.

Managing Users & Passwords

MaxScale allows you to manage user access to its GUI, offering different permission levels to suit various operational needs. Currently, MaxScale supports two primary roles: admin and basic. This functionality is particularly useful for organizations with hierarchical structures or distinct departments, enabling you to grant status view access without allowing execution or manipulation capabilities.

Creating and Deleting Users

To create or delete users in the MaxScale GUI, you can use the maxctrl command. Here’s an example of creating a user with administrative privileges:

To remove an existing user, such as the default admin user, you can use the following command:

Managing Users in the GUI

The MaxScale GUI also provides functionality to manage user access and update the admin password. Through the GUI, you can:

Add Users: Create users with basic or admin access.
Modify User Permissions: Change roles as needed to adapt to evolving security requirements.
Update Admin Password: Enhance security by regularly updating the admin password.

By leveraging these features, you can ensure that your MaxScale environment remains secure and that user access is appropriately managed according to your organization’s needs.

Enabling Audit Logging

Turn on admin auditing to log all login, connection, and configuration changes. Choose an audit file location and set up log rotation.

Enabling and Managing Admin Auditing in MaxScale

Admin auditing in MaxScale provides comprehensive tracking of all administrative activities, including logins, connections, and modifications. These activities are recorded in an audit file for enhanced security and traceability.

To enable admin auditing, add the following configuration to your MaxScale configuration file:

This configuration activates auditing and specifies the location of the audit file. Ensure that the specified directory exists before restarting MaxScale.

Setting Up and Managing Audit Logs

1. Enable Auditing:

Add the configuration lines to your MaxScale configuration file.
Verify the directory specified in admin_audit_file exists.

2. Audit File Management:

Implement log rotation to manage the size and number of audit files. This can be achieved using standard Linux log rotation tools. See

For manual log rotation, you can use the following MaxCtrl command:

Encrypting Database Connections

Configuring SSL Encryption for MaxScale with an Encrypted MariaDB Server

If you have already implemented encryption on your MariaDB server, it’s crucial to extend this encryption configuration to MaxScale to ensure secure communication. Once encryption is enabled on your MariaDB server, follow these steps to configure MaxScale to utilize SSL.

Steps to Configure SSL in MaxScale:

1. Enable SSL:

Add ssl=true to each server section in your MaxScale configuration file.

2. Verify Peer Certificates:

Add ssl_verify_peer_certificate=true to ensure that MaxScale verifies the server’s SSL certificates, providing an additional layer of security.

Your MaxScale configuration file should look something like this:

These settings instruct MaxScale to use SSL for connections to the MariaDB server and to verify peer certificates, enhancing the security of data in transit.

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

Authentication Modules

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

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

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 andauth_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 and roles_mapping. The user should also have the SHOW DATABASES-grant.

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:

Duplicate user accounts. For every user account with a restricted hostname an equivalent user account for MaxScale is added ('alice'@'maxscale-ip').
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 totest_ 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 thetest_.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 withjdoe@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. Usinglower_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}

MaxScale Ed25519 Authenticator

Ed25519 Authenticator

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

Configuration

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

MaxScale will now authenticate 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.

`ed_mode`

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.

`ed_rsa_privkey_path` and `ed_rsa_pubkey_path`

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.

Using a mapping file

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:

Using sha256-authentication

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 keyfiles can be generated with OpenSSL using the following commands.

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

MaxScale LDI Filter

LDI Filter

The ldi (LOAD DATA INFILE) filter was introduced in MaxScale 23.08.0 and it extends the MariaDB LOAD DATA INFILE syntax to support loading data from any object storage that supports the S3 API. This includes cloud offerings like AWS S3 and Google Cloud Storage as well as locally run services like Minio.

If the filename starts with either S3:// or gs://, the path is interpreted as a S3 object file. The prefix is case-insensitive. For example, the following command would load the file my-data.csv from the bucket my-bucket into the table t1.

How to Upload Data

Here is a minimal configuration for the filter that can be used to load data from AWS S3:

The first step is to move the file to be loaded into the same region that MaxScale and the MariaDB servers are in. One factor in the speed of the upload is the network latency and minimizing it by moving the source and the destination closer improves the data loading speed.

The next step is to connect to MaxScale and prepare the session for an upload by providing the service account access and secret keys.

Once the credentials are configured, the data loading can be started:

Data Uploads with MariaDB Xpand

This feature has been removed in MaxScale 24.02.

Common Problems With Data Loading

Missing Files

If you are using self-hosted object storage programs like Minio, a common problem is that they do not necessarily support the newer virtual-hosted-style requests that is used by AWS. This usually manifests as an error either about a missing file or a missing bucket.

If the host parameter is set to a hostname, it's assumed that the object storage supports the newer virtual-hosted-style requests. If this not the case, the filter must be configured with protocol_version=1.

Conversely, if the host parameter is set to a plain IP address, it is assumed that it does not support the newer virtual-hosted-style request. If the host does support it, the filter must be configured with protocol_version=2.

Settings

`key`

Type: string
Mandatory: No
Dynamic: Yes

The S3 access key used to perform all requests to it.

This must be either configured in the MaxScale configuration file or set withSET @maxscale.ldi.s3_key='<key>' before starting the data load.

`secret`

Type: string
Mandatory: No
Dynamic: Yes

The S3 secret key used to perform all requests to it.

This must be either configured in the MaxScale configuration file or set withSET @maxscale.ldi.s3_secret='<secret>' before starting the data load.

`region`

Type: string
Mandatory: No
Dynamic: Yes
Default: us-east-1

The S3 region where the data is located.

The value can be overridden with SET @maxscale.ldi.s3_region='<region>' before starting the data load.

`host`

Type: string
Mandatory: No
Dynamic: Yes
Default: s3.amazonaws.com

The location of the S3 object storage. By default the original AWS S3 host is used. The corresponding value for Google Cloud Storage isstorage.googleapis.com.

The value can be overridden with SET @maxscale.ldi.s3_host='<host>' before starting the data load.

`port`

Type: integer
Mandatory: No
Dynamic: Yes
Default: 0

The port on which the S3 object storage is listening. If unset or set to the value of 0, the default S3 port is used.

The value can be overridden with SET @maxscale.ldi.s3_port=<port> before starting the data load. Note that unlike the other values, the value for this variable must be an SQL integer and not an SQL string.

`no_verify`

Type:
Mandatory: No
Dynamic: Yes
Default: false

If set to true, TLS certificate verification for the object storage is skipped.

`use_http`

Type:
Mandatory: No
Dynamic: Yes
Default: false

If set to true, communication with the object storage is done unencrypted using HTTP instead of HTTPS.

`protocol_version`

Type: integer
Mandatory: No
Dynamic: Yes
Default: 0
Values: 0, 1, 2

Which protocol version to use. By default the protocol version is derived from the value of host but this automatic protocol version deduction will not always produce the correct result. For the legacy path-style requests used by older S3 storage buckets, the value must be set to 1. All new buckets use the protocol version 2.

For object storage programs like Minio, the value must be set to 1 as the bucket name cannot be resolved via the subdomain like it is done for object stores in the cloud.

`import_user`

This parameter has been removed in MaxScale 24.02.

`import_password`

This parameter has been removed in MaxScale 24.02.

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

CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'maxscale-password';
GRANT SELECT ON mysql.user TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.db TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.columns_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.procs_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.proxies_priv TO 'maxscale'@'maxscalehost';
GRANT SELECT ON mysql.roles_mapping TO 'maxscale'@'maxscalehost';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'maxscalehost';

{
    "user_map": [
        {
            "original_user": "alpha",
            "mapped_user": "beta"
        },
        {
            "original_user": "gamma",
            "mapped_user": "gamma"
        }
    ],
    "server_credentials": [
        {
            "mapped_user": "beta",
            "password": "hunter2",
            "plugin": "mysql_native_password"
        },
        {
            "mapped_user": "gamma",
            "password": "letmein",
            "plugin": "ed25519"
        }
    ]
}

[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519auth
authenticator_options=ed_mode=sha256
ssl=true
ssl_key=/tmp/my-key.pem
ssl_cert=/tmp/my-cert.pem
ssl_ca=/tmp/myCA.pem

[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=ed25519auth
authenticator_options=ed_mode=sha256,
 ed_rsa_privkey_path=/tmp/sha_private_key.pem,
 ed_rsa_pubkey_path=/tmp/sha_public_key.pem

Avrorouter Tutorial

This tutorial is a short introduction to the Avrorouter, how to set it up and how it interacts with the binlogrouter.

The first part configures the services and sets them up for the binary log to Avro file conversion. The second part of this tutorial uses the client listener interface for the avrorouter and shows how to communicate with the service over the network.

Configuration

Preparing the primary server

The primary server where we will be replicating from needs to have binary logging enabled, binlog_format set to row and binlog_row_image set tofull. These can be enabled by adding the two following lines to the my.cnf file of the primary.

binlog_format=row
binlog_row_image=full

You can find out more about replication formats from the

Configuring MaxScale

We start by adding two new services into the configuration file. The first service is the binlogrouter service which will read the binary logs from the primary server. The second service will read the binlogs as they are streamed from the primary and convert them into Avro format files.

# The Replication Proxy service
[replication-service]
type=service
router=binlogrouter
server_id=4000
master_id=3000
filestem=binlog
user=maxuser
password=maxpwd

# The Avro conversion service
[avro-service]
type=service
router=avrorouter
source=replication-service
filestem=binlog
start_index=15

# The listener for the replication-service
[replication-listener]
type=listener
service=replication-service
port=3306

# The client listener for the avro-service
[avro-listener]
type=listener
service=avro-service
protocol=CDC
port=4001

The source parameter in the avro-service points to the replication-service we defined before. This service will be the data source for the avrorouter. Thefilestem is the prefix in the binlog files and start_index is the binlog number to start from. With these parameters, the avrorouter will start reading events from binlog binlog.000015.

Note that the filestem and start_index must point to the file that is the first binlog that the binlogrouter will replicate. For example, if the first file you are replicating is my-binlog-file.001234, set the parameters tofilestem=my-binlog-file and start_index=1234.

For more information on the avrorouter options, read the Avrorouter Documentation.

Preparing the data in the primary server

Before starting the MaxScale process, we need to make sure that the binary logs of the primary server contain the DDL statements that define the table layouts. What this means is that the CREATE TABLE statements need to be in the binary logs before the conversion process is started.

If the binary logs contain data modification events for tables that aren't created in the binary logs, the Avro schema of the table needs to be manually created. There are multiple ways to do this:

Dump the database to a replica, configure it to replicate from the primary and point MaxScale to this replica (this is the recommended method as it requires no extra steps)
Use the cdc_schema Go utility and copy the generated .avsc files to the avrodir
Use the Python version of the schema generator and copy the generated .avsc files to the avrodir

If you used the schema generator scripts, all Avro schema files for tables that are not created in the binary logs need to be in the location pointed to by theavrodir parameter. The files use the following naming:<database>.<table>.<schema_version>.avsc. For example, the schema file name of the test.t1 table would be test.t1.0000001.avsc.

Starting MariaDB MaxScale

The next step is to start MariaDB MaxScale and set up the binlogrouter. We do that by connecting to the MySQL listener of the replication_router service and executing a few commands.

CHANGE MASTER TO MASTER_HOST='172.18.0.1',
       MASTER_PORT=3000,
       MASTER_LOG_FILE='binlog.000015',
       MASTER_LOG_POS=4,
       MASTER_USER='maxuser',
       MASTER_PASSWORD='maxpwd';

START SLAVE;

NOTE: GTID replication is not currently supported and file-and-position replication must be used.

This will start the replication of binary logs from the primary server at 172.18.0.1 listening on port 3000. The first file that the binlogrouter replicates is binlog.000015. This is the same file that was configured as the starting file in the avrorouter.

For more details about the SQL commands, refer to the Binlogrouter documentation.

After the binary log streaming has started, the avrorouter will automatically start processing the binlogs.

Creating and Processing Data

Next, create a simple test table and populated it with some data by executing the following statements.

CREATE TABLE test.t1 (id INT);
INSERT INTO test.t1 VALUES (1), (2), (3), (4), (5), (6), (7), (8), (9), (10);

To use the cdc.py command line client to connect to the CDC service, we must first create a user. This can be done via maxctrl by executing the following command.

maxctrl call command cdc add_user avro-service maxuser maxpwd

This will create the maxuser:maxpwd credentials which can then be used to request a JSON data stream of the test.t1 table that was created earlier.

cdc.py -u maxuser -p maxpwd -h 127.0.0.1 -P 4001 test.t1

The output is a stream of JSON events describing the changes done to the database.

{"namespace": "MaxScaleChangeDataSchema.avro", "type": "record", "name": "ChangeRecord", "fields": [{"name": "domain", "type": "int"}, {"name": "server_id", "type": "int"}, {"name": "sequence", "type": "int"}, {"name": "event_number", "type": "int"}, {"name": "timestamp", "type": "int"}, {"name": "event_type", "type": {"type": "enum", "name": "EVENT_TYPES", "symbols": ["insert", "update_before", "update_after", "delete"]}}, {"name": "id", "type": "int", "real_type": "int", "length": -1}]}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 1, "timestamp": 1537429419, "event_type": "insert", "id": 1}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 2, "timestamp": 1537429419, "event_type": "insert", "id": 2}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 3, "timestamp": 1537429419, "event_type": "insert", "id": 3}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 4, "timestamp": 1537429419, "event_type": "insert", "id": 4}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 5, "timestamp": 1537429419, "event_type": "insert", "id": 5}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 6, "timestamp": 1537429419, "event_type": "insert", "id": 6}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 7, "timestamp": 1537429419, "event_type": "insert", "id": 7}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 8, "timestamp": 1537429419, "event_type": "insert", "id": 8}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 9, "timestamp": 1537429419, "event_type": "insert", "id": 9}
{"domain": 0, "server_id": 3000, "sequence": 11, "event_number": 10, "timestamp": 1537429419, "event_type": "insert", "id": 10}

The first record is always the JSON format schema for the table describing the types and names of the fields. All records that follow it represent the changes that have happened on the database.

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

MaxScale Named Server Filter

Named Server Filter

Overview

The namedserverfilter is a MariaDB MaxScale filter module able to route queries to servers based on regular expression (regex) matches. Since it is a filter instead of a router, the NamedServerFilter only sets routing suggestions. It requires a compatible router to be effective. Currently, bothreadwritesplit and hintrouter take advantage of routing hints in the data packets. This filter uses the PCRE2 library for regular expression matching.

Configuration

The filter accepts settings in two modes: legacy and indexed. Only one of the modes may be used for a given filter instance. The legacy mode is meant for backwards compatibility and allows only one regular expression and one server name in the configuration. In indexed mode, up to 25 regex-server pairs are allowed in the form match01 - target01, match02 - target02 and so on. Also, in indexed mode, the server names (targets) may contain a list of names or special tags ->master or ->slave.

All parameters except the deprecated match and target parameters can be modified at runtime. Any modifications to the filter configuration will only affect sessions created after the change has completed.

Below is a configuration example for the filter in indexed-mode. The legacy mode is not recommended and may be removed in a future release. In the example, a SELECT on TableOne (match01) results in routing hints to two named servers, while a SELECT on TableTwo is suggested to be routed to the primary server of the service. Whether a list of server names is interpreted as a route-to-any or route-to-all is up to the attached router. The HintRouter sees a list as a suggestion to route-to-any. For additional information on hints and how they can also be embedded into SQL-queries, see .

Settings

NamedServerFilter requires at least one matchXY - targetXY pair.

`matchXY`

Type:
Mandatory: No
Dynamic: Yes
Default: None

matchXY defines a against which the incoming SQL query is matched. XY must be a number in the range 01 - 25. Each match-setting pairs with a similarly indexed target-setting. If one is defined, the other must be defined as well. If a query matches the pattern, the filter attaches a routing hint defined by the target-setting to the query. Theoptions-parameter affects how the patterns are compiled.

`options`

Type:
Mandatory: No
Dynamic: Yes
Values: ignorecase, case, extended
Default: ignorecase

for matchXY.

`targetXY`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The hint which is attached to the queries matching the regular expression defined bymatchXY. If a compatible router is used in the service the query will be routed accordingly. The target can be one of the following:

a server or service name (adds a HINT_ROUTE_TO_NAMED_SERVER hint)
a list of server names, comma-separated (adds severalHINT_ROUTE_TO_NAMED_SERVER hints)
->master (adds a HINT_ROUTE_TO_MASTER hint)
->slave (adds a HINT_ROUTE_TO_SLAVE hint)
->all (adds a HINT_ROUTE_TO_ALL hint)

The support for service names was added in MaxScale 6.3.2. Older versions of MaxScale did not accept service names in the target parameters.

`source`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This optional parameter defines an IP address or mask which a connecting client's IP address is matched against. Only sessions whose address matches this setting will have this filter active and performing the regex matching. Traffic from other client IPs is simply left as is and routed straight through.

Since MaxScale 2.1 it's also possible to use % wildcards:

Note that using source=% to match any IP is not allowed.

Since MaxScale 2.3 it's also possible to specify multiple addresses separated by comma. Incoming client connections are subsequently checked against each.

`user`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This optional parameter defines a username the connecting client username is matched against. Only sessions that are connected using this username will have the match and routing hints applied to them. Traffic from other users is simply left as is and routed straight through.

Additional remarks

The maximum number of accepted match - target pairs is 25.

In the configuration file, the indexed match and target settings may be in any order and may skip numbers. During SQL-query matching, however, the regexes are tested in ascending order: match01, match02, match03 and so on. As soon as a match is found for a given query, the routing hints are written and the packet is forwarded to the next filter or router. Any remaining match regexes are ignored. This means the match - target pairs should be indexed in priority order, or, if priority is not a factor, in order of decreasing match probability.

Binary-mode prepared statements (COM_STMT_PREPARE) are handled by matching the prepared sql against the match-parameters. If a match is found, the routing hints are attached to any execution of that prepared statement. Text- mode prepared statements are not supported in this way. To divert them, use regular expressions which match the specific "EXECUTE"-query.

Examples

Example 1 - Route queries targeting a specific table to a server

This will route all queries matching the regular expression *from *users to the server named server2. The filter will ignore character case in queries.

A query like SELECT * FROM users would be routed to server2 where as a query like SELECT * FROM accounts would be routed according to the normal rules of the router.

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

MaxScale Lua Filter

Lua Filter

The luafilter is a filter that calls a set of functions in a Lua script.

Read the for information on how to write Lua scripts.

Note: This module is experimental and must be built from source. The module is deprecated in MaxScale 23.08 and might be removed in a future release.

Settings

The luafilter has two parameters. They control which scripts will be called by the filter. Both parameters are optional but at least one should be defined. If both global_script and session_script are defined, the entry points in both scripts will be called.

`global_script`

The global Lua script. The parameter value is a path to a readable Lua script which will be executed.

This script will always be called with the same global Lua state and it can be used to build a global view of the whole service.

`session_script`

The session level Lua script. The parameter value is a path to a readable Lua script which will be executed once for each session.

Each session will have its own Lua state meaning that each session can have a unique Lua environment. Use this script to do session specific tasks.

Lua Script Calling Convention

The entry points for the Lua script expect the following signatures:

nil createInstance(name) - global script only, called when the script is first loaded
- When the global script is loaded, it first executes on a global level before the luafilter calls the createInstance function in the Lua script with the filter's name as its argument.
nil newSession(string, string) - new session is created
- After the session script is loaded, the newSession function in the Lua scripts is called. The first parameter is the username of the client and the second parameter is the client's network address.
nil closeSession() - session is closed
- The closeSession function in the Lua scripts will be called.
(nil | bool | string) routeQuery() - query is being routed
- The Luafilter calls the routeQuery functions of both the session and the global script. The query is passed as a string parameter to the routeQuery Lua function and the return values of the session specific function, if any were returned, are interpreted. If the first value is bool, it is interpreted as a decision whether to route the query or to send an error packet to the client. If it is a string, the current query is replaced with the return value and the query will be routed. If nil is returned, the query is routed normally.
nil clientReply() - reply to a query is being routed
- This function is called with the name of the server that returned the response.
string diagnostic() - global script only, print diagnostic information
- If the Lua function returns a string that is valid JSON, it will be decoded as JSON and displayed as such in the REST API. If the object does not decode into JSON, it will be stored as a JSON string.

These functions, if found in the script, will be called whenever a call to the matching entry point is made.

Script Template

Here is a script template that can be used to try out the luafilter. Copy it into a file and add global_script=<path to script> into the filter configuration. Make sure the file is readable by the maxscale user.

Functions Exposed by the Luafilter

The luafilter exposes the following functions that can be called inside the Lua script API endpoints. The callback function in which they can be called is documented after the function signature. If the functions are called outside of the correct callback function, they raise a Lua error.

string mxs_get_sql() (use: routeQuery)
Returns the SQL of the query being executed. This returns an empty string for any query that is not a text protocol query (COM_QUERY). Support for prepared statements is not yet implemented.
string mxs_get_type_mask() (use: routeQuery)
Returns the type of the current query being executed as a string. The values are the string versions of the query types defined in query_classifier.h are separated by vertical bars (|). This function can only be called from the routeQuery entry point.
string mxs_get_operation() (use: routeQuery)
Returns the current operation type as a string. The values are defined in query_classifier.h. This function can only be called from the routeQuery entry point.
string mxs_get_canonical() (use: routeQuery)
Returns the canonical version of a query by replacing all user-defined constant values with question marks. This function can only be called from the routeQuery entry point.
number mxs_get_session_id() (use: newSession, routeQuery, clientReply, closeSession)
This function returns the session ID of the current session. Inside thecreateInstance and diagnostic endpoints this function will always return the value 0.
string mxs_get_db() (use: newSession, routeQuery, clientReply, closeSession)
Returns the current default database used by the connection.
string mxs_get_user() (use: newSession, routeQuery, clientReply, closeSession)
Returns the username of the client connection.
string mxs_get_host() (use: newSession, routeQuery, clientReply, closeSession)
Returns the address of the client connection.
string mxs_get_replier() (use: clientReply)
Returns the target that returned the result to the latest query.

Example Configuration and Script

Here is a minimal configuration entry for a luafilter definition.

And here is a script that opens a file in /tmp/ and logs output to it.

Limitations

mxs_get_sql() and mxs_get_canonical() do not work with queries done with the binary protocol.
The Lua code is not restricted in any way which means excessively slow execution of it can cause the MaxScale process to become slower or to be aborted due to a SystemD watchdog timeout.

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

[NamedServerFilter]
type=filter
module=namedserverfilter
match01=^Select.*TableOne$
target01=server2,server3
match22=^SELECT.*TableTwo$
target22=->master

[MyService]
type=service
router=readwritesplit
servers=server1,server2,server3
user=myuser
password=mypasswd
filters=NamedServerFilter

[NamedServerFilter]
type=filter
module=namedserverfilter
match02= *from *users
target02=server2

[MyService]
type=service
router=readwritesplit
servers=server1,server2
user=myuser
password=mypasswd
filters=NamedServerFilter

f = io.open("/tmp/test.log", "a+")

function createInstance(name)
    f:write("createInstance for " .. name .. "\n")
end

function newSession(user, host)
    f:write("newSession for: " .. user .. "@" .. host .. "\n")
end

function closeSession()
    f:write("closeSession\n")
end

function routeQuery()
    f:write("routeQuery: " .. mxs_get_sql() .. " -- type: " .. mxs_qc_get_type_mask() .. " operation: " .. mxs_qc_get_operation() .. "\n")
end

function clientReply()
    f:write("clientReply: " .. mxs_get_replier() .. "\n")
end

function diagnostic()
    f:write("diagnostics\n")
    return "Hello from Lua!"
end

MaxScale Hintfilter

Hintfilter

Hint Syntax
Prepared Statements
- Binary Protocol
- Text Protocol
Examples
- Routing SELECT queries to primary

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

Hint body

All hints must start with the maxscale tag.

-- maxscale <hint body>

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

Routing destination hints

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

-- maxscale route to [master | slave | server <server name>]

Route to primary

-- maxscale route to master

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

-- maxscale route to slave

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

-- maxscale route to server <server name>

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

-- maxscale route to last

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

-- maxscale <param>=<value>

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.

Hint stack

Hints can be either single-use hints, which makes them affect only one query, or named hints, which can be pushed on and off a stack of active hints.

Defining named hints:

-- maxscale <hint name> prepare <hint content>

Pushing a hint onto the stack:

-- maxscale <hint name> begin

Popping the topmost hint off the stack:

-- maxscale end

You can define and activate a hint in a single command using the following:

-- maxscale <hint name> begin <hint content>

You can also push anonymous hints onto the stack which are only used as long as they are on the stack:

-- maxscale begin <hint content>

Prepared Statements

The hintfilter supports routing hints in prepared statements for both thePREPARE and EXECUTE SQL commands as well as the binary protocol prepared statements.

Binary Protocol

With binary protocol prepared statements, a routing hint in the prepared statement is applied to the execution of the statement but not the preparation of it. The preparation of the statement is routed normally and is sent to all servers.

For example, when the following prepared statement is prepared with the MariaDB Connector-C function mariadb_stmt_prepare and then executed withmariadb_stmt_execute the result is always returned from the primary:

SELECT user FROM accounts WHERE id = ? -- maxscale route to master

Support for binary protocol prepared statements was added in MaxScale 6.0 (MXS-2838).

The protocol commands that the routing hints are applied to are:

COM_STMT_EXECUTE
COM_STMT_BULK_EXECUTE
COM_STMT_SEND_LONG_DATA
COM_STMT_FETCH
COM_STMT_RESET

Support for direct execution of prepared statements was added in MaxScale 6.2.0. For example the MariaDB Connector-C uses direct execution whenmariadb_stmt_execute_direct is used.

Text Protocol

Text protocol prepared statements (i.e. the PREPARE and EXECUTE SQL commands) behave differently. If a PREPARE command has a routing hint, it will be routed according to the routing hint. Any subsequent EXECUTE command will not be affected by the routing hint in the PREPARE statement. This means they must have their own routing hints.

The following example is the recommended method of executing text protocol prepared statements with hints:

PREPARE my_ps FROM 'SELECT user FROM accounts WHERE id = ?';
EXECUTE my_ps USING 123; -- maxscale route to master

The PREPARE is routed normally and will be routed to all servers. TheEXECUTE will be routed to the primary as a result of it having the route to master hint.

Examples

Routing `SELECT` queries to primary

In this example, MariaDB MaxScale is configured with the readwritesplit router and the hint filter.

[ReadWriteService]
type=service
router=readwritesplit
servers=server1,server2
user=maxuser
password=maxpwd
filters=Hint

[Hint]
type=filter
module=hintfilter

Behind MariaDB MaxScale is a primary server and a replica server. If there is replication lag between the primary and the replica, read queries sent to the replica might return old data. To guarantee up-to-date data, we can add a routing hint to the query.

INSERT INTO table1 VALUES ("John","Doe",1);
SELECT * FROM table1; -- maxscale route to master

The first INSERT query will be routed to the primary. The following SELECT query would normally be routed to the replica but with the added routing hint it will be routed to the primary. This way we can do an INSERT and a SELECT right after it and still get up-to-date data.

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

SET SESSION autocommit=OFF;
SELECT * FROM hq_sales.invoices WHERE branch_id=1;
INSERT INTO hq_sales.invoices
   (customer_id, invoice_date, invoice_total, payment_method)
VALUES
   (1, '2020-05-10 12:35:10', 1087.23, 'CREDIT_CARD');
COMMIT;

BEGIN;
SELECT * FROM hq_sales.invoices WHERE branch_id=1;
INSERT INTO hq_sales.invoices
   (customer_id, invoice_date, invoice_total, payment_method)
VALUES
   (1, '2020-05-10 12:35:10', 1087.23, 'CREDIT_CARD');
COMMIT;

Galera Monitor

Overview

The Galera Monitor is a monitoring module for MaxScale that monitors a Galera cluster. It detects whether nodes are a part of the cluster and if they are in sync with the rest of the cluster. It can also assign primary and replica roles inside MaxScale, allowing Galera clusters to be used with modules designed for traditional primary-replica clusters.

By default, the Galera Monitor will choose the node with the lowestwsrep_local_index value as the primary. This will mean that two MaxScales running on different servers will choose the same server as the primary.

WSREP Variables and Their Effects

The following WSREP variables are inspected by galeramon to see whether a node is usable. If the node is not usable, it loses the Master and Slave labels and will be in the Running state.

If wsrep_ready=0, the WSREP system is not yet ready and the Galera node cannot accept queries.
If wsrep_desync=1 is set, the node is desynced and is not participating in the Galera replication.
If wsrep_reject_queries=[ALL|ALL_KILL] is set, queries are refused and the node is unusable.
With wsrep_sst_donor_rejects_queries=1, donor nodes reject queries. Galeramon treats this the same as if wsrep_reject_queries=ALL was set.
If wsrep_local_state is not 4 (or 2 with available_when_donor=true), the node is not in the correct state and is not used.

Galera clusters and replicas replicating from it

MaxScale 2.4.0 added support for replicas replicating off of Galera nodes. If a non-Galera server monitored by galeramon is replicating from a Galera node also monitored by galeramon, it will be assigned the Slave, Running status as long as the replication works. This allows read-scaleout with Galera servers without increasing the size of the Galera cluster.

Required Grants

The Galera Monitor requires the REPLICA MONITOR grant to work:

CREATE USER 'maxscale'@'maxscalehost' IDENTIFIED BY 'maxscale-password';
GRANT REPLICA MONITOR ON *.* TO 'maxscale-user'@'maxscalehost';

With MariaDB Server 10.4 and earlier, REPLICATION CLIENT is required instead.

GRANT REPLICATION CLIENT ON *.* TO 'maxscale-user'@'maxscalehost';

If set_donor_nodes is configured, the SUPER grant is required:

GRANT SUPER ON *.* TO 'maxscale'@'maxscalehost';

Configuration

A minimal configuration for a monitor requires a set of servers for monitoring and a username and a password to connect to these servers. The user requires the REPLICATION CLIENT privilege to successfully monitor the state of the servers.

[Galera-Monitor]
type=monitor
module=galeramon
servers=server1,server2,server3
user=myuser
password=mypwd

Common Monitor Settings

For a list of optional parameters that all monitors support, read the Monitor Common document.

Settings

These are optional parameters specific to the Galera Monitor.

`disable_master_failback`

Type: boolean
Default: false
Dynamic: Yes

If a node marked as primary inside MaxScale happens to fail and the primary status is assigned to another node MaxScale will normally return the primary status to the original node after it comes back up. With this option enabled, if the primary status is assigned to a new node it will not be reassigned to the original node for as long as the new primary node is running. In this case theMaster Stickiness status bit is set which will be visible in themaxctrl list servers output.

`available_when_donor`

Type: boolean
Default: false
Dynamic: Yes

This option allows Galera nodes to be used normally when they are donors in an SST operation when the SST method is non-blocking (e.g. wsrep_sst_method=mariadb-backup).

Normally when an SST is performed, both participating nodes lose their Synced,Master or Slave statuses. When this option is enabled, the donor is treated as if it was a normal member of the cluster (i.e. wsrep_local_state = 4). This is especially useful if the cluster drops down to one node and an SST is required to increase the cluster size.

The current list of non-blocking SST methods are xtrabackup, xtrabackup-v2 and mariadb-backup. Read the documentation for more details.

`disable_master_role_setting`

Type: boolean
Default: false
Dynamic: Yes

This disables the assignment of primary and replica roles to the Galera cluster nodes. If this option is enabled, Synced is the only status assigned by this monitor.

`use_priority`

Type: boolean
Default: false
Dynamic: Yes

Enable interaction with server priorities. This will allow the monitor to deterministically pick the write node for the monitored Galera cluster and will allow for controlled node replacement.

`root_node_as_master`

Type: boolean
Default: false
Dynamic: Yes

This option controls whether the write primary Galera node requires awsrep_local_index value of 0. This option was introduced in MaxScale 2.1.0 and it is disabled by default in versions 2.1.5 and newer. In versions 2.1.4 and older, the option was enabled by default.

A Galera cluster will always have a node which has a wsrep_local_index value of 0. Based on this information, multiple MaxScale instances can always pick the same node for writes.

If the root_node_as_master option is disabled for galeramon, the node with the lowest index will always be chosen as the primary. If it is enabled, only the node with a wsrep_local_index value of 0 can be chosen as the primary.

This parameter can work with disable_master_failback but using them together is not advisable: the intention of root_node_as_master is to make sure that all MaxScale instances that are configured to use the same Galera cluster will send writes to the same node. If disable_master_failback is enabled, this is no longer true if the Galera cluster reorganizes itself in a way that a different node gets the node index 0, writes would still be going to the old node that previously had the node index 0. A restart of one of the MaxScales or a new MaxScale joining the cluster will cause writes to be sent to the wrong node, thus resulting in an increasing the rate of deadlock errors and sub-optimal performance.

`set_donor_nodes`

Type: boolean
Default: false
Dynamic: Yes

This option controls whether the global variable wsrep_sst_donor should be set in each cluster node with slave' status. The variable contains a list of replica servers, automatically sorted, with possible primary candidates at its end.

The sorting is based either on wsrep_local_index or node server priority depending on the value of use_priority option. If no server has priority defined the sorting switches to wsrep_local_index. Node names are collected by fetching the result of the variable wsrep_node_name.

Example of variable being set in all replica nodes, assuming three nodes:

SET GLOBAL wsrep_sst_donor = "galera001,galera000"

Note: in order to set the global variable wsrep_sst_donor, proper privileges are required for the monitor user that connects to cluster nodes. This option is disabled by default and was introduced in MaxScale 2.1.0.

Interaction with Server Priorities

If the use_priority option is set and a server is configured with thepriority=<int> parameter, galeramon will use that as the basis on which the primary node is chosen. This requires the disable_master_role_setting to be undefined or disabled. The server with the lowest positive value of priority will be chosen as the primary node when a replacement Galera node is promoted to a primary server inside MaxScale. If all candidate servers have the same priority, the order of the servers in the servers parameter dictates which is chosen as the primary.

Nodes with a negative value (priority < 0) will never be chosen as the primary. This allows you to mark some servers as permanent replicas by assigning a non-positive value into priority. Nodes with the default priority of 0 are only selected if no nodes with higher priority are present and the normal node selection rules apply to them (i.e. selection is based on wsrep_local_index).

Here is an example.

[node-1]
type=server
address=192.168.122.101
port=3306
priority=1

[node-2]
type=server
address=192.168.122.102
port=3306
priority=3

[node-3]
type=server
address=192.168.122.103
port=3306
priority=2

[node-4]
type=server
address=192.168.122.104
port=3306
priority=-1

In this example node-1 is always used as the primary if available. If node-1 is not available, then the next node with the highest priority rank is used. In this case it would be node-3. If both node-1 and node-3 were down, thennode-2 would be used. Because node-4 has a value of -1 in priority, it will never be the primary. Nodes without priority parameter are considered as having a priority of 0 and will be used only if all nodes with a positivepriority value are not available.

With priority ranks you can control the order in which MaxScale chooses the primary node. This will allow for a controlled failure and replacement of nodes.

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

MaxScale 25.01 Limitations and Known Issues within MariaDB MaxScale

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.

Configuration limitations

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.

Multiple MaxScales on same server

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.

Security limitations

MariaDB 10.2

The parser of MaxScale correctly parses WITH statements, but fails to collect columns, functions and tables used in the SELECT defining theWITH clause.

Consequently, the database firewall will not block WITH statements where the SELECT of the WITH clause refers to forbidden columns.

MariaDB Default Values

MaxScale assumes that certain configuration parameters in MariaDB are set to their default values. These include but are not limited to:

autocommit: Autocommit is enabled for all new connections.
tx_read_only: Transactions use READ WRITE permissions by default.

Query Classification

Transaction Boundary Detection

If a module in MaxScale requires tracking of transaction boundaries but does not require query classification, a custom parser is used to detect them. Currently the only situation in which this parser is used is when a readconnroute service uses the cache filter.

The custom parser detects a subset of the full SQL syntax used to start transactions. This means that more complex statements will not be fully parsed and will cause the transaction state to not match the real state on the database. For example, SET @my_var = (SELECT 1), autocommit = 0 is not parsed by the custom parser and causes the autocommit modification to not be noticed.

XA Transactions

MaxScale will treat statements executed after XA START and before XA END as if they were executed in a normal read-write transaction started with START TRANSACTION. This means that only XA transactions in the ACTIVE state will be routed as transactions and all statements after XA END are routed normally.

XA transactions and normal transactions are mutually exclusive in MariaDB. This means that a START TRANSACTION command will fail if the connection already has an open XA transaction. MaxScale currently only inspects the SQL and deduces the transaction state from that. If a transaction fails to start due to an open XA transaction, the state in MaxScale and in MariaDB can be different and MaxScale will keep routing statements as if they were inside of a transaction. However, as this is an unlikely scenario, usually no action needs to be taken.

Prepared Statements

For its proper functioning, MaxScale needs in general to be aware of the transaction state and autocommit mode. In order to be that, MaxScale parses statements going through it.

However, if a transaction is committed or rolled back, or the autocommit mode is changed using a prepared statement, MaxScale will miss that and its internal state will be incorrect, until the transaction state or autocommit mode is changed using an explicit statement.

For instance, after the following sequence of commands, MaxScale will still think autocommit is on:

To ensure that MaxScale functions properly, do not commit or rollback a transaction or change the autocommit mode using a prepared statement.

Protocol limitations

Limitations with MySQL/MariaDB Protocol support (MariaDBClient)

Compression is not included in the server handshake.
If a KILL [CONNECTION] <ID> statement is executed, MaxScale will intercept it. If the ID matches a MaxScale session ID, it will be closed by sending modified KILL commands of the same type to all backend server to which the session in question is connected to. This results in behavior that is similar to how MariaDB does it. If the KILL CONNECTION USER <user> form is given, all connections with a matching username will be closed instead.
MariaDB MaxScale does not support KILL QUERY ID <query_id> type statements. If a query by a query ID is to be killed, it needs to be done directly on the backend databases.
Any KILL commands executed using a prepared statement are ignored by MaxScale. If any are executed, it is highly likely that the wrong connection ends up being killed.
If a KILL connection kills a session that is connected to a readwritesplit service that has transaction_replay or delayed_retry enabled, it is possible that the query is retried even if the connection is killed. To avoid this, use KILL QUERY instead.
A KILL on one service can cause a connection from another service to be closed even if it uses a different protocol.
The change user command (COM_CHANGE_USER) only works with standard authentication.
If a COM_CHANGE_USER succeeds on MaxScale yet fails on the server the session ends up in an inconsistent state. This can happen if the password of the target user is changed and MaxScale uses old user account data when processing the change user. In such a situation, MaxScale and server will disagree on the current user. This can affect e.g. reconnections.

Authenticator limitations

Limitations in the MySQL authenticator (MariaDBAuth)

MySQL old style passwords are not supported. MySQL versions 4.1 and newer use a new authentication protocol which does not support pre-4.1 style passwords.
When users have different passwords based on the host from which they connect MariaDB MaxScale is unable to determine which password it should use to connect to the backend database. This results in failed connections and unusable usernames in MariaDB MaxScale.

Filter limitations

Tee filter limitations (tee)

The Tee filter does not support binary protocol prepared statements. The execution of a prepared statements through a service that uses the tee filter is not guaranteed to succeed on the service where the filter branches to as it does on the original service.

This possibility exists due to the fact that the binary protocol prepared statements are identified by a server-generated ID. The ID sent to the client from the main service is not guaranteed to be the same that is sent by the branch service.

Monitor limitations

A server can only be monitored by one monitor. Two or more monitors monitoring the same server is considered an error.

Limitations with Galera Cluster Monitoring (galeramon)

The default master selection is based only on MIN(wsrep_local_index). This can be influenced with the server priority mechanic described in the manual.

Router limitations

Refer to individual router documentation for a list of their limitations.

ETL Limitations

The ETL feature in MaxScale always uses the MariaDB Connector/ODBC driver to perform the data loading into MariaDB. The recommended minimum version of the connector is 3.1.18. Older versions of the driver suffer from problems that may manifest as crashes or memory leaks. The driver must be installed on the system in order for the ETL feature to work.

The data loading into MariaDB is done with autocommit, unique_checks andforeign_key_checks disabled inside of a single transaction. This is done to leverage the optimizations done for InnoDB that allows faster insertions into empty tables. When loading data into MariaDB versions 10.5 or older, this can translate into long rollback times in case the ETL operation fails.

ETL Limitations with PostgreSQL as the Source

For ETL operations that migrate data from PostgreSQL, we recommend using the official PostgreSQL ODBC driver. Use of other PostgreSQL ODBC drivers is possible but not recommended: correct configuration of the driver is necessary to prevent the driver from consuming too much memory.

Limitations in Automatic SQL Generation

Triggers on tables are not migrated automatically.
Check constraints are defined using the native PostgreSQL syntax. Incompatibilities must be manually fixed.
All indexes specific to PostgreSQL will be converted into normal indexes in MariaDB.
The GEOMETRY type is assumed to be the type provided by PostGIS. It is converted into a MariaDB GEOMETRY type and is extracted using ST_AsText.

ETL Limitations with Generic ODBC Targets

It is the responsibility of the end-user to correctly configure the ODBC driver. Some drivers read the whole resultset into memory by default which will result in MaxScale running out of memory

ETL operations that operate on more than one catalog are not supported.

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

Automatic Failover With MariaDB Monitor

The is not only capable of monitoring the state of a MariaDB primary-replica cluster but is also capable of performing failover and switchover. In addition, in some circumstances it is capable of rejoining a primary that has gone down and later reappears.

Note that the failover (and switchover and rejoin) functionality is only supported in conjunction with GTID-based replication and initially only for simple topologies, that is, 1 primary and several replicas.

The failover, switchover and rejoin functionality are inherent parts of the MariaDB Monitor, but neither automatic failover nor automatic rejoin are enabled by default.

The following examples have been written with the assumption that there are four servers - server1, server2, server3 and server4 - of which server1 is the initial primary and the other servers are replicas. In addition there is a monitor called TheMonitor that monitors those servers.

Somewhat simplified, the MaxScale configuration file would look like:

Manual Failover

If everything is in order, the state of the cluster will look something like this:

If the primary now for any reason goes down, then the cluster state will look like this:

Note that the status for server1 is Down.

Since failover is by default not enabled, the failover mechanism must be invoked manually:

There are quite a few arguments, so let's look at each one separatelycall command indicates that it is a module command that is to be &#xNAN;invoked, mariadbmon indicates the module whose command we want to invoke (that is the MariaDB Monitor),failover is the command we want to invoke, and TheMonitor is the first and only argument to that command, the name of the monitor as specified in the configuration file.

The MariaDB Monitor will now autonomously deduce which replica is the most appropriate one to be promoted to primary, promote it to primary and modify the other replicas accordingly.

If we now check the cluster state we will see that one of the remaining replicas has been made into primary.

If server1 now reappears, it will not be rejoined to the cluster, as shown by the following output:

Had auto_rejoin=true been specified in the monitor section, then an attempt to rejoin server1 would have been made.

In MaxScale 2.2.1, rejoining cannot be initiated manually, but in a subsequent version a command to that effect will be provided.

Automatic Failover

To enable automatic failover, simply add auto_failover=true to the monitor section in the configuration file.

When everything is running fine, the cluster state looks like follows:

If server1 now goes down, failover will automatically be performed and an existing replica promoted to new primary.

If you are continuously monitoring the server states, you may notice for a brief period that the state of server1 is Down and the state ofserver2 is still Slave, Running.

Rejoin

To enable automatic rejoin, simply add auto_rejoin=true to the monitor section in the configuration file.

When automatic rejoin is enabled, the MariaDB Monitor will attempt to rejoin a failed primary as a replica, if it reappears.

When everything is running fine, the cluster state looks like follows:

Assuming auto_failover=true has been specified in the configuration file, when server1 goes down for some reason, failover will be performed and we end up with the following cluster state:

If server1 now reappears, the MariaDB Monitor will detect that and attempt to rejoin the old primary as a replica.

Whether rejoining will succeed depends upon the actual state of the old primary. For instance, if the old primary was modified and the changes had not been replicated to the new primary, before the old primary went down, then automatic rejoin will not be possible.

If rejoining can be performed, then the cluster state will end up looking like:

Switchover

Switchover is for cases when you explicitly want to move the primary role from one server to another.

If we continue from the cluster state at the end of the previous example and want to make server1 primary again, then we must issue the following command:

There are quite a few arguments, so let's look at each one separatelycall command indicates that it is a module command that is to be &#xNAN;invoked, mariadbmon indicates the module whose command we want to invoke,switchover is the command we want to invoke, and TheMonitor is the first argument to the command, the name of the monitor as specified in the configuration file,server1 is the second argument to the command, the name of the server we &#xNAN;want to make into primary, and server2 is the third argument to the command, the name of the currentprimary.

If the command executes successfully, we will end up with the following cluster state:

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

MaxScale Administration Tutorial

The purpose of this tutorial is to introduce the MariaDB MaxScale Administrator to a few of the common administration tasks. This is intended to be an introduction for administrators who are new to MariaDB MaxScale and not a reference to all the tasks that may be performed.

Administration audit file

The REST API calls that MaxCtrl and MaxGui issue to MaxScale can be logged by enabling .

The generated file is a csv file that can be opened in most spread sheet programs.

[Rotating Log Files](#Rotating Log Files) also applies to the audit file. The admin audit file will never be overwritten as a result of a rotate, unlike the regular log file (in case a rotate is issued, but the file name has not been moved). There is also the option to change the audit file name, which effectively rotates it independently of the regular log file. For example:

Starting and Stopping MariaDB MaxScale

MaxScale uses systemd for managing the process. This means that normalsystemctl commands can be used to start and stop MaxScale. To start MaxScale, use systemctl start maxscale. To stop it, use systemctl stop maxscale.

The systemd service file for MaxScale is located in /lib/systemd/system/maxscale.service.

Additional Options for MaxScale

Additional command line options and other systemd configuration options can be given to MariaDB MaxScale by creating a drop-in file for the service unit file. You can do this with the systemctl edit maxscale.servicecommand. For more information about systemd drop-in files, refer to and .

Checking The Status Of The MariaDB MaxScale Services

It is possible to use the maxctrl command to obtain statistics about the services that are running within MaxScale. The maxctrl command list serviceswill give very basic information regarding services. This command may be either run in interactive mode or passed on the maxctrl command line.

Network listeners count as a user of the service, therefore there will always be one user per network port in which the service listens. More details can be obtained by using the "show service" command.

What Clients Are Connected To MariaDB MaxScale

To determine what client are currently connected to MariaDB MaxScale, you can use the list sessions command within maxctrl. This will give you IP address and the ID of the session for that connection. As with any maxctrl command this can be passed on the command line or typed interactively in maxctrl.

Rotating Log Files

Log rotation applies to the MaxScale log file, admin audit file and qlafilter files.

MariaDB MaxScale logs messages of different priority into a single log file. With the exception if error messages that are always logged, whether messages of a particular priority should be logged or not can be enabled via the maxctrl interface or in the configuration file. By default, MaxScale keeps on writing to the same log file. To prevent the file from growing indefinitely, the administrator must take action.

The name of the log file is maxscale.log. When the log is rotated, MaxScale closes the current log file and opens a new one using the same name.

Log file rotation is achieved by use of the rotate logs command in maxctrl.

As there currently is only the maxscale log, that is the only one that will be rotated.

This may be integrated into the Linux logrotate mechanism by adding a configuration file to the /etc/logrotate.d directory. If we assume we want to rotate the log files once per month and wish to keep 5 log files worth of history, the configuration file would look as follows.

MariaDB MaxScale will also rotate all of its log files if it receives the USR1 signal. Using this the logrotate configuration script can be rewritten as

In older versions MaxScale renamed the log file, behavior which is not fully compliant with the assumptions of logrotate and may lead to issues, depending on the used logrotate configuration file. From version 2.1 onward, MaxScale will not itself rename the log file, but when the log is rotated, MaxScale will simply close and reopen the same log file. That will make the behavior fully compliant with logrotate.

Taking Objects Temporarily Out of Use

Putting Servers into Maintenance

MariaDB MaxScale supports the concept of maintenance mode for servers within a cluster. This allows for planned, temporary removal of a database from the cluster without the need to change the MariaDB MaxScale configuration.

To achieve this, you can use the set server command in maxctrl to set the maintenance mode flag for the server. This may be done interactively within maxctrl or by passing the command on the command line.

This will cause MariaDB MaxScale to stop routing any new requests to the server, however if there are currently requests executing on the server these will not be interrupted. Connections to servers in maintenance mode are closed as soon as the next request arrives. To close them immediately, use the --force option for maxctrl set server.

Clearing the maintenance mode for a server will bring it back into use. If multiple MariaDB MaxScale instances are configured to use the node then maintenance mode must be set within each MariaDB MaxScale instance.

Stopping and Starting Services

Services can be stopped to temporarily halt their use. Stopping a service will cause it to stop accepting new connections until it is started. New connections are not refused if the service is stopped and are queued instead. This means that connecting clients will wait until the service is started again.

Starting a service will cause it to accept all queued connections that were created while it was stopped.

Stopping and Starting Monitors

Stopping a monitor will cause it to stop monitoring the state of the servers assigned to it. This is useful when the state of the servers is assigned manually with maxctrl set server.

Starting a monitor will make it resume monitoring of the servers. Any manually assigned states will be overwritten by the monitor.

Runtime Configuration Modification

The MaxScale configuration can be changed at runtime by using the create,alter and destroy commands of maxctrl. These commands either create, modify or destroy objects (servers, services, monitors etc.) inside MaxScale. The exact syntax for each of the commands and any additional options that they take can be seen with maxctrl --help <command>.

Not all parameters can be modified at runtime. Refer to the module documentation for more information on which parameters can be modified at runtime. If a parameter cannot be modified at runtime, the object can be destroyed and recreated in order to change it.

All runtime changes are persisted in files stored by default in /var/lib/maxscale/maxscale.cnf.d/. This means that any changes done at runtime persist through restarts. Any changes done to objects in the main configuration file are ignored if a persisted entry is found for it.

For example, if the address of a server is modified with maxctrl alter server db-server-1 address 192.168.0.100, the file/var/lib/maxscale/maxscale.cnf.d/db-server-1.cnf is created with the complete configuration for the object. To remove all runtime changes for all objects, remove all files found in /var/lib/maxscale/maxscale.cnf.d.

Core Parameter Configuration

Modify global MaxScale parameters:

Some global parameters cannot be modified at runtime. Refer to the for a full list of parameters that can be modified at runtime.

Managing Servers

Create a new server

Modify a Server

Destroy a Server

A server can only be destroyed if it is not used by any services or monitors. To automatically remove the server from the services and monitors that use it, use the --force flag.

Drain a Server

When a server is set into the drain state, no new connections to it are created. Unlike to the maintenance state which immediately stops all new requests and closes all connections if used with the --force option, thedrain state allows existing connections to continue routing requests to them in order to be gracefully closed once the client disconnects.

To remove the drain state, use clear server command:

Servers with the Master state cannot be drained. To drain them, first perform a switchover to another node and then drain the server.

Managing Monitors

Create a new Monitor

Modify a Monitor

Add Server to a Monitor

Remove a Server from a Monitor

Destroy a Monitor

A monitor can only be destroyed if it is not monitoring any servers. To automatically remove the servers from the monitor, use the --force flag.

Managing Services

Create a New Service

Modify a Service

Add Servers to a Service

Any servers added to services will only be used by new sessions. Existing sessions will use the servers that were available when they connected.

Remove Servers from a Service

Similarly to adding servers, removing servers from a service will only affect new sessions. Existing sessions keep using the servers even if they are removed from a service.

Change the Filters of a Service

The order of the filters is significant: the first filter will be the first to receive the query. The new set of filters will only be used by new sessions. Existing sessions will keep using the filters that were configured when they connected.

Destroy a Service

The service can only be destroyed if it uses no servers or clusters and has no listeners associated with it. To force destruction of a service even if it does use servers or has listeners, use the --force flag. This will also destroy any listeners associated with the service.

Managing Filters

Create a New Filter

Destroy a Filter

A filter can only be destroyed if it is not used by any services. To automatically remove the filter from all services using it, use the --forceflag.

Filters cannot be altered at runtime in MaxScale 2.5. To modify the parameters of a filter, destroy it and recreate it with the modified parameters.

Managing Listeners

Create a New Listener

Destroy a Listener

Destroying a listener will close the network socket and stop it from accepting new connections. Existing connections that were created through it will keep displaying it as the originating listener.

Listeners cannot be moved from one service to another. In order to do this, the listener must be destroyed and then recreated with the new service.

Managing MaxCtrl and REST API Users

MaxCtrl uses the same credentials as the MaxScale REST API. These users can be managed via MaxCtrl.

Create a New MaxCtrl User

By default new users are only allowed to read data. To make the account an administrative account, add the --type=admin option to the command:

Administrative accounts are allowed to use all MaxCtrl commands and modify any parts of MaxScale.

Change the Password of an Existing User

Remove a User

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

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬────────────────┐
│ Server  │ Address         │ Port │ Connections │ State          │
├─────────┼─────────────────┼──────┼─────────────┼────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Down           │
├─────────┼─────────────────┼──────┼─────────────┼────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Slave, Running │
├─────────┼─────────────────┼──────┼─────────────┼────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running │
├─────────┼─────────────────┼──────┼─────────────┼────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running │
└─────────┴─────────────────┴──────┴─────────────┴────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Down            │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Running         │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬────────────────────────┐
│ Server  │ Address         │ Port │ Connections │ State                  │
├─────────┼─────────────────┼──────┼─────────────┼────────────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Down                   │
├─────────┼─────────────────┼──────┼─────────────┼────────────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Master, Slave, Running │
├─────────┼─────────────────┼──────┼─────────────┼────────────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running         │
├─────────┼─────────────────┼──────┼─────────────┼────────────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running         │
└─────────┴─────────────────┴──────┴─────────────┴────────────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Down            │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list servers
┌─────────┬─────────────────┬──────┬─────────────┬─────────────────┐
│ Server  │ Address         │ Port │ Connections │ State           │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server1 │ 192.168.121.51  │ 3306 │ 0           │ Master, Running │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server2 │ 192.168.121.190 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server3 │ 192.168.121.112 │ 3306 │ 0           │ Slave, Running  │
├─────────┼─────────────────┼──────┼─────────────┼─────────────────┤
│ server4 │ 192.168.121.201 │ 3306 │ 0           │ Slave, Running  │
└─────────┴─────────────────┴──────┴─────────────┴─────────────────┘

$ maxctrl list services
┌────────────────────────┬────────────────┬─────────────┬───────────────────┬────────────────────────────────────┐
│ Service                │ Router         │ Connections │ Total Connections │ Servers                            │
├────────────────────────┼────────────────┼─────────────┼───────────────────┼────────────────────────────────────┤
│ CLI                    │ cli            │ 1           │ 1                 │                                    │
├────────────────────────┼────────────────┼─────────────┼───────────────────┼────────────────────────────────────┤
│ RW-Split-Router        │ readwritesplit │ 1           │ 1                 │ server1, server2, server3, server4 │
├────────────────────────┼────────────────┼─────────────┼───────────────────┼────────────────────────────────────┤
│ RW-Split-Hint-Router   │ readwritesplit │ 1           │ 1                 │ server1, server2, server3, server4 │
├────────────────────────┼────────────────┼─────────────┼───────────────────┼────────────────────────────────────┤
│ SchemaRouter-Router    │ schemarouter   │ 1           │ 1                 │ server1, server2, server3, server4 │
├────────────────────────┼────────────────┼─────────────┼───────────────────┼────────────────────────────────────┤
│ Read-Connection-Router │ readconnroute  │ 1           │ 1                 │ server1                            │
└────────────────────────┴────────────────┴─────────────┴───────────────────┴────────────────────────────────────┘

$ maxctrl list sessions
┌────┬─────────┬──────────────────┬──────────────────────────┬──────┬─────────────────┐
│ Id │ User    │ Host             │ Connected                │ Idle │ Service         │
├────┼─────────┼──────────────────┼──────────────────────────┼──────┼─────────────────┤
│ 6  │ maxuser │ ::ffff:127.0.0.1 │ Thu Aug 27 10:39:16 2020 │ 4    │ RW-Split-Router │
└────┴─────────┴──────────────────┴──────────────────────────┴──────┴─────────────────┘

/var/log/maxscale/maxscale.log {
monthly
rotate 5
missingok
nocompress
sharedscripts
postrotate
\# run if maxscale is running
if test -n "`ps acx|grep maxscale`"; then
/usr/bin/maxctrl rotate logs
fi
endscript
}

Schemarouter: Simple Sharding With Two Servers

Sharding is the method of splitting a single logical database server into separate physical databases. This tutorial describes a very simple way of sharding. Each schema is located on a different database server and MariaDB MaxScale's schemarouter module is used to combine them into a single logical database server.

Environment

This tutorial was written for Ubuntu 22.04, MaxScale 23.08 and MariaDB 10.11. In addition to the MaxScale server, you'll need two MariaDB servers which will be used for the sharding. The installation of MariaDB is not covered by this tutorial.

Installing MaxScale

The easiest way to install MaxScale is to use the MariaDB repositories.

# Install MaxScale
apt update
apt -y install sudo curl
curl -LsS https://r.mariadb.com/downloads/mariadb_repo_setup | sudo bash
apt -y install maxscale

Creating Users

This tutorial uses a broader set of grants than is required for the sake of brevity and backwards compatibility. For the minimal set of grants, refer to the MaxScale Configuration Guide.

All MaxScale configurations require at least two accounts: one for reading authentication data and another for monitoring the state of the database. Services will use the first one and monitors will use the second one. In addition to this, we want to have a separate account that our application will use.

-- Create the user for the service
-- https://mariadb.com/kb/en/mariadb-maxscale-2308-authentication-modules/#required-grants
CREATE USER 'service_user'@'%' IDENTIFIED BY 'secret';
GRANT SELECT ON mysql.* TO 'service_user'@'%';
GRANT SHOW DATABASES ON *.* TO 'service_user'@'%';

-- Create the user for the monitor
-- https://mariadb.com/kb/en/mariadb-maxscale-2308-galera-monitor/#required-grants
CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'secret';
GRANT REPLICATION CLIENT ON *.* TO 'monitor_user'@'%';

-- Create the application user
-- https://mariadb.com/kb/en/mariadb-maxscale-2308-authentication-modules/#limitations-and-troubleshooting
CREATE USER app_user@'%' IDENTIFIED BY 'secret';
GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO app_user@'%';

All of the users must be created on both of the MariaDB servers.

Creating the Schemas and Tables

Each server will hold one unique schema which contains the data of one specific customer. We'll also create a shared schema that is present on all shards that the shard-local tables can be joined into.

Create the tables on the first server:

CREATE DATABASE IF NOT EXISTS customer_01;
CREATE TABLE IF NOT EXISTS customer_01.accounts(id INT, account_type INT, account_name VARCHAR(255));
INSERT INTO customer_01.accounts VALUES (1, 1, 'foo');

-- The shared schema that's on all shards
CREATE DATABASE IF NOT EXISTS shared_info;
CREATE TABLE IF NOT EXISTS shared_info.account_types(account_type INT, type_name VARCHAR(255));
INSERT INTO shared_info.account_types VALUES (1, 'admin'), (2, 'user');

Create the tables on the second server:

CREATE DATABASE IF NOT EXISTS customer_02;
CREATE TABLE IF NOT EXISTS customer_02.accounts(id INT, account_type INT, account_name VARCHAR(255));
INSERT INTO customer_02.accounts VALUES (2, 2, 'bar');

-- The shared schema that's on all shards
CREATE DATABASE IF NOT EXISTS shared_info;
CREATE TABLE IF NOT EXISTS shared_info.account_types(account_type INT, type_name VARCHAR(255));
INSERT INTO shared_info.account_types VALUES (1, 'admin'), (2, 'user');

Configuring MaxScale

The MaxScale configuration is stored in /etc/maxscale.cnf.

First, we configure two servers we will use to shard our database. The db-01 server has the customer_01 schema and the db-02 server has the customer_02 schema.

[db-01]
type=server
address=192.168.0.102
port=3306

[db-02]
type=server
address=192.168.0.103
port=3306

The next step is to configure the service which the users connect to. This section defines which router to use, which servers to connect to and the credentials to use. For sharding, we use schemarouter router and the service_user credentials we defined earlier. By default the schemarouter warns if two or more nodes have duplicate schemas so we need to ignore them withignore_tables_regex=.*.

[Sharded-Service]
type=service
router=schemarouter
targets=db-02,db-01
user=service_user
password=secret
ignore_tables_regex=.*

After this we configure a listener for the service. The listener is the actual port that the user connects to. We will use the port 4000.

[Sharded-Service-Listener]
type=listener
service=Sharded-Service
port=4000

The final step is to configure a monitor which will monitor the state of the servers. The monitor will notify MariaDB MaxScale if the servers are down. We add the two servers to the monitor and use the monitor_user credentials. For the sharding use-case, the galeramon module is suitable even if we're not using a Galera cluster. The schemarouter is only interested in whether the server is in the Running state or in the Down state.

[Shard-Monitor]
type=monitor
module=galeramon
servers=db-02,db-01
user=monitor_user
password=secret

After this we have a fully working configuration and the contents of/etc/maxscale.cnf should look like this.

[db-01]
type=server
address=192.168.0.102
port=3306

[db-02]
type=server
address=192.168.0.103
port=3306

[Sharded-Service]
type=service
router=schemarouter
targets=db-02,db-01
user=service_user
password=secret
ignore_tables_regex=.*

[Sharded-Service-Listener]
type=listener
service=Sharded-Service
protocol=MariaDBClient
port=4000

[Shard-Monitor]
type=monitor
module=galeramon
servers=db-02,db-01
user=monitor_user
password=secret

Then you're ready to start MaxScale.

systemctl start maxscale.service

Testing the Sharding

MariaDB MaxScale is now ready to start accepting client connections and routing them. Queries are routed to the right servers based on the database they target and switching between the shards is seamless since MariaDB MaxScale keeps the session state intact between servers.

To test, we query the schema that's located on the local shard and join it to the shared table.

$ mariadb -A -u app_user -psecret -h 127.0.0.1 -P 4000
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 3
Server version: 10.11.7-MariaDB-1:10.11.7+maria~ubu2004-log mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> USE customer_01;
Database changed
MariaDB [customer_01]> SELECT c.account_name, c.account_type, s.type_name FROM accounts c
    ->   JOIN shared_info.account_types s ON (c.account_type = s.account_type);
+--------------+--------------+-----------+
| account_name | account_type | type_name |
+--------------+--------------+-----------+
| foo          |            1 | admin     |
+--------------+--------------+-----------+
1 row in set (0.001 sec)

MariaDB [customer_01]> USE customer_02;
Database changed
MariaDB [customer_02]> SELECT c.account_name, c.account_type, s.type_name FROM accounts c
    ->   JOIN shared_info.account_types s ON (c.account_type = s.account_type);
+--------------+--------------+-----------+
| account_name | account_type | type_name |
+--------------+--------------+-----------+
| bar          |            2 | user      |
+--------------+--------------+-----------+
1 row in set (0.000 sec)

The sharding also works even if no default database is selected.

MariaDB [(none)]> SELECT c.account_name, c.account_type, s.type_name FROM customer_01.accounts c
    ->   JOIN shared_info.account_types s ON (c.account_type = s.account_type);
+--------------+--------------+-----------+
| account_name | account_type | type_name |
+--------------+--------------+-----------+
| foo          |            1 | admin     |
+--------------+--------------+-----------+
1 row in set (0.001 sec)

MariaDB [(none)]> SELECT c.account_name, c.account_type, s.type_name FROM customer_02.accounts c
    ->   JOIN shared_info.account_types s ON (c.account_type = s.account_type);
+--------------+--------------+-----------+
| account_name | account_type | type_name |
+--------------+--------------+-----------+
| bar          |            2 | user      |
+--------------+--------------+-----------+
1 row in set (0.001 sec)

One limitation of this sort of simple sharding is that cross-shard joins are not possible.

MariaDB [(none)]> SELECT * FROM customer_01.accounts UNION SELECT * FROM customer_02.accounts;
ERROR 1146 (42S02): Table 'customer_01.accounts' doesn't exist
MariaDB [(none)]> USE customer_01;
Database changed
MariaDB [customer_01]> SELECT * FROM customer_01.accounts UNION SELECT * FROM customer_02.accounts;
ERROR 1146 (42S02): Table 'customer_02.accounts' doesn't exist
MariaDB [customer_01]> USE customer_02;
Database changed
MariaDB [customer_02]> SELECT * FROM customer_01.accounts UNION SELECT * FROM customer_02.accounts;
ERROR 1146 (42S02): Table 'customer_01.accounts' doesn't exist

In most multi-tenant situations, this is an acceptable limitation. If you do need cross-shard joins, the Spider storage engine will provide you this.

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

REST API Tutorial

This tutorial is a quick overview of what the MaxScale REST API offers, how it can be used to inspect the state of MaxScale and how to use it to modify the runtime configuration of MaxScale. The tutorial uses the curl command line client to demonstrate how the API is used.

Configuration and Hardening

The MaxScale REST API listens on port 8989 on the local host. The admin_port and admin_host parameters control which port and address the REST API listens on. Note that for security reasons the API only listens for local connections with the default configuration. It is critical that the default credentials are changed and TLS/SSL encryption is configured before exposing the REST API to a network.

The default user for the REST API is admin and the password is mariadb. The easiest way to secure the REST API is to use the maxctrl command line client to create a new admin user and delete the default one. To do this, run the following commands:

maxctrl create user my_user my_password --type=admin
maxctrl destroy user admin

This will create the user my_user with the password my_password that is an administrative account. After this account is created, the default admin account is removed with the next command.

The next step is to enable TLS encryption. To do this, you need a CA certificate, a private key and a public certificate file all in PEM format. Add the following three parameters under the [maxscale] section of the MaxScale configuration file and restart MaxScale.

admin_ssl_key=/certs/server-key.pem
admin_ssl_cert=/certs/server-cert.pem
admin_ssl_ca_cert=/certs/ca-cert.pem

Use maxctrl to verify that the TLS encryption is enabled. In this tutorial our server certificates are self-signed so the --tls-verify-server-cert=false option is required.

maxctrl --user=my_user --password=my_password --secure --tls-ca-cert=/certs/ca-cert.pem --tls-verify-server-cert=false show maxscale

If no errors are raised, this means that the communication via the REST API is now secure and can be used across networks.

Requesting Data

Note: For the sake of brevity, the rest of this tutorial will omit theTLS/SSL options from the curl command line. For more information, refer to thecurl manpage.

The most basic task to do with the REST API is to see whether MaxScale is up and running. To do this, we do a HTTP request on the root resource (the -i option shows the HTTP headers).

curl -i 127.0.0.1:8989/v1/

HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 0
Last-Modified: Mon, 04 Mar 2019 08:23:09 GMT
ETag: "0"
Date: Mon, 04 Mar 19 08:29:41 GMT

To query a resource collection endpoint, append it to the URL. The /v1/filters/ endpoint shows the list of filters configured in MaxScale. This is a resource &#xNAN;collection endpoint: it contains the list of all resources of a particular type.

curl 127.0.0.1:8989/v1/filters

{
    "links": {
        "self": "http://127.0.0.1:8989/v1/filters/"
    },
    "data": [
        {
            "id": "Hint",
            "type": "filters",
            "relationships": {
                "services": {
                    "links": {
                        "self": "http://127.0.0.1:8989/v1/services/"
                    },
                    "data": [
                        {
                            "id": "RW-Split-Hint-Router",
                            "type": "services"
                        }
                    ]
                }
            },
            "attributes": {
                "module": "hintfilter",
                "parameters": {}
            },
            "links": {
                "self": "http://127.0.0.1:8989/v1/filters/Hint"
            }
        },
        {
            "id": "Logger",
            "type": "filters",
            "relationships": {
                "services": {
                    "links": {
                        "self": "http://127.0.0.1:8989/v1/services/"
                    },
                    "data": []
                }
            },
            "attributes": {
                "module": "qlafilter",
                "parameters": {
                    "match": null,
                    "exclude": null,
                    "user": null,
                    "source": null,
                    "filebase": "/tmp/log",
                    "options": "ignorecase",
                    "log_type": "session",
                    "log_data": "date,user,query",
                    "newline_replacement": "\" \"",
                    "separator": ",",
                    "flush": false,
                    "append": false
                },
                "filter_diagnostics": {
                    "separator": ",",
                    "newline_replacement": "\" \""
                }
            },
            "links": {
                "self": "http://127.0.0.1:8989/v1/filters/Logger"
            }
        }
    ]
}

The data holds the actual list of resources: the Hint and Logger filters. Each object has the id field which is the unique name of that object. It is the same as the section name in maxscale.cnf.

Each resource in the list has a relationships object. This shows the relationship links between resources. In our example, the Hint filter is used by a service named RW-Split-Hint-Router and the Logger is not currently in use.

To request an individual resource, we add the object name to the resource collection URL. For example, if we want to get only the Logger filter we execute the following command.

curl 127.0.0.1:8989/v1/filters/Logger

{
    "links": {
        "self": "http://127.0.0.1:8989/v1/filters/Logger"
    },
    "data": {
        "id": "Logger",
        "type": "filters",
        "relationships": {
            "services": {
                "links": {
                    "self": "http://127.0.0.1:8989/v1/services/"
                },
                "data": []
            }
        },
        "attributes": {
            "module": "qlafilter",
            "parameters": {
                "match": null,
                "exclude": null,
                "user": null,
                "source": null,
                "filebase": "/tmp/log",
                "options": "ignorecase",
                "log_type": "session",
                "log_data": "date,user,query",
                "newline_replacement": "\" \"",
                "separator": ",",
                "flush": false,
                "append": false
            },
            "filter_diagnostics": {
                "separator": ",",
                "newline_replacement": "\" \""
            }
        },
        "links": {
            "self": "http://127.0.0.1:8989/v1/filters/Logger"
        }
    }
}

Note that this time the data member holds an object instead of an array of objects. All other parts of the response are similar to what was shown in the previous example.

Creating Objects

One of the uses of the REST API is to create new objects in MaxScale at runtime. This allows new servers, services, filters, monitor and listeners to be created without restarting MaxScale.

For example, to create a new server in MaxScale the JSON definition of a server must be sent to the REST API at the /v1/servers/ endpoint. The request body defines the server name as well as the parameters for it.

To create objects with curl, first write the JSON definition into a file.

{
    "data": {
        "id": "server1",
        "type": "servers",
        "attributes": {
            "parameters": {
                "address": "127.0.0.1",
                "port": 3003
            }
        }
    }
}

To send the data, use the following command.

curl -X POST -d @new_server.txt 127.0.0.1:8989/v1/servers

The -d option takes a file name prefixed with a @ as an argument. Here we have @new_server.txt which is the name of the file where the JSON definition was stored. The -X option defines the HTTP verb to use and to create a new object we must use the POST verb.

To verify the data request the newly created object.

curl 127.0.0.1:8989/v1/servers/server1

Modifying Data

The easiest way to modify an object is to first request it, store the result in a file, edit it and then send the updated object back to the REST API.

Let's say we want to modify the port that the server we created earlier listens on. First we request the current object and store the result in a file.

curl 127.0.0.1:8989/v1/servers/server1 > server1.txt

After that we edit the file and change the port from 3003 to 3306. Next the modified JSON object is sent to the REST API as a PATCH command. To do this, execute the following command.

curl -X PATCH -d @server1.txt 127.0.0.1:8989/v1/servers/server1

To verify that the data was updated correctly, request the updated object.

curl 127.0.0.1:8989/v1/servers/server1

Object Relationships

To continue with our previous example, we add the updated server to a service. To do this, the relationships object of the server must be modified to include the service we want to add the server to.

To define a relationship between a server and a service, the data member must have the relationships field and it must contain an object with the servicesfield (some fields omitted for brevity).

{
    "data": {
        "id": "server1",
        "type": "servers",
        "relationships": {
            "services": {
                "data": [
                    {
                        "id": "RW-Split-Router",
                        "type": "services"
                    }
                ]
            }
        },
        "attributes":  ...
    }
}

The data.relationships.services.data field contains a list of objects that define the id and type fields. The id is the name of the object (a service or a monitor for servers) and the type tells which type it is. Only services type objects should be present in the services object.

In our example we are linking the server1 server to the RW-Split-Router service. As was seen with the previous example, the easiest way to do this is to store the result, edit it and then send it back with a HTTP PATCH.

If we want to remove a server from all services and monitors, we can set thedata member of the services and monitors relationships to an empty array:

{
    "data": {
        "relationships": {
            "services": {
                "data": []
            },
            "monitors": {
                "data": []
            }
        }
    }
}

This is useful if you want to delete the server which can only be done if it has no relationships to other objects.

Deleting Objects

To delete an object, simply execute a HTTP DELETE request on the resource you want to delete. For example, to delete the server1 server, execute the following command.

curl -X DELETE 127.0.0.1:8989/v1/servers/server1

In order to delete an object, it must not have any relationships to other. objects.

MaxScale Troubleshooting

Troubleshoot MariaDB MaxScale issues effectively. This section provides common problems, diagnostic steps, and solutions to help you maintain a stable and high-performing database proxy.

SystemD Watchdog Kills MaxScale

This can occur if a reverse DNS name lookup takes a long time. To disable reverse name lookups of client IPs to client hostnames, add skip_name_resolve=true under the [maxscale] section.

High Memory Usage

MaxScale starting with 22.08.4

The default value of writeq_high_water was lowered to 64KiB to reduce excessive memory usage. This change should result in a net decrease in memory usage and possibly a small improvement in performance.

Set writeq_high_water and writeq_low_water to lower values, for example writeq_high_water=512 and writeq_low_water=128. The default is to buffer a maximum of 16MB in memory before network throttling begins which under intensive loads can result in a large amount of memory being used per client.

The query classifier cache in MaxScale by default takes up to 15% of memory to cache query classification data. This value can be lowered using the query_classifier_cache_size parameter.

The retain_last_statements and session_trace debugging parameters can cause memory usage to increase. Disabling them under intensive loads is recommended if they are not needed. Note that the maxctrl list queries requires that retain_last_statements=1 is set.

Profiling Memory Usage

Profiling the memory usage can be useful for finding out why MaxScale appears to use more memory than it should. It is especially helpful for analyzing OOM situations or other cases where the memory grows linearly and causes problems.

To profile the memory usage of MaxScale, there are multiple options. The following sections describe the methods that are available.

If a problem in memory usage is identified and it appears to be due to a bug in MaxScale, please open a new bug report on the MariaDB Jira under the MaxScale project. Remember to include all the profiling and leak check reports along with the MaxScale version number and the configuration file with all password and other sensitive information removed.

Debug Binaries

The easiest option is to install the MaxScale debug binaries which are built with AddressSanitizer and LeakSanitizer enabled. These are low-impact instrumentation tools that detect memory access errors as well as memory leaks.

Once installed, make sure that the maxlog parameter is not disabled and then start MaxScale. Let it run until the memory usage grows beyond normal limits and then shut MaxScale down with systemctl stop maxscale.service. The MaxScale log should contain a verbose explanation of where memory leaks occurred, if any were found.

Profiling Release Mode Binaries

The instructions on the profiling-memory-usage page that are for the MariaDB server also apply to MaxScale. The following modifications to the commands must be done in order for them to work with MaxScale.

Replace /usr/sbin/mariadbd with /usr/bin/maxscale
Replace /var/lib/mysql/ with /var/log/maxscale/
Replace pidof mariadbd with pidof maxscale
Replace mariadb.service with maxscale.service

Valgrind

Valgrind can be used to analyze memory usage problems but usually it is left as the last resort due to the heavy performance penalty that it incurs. However, the use of Valgrind is simple as it is widely available and can be used with existing MaxScale binaries.

To use valgrind for memory leak detection, edit the systemd service file with systemctl edit maxscale.service and add the following values to it:

[Service]
ExecStart=valgrind --leak-check=full /usr/bin/maxscale -d
Type=simple

Then restart the MaxScale process with systemctl restart maxscale.service. Once the memory problem is confirmed, stop the MaxScale process with systemctl stop maxscale.service. Valgrind will print the leak report into the system journal that can be viewed with journalctl -u maxscale.

Authentication Errors

`Access Denied`

If you are receiving authentication errors like this:

ERROR 1045 (28000): Access denied for user 'bob'@'office' (using password: YES)

Make sure you create users for both 'bob'@'office' and 'bob'@'maxscale'. The host 'office' is where the client is attempting to connect from and 'maxscale' is the host where MaxScale is installed.

If you do not want to create a second set of users, you can enable proxy_protocol in MaxScale and configure the MariaDB server to from the MaxScale host.

Verifying that a user is allowed to connect

MaxScale connection
1. SSH to the server where MaxScale is installed
2. Connect to MariaDB
3. Check output of SHOW GRANTS
Client connection
1. SSH to theserver where client is connecting from
2. Connect to MariaDB
3. Check output of SHOW GRANTS

Checking MaxScale has correct grants

Service Grants

Make sure that the MaxScale services have a user configured and that it has the correct grants. Refer to the MariaDB protocol documentation on what grants are required for services.

Monitor Grants

The monitor user requires different grants than the service user and each monitor type requires different grants.

Asynchronous MariaDB replication with mariadbmon
Galera clusters with galeramon
Xpand replication

Other Errors

For all authentication and permission related errors, add debug=enable-statement-logging under the [maxscale] section of your MaxScale configuration file. This will cause all SQL statements to be logged on the notice level which will help you figure out what the problem is.

Access denied errors for user root!

If you want to connect as root, you'll need to add enable_root_user=true to the service.

Access denied on databases/tables containing underscores

There seems to be a bug for databases containing underscores. Connect as root and use "SHOW GRANTS FOR user".

GRANT SELECT ON my\_database.* TO 'user'@'%' <-- bad

GRANT SELECT ON my_database.* TO 'user'@'%' <-- good

If you got a grant containing a escaped underscore, you can add the strip_db_esc=true parameter to the service to automatically strip escape characters or just replace the grant with a unescaped one.

System Errors

`Failed to write message: 11, Resource temporarily unavailable`

MaxScale starting with 22.08.0

MaxScale 22.08 no longer uses pipes for internal communication. This means that this error is never logged and the pipe size no longer needs to be adjusted.

MaxScale starting with 6.4.5

Older MaxScale versions suffer from a bug (MXS-4474) that caused messages in the queue to take up 4096 bytes of memory per message instead of the intended 24 bytes which translates to a maximum of 256 messages instead of the expected 43690 messages with a 1MiB pipe size. Starting with MaxScale 6.4.5 and 2.5.25, the size is 24 bytes as expected which causes the maximum limit to be the expected 43690 messages. The problem still theoretically exists under extreme workloads where there are more than 43k concurrent clients but in practice the problem should almost never occur.

The MaxScale can log the Failed to write message: 11, Resource temporarily unavailable message under extremely intensive workloads (see MXS-1983 and MXS-4474).

The first action to take when these messages are encountered is to upgrade your MaxScale installation to the latest version. Whenever this message is seen, it means that something is causing the internal message queue in MaxScale to fill up. More often than not it is a sign of a possible bug in MaxScale and most likely has been fixed in the most recent release of MaxScale.

If this is still seen even after upgrading to the latest release, the pipe buffer size can be increased from the default 1MB to a higher value to prevent the problem from occurring. At least 8MB is recommended and should be increased until the message stops appearing.

To set the pipe buffer size, execute the following command.

sudo sysctl -w fs.pipe-max-size=8388608

If after all these actions you still see these warnings, please open a bug report on the MariaDB Jira under the MaxScale project.

Error 23: Too many open files

This is a common error when system limits for open files is too low. The fix to this is to increase the limits.

Systemd

Edit or add LimitNOFILE=<number of files> under the [Service] section in /usr/lib/systemd/system/maxscale.service.

MaxCtrl

`Error: ENOENT: no such file or directory, uv_cwd`

If MaxCtrl fails to start and throws the following error, it means that the current working directory no longer exists. Moving into a directory that does exist fixes the problem.

pkg/prelude/bootstrap.js:1872
      throw error;
      ^

Error: ENOENT: no such file or directory, uv_cwd
1) If you want to compile the package/file into executable, please pay attention to compilation warnings and specify a literal in 'require' call. 2) If you don't want to compile the package/file into executable and want to 'require' it from filesystem (likely plugin), specify an absolute path in 'require' call using process.cwd() or process.execPath.
    at Object.wrappedCwd [as cwd] (internal/bootstrap/switches/does_own_process_state.js:130:28)
    at /snapshot/maxctrl/node_modules/yargs/build/index.cjs:1:59463
    at Argv (/snapshot/maxctrl/node_modules/yargs/index.cjs:12:16)
    at Object.<anonymous> (/snapshot/maxctrl/node_modules/yargs/index.cjs:7:1)
    at Module._compile (pkg/prelude/bootstrap.js:1926:22)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    at Module.load (internal/modules/cjs/loader.js:950:32)
    at Function.Module._load (internal/modules/cjs/loader.js:790:12)
    at Module.require (internal/modules/cjs/loader.js:974:19)
    at Module.require (pkg/prelude/bootstrap.js:1851:31) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'uv_cwd',
  pkg: true
}

`Pkg: Error reading from file.`

If MaxCtrl fails to start and throws this error, it most likely means that the maxctrl executable has been stripped of symbols. To fix this problem, reinstall the MaxScale package.

Binlogrouter

Commands not Working

Make sure you are connecting on the port where the binlogrouter is listening. A common mistake is to connect to a readwritesplit or readconnroute port and execute the replication configuration commands there.

MaxScale CDC: Avrorouter

For most problems, resetting the conversion state is the solution. If the conversion repeatedly stops at a certain point, please open a bug report.

Resetting conversion state

Stop MaxScale
Remove the avro.index and avro-conversion.ini files along with any generated .avro files from the director where the Avro files are stored
Start MaxScale

Binlog files are not found

Make sure the start_index parameter is set to the lowest binlog file number. For example, to start from mariadb-bin-000005, set start_index=5.

Access denied to CDC interface

Create the user with maxadmin call command cdc add_user <service name> <user> <password> or maxctrl call command cdc add_user <service name> <user> <password>.

Coredumps Are Not Being Generated

Check that sysctl kernel.core_pattern is set to forward coredupms to systemd-coredump:

sysctl -w kernel.core_pattern='|/usr/lib/systemd/systemd-coredump %P %u %g %s %t %c %e'

Also make sure that SystemD is configured to allow coredumps. In External images are disabled suitable size limits must be set as they are set to zero by default.

$ cat /etc/systemd/coredump.conf
#  This file is part of systemd.
#
#  systemd is free software; you can redistribute it and/or modify it
#  under the terms of the GNU Lesser General Public License as published by
#  the Free Software Foundation; either version 2.1 of the License, or
#  (at your option) any later version.
#
# Entries in this file show the compile time defaults.
# You can change settings by editing this file.
# Defaults can be restored by simply deleting this file.
#
# See coredump.conf(5) for details.

[Coredump]
Storage=external
Compress=yes
ProcessSizeMax=1G
ExternalSizeMax=1G
JournalSizeMax=1G
#MaxUse=
#KeepFree=

Read the MariaDB documentation for and . Most of the operating system level documentation applies to MaxScale as well except that MaxScale is always run as a SystemD service and it only supports Linux as the platform.

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

MaxScale Top Filter

Top Filter

Overview

The top filter is a filter module for MariaDB MaxScale that monitors every SQL statement that passes through the filter. It measures the duration of that statement, the time between the statement being sent and the first result being returned. The top N times are kept, along with the SQL text itself and a list sorted on the execution times of the query is written to a file upon closure of the client session.

Configuration

Example minimal configuration:

Settings

The top filter has one mandatory parameter, filebase, and a number of optional parameters.

`filebase`

Type: string
Mandatory: Yes
Dynamic: Yes

The basename of the output file created for each session. The session ID is added to the filename for each file written. This is a mandatory parameter.

The filebase may also be set as the filter, the mechanism to set the filebase via the filter option is superseded by the parameter. If both are set the parameter setting will be used and the filter option ignored.

`count`

Type: number
Mandatory: No
Dynamic: Yes
Default: 10

The number of SQL statements to store and report upon.

`match`

Type:
Mandatory: No
Dynamic: Yes
Default: None

the queries logged by the filter.

`exclude`

Type:
Mandatory: No
Dynamic: Yes
Default: None

the queries logged by the filter.

`options`

Type:
Mandatory: No
Dynamic: No
Values: ignorecase, case, extended
Default: case

for match and exclude.

`source`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

Defines an address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this address will be logged.

`user`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

Defines a username that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username will result in results being generated.

Examples

Example 1 - Heavily Contended Table

You have an order system and believe the updates of the PRODUCTS table is causing some performance issues for the rest of your application. You would like to know which of the many updates in your application is causing the issue.

Add a filter with the following definition:

Note the exclude entry, this is to prevent updates to the PRODUCTS_STOCK table from being included in the report.

Example 2 - One Application Server is Slow

One of your applications servers is slower than the rest, you believe it is related to database access but you are not sure what is taking the time.

Add a filter with the following definition:

In order to produce a comparison with an unaffected application server you can also add a second filter as a control.

In the service definition add both filters

You will then have two sets of logs files written, one which profiles the top 20 queries of the slow application server and another that gives you the top 20 queries of your control application server. These two sets of files can then be compared to determine what if anything is different between the two.

Output Report

The following is an example report for a number of fictitious queries executed against the employees example database available for MySQL.

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

MaxScale Tee Filter

Tee Filter

Overview

The tee filter is a "plumbing" fitting in the MariaDB MaxScale filter toolkit. It can be used in a filter pipeline of a service to make copies of requests from the client and send the copies to another service within MariaDB MaxScale.

Please Note: Starting with MaxScale 2.2.0, any client that connects to a service which uses a tee filter will require a grant for the loopback address, i.e. 127.0.0.1.

Configuration

The configuration block for the TEE filter requires the minimal filter parameters in its section within the MaxScale configuration file. The service to send the duplicates to must be defined.

Settings

The tee filter requires a mandatory parameter to define the service to replicate statements to and accepts a number of optional parameters.

`target`

Type: target
Mandatory: No
Dynamic: Yes
Default: none

The target where the filter will duplicate all queries. The target can be either a service or a server. The duplicate connection that is created to this target will be referred to as the "branch target" in this document.

`service`

Type: service
Mandatory: No
Dynamic: Yes
Default: none

The service where the filter will duplicate all queries. This parameter is deprecated in favor of the target parameter and will be removed in a future release. Both target and service cannot be defined.

`match`

Type:
Mandatory: No
Dynamic: Yes
Default: None

What queries should be included.

`exclude`

Type:
Mandatory: No
Dynamic: Yes
Default: None

What queries should be excluded.

`options`

Type:
Mandatory: No
Dynamic: Yes
Values: ignorecase, case, extended
Default: ignorecase

How regular expressions should be interpreted.

`source`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

`user`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The optional user parameter defines a user name that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username are replicated.

`sync`

Type:
Mandatory: No
Dynamic: Yes
Default: false

Enable synchronous routing mode. When configured with sync=true, the filter will queue new queries until the response from both the main and the branch target has been received. This means that for n executed queries, n - 1 queries are guaranteed to be synchronized. Adding one extra statement (e.g. SELECT 1) to a batch of statements guarantees that all previous SQL statements have been successfully executed on both targets.

In the synchronous routing mode, a failure of the branch target will cause the client session to be closed.

Limitations

All statements that are executed on the branch target are done in an asynchronous manner. This means that when the client receives the response there is no guarantee that the statement has completed on the branch target. The sync feature provides some synchronization guarantees that can be used to verify successful execution on both targets.
Any errors on the branch target will cause the connection to it to be closed. If target is a service, it is up to the router to decide whether the connection is closed. For direct connections to servers, any network errors cause the connection to be closed. When the connection is closed, no new queries will be routed to the branch target.

With sync=true, a failure of the branch target will cause the whole session to be closed.

Module commands

Read documentation for details about module commands.

The tee filter supports the following module commands.

`tee disable [FILTER]`

This command disables a tee filter instance. A disabled tee filter will not send any queries to the target service.

`tee enable [FILTER]`

Enable a disabled tee filter. This resumes the sending of queries to the target service.

Examples

Example 1 - Replicate all inserts into the orders table

Assume an order processing system that has a table called orders. You also have another database server, the datamart server, that requires all inserts into orders to be replicated to it. Deletes and updates are not, however, required.

Set up a service in MariaDB MaxScale, called Orders, to communicate with the order processing system with the tee filter applied to it. Also set up a service to talk to the datamart server, using the DataMart service. The tee filter would have as its service entry the DataMart service, by adding a match parameter of "insert into orders" would then result in all requests being sent to the order processing system, and insert statements that include the orders table being additionally sent to the datamart server.

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

-bash-4.1$ cat /var/logs/top/Employees-top-10.137

Top 10 longest running queries in session.

==========================================

Time (sec) | Query

-----------+-----------------------------------------------------------------

    22.985 |  select sum(salary), year(from_date) from salaries s, (select distinct year(from_date) as y1 from salaries) y where (makedate(y.y1, 1) between s.from_date and s.to_date) group by y.y1

     5.304 |  select d.dept_name as "Department", y.y1 as "Year", count(*) as "Count" from departments d, dept_emp de, (select distinct year(from_date) as y1 from dept_emp order by 1) y where d.dept_no = de.dept_no and (makedate(y.y1, 1) between de.from_date and de.to_date) group by y.y1, d.dept_name order by 1, 2

     2.896 |  select year(now()) - year(birth_date) as age, gender, avg(salary) as "Average Salary" from employees e, salaries s where e.emp_no = s.emp_no and ("1988-08-01"  between from_date AND to_date) group by year(now()) - year(birth_date), gender order by 1,2

     2.160 |  select dept_name as "Department", sum(salary) / 12 as "Salary Bill" from employees e, departments d, dept_emp de, salaries s where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01"  between de.from_date AND de.to_date) and ("1988-08-01"  between s.from_date AND s.to_date) and s.emp_no = e.emp_no group by dept_name order by 1

     0.845 |  select dept_name as "Department", avg(year(now()) - year(birth_date)) as "Average Age", gender from employees e, departments d, dept_emp de where e.emp_no = de.emp_no and de.dept_no = d.dept_no and ("1988-08-01"  between from_date AND to_date) group by dept_name, gender

     0.668 |  select year(hire_date) as "Hired", d.dept_name, count(*) as "Count" from employees e, departments d, dept_emp de where de.emp_no = e.emp_no and de.dept_no = d.dept_no group by d.dept_name, year(hire_date)

     0.249 |  select moves.n_depts As "No. of Departments", count(moves.emp_no) as "No. of Employees" from (select de1.emp_no as emp_no, count(de1.emp_no) as n_depts from dept_emp de1 group by de1.emp_no) as moves group by moves.n_depts order by 1

     0.245 |  select year(now()) - year(birth_date) as age, gender, count(*) as "Count" from employees group by year(now()) - year(birth_date), gender order by 1,2

     0.179 |  select year(hire_date) as "Hired", count(*) as "Count" from employees group by year(hire_date)

     0.160 |  select year(hire_date) - year(birth_date) as "Age", count(*) as Count from employees group by year(hire_date) - year(birth_date) order by 1

-----------+-----------------------------------------------------------------

Session started Wed Jun 18 18:41:03 2014

Connection from 127.0.0.1

Username        massi

Total of 24 statements executed.

Total statement execution time      35.701 seconds

Average statement execution time     1.488 seconds

Total connection time               46.500 seconds

-bash-4.1$

[Orders]
type=service
router=readconnroute
servers=server1, server2, server3, server4
user=massi
password=6628C50E07CCE1F0392EDEEB9D1203F3
filters=ReplicateOrders

[ReplicateOrders]
type=filter
module=tee
target=DataMart
match=insert[   ]*into[     ]*orders

[DataMart]
type=service
router=readconnroute
servers=datamartserver
user=massi
password=6628C50E07CCE1F0392EDEEB9D1203F3
filters=QLA-DataMart

[QLA-DataMart]
type=filter
module=qlafilter
options=/var/log/DataMart/InsertsLog

[Orders-Listener]
type=listener
target=Orders
port=4011

[DataMart-Listener]
type=listener
target=DataMart
port=4012

MaxScale Rewrite Filter

Rewrite Filter

Overview

The rewrite filter allows modification of sql queries on the fly. Reasons for modifying queries can be to rewrite a query for performance, or to change a specific query when the client query is incorrect and cannot be changed in a timely manner.

The examples will use Rewrite Filter file format. See below.

Syntax

Native syntax

Rewriter native syntax uses placeholders to grab and replace parts of text.

Placeholders

The syntax for a plain placeholder is @{N} where N is a positive integer.

The syntax for a placeholder regex is @{N:regex}. It allows more control when needed.

The below is a valid entry in rf format. For demonstration, all options are set. This entry is a do-nothing entry, but illustrates placeholders.

%%
# options
regex_grammar: Native
case_sensitive: true
what_if: false
continue_if_matched: false
ignore_whitespace: true
%
# match template
@{1:^}select @{2} from my_table where id = @{3}
%
# replace template
select @{2} from my_table where id = @{3}

If the input sql is select id, name from my_table where id = 42 then @{2} = "id, name" and @{3} = "42". Since the replace template is identical to the match template the end result is that the output sql will be the same as the input sql.

Placeholders can be used as forward references.@{1:^}select @{2}, count(*) from @{3} group by @{2}. For a match, the two @{2} text grabs must be equal.

Match template

The match template is used to match against the sql to be rewritten.

The match template can be partial from mytable. But the actual underlying regex match is always for the whole sql. If the match template does not start or end with a placeholder, placeholders are automatically added so that the above becomes @{1}from mytable@{2}. The automatically added placeholders cannot be used in the replace template.

Matching the whole input also means that Native syntax does not support (and is not intended to support) scan and replace. Only the first occurrence of the above from mytable can be modified in the replace template. However, one can selectively choose to modify e.g. the first through third occurrence of from mytable by writingfrom mytable @{1} from mytable @{2} from mytable @{3}.

For scan and replace use a different regex_grammar (see below).

Replace template

The replace template uses the placeholders from the match template to rewrite sql.

%%
# use default options by leaving this blank
%
@{1:^}select count(distinct @{2}) from @{3}
%
select count(*) from (select distinct @{1} from @{2}) as t123

Input: select count(distinct author) from books where entity != "AI"

Rewritten: select count(*) from (select distinct author from books where entity != "AI") as t123

An important option for smooth matching is ignore_whitespace, which is on (true) by default. It creates the match regex in such a way that the amount and kind of whitespace does not affect matching. However, to make ignore_whitespace always work, it is important to add whitespace where allowed. If "id=42" is in the match template then only the exact "id=42" can match. But if "id = 42" is used, andignore_whitespace is on, both "id=42" and "id = 42" will match.

Another example, and what not to do:

%%
%
from mytable
%
from mytable force index (myindex)

Input: select name from mytable where id=42

Rewritten: select name from mytable force index (myindex) where id=42

That works, but because the match lacks specific detail about the expected sql, things are likely to break. In this caseshow indexes from my_table would no longer work.

The minimum detail in this case could be:

%%
%
@{1:^}select @{2} from mytable
%
select @{2} from mytable force index (myindex)

but if more detail is known, like something specific in the where clause, that too should be added.

Placeholder Regex

Syntax: @{N:regex}

In a placeholder regex the character } must be escaped to \} (for literal matching). Plain parenthesis "()" indicate capturing groups, which are internally used by the Native grammar. Thus plain parentheses in a placeholder regex will break matching. However, non-capturing groups can be used: e.g. @{1:(:?Jane|Joe)}. To match a literal parenthesis use an escape, e.g. \(.

Suppose an application is misbehaving after an upgrade and a quick fix is needed. This query select zip from address_book where str_id = "AZ-124" is correct, but if the id is an integer the where clause should be id = 1234.

%%
%
@{1:^}select zip_code from address_book where str_id = @{1:["]}@{2:[[:digit:]]+}@{3:["]}
%
select zip_code from address_book where id = @{2}

Input: select zip_code from address_book where str_id = "1234"

Rewritten: select zip_code from address_book where id = 1234

Using plain regular expressions

For scan and replace the regex_grammar must be set to something else than Native. An example will illustrate the usage.

Replace all occurrences of "wrong_table_name" with "correct_table_name". Further, if the replacement was made then replace all occurrences of wrong_column_name with correct_column_name.

%%
regex_grammar: EPosix
continue_if_matched: true
%
wrong_table_name
%
correct_table_name

%%
regex_grammar: EPosix
%
wrong_column_name
%
correct_column_name

Configuration

Adding a rewrite filter.

[Rewrite]
type = filter
module = rewritefilter
template_file = /path/to/template_file.rf
...

[Router]
type=service
...
filters=Rewrite

Settings

`template_file`

Type: string
Mandatory: Yes
Dynamic: Yes
Default: No default value

Path to the template file.

`regex_grammar`

Type: string
Mandatory: No
Dynamic: Yes
Default: Native
Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep

Default regex_grammar for templates

`case_sensitive`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Default case sensitivity for templates

`log_replacement`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Log replacements at NOTICE level.

Settings per template in the template file

`regex_grammar`

Type: string
Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep
Default: From maxscale.cnf

Overrides the global regex_grammar of a template.

`case_sensitive`

Type: boolean
Default: From maxscale.cnf

Overrides the global case sensitivity of a template.

`ignore_whitespace`

Type: boolean
Default: true

Ignore whitespace differences in the match template and input sql.

`continue_if_matched`

Type: boolean
Default: false

If a template matches and the replacement is done, continue to the next template and apply it to the result of the previous rewrite.

`what_if`

Type: boolean
Default: false

Do not make the replacement, only log what would have been replaced (NOTICE level).

Rewrite file format

The rf format for an entry is:

%%
options
%
match template
%
replace template

The character # starts a single line comment when it is the first character on a line.

Empty lines are ignored.

The rf format does not need any additional escaping to what the basic format requires (see Placeholder Regex).

Options are specified as follows:

case_sensitive: true

The colon must stick to the option name.

The separators % and %% must be the exact content of their respective separator lines.

The templates can span multiple lines. Whitespace does not matter as long as ignore_whitespace = true. Always use space where space is allowed to maximize the utility ofignore_whitespace.

Example

%%
case_sensitive: false
%
@{1:^}select @{2}
from mytable
where user = @{3}
%
select @{2} from mytable where user = @{3}
and @{3} in (select user from approved_users)

Json file format

The json file format is harder to read and edit manually. It will be needed if support for editing of rewrite templates is added to the GUI.

All double quotes and escape characters have to be escaped in json, i.e '"' and '\'.

The same example as above is:

{ "templates" :
    [
        {
            "case_sensitive" : false,
            "match_template" : "@{1:^}select @{2} from mytable where user = @{3}",
            "replace_template" : "select @{2} from mytable where user = @{3}
and @{3} in (select user from approved_users)"
        }
    ]
}

Reload template file

The configuration is re-read if any dynamic value is updated even if the value does not change.

maxctrl alter filter Rewrite log_replacement=false

Reference

ECMAScript ECMAScript
Posix V1_chap09.html#tag_09_03
EPosix V1_chap09.html#tag_09_04
Awk awk.html#tag_20_06_13_04
Grep Same as Posix with the addition of newline '\n' as an alternation separator.
EGrep Same as EPosix with the addition of newline '\n' as an alternation separator in addition to '|'.

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

MaxScale PAM Authenticator

PAM Authenticator

PAM Authenticator

Pluggable authentication module (PAM) is a general purpose authentication API. An application using PAM can authenticate a user without knowledge about the underlying authentication implementation. The actual authentication scheme is defined in the operating system PAM config (e.g. /etc/pam.d/), and can be quite elaborate. MaxScale supports a very limited form of the PAM protocol, which this document details.

Configuration

The MaxScale PAM module requires little configuration. All that is required is to change the listener authenticator module to "PAMAuth".

[Read-Write-Listener]
type=listener
address=::
service=Read-Write-Service
authenticator=PAMAuth

[Primary-Server]
type=server
address=123.456.789.10
port=12345

MaxScale uses the PAM authenticator plugin to authenticate users with plugin set to "pam" in the mysql.user-table. The PAM service name of a user is read from the authentication_string-column. The matching PAM service in the operating system PAM config is used for authenticating the user. If theauthentication_string for a user is empty, the fallback service "mysql" is used.

PAM service configuration is out of the scope of this document, see The Linux-PAM System Administrators' Guide for more information. A simple service definition used for testing this module is below.

auth            required        pam_unix.so
account         required        pam_unix.so

Settings

`pam_use_cleartext_plugin`

Type: boolean
Mandatory: No
Dynamic: No
Default: false

If enabled, MaxScale communicates with the client as if using mysql_clear_password. This setting has no effect on MaxScale-to-backend communication, which adapts to either "dialog" or "mysql_clear_password", depending on which one the backend suggests. This setting is meant to be used with the similarly named MariaDB Server setting.

authenticator_options=pam_use_cleartext_plugin=1

`pam_mode`

Type: enumeration
Mandatory: No
Dynamic: No
Values: password, password_2FA, suid
Default: password

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

password Normal password-based authentication
password_2FA Password + 2FA-code based authentication
suid Authenticate using suid sandbox subprocess

authenticator_options=pam_mode=password_2FA

If set to password_2FA, any users authenticating via PAM will be asked two passwords ("Password" and "Verification code") during login. MaxScale uses the normal password when either the local PAM api or a backend asks for "Password". MaxScale answers any other password prompt (e.g. "Verification code") with the second password. See the limitations section for more details. Two-factor mode is incompatible withpam_use_cleartext_plugin.

If set to suid, MaxScale will launch a separate subprocess for every client to handle pam authentication. This subprocess runs the binarymaxscale_pam_auth_tool (installed in the binary directory), which calls the system pam libraries. The binary is installed with the SUID bit set, which means that it runs with root-privileges regardless of the user launching it. This should bypass any file grant issues (e.g. reading etc/shadow) that may arise with the password or password_2FA options. The suid-option may also perform faster if many clients authenticate with pam simultaneously due to better separation of clients. It may also resist buggy pam plugins crashing, as the crash would be limited to the subprocess only. The MariaDB Server uses a similar pam authentication scheme. suid-mode supports two-factor authentication.

`pam_backend_mapping`

Type: enumeration
Mandatory: No
Dynamic: No
Values: none, mariadb
Default: none

Defines backend authentication mapping, i.e. switch of authentication method between client-to-MaxScale and MaxScale-to-backend. Supported values:

none No mapping
mariadb Map users to normal MariaDB accounts

authenticator_options=pam_backend_mapping=mariadb

If set to "mariadb", MaxScale will authenticate clients to backends using standard MariaDB authentication. Authentication to MaxScale itself still uses PAM. MaxScale asks the local PAM system if the client username was mapped to another username during authentication, and use the mapped username when logging in to backends. Passwords for the mapped users can be given in a file, see pam_mapped_pw_file below. If passwords are not given, MaxScale will try to authenticate without a password. Because of this, normal PAM users and mapped users cannot be used on the same listener.

Because the client still needs to authenticate to MaxScale normally, an anonymous user may be required. If the backends do not allow such a user, one can be manually added using the service setting user_accounts_file.

To map usernames, the PAM service needs to use a module such aspam_user_map.so. This module is not a standard Linux component and needs to be installed separately. It is included in recent MariaDB Server packages and can also be compiled from source. See for more information on how to configure the module. If the goal is to only map users from PAM to MariaDB in MaxScale, then configuring user mapping on just the machine running MaxScale is enough.

Instead of using pam_backend_mapping, consider using the listener setting user_mapping_file, as it is easier to configure. pam_backend_mapping should only be used when the user mapping needs to be defined by pam.

`pam_mapped_pw_file`

Type: path
Mandatory: No
Dynamic: No
Default: None

Path to a json-text file with user passwords. Default value is empty, which disables the feature.

authenticator_options=pam_mapped_pw_file=/home/root/passwords.json,pam_backend_mapping=mariadb

This feature only works together with pam_backend_mapping=mariadb. The file is only read during listener creation (typically MaxScale start) or when a listener is modified during runtime. The file should contain passwords for the mapped users. When a client is authenticating, MaxScale searches the password data for a matching username. If one is found, MaxScale uses the supplied password when logging in to backends. Otherwise, MaxScale tries to authenticate without a password.

One array, "users_and_passwords", is read from the file. Each array element in the array must define the following fields:

"user": String. Mapped client username.
"password": String. Backend server password. Can be encrypted with maxpasswd.

An example file is below.

{
    "users_and_passwords": [
        {
            "user": "my_mapped_user1",
            "password": "my_mapped_pw1"
        },
        {
            "user": "my_mapped_user2",
            "password": "A6D4C53619FFFF4DF252A0E595EDB0A12CA44E16AF154D0ED08F687E81604BFF42218B4EBA9F3EF8D907CF35E74ABDAA"
        }
    ]
}

Anonymous user mapping

When backend authenticator mapping is not in use (authenticator_options=pam_backend_mapping=none), the PAM authenticator supports a limited version of . It requires less configuration but is also less accurate than proper mapping. Anonymous mapping is enabled in MaxScale if the following user exists:

Empty username (e.g. ''@'%' or ''@'myhost.com')
plugin = 'pam'
Proxy grant is on (The query SHOW GRANTS FOR user@host; returns at least one row with GRANT PROXY ON ...)

When the authenticator detects such users, anonymous account mapping is enabled for the hosts of the anonymous users. To verify this, enable the info log (log_info=1 in MaxScale config file). When a client is logging in using the anonymous user account, MaxScale will log a message starting with "Found matching anonymous user ...".

When mapping is on, the MaxScale PAM authenticator does not require client accounts to exist in the mysql.user-table received from the backend. MaxScale only requires that the hostname of the incoming client matches the host field of one of the anonymous users (comparison performed using LIKE). If a match is found, MaxScale attempts to authenticate the client to the local machine with the username and password supplied. The PAM service used for authentication is read from the authentication_string-field of the anonymous user. If authentication was successful, MaxScale then uses the username and password to log to the backends.

Anonymous mapping is only attempted if the client username is not found in themysql.user-table as explained in Configuration. This means, that if a user is found and the authentication fails, anonymous authentication is not attempted even when it could use a different PAM service with a different outcome.

Setting up PAM group mapping for the MariaDB server is a more involved process as the server requires details on which Unix user or group is mapped to which MariaDB user. See for more details. Performing all the steps in the guide also on the MaxScale machine is not required, as the MaxScale PAM plugin only checks that the client host matches an anonymous user and that the client (with the username and password it provided) can log into the local PAM configuration. If using normal password authentication, simply generating the Unix user and password should be enough.

Implementation details and limitations

The general PAM authentication scheme is difficult for a proxy such as MaxScale. An application using the PAM interface needs to define a conversation function to allow the OS PAM modules to communicate with the client, possibly exchanging multiple messages. This works when a client logs in to a normal server, but not with MaxScale since it needs to autonomously log into multiple backends. For MaxScale to successfully log into the servers, the messages and answers need to be predefined. The passwords given to MaxScale need to work as is when MaxScale logs into the backends. This requirement prevents the use of one-time passwords.

The MaxScale PAM authentication module supports two password modes. In normal mode, client authentication begins with MaxScale sending an AuthSwitchRequest packet. In addition to the command, the packet contains the client plugin name ("dialog" or "mysql_clear_password"), a message type byte (4) and the message "Password: ". In the next packet, the client should send the password, which MaxScale will forward to the PAM api running on the local machine. If the password is correct, an OK packet is sent to the client. If the local PAM api asks for additional credentials as is typical in two-factor authentication schemes, authentication fails. Informational messages such as password expiration notifications are allowed. These are simply printed to the log.

On the backend side, MaxScale expects the servers to act as MaxScale did towards the client. The servers should send an AuthSwitchRequest packet as defined above, MaxScale responds with the password received by the client authenticator and finally backend replies with OK. Informational messages from backends are only printed to the info-log.

Two-factor authentication support

MaxScale supports a limited form of two-factor authentication with thepam_mode=password_2FA-option. Since MaxScale uses the 2FA-code given by the client to log in to the local PAM api as well as all the backends, the code must be reusable. This prevents the use of any kind of centrally checked one-use codes. Time-based codes work, assuming the backends are checking the codes independently of each other. Automatic reconnection features (e.g. readwritesplit-router) will not work, as the code has likely changed since original authentication.

Optionally, the PAM configuration on the backend servers can be weakened such that the servers only asks for the normal password. This way, MaxScale will check the 2FA-code of the incoming client, while MaxScale logs into the backends using only the password.

Due to technical reasons, MaxScale does not forward the password prompts from the PAM api to the client. MaxScale will always ask for "Password" and "Verification code", even if the PAM api asks for other items. This prevents the use of authentication schemes where a specific question must be answered (e.g. "Input code Nr. 5"). This is not a significant limitation, as such schemes would not work with backend servers anyway.

Test tool

MaxScale binary directory contains the test_pam_login-executable. This simple program asks for a username, password and PAM service and then uses the given credentials to login to the given service. test_pam_login uses the same code as MaxScale itself to communicate with the OS PAM interface and may be useful for diagnosing PAM login issues.

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

MaxScale Query Log All Filter

Query Log All Filter

Overview

The Query Log All (QLA) filter logs query content. Logs are written to a file in CSV format. Log elements are configurable and include the time submitted and the SQL statement text, among others.

Configuration

A minimal configuration is below.

[MyLogFilter]
type=filter
module=qlafilter
filebase=/tmp/SqlQueryLog

[MyService]
type=service
router=readconnroute
servers=server1
user=myuser
password=mypasswd
filters=MyLogFilter

Log Rotation

The qlafilter logs can be rotated by executing the maxctrl rotate logs command. This will cause the log files to be reopened when the next message is written to the file. This applies to both unified and session type logging.

Settings

The QLA filter has one mandatory parameter, filebase, and a number of optional parameters. These were introduced in the 1.0 release of MariaDB MaxScale.

`filebase`

Type: string
Mandatory: Yes
Dynamic: No

The basename of the output file created for each session. A session index is added to the filename for each written session file. For unified log files,.unified is appended.

filebase=/tmp/SqlQueryLog

`match`

Type: regex
Mandatory: No
Dynamic: Yes
Default: None

Include queries that match the regex.

`exclude`

Type: regex
Mandatory: No
Dynamic: Yes
Default: None

Exclude queries that match the regex.

`options`

Type: enum_mask
Mandatory: No
Dynamic: Yes
Values: case, ignorecase, extended
Default: case

The extended option enables PCRE2 extended regular expressions.

`user`

Type: string
Mandatory: No
Dynamic: Yes
Default: ""

Limit logging to sessions with this user.

`source`

Type: string
Mandatory: No
Dynamic: Yes
Default: ""

Limit logging to sessions with this client source address.

`user_match`

Type: regex
Mandatory: No
Dynamic: Yes

Only log queries from users that match this pattern. If the user parameter is used, the value of user_match is ignored.

Here is an example pattern that matches the users alice and bob:

user_match=/(^alice$)|(^bob$)/

`user_exclude`

Type: regex
Mandatory: No
Dynamic: Yes

Exclude all queries from users that match this pattern. If the user parameter is used, the value of user_exclude is ignored.

Here is an example pattern that excludes the users alice and bob:

user_exclude=/(^alice$)|(^bob$)/

`source_match`

Type: regex
Mandatory: No
Dynamic: Yes

Only log queries from hosts that match this pattern. If the source parameter is used, the value of source_match is ignored.

Here is an example pattern that matches the loopback interface as well as the address 192.168.0.109:

source_match=/(^127[.]0[.]0[.]1)|(^192[.]168[.]0[.]109)/

`source_exclude`

Type: regex
Mandatory: No
Dynamic: Yes

Exclude all queries from hosts that match this pattern. If the source parameter is used, the value of source_exclude is ignored.

Here is an example pattern that excludes the loopback interface as well as the address 192.168.0.109:

source_exclude=/(^127[.]0[.]0[.]1)|(^192[.]168[.]0[.]109)/

`log_type`

Type: enum_mask
Mandatory: No
Dynamic: Yes
Values: session, unified, stdout
Default: session

The type of log file to use.

Value

Description

session

Write to session-specific files

unified

Use one file for all sessions

stdout

Same as unified, but to stdout

`log_data`

Type: enum_mask
Mandatory: No
Dynamic: Yes
Values: service, session, date, user, reply_time, total_reply_time, query, default_db, num_rows, reply_size, transaction, transaction_time, num_warnings, error_msg
Default: date, user, query

Type of data to log in the log files.

Value

Description

service

Service name

session

Unique session id (ignored for session files)

date

Timestamp

user

User and hostname of client

reply_time

Duration from client query to first server reply

total_reply_time

Duration from client query to last server reply (v6.2)

query

The SQL of the query if it contains it

default_db

The default (current) database

num_rows

Number of rows in the result set (v6.2)

reply_size

Number of bytes received from the server (v6.2)

transaction

BEGIN, COMMIT and ROLLBACK (v6.2)

transaction_time

The duration of a transaction (v6.2)

num_warnings

Number of warnings in the server reply (v6.2)

error_msg

Error message from the server (if any) (v6.2)

server

The server where the query was routed (if any) (v22.08)

command

The protocol command that was executed (v24.02)

The durations reply_time and total_reply_time are by default in milliseconds, but can be specified to another unit using duration_unit.

The log entry is written when the last reply from the server is received. Prior to version 6.2 the entry was written when the query was received from the client, or if reply_time was specified, on first reply from the server.

NOTE The error_msg is the raw message from the server. Even if use_canonical_form is set the error message may contain user defined constants. For example:

MariaDB [test]> select secret from T where x password="clear text pwd";
ERROR 1064 (42000): You have an error in your SQL syntax; check the manual
that corresponds to your MariaDB server version for the right syntax to
use near 'password="clear text pwd"' at line 1

Starting with MaxScale 24.02, the query parameter now correctly logs the execution of binary protocol commands as SQL (MXS-4959). The execution of batched statements (COM_STMT_BULK_LOAD) used by some connectors is not logged.

`duration_unit`

Type: string
Mandatory: No
Dynamic: Yes
Default: milliseconds

The unit for logging a duration. The unit can be milliseconds or microseconds. The abbreviations ms for milliseconds and us for microseconds are also valid. This option is available as of MaxScale version 6.2.

`use_canonical_form`

Type: bool
Mandatory: No
Dynamic: Yes
Default: false

When this option is true the canonical form of the query is logged. In the canonical form all user defined constants are replaced with question marks. This option is available as of MaxScale version 6.2.

`flush`

Type: bool
Mandatory: No
Dynamic: Yes
Default: false

Flush log files after every write.

`append`

Type: bool
Mandatory: No
Dynamic: Yes
Default: true

`separator`

Type: string
Mandatory: No
Dynamic: Yes
Default: ","

Defines the separator string between elements of log entries. The value should be enclosed in quotes.

`newline_replacement`

Type: string
Mandatory: No
Dynamic: Yes
Default: " "

Default value is " " (one space). SQL-queries may include line breaks, which, if printed directly to the log, may break automatic parsing. This parameter defines what should be written in the place of a newline sequence (\r, \n or \r\n). If this is set as the empty string, then newlines are not replaced and printed as is to the output. The value should be enclosed in quotes.

newline_replacement=" NL "

Limitations

Trailing parts of SQL queries that are larger than 16MiB are not logged. This means that the log output might contain truncated SQL.
Batched execution using COM_STMT_BULK_EXECUTE is not converted into their textual form. This is done due to the large volumes of data that are usually involved with batched execution.

Examples

Example 1 - Query without primary key

Imagine you have observed an issue with a particular table and you want to determine if there are queries that are accessing that table but not using the primary key of the table. Let's assume the table name is PRODUCTS and the primary key is called PRODUCT_ID. Add a filter with the following definition:

[ProductsSelectLogger]
type=filter
module=qlafilter
match=SELECT.*from.*PRODUCTS .*
exclude=WHERE.*PRODUCT_ID.*
filebase=/var/logs/qla/SelectProducts

[Product-Service]
type=service
router=readconnroute
servers=server1
user=myuser
password=mypasswd
filters=ProductsSelectLogger

The result of using this filter with the service used by the application would be a log file of all select queries querying PRODUCTS without using the PRODUCT_ID primary key in the predicates of the query. Executing SELECT * FROM PRODUCTS would log the following into /var/logs/qla/SelectProducts:

07:12:56.324 7/01/2016, SELECT * FROM PRODUCTS

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

MaxScale Workload Capture and Replay

The WCAR (Workload Capture and Replay) module is a sophisticated feature designed to capture and archive client traffic passing through a MaxScale instance. This allows system administrators and developers to process and store vast volumes of data related to client-server interactions in a reliable manner. By harnessing this captured data, users gain the flexibility to replay and simulate the varied client activity typically seen in a production environment.

One of the module's primary advantages is that it removes the necessity of creating explicit traffic generators, which can be resource-intensive and complex to maintain. Instead, the WCAR module provides a seamless method for mirroring realistic client interactions and behavior patterns, which can be critical for testing, debugging, and optimizing system performance.

Additionally, by facilitating traffic replay, the WCAR module aids in identifying potential system vulnerabilities and performance bottlenecks, allowing for preemptive optimization. This proactive approach ensures that systems are well-prepared for live production scenarios, enhancing overall efficiency and uptime.

In essence, the WCAR module not only preserves detailed and valuable traffic data but also empowers users with the tools to analyze and refine their systems through accurate simulation, paving the way for robust and resilient system architectures.

Workload Capture and Replay

Overview

The WCAR filter (module wcar) captures client traffic and stores it in a replayable format.

WCAR is designed to capture traffic on a production MaxScale instance. The captured data can then be used as a reproducible way of generating client traffic without having to write application-specific traffic generators.

The captured workloads can be used to:

Verify that upgrades of MariaDB behave as expected.
Repeatedly measure effects of configuration changes, which is useful for database tuning.
Investigate why certain scenarios take longer then expected, as a kind of SQL debugging tool.

Prerequisites

Both the capture MaxScale and replay MaxScale servers must use the same linux distribution and CPU architecture. For example, if the capture was taken on an x86_64 RHEL 8 instance, the replay should also happen on an x86_64 RHEL 8 instance. Captured workloads are however usually compatible across different linux distributions that use the same CPU architecture.
The capture MariaDB instance must have binlogging enabled (log-bin=1)

Capture

Quick start

Workload capture can be used without definitions in static configuration files and without a MaxScale restart.

If you have an existing routing service named, e.g., RWS-Router in your configuration you can attach a capture filter to it dynamically:

maxctrl create filter CAPTURE_FLTR wcar
maxctrl link service RWS-Router CAPTURE_FLTR

You can then start a capture with

maxctrl call command wcar start CAPTURE_FLTR <options>

If limiting options were given the capture will stop automatically when one of the limits is triggered. You can also stop the capture at any time with:

maxctrl call command wcar stop CAPTURE_FLTR

See Replay to see how the captured files are used.

When capture is no longer needed you can remove it with:

maxctrl unlink service RWS-Router CAPTURE_FLTR
maxctrl destroy filter CAPTURE_FLTR

File based configuration

Define a capture filter by adding the following configuration object and add it to each service whose traffic is to be captured. The traffic from all services that use the filter will be combined so only use the filter in services that point to the same database cluster.

[CAPTURE_FLTR]
type=filter
module=wcar
capture_duration=1h # Limit capture duration to one hour
capture_size=1Gi    # Limit capture size to 1GiB
start_capture=true  # Start capturing immediately after starting MaxScale

Example configuration file

Here is an example configuration for capturing from a single MariaDB server, where capture starts when MaxScale starts and stops when MaxScale is stopped (start_capture=true). MaxScale listens on port 4006 and connects to MariaDB on port 3306.

[server1]
type=server
address=127.0.0.1
port=3306

[MariaDB-Monitor]
type=monitor
module=mariadbmon
servers=server1
user=maxuser
password=maxpwd

[CAPTURE_FLTR]
type=filter
module=wcar
capture_duration=1h     # Limit capture duration to one hour
capture_size=1Gi        # Limit capture size to 1GiB
start_capture=true      # Start capturing immediately after starting MaxScale

[RWS-Router]
type=service
router=readwritesplit
cluster=MariaDB-Monitor
user=maxuser
password=maxpwd
filters=CAPTURE_FLTR

[RWS-Listener]
type=listener
service=RWS-Router
protocol=MariaDBClient
port=4006

Capturing Traffic

This section explains how capture is done with configuration value start_capture=true.

Two things are needed to replay a workload: the client traffic that's captured by MaxScale and a backup of the database that is used to initialize the replay server. The backup should be taken from the point in time where the capture starts and the simplest way to achieve this is to take a logical backup by doing the following.

Stop MaxScale
Take a backup of the database with mariadb-dump --all-databases --system=all
Start MaxScale

Once MaxScale has been started, the captured traffic will be written to files in/var/lib/maxscale/wcar/<name> where <name> is the name of the filter (CAPTURE_FLTR in the examples).

Each capture will generate a number of files named NAME_YYYY-MM-DD_HHMMSS.SUFFIX where NAME is the capture name (defaults to capture), YYYY-MM-DD is the date and HHMMSS is the time and the SUFFIX is one of .cx, .ex or.tx. For example, a capture started on the 18th of April 2024 at 10:26:11 would generate a file named capture_2024-04-18_102611.cx.

Stopping the Capture

To stop the capture, simply stop MaxScale, or issue the command:

maxctrl call command wcar stop CAPTURE_FLTR

where "CAPTURE_FLTR" is the name given to the filter as in the example configuration above.

To disable capturing altogether, remove the capture filter from the configuration and remove it from all services that it was added to. Restart MaxScale.

If the replay is to take place on another server, the results can be collected easily from /var/lib/maxscale/wcar/ with the following command.

tar -caf captures.tar.gz -C /var/lib/maxscale wcar

Once the capture tarball has been generated, copy it to the replay server. You might then want to delete the directories on the capture server from /var/lib/maxscale/wcar/* to save space (and not copy them again later).

Commands

Each of the commands can be called with the following syntax.

maxctrl call command wcar <command> <filter> [options]

The <filter> is the name of the filter instance. In the example configuration, the value is CAPTURE_FLTR. The [options] is a list of optional arguments that the command might expect.

`start <filter> [options]`

Starts a new capture. Issuing a start command will stop any ongoing capture.

The start command supports optional key-value pairs. If the values are also defined in the configuration file the command line options have priority. The supported keys are:

prefix The prefix added to capture files. The default value is capture.
duration Limit capture to this duration. See also configuration file value 'capture_duration'.
size Limit capture to approximately this many bytes in the file system. See also configuration file value 'capture_size'.

The start command options are not persistent, and only apply to the capture that was thus started.

For example, starting a capture with the below command would create a capture file named Scenario1_2024-04-18_102605.cx and limit the file system usage to approximately 10GiB. If capture_duration was defined in the configuration file it would also be used.

If both duration and size are specified, the one that triggers first, stops the capture.

maxctrl call command wcar start CAPTURE_FLTR prefix=Scenario1 size=10G

Running the same command again, but without size=10G, the capture_size used would be that defined in the configuration file or no limit if there was no such definition.

`stop <filter>`

Stops the currently active capture if one is in progress.

maxctrl call command wcar stop CAPTURE_FLTR

Replay

Installation

Install the required packages on the MaxScale server where the replay is to be done. An additional dependency that must be manually installed is Python, version 3.9 or newer. On most linux distributions a new enough version is available as the default Python interpreter. You may also need to install the development packages for Python, python3-devel on RHEL based systems or python3-dev on Debian based systems, as well as a C++ compiler.

For RHEL 8, Rocky Linux 8 and Alma Linux 8, a newer version of Python must be installed along with the development headers with dnf install python39 python39-devel gcc-c++ and it must be set as the default python implementation with alternatives --set python3 /usr/bin/python3.9.

The replay consists of restoring the database to the point in time where the capture was started. Start by restoring the replay database to this state. Once the database has been restored from the backup, copy the capture files over to the replay MaxScale server.

Preparing the Replay MariaDB Database

Full Restore

Start by restoring the database from the backup to put it at the point in time where the capture was started. The GTID position of the first commit within the capture can be seen in the output of the summary command:

maxplayer summary /path/to/capture.cx

If the captured data has not been transformed to replay format yet, the command will perform the transformation before displaying the summary.

Run maxplayer --help to see the command line options. The help output is also shown at the end of this file.

The replay also requires a user account using which the captured traffic is replayed. This user must have access to all the tables in question. In practice the simplest way to do this for testing is to create the user as follows:

CREATE USER 'maxreplay'@'%' IDENTIFIED BY 'replay-pw';
GRANT ALL ON *.* TO 'maxreplay'@'%';

Restore for read-only Replay

For captures that are intended for read-only Replay, it may not be as important that the servers to be tested against are in the exact GTID the capture server was when capture started. In fact, it may be advantageous that the servers are at the state after the capture finished.

On the other hand, Replay also supports write-only. Following the Full Restore procedure above and then running a write-only Replay prepares the replay server(s) for easily running read-only multiple times. This way of running read-only may, for example, be used when fine tuning server settings.

Replaying the Capture

When replay is first done, the capture files will be transformed in-place. Transform can be run separately as well. Depending on the size and structure of the capture file, Transform can use up to twice the space of the capture.ex file. The files with extension .ex contain most of the captured data (events).

Start by copying the replay file tarball created earlier (captures.tar.gz) to the replay MaxScale server and copy it to a directory of your choice (here called/path/to/capture-dir). Then extract the files.

cd /path/to/capture-dir
tar -xaf captures.tar.gz

After this, replay the workload against the baseline MariaDB setup:

maxplayer replay --user maxreplay --password replay-pw --host <host:port> --output baseline-result.csv /path/to/capture.cx

Once the baseline replay results have been generated, run the replay again but this time against the new MariaDB setup to which the baseline is compared to:

maxplayer replay --user maxreplay --password replay-pw --host <host:port> --output comparison-result.csv /path/to/capture.cx

After both replays have been completed, the results can be post-processed and visualized.

Visualizing

The results of the captured replay must first be post-processed into summaries that the visualization will then use. First, the canonicals.csv file must be generated that is needed in the post-processing:

maxplayer canonicals /path/to/capture.cx > canonicals.csv

After that, the baseline and comparison replay results can be post-processed into summaries using the maxpostprocess command:

maxpostprocess canonicals.csv baseline-result.csv -o baseline-summary.json
maxpostprocess canonicals.csv comparison-result.csv -o comparison-summary.json

The visualization itself is done with the maxvisualize program. The visualization will open up a browser window to show the visualization. If no browser opens up, the visualization URL is also printed into the command line which by default should be http://localhost:8866/.

maxvisualize baseline-summary.json comparison-summary.json

To listen on all network interfaces, use --Voila.ip='0.0.0.0' as the last argument.

maxvisualize baseline-summary.json comparison-summary.json --Voila.ip='0.0.0.0'

Settings

`capture_dir`

Type: path
Default: /var/lib/maxscale/wcar/
Mandatory: No
Dynamic: No

Directory under which capture directories are stored. Each capture directory has the name of the filter. In the examples above the name "CAPTURE_FLTR" was used.

`start_capture`

Type: boolean
Default: false
Mandatory: No
Dynamic: No

Start capture when maxscale starts.

`capture_duration`

Type: duration
Default: 0s
Maximum: Unlimited in MaxScale, 5min in MaxScale Lite.
Mandatory: No
Dynamic: No

Limit capture to this duration. If set to zero there is no limit.

`capture_size`

Type: size
Default: 0
Maximum: Unlimited in MaxScale, 10MB in MaxScale Lite.
Mandatory: No
Dynamic: No

Limit capture to approximately this many bytes in the file system. If set to zero there is no limit.

maxplayer command line options

maxplayer -u user -p pwd --speed 1.5 -i 5s -o baseline.csv capture_2024-09-06_090002.cx --help
Usage: maxplayer [OPTION]... [COMMAND] FILE

Commands: (default: replay)
summary    Show a summary of the capture.
replay     Replay the capture.
convert    Converts the input file (either .cx or .rx) to a replay file (.rx or .csv).
canonicals List the canonical forms of the captured SQL as CSV.
dump-data  Dump capture data as SQL.
show       Show the SQL of one or more events.

Options:
--user          User name for login to the replay server.
-u              This version does not support using the actual user names
                that were used during capture.

--password      Only clear text passwords are supported as of yet.
-p

--host          The address of the replay server in <IP>:<port> format.
-h              E.g. 127.0.0.1:4006

--output        The name of the output file: e.g. baseline.csv.
-o

--report        Periodically report statistics of ongoing operations.
-r              The option takes a duration, such as 10s.

--report-file   The --report option by default writes to stdout.
-R              Provide the name of the file to write to. The file will
                be truncated every time it is written to, allowing for a
                simple status window by running 'watch cat <path-to-file>'
                in a terminal.

--speed         The value is a multiplier. 2.5 is 2.5x speed and 0.5 is half speed.
-s              A value of zero means no limit, or replay as fast as possible.
                A multiplier of 2.5 might not have any effect as the actual time spent
                depends on many factors, such as the captured volume and replay server.

--idle-wait     Relates to playback speed, and can be used together with --speed.
-i              During capture there can be long delays where there is no traffic.
                One hour of no capture traffic would mean replay waits for one hour.
                idle-wait allows to move simulation time forwards when such gaps
                occure. A 'gap' starts when all prior queries have fully executed.
                --idle-wait takes a duration value. A negative value turns the feature off,
                            i.e. the one hour wait would happen.
                --idle-wait 0s means time moves to the event start-time immediately
                            when a gap is detected, i.e., all gaps are skipped over.
                --idle-wait 10s means time moves to the event start-time 10 seconds
                            (wall time) after the gap was detected. Shorter
                            gaps than 10 seconds will thus be fully waited for.
                --idle-wait has a default value of 1 second.
                Examples: 1h, 60m, 3600s, 3600000ms, which all define the same duration.

--query-filter  Options: none, write-only, read-only. Default: none.
-f              Replay can optionally apply only writes or only reads. This option is useful
                once the databases to be tested have been prepared (see full documentation)
                and optionally either a write-only run, or a full replay has been run.
                Now multiple read-only runs against the server(s) are simple as no further
                data syncronization is needed.
                Note that this mode has its limitations as the query results may
                be very different than what they were during capture.

--analyze       Enabling this option will track the server Rows_read statistic for each query.
-A              This will slow down the overall replay time. The query time measurements
                are still valid, but currently this option should only be used when
                it is of real value to know how many rows the server read for each query.

--verbose       Verbose output. The option can be repeated for more verbosity: -vvv
-v

--version       Display the version number and copyrights.
-V

input file:       capture_2024-09-06_090002.cx
-h --help         true
-u --user         user
-p --password     pwd
-H --host         127.1.1.0:3306
-o --output       baseline.csv
-r --report       0ns
-R --report-file
-s --speed        1.5
-i --idle-wait    5s
-f --query-filter none
-A --analyze      false
-v --verbose      0
-V --version      0.2

Limitations

KILL commands do not work correctly during replay and may kill the wrong session (MXS-5056)
COM_STMT_BULK_EXECUTE is not captured (MXS-5057)
COM_STMT_EXECUTE that uses a cursor is replayed without a cursor (MXS-5059)
For MyISAM and Aria tables, this will cause the table level lock to be held for a shorter time.
Execution of a COM_STMT_SEND_LONG_DATA will not work (MXS-5060)
The capture files are not necessarily compatible with different linux distributions and CPU architectures than the original capture server has. Different combinations will require further testing, and once done, this document will be updated.

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

MaxScale Masking Filter

Masking

Overview

With the masking filter it is possible to obfuscate the returned value of a particular column.

For instance, suppose there is a table person that, among other columns, contains the column ssn where the social security number of a person is stored.

With the masking filter it is possible to specify that when the ssn field is queried, a masked value is returned unless the user making the query is a specific one. That is, when making the query

instead of getting the real result, as in

the ssn would be masked, as in

Note that the masking filter should be viewed as a best-effort solution intended for protecting against accidental misuse rather than malicious attacks.

Security

From MaxScale 2.3 onwards, the masking filter will reject statements that use functions in conjunction with columns that should be masked. Allowing function usage provides a way for circumventing the masking, unless a firewall filter is separately configured and installed.

Please see the configuration parameter for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will check the definition of user variables and reject statements that define a user variable using a statement that refers to columns that should be masked.

Please see the configuration parameter for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will examine unions and if the second or subsequent SELECT refer to columns that should be masked, the statement will be rejected.

Please see the configuration parameter for how to change the default behaviour.

From MaxScale 2.3.5 onwards, the masking filter will examine subqueries and if a subquery refers to columns that should be masked, the statement will be rejected.

Please see the configuration parameter for how to change the default behaviour.

Note that in order to ensure that it is not possible to get access to masked data, the privileges of the users should be minimized. For instance, if a user can create tables and perform inserts, he or she can execute something like

to get access to the cleartext version of a masked field ssn.

From MaxScale 2.3.5 onwards, the masking filter will, if any of theprevent_function_usage, check_user_variables, check_unions orcheck_subqueries parameters is set to true, block statements that cannot be fully parsed.

Please see the configuration parameter for how to change the default behaviour.

From MaxScale 2.3.7 onwards, the masking filter will treat any strings passed to functions as if they were fields. The reason is that as the MaxScale query classifier is not aware of whether ANSI_QUOTES is enabled or not, it is possible to bypass the masking by turning that option on.

Before this change, the content of the field ssn would have been returned in clear text even if the column should have been masked.

Note that this change will mean that there may be false positives if ANSI_QUOTES is not enabled and a string argument happens to be the same as the name of a field to be masked.

Please see the configuration parameter [treat_string_arg_as_field(#treat_string_arg_as_field) for how to change the default behaviour.

Limitations

The masking filter can only be used for masking columns of the following types: BINARY, VARBINARY, CHAR, VARCHAR, BLOB, TINYBLOB,MEDIUMBLOB, LONGBLOB, TEXT, TINYTEXT, MEDIUMTEXT, LONGTEXT,ENUM and SET. If the type of the column is something else, then no masking will be performed.

Currently, the masking filter can only work on packets whose payload is less than 16MB. If the masking filter encounters a packet whose payload is exactly that, thus indicating a situation where the payload is delivered in multiple packets, the value of the parameter large_payloads specifies how the masking filter should handle the situation.

Configuration

The masking filter is taken into use with the following kind of configuration setup.

Settings

The masking filter has one mandatory parameter - rules.

`rules`

Type: path
Mandatory: Yes
Dynamic: Yes

Specifies the path of the file where the masking rules are stored. A relative path is interpreted relative to the module configuration directory of MariaDB MaxScale. The default module configuration directory is/etc/maxscale.modules.d.

`warn_type_mismatch`

Type:
Mandatory: No
Dynamic: Yes
Values: never, always
Default: never

With this optional parameter the masking filter can be instructed to log a warning if a masking rule matches a column that is not of one of the allowed types.

`large_payload`

Type:
Mandatory: No
Dynamic: Yes
Values: ignore, abort
Default: abort

This optional parameter specifies how the masking filter should treat payloads larger than 16MB, that is, payloads that are delivered in multiple MySQL protocol packets.

The values that can be used are ignore, which means that columns in such payloads are not masked, and abort, which means that if such payloads are encountered, the client connection is closed. The default is abort.

Note that the aborting behaviour is applied only to resultsets that contain columns that should be masked. There are no limitations on resultsets that do not contain such columns.

`prevent_function_usage`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should behave if a column that should be masked, is used in conjunction with some function. As the masking filter works only on the basis of the information in the returned result-set, if the name of a column is not present in the result-set, then the masking filter cannot mask a value. This means that the masking filter basically can be bypassed with a query like:

If the value of prevent_function_usage is true, then all statements that contain functions referring to masked columns will be rejected. As that means that also queries using potentially harmless functions, such as LENGTH(masked_column), are rejected as well, this feature can be turned off. In that case, the firewall filter should be setup to allow or reject the use of certain functions.

`require_fully_parsed`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should behave in case any of prevent_function_usage, check_user_variables,check_unions or check_subqueries is true and it encounters a statement that cannot be fully parsed,

If true, then statements that cannot be fully parsed (due to a parser limitation) will be blocked.

Note that if this parameter is set to false, then prevent_function_usage,check_user_variables, check_unions and check_subqueries are rendered less effective, as it with a statement that cannot be fully parsed may be possible to bypass the protection that they are intended to provide.

`treat_string_arg_as_field`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should treat strings used as arguments to functions. If true, they will be handled as fields, which will cause fields to be masked even if ANSI_QUOTES has been enabled and " is used instead of backtick.

`check_user_variables`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should behave with respect to user variables. If true, then a statement like

will be rejected if ssn is a column that should be masked.

`check_unions`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should behave with respect to UNIONs. If true, then a statement like

will be rejected if b is a column that should be masked.

`check_subqueries`

Type:
Mandatory: No
Dynamic: Yes
Default: true

This optional parameter specifies how the masking filter should behave with respect to subqueries. If true, then a statement like

will be rejected if a is a column that should be masked.

Rules

The masking rules are expressed as a JSON object.

The top-level object is expected to contain a key rules whose value is an array of rule objects.

Each rule in the rules array is a JSON object, expected to contain the keys replace, with, applies_to andexempted. The two former ones are obligatory and the two latter ones optional.

`replace`

The value of this key is an object that specifies the column whose values should be masked. The object must contain the keycolumn and may contain the keys table and database. The value of these keys must be a string.

If only column is specified, then a column with that name matches irrespective of the table and database. If table is specified, then the column matches only if it is in a table with the specified name, and if database is specified when the column matches only if it is in a database with the specified name.

NOTE If a rule contains a table/database then if the resultset does not contain table/database information, it will always be considered a match if the column matches. For instance, given the rule above, if there is a table person2, also containing an ssn field, then a query like

will not return masked values, but a query like

will only return masked values, even if the ssn values fromperson2 in principle should not be masked. The same effect is observed even with a nonsensical query like

even if nothing from person2 should be masked. The reason is that as the resultset contains no table information, the values must be masked if the column name matches, as otherwise the masking could easily be circumvented with a query like

The optional key match makes partial replacement of the original value possible: only the matched part would be replaced with the fill character. The match value must be a valid pcre2 regular expression.

`obfuscate`

The obfuscate rule allows the obfuscation of the value by passing it through an obfuscation algorithm. Current solution uses a non-reversible obfuscation approach.

However, note that although it is in principle impossible to obtain the original value from the obfuscated one, if the range of possible original values is limited, it is straightforward to figure out the possible original values by running all possible values through the obfuscation algorithm and then comparing the results.

The minimal configuration is:

Output example for Db field name = 'remo'

`with`

The value of this key is an object that specifies what the value of the matched column should be replaced with for the replace rule. Currently, the object is expected to contain either the key value or the key fill. The value of both must be a string with length greater than zero. If both keys are specified, value takes precedence. If fill is not specified, the default X is used as its value.

If value is specified, then its value is used to replace the actual value verbatim and the length of the specified value must match the actual returned value (from the server) exactly. If the lengths do not match, the value offill is used to mask the actual value.

When the value of fill (fill-value) is used for masking the returned value, the fill-value is used as many times as necessary to match the length of the return value. If required, only a part of the fill-value may be used in the end of the mask value to get the lengths to match.

`applies_to`

With this optional key, whose value must be an array of strings, it can be specified what users the rule is applied to. Each string should be a MariaDB account string, that is, % is a wildcard.

If this key is not specified, then the masking is performed for all users, except the ones exempted using the key exempted.

`exempted`

With this optional key, whose value must be an array of strings, it can be specified what users the rule is not applied to. Each string should be a MariaDB account string, that is, % is a wildcard.

Module commands

Read documentation for details about module commands.

The masking filter supports the following module commands.

`reload`

Reload the rules from the rules file. The new rules are taken into use only if the loading succeeds without any errors.

MyMaskingFilter refers to a particular filter section in the MariaDB MaxScale configuration file.

Example

In the following we configure a masking filter MyMasking that should always log a warning if a masking rule matches a column that is of a type that cannot be masked, and that should abort the client connection if a resultset package is larger than 16MB. The rules for the masking filter are in the file masking_rules.json.

Configuration

`masking_rules.json`

The rules specify that the data of a column whose name is ssn, should be replaced with the string 012345-ABCD. If the length of the data is not exactly the same as the length of the replacement value, then the data should be replaced with as many X characters as needed.

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

{
    "rules": [
        {
            "replace": {
                "database": "db1",
                "table": "person",
                "column": "ssn"
            },
            "with": { ... },
            "applies_to": [ ... ],
            "exempted": [ ... ]
        }
    ]
}

{
    "rules": [
        {
            "replace": {
                "column": "ssn"
            },
            "with": {
                "value": "XXX-XX-XXXX"
            },
            "applies_to": [ ... ],
            "exempted": [ ... ]
        },
        {
            "replace": {
                "column": "age"
            },
            "with": {
                "fill": "*"
            },
            "applies_to": [ ... ],
            "exempted": [ ... ]
        },
        {
            "replace": {
                "column": "creditcard"
            },
            "with": {
                "value": "1234123412341234",
                "fill": "0"
            },
            "applies_to": [ ... ],
            "exempted": [ ... ]
        },
    ]
}

{
    "rules": [
        {
            "replace": { ... },
            "with": { ... },
            "applies_to": [ "'alice'@'host'", "'bob'@'%'" ],
            "exempted": [ ... ]
        }
    ]
}

{
    "rules": [
        {
            "replace": {
                "column": "ssn"
            },
            "with": {
                "value": "012345-ABCD",
                "fill": "X"
            }
        }
    ]
}

Using MaxGUI

Using MaxGUI Tutorial

Introduction

This tutorial is an overview of what the MaxGUI offers as an alternative solution to MaxCtrl.

Dashboard

Annotation

MaxScale object. i.e. Service, Server, Monitor, Filter, and Listener (Clicking on it will navigate to its detail page)
Create a new MaxScale object.
Dashboard Tab Navigation.
Search Input. This can be used as a quick way to search for a keyword in tables.
Dashboard graphs. Refresh interval is 10 seconds.

SESSIONS graph illustrates the total number of current sessions.
CONNECTIONS graph shows servers current connections.
LOAD graph shows the last second load of thread.

Logout of the app.
Sidebar navigation menu. Access to the following pages: Dashboard, Visualization, Settings, Logs Archive, Query Editor
Expand/Collapse the graphs.
Graph annotation configuration.
Active Operations Bar: This bar chart represents the proportion of active operations on the server relative to the total number of connections. The value displayed is the ratio of active_operations to connections, providing a visual gauge of server activity.

Create a new MaxScale object

Clicking on the Create New button (Annotation 2) to open a dialog for creating a new object.

View Replication Status

The replication status of a server monitored by MariaDB-Monitor can be viewed by mousing over the server name. A tooltip will be displayed with the following information: replication_state, seconds_behind_master, slave_io_running, slave_sql_running.

How to kill a session

A session can be killed easily on the "Current Sessions" list which can be found on the Dashboard, Server detail, and Service detail page.

Annotation

Kill session button. This button is shown on the mouse hover.
Confirm killing the session dialog.

View sessions created by the "Workspace"

Sessions created by the "Workspace", such as via the Query Editor can be found in two places:

Dashboard "Current Sessions" tab

Annotation

A session with an icon next to the "CLIENT" column indicates a connection created by the "Workspace".

Query Editor "Processlist"

This table displays the result set from the PROCESSLIST table, with options to filter processes created by the "Workspace".

Annotation

Filter option.

Detail

This page shows information on each MaxScale object and allow to edit its parameter, relationships and perform other manipulation operations. Most of the control buttons will be shown on the mouse hover. Below is a screenshot of a Monitor Detail page, other Detail pages also have a similar layout structure so this is used for illustration purpose.

Annotation

Settings option. Clicking on the gear icon will show icons allowing to do different operations depending on the type of the Detail page.

Monitor Detail page, there are icons to Stop, Start, and Destroy monitor.
Service Detail page, there are icons to Stop, Start, and Destroy service.
Server Detail page, there are icons to Set maintenance mode, Clear server state, Drain and Delete server.
Filter and Listener Detail page, there is a delete icon to delete the object.

Switchover button. This button is shown on the mouse hover allowing to swap the running primary server with a designated secondary server.
Edit parameters button. This button is shown on the mouse hover allowing to edit the MaxScale object's parameter. Clicking on it will enable editable mode on the table. After finishing editing the parameters, simply click the Done Editing button.
A Detail page has tables showing "Relationship" between other MaxScale object. This "unlink" icon is shown on the mouse hover allowing to remove the relationship between two objects.
This button is used to link other MaxScale objects to the relationship.

Visualization

This page visualizes MaxScale configuration and clusters.

Configuration

This page visualizes MaxScale configuration as shown in the figure below.

Annotation

A MaxScale object (a node graph). The position of the node in the graph can be changed by dragging and dropping it.
Anchor link. The detail page of each MaxScale object can be accessed by clicking on the name of the node.
Filter visualization button. By default, if the number of filters used by a service is larger than 3, filter nodes aren't visualized as shown in the figure. Clicking this button will visualize them.
Hide filter visualization button.
Refresh rate dropdown. The frequency with which the data is refreshed.
Create a new MaxScale object button.
Zoom level control.
Export diagram as jpeg.

Clusters

This page shows all monitor clusters using mariadbmon module in a card-like view. Clicking on the card will visualize the cluster into a tree graph as shown in the following figure.

Annotation

Drag a secondary server on top of a primary server to promote the secondary server as the new primary server.
Server manipulation operations button. Showing a dropdown with the following operations:

Set maintenance mode: Setting a server to a maintenance mode.
Clear server state: Clear current server state.
Drain server: Drain the server of connections.

Quick access to query editor button. Opening the Query Editor page for this server. If the connection is already created for that server, it'll use it. Otherwise, it creates a blank worksheet and shows a connection dialog to connect to that server.
Carousel navigation button. Viewing more information about the server in the next slide.
Collapse the carousel.
Anchor link of the server. Opening the detail page of the server in a new tab.
Collapse its children nodes.
Rejoin node. When the auto_rejoin parameter is disabled, the node can be manually rejoined by dragging it on top of the primary server.
Monitor manipulation operations button. Showing a dropdown with the following operations:

Stop monitor.
Start monitor.
Destroy monitor.
Reset Replication.
Release ownership.
Master failover. Manually performing a primary failover. This option is visible only when the auto_failover parameter is disabled.

ColumnStore operations:

Stop cluster.
Start cluster.
Set cluster Read-Only.
Set cluster Read-Write.
Add node to cluster.
Remove node from cluster.

Refresh rate dropdown. The frequency with which the data is refreshed.
Create a new MaxScale object button.

Settings

This page shows and allows editing of MaxScale parameters.

Annotation

Edit parameters button. This button is shown on the mouse hover allowing to edit the MaxScale parameter. Clicking on it will enable editable mode on the table.
Editable parameters are visible as it's illustrated in the screenshot.
After finishing editing the parameters, simply click the Done Editing button.

Logs Archive

This page show real-time MaxScale logs with filter options.

Annotation

Filter by priorities.
Apply filter button.

Workspace

On this page, you may add numerous worksheets, each of which can be used for "Run queries", "Data migration", or "Create an ERD" task.

Run Queries

Clicking on the "Run Queries" card will open a dialog, providing options to establish a connection to different MaxScale object types, including "Listener, Server, Service".

The Query Editor worksheet will be rendered in the active worksheet after correctly connecting.

Query Editor worksheet

There are various features in the Query Editor worksheet, the most notable ones are listed below.

Create a new connection

If the connection of the Query Editor expires, or if you wish to make a new connection for the active worksheet, simply clicking on the button located on the right side of the query tabs navigation bar which features a server icon and an active connection name as a label. This will open the connection dialog and allow you to create a new connection.

Schemas objects sidebar

Set the current database

There are two ways to set the current database:

Double-click on the name of the database.
Right-click on the name of the database to show the context menu, then select the Use database option.

Preview table data of the top 1000 rows

There are two ways to preview data of a table:

Click on the name of the table.
Right-click on the name of the table to show the context menu, then select the Preview Data (top 1000) option.

Describe table

Right-click on the name of the table to show the context menu, then select theView Details option.

Alter/Drop/Truncate/Create table

Right-click on the name of the table to show the context menu, then select the desired option.

Alter/Drop/Create schema

Right-click on the name of the schema to show the context menu, then select the desired option.

Alter/Create View, Function, Stored Procedure, Trigger

Right-click on the group node (e.g., Views, Functions, Stored Procedures, Triggers) to show the context menu, then select the desired option.

Quickly insert an object into the editor

There are two ways to quickly insert an object to the editor:

Drag the object and drop it in the desire position in the editor.
Right-click on the object to show the context menu, then mouse hover the Place to Editor option and select the desired insert option.

Show object creation statement and insights info

To view the statement that creates the given object in the Schemas objects sidebar, right-clicking on schema or table node and select the View Insights option. For other objects such as view, stored procedure, function and trigger, select the Show Create option.

Editor

The editor is powered by Monaco editor, therefore, its features are similar to those of Visual Studio Code.

To see the command palette, press F1 while the cursor is active on the editor.

The editor also comes with various options to assist your querying tasks. To see available options, right-click on the editor to show the context menu.

The editor is powered by Monaco editor, therefore, its features are similar to those of Visual Studio Code.

How to write compound statements

By default, all statements in the "Query Tab" are split by semicolons and executed one by one on the server. To write the compound statements, use the DELIMITER command to change the delimiter.

Annotation

Change the delimiter to //
End of the statement using the new delimiter
Change the delimiter back to the default semicolon.

Re-execute old queries

Every executed query will be saved in the browser's storage (IndexedDB). Query history can be seen in the History/Snippets tab. To re-execute a query, follow the same step to insert an object into the editor and click the execute query button in the editor.

Create query snippet

Press CTRL/CMD + D to save the current SQL in the editor to the snippets storage. A snippet is created with a prefix keyword, so when that keyword is typed in the editor, it will be suggested in the "code completion" menu.

Generate an ERD

To initiate the process, either right-click on the schema name and select theGenerate ERD option, or click on the icon button that resembles a line graph, located on the schemas sidebar. This will open a dialog for selecting the tables for the diagram.

Data Migration

Clicking on the "Data Migration" card will open a dialog, providing an option. to name the task. The Data Migration worksheet will be rendered in the active worksheet after clicking the Create button in the dialog.

Data Migration worksheet

MaxScale uses ODBC for extracting and loading from the data source to a server in MaxScale. Before starting a migration, ensure that you have set up the necessary configurations on the MaxScale server. Instruction can be found here and limitations here.

Connections

Source connection shows the most common parameter inputs for creating an ODBC connection. For extra parameters, enable the Advanced mode to manually edit the Connection String input.

After successfully connected to both source and destination servers, click on the Select objects to migrate to navigate to the next stage.

Objects Selection

Select the objects you wish to migrate to the MariaDB server.

After selecting the desired objects, click on the Prepare Migration Script to navigate to the next stage. The migration scripts will be generated differently based on the value selected for the Create mode input. Hover over the question icon for additional information on the modes.

Migration

As shown in the screenshot, you can quickly modify the script for each object by selecting the corresponding object in the table and using the editors on the right-hand side to make any necessary changes.

After clicking the Start Migration button, the script for each object will be executed in parallel.

Migration report

If errors are reported for certain objects, review the output messages and adjust the script accordingly. Then, click the Manage button and select Restart.

To migrate additional objects, click the Manage button and selectMigrate other objects. Doing so will replace the current migration report for the current object with a new one.

To retain the report and terminate open connections after migration, click theManage button, then select Disconnect, and finally delete the worksheet.

Deleting the worksheet will not delete the migration task. To clean-up everything after migration, click the Manage button, then selectDelete.

Create an ERD

There are various features in the ERD worksheet, the most notable ones are listed below.

ERD worksheet

From an empty new worksheet, clicking on the "Create an ERD" card will open a connection dialog. After connecting successfully, the ERD worksheet will be rendered in the active worksheet. The connection is required to retrieve essential metadata, such as engines, character sets, and collation.

Generate an ERD from the existing databases

Click on the icon button featured as a line graph, located on the top toolbar next to the connection button. This will open a dialog for selecting the tables for the diagram.

Create a new ERD

New tables can be created by using either of the following methods:

Click on the icon button that resembles a line graph, located on the top toolbar.
Right-click on the diagram board and select the Create Table option.

Entity options

Two options are available: Edit Table and Remove from Diagram. These options can be accessed using either of the following methods:

Right-click on the entity and choose the desired option.
Hover over the entity, click the gear icon button, and select the desired option.

For quickly editing or viewing the table definitions, double-clicking on the entity. The entity editor will be shown at the bottom of the worksheet.

Foreign keys quick common options

Edit Foreign Key, this opens an editor for viewing/editing foreign keys.
Remove Foreign Key.
Change to One To One or Change to One To Many. Toggling the uniqueness of the foreign key column.
Set FK Column Mandatory or Set FK Column Optional. Toggling theNOT NULL option of the foreign key column.
Set Referenced Column Mandatory or Set Referenced Column Optional Toggling the NOT NULL option of the referenced column.

To show the above foreign key common options, perform a right-click on the link within the diagram.

Viewing foreign key constraint SQL

Hover over the link in the diagram, the constraint SQL of that foreign key will be shown in a tooltip.

Quickly draw a foreign key link

As shown in the screenshot, a foreign key can be quickly established by performing the following actions:

Click on the entity that will have the foreign key.
Click on the connecting point of the desired foreign key column and drag it over the desired referenced column.

Entity editor

Table columns, foreign keys and indexes can be modified via the entity editor which can be accessed quickly by double-clicking on the entity.

Export options

Three options are available: Copy script to clipboard, Export script andExport as jpeg. These options can be accessed using either of the following methods:

Right-click on the diagram board and choose the desired option.
Click the export icon button, and select the desired option.

Applying the script

Click the icon button resembling a play icon to execute the generated script for all tables in the diagram. This action will prompt a confirmation dialog for script execution. If needed, the script can be manually edited using the editor within the dialog.

Visual Enhancement options

The first section of the top toolbar, there are options to improve the visual of the diagram as follows:

Change the shape of links.
Draw foreign keys to columns.
Auto-arrange entities.
Highlight relationship.
Zoom control.

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

Common Monitor Parameters

This document settings supported by all monitors. These should be defined in the monitor section of the configuration file.

Settings

`module`

Type: string
Mandatory: Yes
Dynamic: No

The monitor module this monitor should use. Typically mariadbmon orgaleramon.

`user`

Type: string
Mandatory: Yes
Dynamic: Yes

Username used by the monitor to connect to the backend servers. If a server defines the monitoruser parameter, that value will be used instead.

`password`

Type: string
Mandatory: Yes
Dynamic: Yes

Password for the user defined with the user parameter. If a server defines the monitorpw parameter, that value will be used instead.

Note: In older versions of MaxScale this parameter was called passwd. The use of passwd was deprecated in MaxScale 2.3.0.

`servers`

Type: string
Mandatory: Yes
Dynamic: Yes

A comma-separated list of servers the monitor should monitor.

servers=MyServer1,MyServer2

`monitor_interval`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 2s

Defines how often the monitor updates the status of the servers. Choose a lower value if servers should be queried more often. The smallest possible value is 100 milliseconds. If querying the servers takes longer than monitor_interval, the effective update rate is reduced.

monitor_interval=2s

The interval is specified as documented here. If no explicit unit is provided, the value is interpreted as milliseconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected.

`backend_connect_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 3s

This parameter controls the timeout for connecting to a monitored server. The interval is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second. The minimum value is 1 second.

backend_connect_timeout=3s

`backend_write_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 3s

This parameter controls the timeout for writing to a monitored server. The timeout is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second. The minimum value is 1 seconds.

backend_write_timeout=3s

`backend_read_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 3s

This parameter controls the timeout for reading from a monitored server. The timeout is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second. The minimum value is 1 second.

backend_read_timeout=3s

`backend_connect_attempts`

Type: number
Mandatory: No
Dynamic: Yes
Default: 1

This parameter defines the maximum times a backend connection is attempted every monitoring loop. Every attempt may take up to backend_connect_timeout seconds to perform. If none of the attempts are successful, the backend is considered to be unreachable and down.

backend_connect_attempts=1

`disk_space_threshold`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This parameter duplicates the disk_space_thresholdserver parameter. If the parameter has not been specified for a server, then the one specified for the monitor is applied.

NOTE: Since MariaDB 10.4.7, MariaDB 10.3.17 and MariaDB 10.2.26, the information will be available only if the monitor user has the FILE privilege.

That is, if the disk configuration is the same on all servers monitored by the monitor, it is sufficient (and more convenient) to specify the disk space threshold in the monitor section, but if the disk configuration is different on all or some servers, then the disk space threshold can be specified individually for each server.

For example, suppose server1, server2 and server3 are identical in all respects. In that case we can specify disk_space_threshold in the monitor.

[server1]
type=server
...

[server2]
type=server
...

[server3]
type=server
...

[monitor]
type=monitor
servers=server1,server2,server3
disk_space_threshold=/data:80
...

However, if the servers are heterogeneous with the disk used for the data directory mounted on different paths, then the disk space threshold must be specified separately for each server.

[server1]
type=server
disk_space_threshold=/data:80
...

[server2]
type=server
disk_space_threshold=/Data:80
...

[server3]
type=server
disk_space_threshold=/DBData:80
...

[monitor]
type=monitor
servers=server1,server2,server3
...

If most of the servers have the data directory disk mounted on the same path, then the disk space threshold can be specified on the monitor and separately on the server with a different setup.

[server1]
type=server
disk_space_threshold=/DbData:80
...

[server2]
type=server
...

[server3]
type=server
...

[monitor]
type=monitor
servers=server1,server2,server3
disk_space_threshold=/data:80
...

Above, server1 has the disk used for the data directory mounted at /DbData while both server2 and server3 have it mounted on/data and thus the setting in the monitor covers them both.

`disk_space_check_interval`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 0s

With this parameter it can be specified the minimum amount of time between disk space checks. The interval is specified as documented here. If no explicit unit is provided, the value is interpreted as milliseconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. The default value is 0, which means that by default the disk space will not be checked.

Note that as the checking is made as part of the regular monitor interval cycle, the disk space check interval is affected by the value ofmonitor_interval. In particular, even if the value ofdisk_space_check_interval is smaller than that of monitor_interval, the checking will still take place at monitor_interval intervals.

`script`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This command will be executed on a server state change. The parameter should be an absolute path to a command or the command should be in the executable path. The user running MaxScale should have execution rights to the file itself and the directory it resides in. The script may have placeholders which MaxScale will substitute with useful information when launching the script.

The placeholders and their substitution results are:

$INITIATOR -> IP and port of the server which initiated the event
$EVENT -> event description, e.g. "server_up"
$LIST -> list of IPs and ports of all servers
$NODELIST -> list of IPs and ports of all running servers
$SLAVELIST -> list of IPs and ports of all replica servers
$MASTERLIST -> list of IPs and ports of all primary servers
$SYNCEDLIST -> list of IPs and ports of all synced Galera nodes
$PARENT -> IP and port of the parent of the server which initiated the event. For primary-replica setups, this will be the primary if the initiating server is a replica.
$CHILDREN -> list of IPs and ports of the child nodes of the server who initiated the event. For primary-replica setups, this will be a list of replica servers if the initiating server is a primary.

The expanded variable value can be an empty string if no servers match the variable's requirements. For example, if no primaries are available $MASTERLIST will expand into an empty string. The list-type substitutions will only contain servers monitored by the current monitor.

script=/home/user/myscript.sh initiator=$INITIATOR event=$EVENT live_nodes=$NODELIST

The above script could be executed as:

/home/user/myscript.sh initiator=[192.168.0.10]:3306 event=master_down live_nodes=[192.168.0.201]:3306,[192.168.0.121]:3306

See section Script example below for an example script.

Any output by the executed script will be logged into the MaxScale log. Each outputted line will be logged as a separate log message.

The log level on which the messages are logged depends on the format of the messages. If the first word in the output line is one of alert:, error:,warning:, notice:, info: or debug:, the message will be logged on the corresponding level. If the message is not prefixed with one of the keywords, the message will be logged on the notice level. Whitespace before, after or between the keyword and the colon is ignored and the matching is case-insensitive.

Currently, the script must not execute any of the following MaxCtrl calls as they cause a deadlock:

alter monitor to the monitor executing the script
stop monitor to the monitor executing the script
call command to a MariaDB-Monitor that is executing the script

`script_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 90s

The timeout for the executed script. The interval is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

If the script execution exceeds the configured timeout, it is stopped by sending a SIGTERM signal to it. If the process does not stop, a SIGKILL signal will be sent to it once the execution time is greater than twice the configured timeout.

`events`

Type: enum
Mandatory: No
Dynamic: Yes
Values: master_down, master_up, slave_down, slave_up, server_down, server_up, lost_master, lost_slave, new_master, new_slave
Default: All events

A list of event names which cause the script to be executed. If this option is not defined, all events cause the script to be executed. The list must contain a comma separated list of event names.

events=master_down,slave_down

The following table contains all the possible event types and their descriptions.

Event Name

Description

master_down

A Primary server has gone down

master_up

A Primary server has come up

slave_down

A Replica server has gone down

slave_up

A Replica server has come up

server_down

A server with no assigned role has gone down

server_up

A server with no assigned role has come up

lost_master

A server lost Primary status

lost_slave

A server lost Replica status

new_master

A new Primary was detected

new_slave

A new Replica was detected

`journal_max_age`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 28800s

The maximum journal file age. The interval is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the max age is seconds, a max age specified in milliseconds will be rejected, even if the duration is longer than a second.

When the monitor starts, it reads any stored journal files. If the journal file is older than the value of journal_max_age, it will be removed and the monitor starts with no prior knowledge of the servers.

Monitor Crash Safety

Starting with MaxScale 2.2.0, the monitor modules keep an on-disk journal of the latest server states. This change makes the monitors crash-safe when options that introduce states are used. It also allows the monitors to retain stateful information when MaxScale is restarted.

For MySQL monitor, options that introduce states into the monitoring process are the detect_stale_master and detect_stale_slave options, both of which are enabled by default. Galeramon has the disable_master_failback parameter which introduces a state.

The default location for the server state journal is in/var/lib/maxscale/<monitor name>/monitor.dat where <monitor name> is the name of the monitor section in the configuration file. If MaxScale crashes or is shut down in an uncontrolled fashion, the journal will be read when MaxScale is started. To skip the recovery process, manually delete the journal file before starting MaxScale.

Script example

Below is an example monitor configuration which launches a script with all supported substitutions. The example script reads the results and prints it to file and sends it as email.

[MyMonitor]
type=monitor
module=mariadbmon
servers=C1N1,C1N2,C1N3
user=maxscale
password=password
monitor_interval=10s
script=/path/to/maxscale_monitor_alert_script.sh --initiator=$INITIATOR --parent=$PARENT --children=$CHILDREN --event=$EVENT --node_list=$NODELIST --list=$LIST --master_list=$MASTERLIST --slave_list=$SLAVELIST --synced_list=$SYNCEDLIST

File "maxscale_monitor_alert_script.sh":

#!/usr/bin/env bash

initiator="" parent="" children="" event="" node_list="" list="" master_list="" slave_list="" synced_list=""

process_arguments() { while [ "$1" != "" ]; do if [[ "$1" =~ ^--initiator=.* ]]; then initiator=${1#'--initiator='} elif [[ "$1" =~ ^--parent.* ]]; then parent=${1#'--parent='} elif [[ "$1" =~ ^--children.* ]]; then children=${1#'--children='} elif [[ "$1" =~ ^--event.* ]]; then event=${1#'--event='} elif [[ "$1" =~ ^--node_list.* ]]; then node_list=${1#'--node_list='} elif [[ "$1" =~ ^--list.* ]]; then list=${1#'--list='} elif [[ "$1" =~ ^--master_list.* ]]; then master_list=${1#'--master_list='} elif [[ "$1" =~ ^--slave_list.* ]]; then slave_list=${1#'--slave_list='} elif [[ "$1" =~ ^--synced_list.* ]]; then synced_list=${1#'--synced_list='} fi shift done }

process_arguments $@ read -r -d '' MESSAGE << EOM A server has changed state. The following information was provided:

Initiator: $initiator Parent: $parent Children: $children Event: $event Node list: $node_list List: $list Primary list: $master_list Replica list: $slave_list Synced list: $synced_list EOM

print message to file

echo "$MESSAGE" > /path/to/script_output.txt

email the message

echo "$MESSAGE" | mail -s "MaxScale received $event event for initiator $initiator." mariadb_admin@domain.com |

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

Upgrading MaxScale

Before upgrading to MariaDB MaxScale, it is critical to review the changes. This guide outlines new features, altered parameters, and deprecated functionality to ensure a smooth transition.

For more information about what has changed, please refer to the ChangeLog and to the release notes.

Before starting the upgrade, any existing configuration files should be backed up.

Upgrading MariaDB MaxScale from 24.02 to 25.01

Readwritesplit

`reuse_prepared_statements`

The reuse_prepared_statements parameter has been replaced with the use of the PsReuse filter module.

The functionality that previously was enabled with:

[My-Readwritesplit]
type=service
router=readwritesplit
reuse_prepared_statements=true

Should now be implemented with:

[PsReuse]
type=filter
module=psreuse

[My-Readwritesplit]
type=service
router=readwritesplit
filters=PsReuse

`optimistic_trx`

The optimistic_trx parameter has been replaced with the use of the OptimisticTrx filter module.

The functionality that previously was enabled with:

[My-Readwritesplit]
type=service
router=readwritesplit
optimistic_trx=true

Should now be implemented with:

[OptimisticTrx]
type=filter
module=optimistictrx

[My-Readwritesplit]
type=service
router=readwritesplit
transaction_replay=true
filters=OptimisticTrx

Upgrading MariaDB MaxScale from 23.08 to 24.02

Downgrading to older major versions

The MaxScale packaging has been modified in 24.02 to include all of the necessary files in the package itself. This removes the need for a post-installation script that installs them while also clearly stating what's included in the package.

However, as a result of this change, downgrades from 24.02 to older major versions may cause the removal of necessary directories, namely the /var/cache/maxscale/ directory.

To downgrade from MaxScale 24.02 to an older MaxScale major release:

Remove MaxScale 24.02 (e.g. dnf remove maxscale or apt -y remove maxscale)
Install the older MaxScale version

Upgrading MariaDB MaxScale from 23.02 to 23.08

MariaDB Monitor switchover requires an additional grant on MariaDB Server 10.5 and later. See Cluster Manipulation Grants for more information.

Upgrading MariaDB MaxScale from 22.08 to 23.02

Removed Features

The csmon and auroramon monitors have been removed.
The obsolete maxctrl drain command has been removed.
The maxctrl cluster commands have been removed.

Upgrading MariaDB MaxScale from 21.06 to 22.08

Removed Features

The support for legacy encryption keys generated with maxkeys from pre-2.5 versions has been removed. This feature was deprecated in MaxScale 2.5 when the new key storage format was introduced. To migrate to the new key storage format, create a new key file with maxkeys and re-encrypt the passwords withmaxpasswd.
The deprecated Database Firewall filter has been removed.

Upgrading MariaDB MaxScale from 2.5 to 21.06

MaxScale 6.4 was renamed to 21.06 in May 2024. Thus, what would have been released as 6.4.16 in June, was released as 21.06.16. The purpose of this change is to make the versioning scheme used by all MaxScale series identical. 21.06 denotes the year and month when the first 6 release was made.

Duration Type Parameters

Using duration type parameters without an explicit suffix has been deprecated in MaxScale 2.4. In MaxScale 6 they are no longer allowed when used with the REST API or MaxCtrl. This means that any create or alter commands in MaxCtrl that use a duration type parameter must explicitly specify the suffix of the unit.

For example, the following command:

maxctrl alter service My-Service connection_keepalive 30000

should be replaced with:

maxctrl alter service My-Service connection_keepalive 30000ms

Duration type parameters can still be defined in the configuration file without an explicit suffix but this behavior is deprecated. The recommended approach is to add explicit suffixes to all duration type parameters when upgrading to MaxScale 6.

Changed Parameters

`threads`

The default value of threads was changed to auto.

Removed Parameters

Core Parameters

The following deprecated core parameters have been removed:

thread_stack_size

Schemarouter

The deprecated aliases for the schemarouter parameters ignore_databases andignore_databases_regex have been removed. They can be replaced withignore_tables and ignore_tables_regex.

In addition, the preferred_server parameter that was deprecated in 2.5 has also been removed.

`mariadbmon`

MariaDBMonitor settings ignore_external_masters, detect_replication_lagdetect_standalone_master, detect_stale_master and detect_stale_slave have been removed. The first two were ineffective, the latter three are replaced by master_conditions and slave_conditions.

Session Command History

The prune_sescmd_history, max_sescmd_history and disable_sescmd_history have been made into generic service parameters that are shared between all routers that support it.

The default value of prune_sescmd_history was changed from false totrue. This was done as most MaxScale installations either benefit from it being enabled or are not affected by it.

Upgrading MariaDB MaxScale from 2.4 to 2.5

MaxAdmin

The deprecated MaxAdmin interface has been removed in 2.5.0 in favor of the REST API and the MaxCtrl command line client. The cli and maxscaled modules can no longer be used.

Authentication

The credentials used by services now require additional grants. For a full list of required grants, refer to the protocol documentation.

MariaDB-Monitor

The settings detect_stale_master, detect_standalone_master anddetect_stale_slave are replaced by master_conditions andslave_conditions. The old settings may still be used, but will be removed in a later version.

Password encryption

The encrypted passwords feature has been updated to be more secure. Users are recommended to generate a new encryption key and re-encrypt their passwords using the maxkeys and maxpasswd utilities. Old passwords still work.

Default Server State

The default state of servers in 2.4 was Running and in 2.5 it is nowDown. This was done to prevent newly added servers from being accidentally used before they were monitored.

Columnstore Monitor

It is now mandatory to specify in the configuration what version the monitored Columnstore cluster is.

[CSMonitor]
type=monitor
module=csmon
version=1.5
...

New binlog router

The binlog router delivered with MaxScale 2.5 is completely new and not 100% backward compatible with the binlog router delivered with earlier MaxScale versions. If you use the binlog router, carefully assess whether the functionality provided by the new one fulfills your requirements, before upgrading MaxScale.

Tee Filter

The tee filter parameter service has been deprecated in favor of the target parameter. All usages of service can be replaced with target.

Upgrading MariaDB MaxScale from 2.3 to 2.4

Section Names

Reserved Names

Section and object names starting with @@ are now reserved for internal use by MaxScale.

In case such names have been used, they must manually be changed in all configuration files of MaxScale, before MaxScale 2.4 is started.

Those files are:

The main configuration file; typically /etc/maxscale.cnf.
All nested configuration files; typically /etc/maxscale.cnf.d/*.
All dynamic configuration files; typically /var/lib/maxscale/maxscale.cnd.d/*.

Whitespace in Names

Whitespace in section names that was deprecated in MaxScale 2.2 will now be rejected, which will cause the startup of MaxScale to fail.

To prevent that, section names like

[My Server]
...

[My Service]
...
servers=My Server

must be changed, for instance, to

[MyServer]
...

[MyService]
...
servers=MyServer

Durations

Durations can now be specified using one of the suffixes h, m, s and ms for specifying durations in hours, minutes, seconds and milliseconds, respectively.

Not providing an explicit unit has been deprecated in MaxScale 2.4, so it is advisable to add suffixes to durations. For instance,

some_param=60s
some_param=60000ms

Improved Admin User Encryption

MaxScale 2.4 will use a SHA2-512 hash for new admin user passwords. To upgrade a user to use the better hashing algorithm, either recreate the user or use themaxctrl alter user command.

MariaDB-Monitor

The following settings have been removed and cause a startup error if defined:

mysql51_replication
multimaster
allow_cluster_recovery.

ReadWriteSplit

If multiple masters are available for a readwritesplit service, the one with the lowest connection count is selected.
If a master server is placed into maintenance mode, all open transactions are allowed to gracefully finish before the session is closed. To forcefully close the connections, use the --force option for maxctrl set server.
The lazy_connect feature can be used as a workaround to MXS-619. It also reduces the overall load on the system when connections are rapidly opened and closed.
Transaction replays now have a limit on how many times a replay is attempted. The default values is five attempts and is controlled by thetransaction_replay_attempts parameter.
If transaction replay is enabled and a deadlock occurs (SQLSTATE 40XXX), the transaction is automatically retried.

Upgrading MariaDB MaxScale from 2.2 to 2.3

Increased Memory Use

Starting with MaxScale 2.3.0 up to 40% of the memory can be used for caching parsed queries. The most noticeable change is that it improves performance in almost all cases where queries need to be parsed. Most of the time this happens when the readwritesplit router or filters are used.

The amount of memory that MaxScale uses can be controlled with thequery_classifier_cache_size parameter. For example, to limit the total memory to 1GB, add query_classifier_cache_size=1G to your configuration. To disable it, set the value to 0.

In addition to the aforementioned query classifier caching, the readwritesplit session command history is enabled by default in 2.3 but is limited to a maximum of 50 commands after which the history is disabled. This is unlikely to show in any metrics but it contributes to the increased memory footprint of MaxScale.

Unknown Global Parameters

All unknown parameters are now treated as errors. Check your configuration for errors if MaxScale fails to start after upgrading to 2.3.1.

`passwd` is deprecated

In the configuration file, passwords for monitors and services should be specified using password; the support for the deprecatedpasswd will be removed in the future. That is, the following

[The-Service]
type=service
passwd=some-service-password
...

[The-Monitor]
type=monitor
passwd=some-monitor-password
...

should be changed to

[The-Service]
type=service
password=some-service-password
...

[The-Monitor]
type=monitor
password=some-monitor-password
...

`authenticator_options` for servers is ignored

Authenticator options are now only used with listeners.

Upgrading MariaDB MaxScale from 2.1 to 2.2

Administrative Users

The file format for the administrative users used by MaxScale has been changed. Old style files are automatically upgraded and a backup of the old file is stored in /var/lib/maxscale/passwd.backup.

Regular Expression Parameters

Modules may now use a built-in regular expression string parameter type instead of a normal string when accepting patterns. The modules that use the new regex parameter type are qlafilter and tee. When inputting pattern, enclose the string in slashes, e.g. match=/^select/ defines the pattern ^select.

Binlog Server

Binlog server automatically accepts GTID connection from MariaDB 10 slave servers by saving all incoming GTIDs into a SQLite map database.

MaxCtrl Included in Main Package

In the 2.2.1 beta version MaxCtrl was in its own package whereas in 2.2.2 it is in the main maxscale package. If you have a previous installation of MaxCtrl, please remove it before upgrading to MaxScale 2.2.2.

Upgrading MariaDB MaxScale from 2.0 to 2.1

IPv6 Support

MaxScale 2.1.2 added support for IPv6 addresses. The default interface that listeners bind to was changed from the IPv4 address 0.0.0.0 to the IPv6 address ::. To bind to the old IPv4 address, add address=0.0.0.0 to the listener definition.

Persisted Configuration Files

Starting with MaxScale 2.1, any changes made with the newly added runtime configuration change will be persisted in a configuration file. These files are located in /var/lib/maxscale/maxscale.cnf.d/.

MaxScale Log Files

The name of the log file was changed from maxscaleN.log to maxscale.log. The default location for the log file is /var/log/maxscale/maxscale.log.

Rotating the log files will cause MaxScale to reopen the file instead of renaming them. This makes the MaxScale logging facility logrotate compatible.

ReadWriteSplit

The disable_sescmd_history option is now enabled by default. This means that slaves will not be recovered mid-session even if a replacement slave is available. To enable the legacy behavior, add the disable_sescmd_history=true parameter to the service definition.

Persistent Connections

The MariaDB session state is reset in MaxScale 2.1 for persistent connections. This means that any modifications to the session state (default database, user variable etc.) will not survive if the connection is put into the connection pool. For most users, this is the expected behavior.

User Data Cache

The location of the MariaDB user data cache was moved from/var/cache/maxscale/<Service> to /var/cache/maxscale/<Service>/<Listener>.

Galeramon Monitoring Algorithm

Galeramon will assign the master status only to the node which has awsrep_local_index value of 0. This will guarantee consistent writes with multiple MaxScales but it also causes slower changes of the master node.

To enable the legacy behavior, add root_node_as_master=false to the Galera monitor configuration.

MaxAdmin Editing Mode

The default editing mode was changed from vim to emacs mode. To start maxadmin in the legacy mode, use the -i option.

Upgrading MariaDB MaxScale from 1.4 to 2.0

MaxAdmin

The default way the communication between MaxAdmin and MariaDB MaxScale is handled has been changed from an internet socket to a Unix domain socket. The former alternative is still available but has been deprecated.

If no arguments are given to MaxAdmin, it will attempt to connect to MariaDB MaxScale using a Unix domain socket. After the upgrade you will need to provide at least one internet socket related flag - -h, -P,-u or -p - to force MaxAdmin to use the internet socket approach.

E.g.

user@host $ maxadmin -u admin

MySQL Monitor

The MySQL Monitor now assigns the stale state to the master server by default. In addition to this, the slave servers receive the stale slave state when they lose the connection to the master. This should not cause changes in behavior but the output of MaxAdmin will show new states when replication is broken.

Upgrading MaxScale from 1.3 to 1.4

Service user permissions

The service users now also need SELECT privileges on mysql.tables_priv. This is required for the resolution of table level grants. To grant SELECT privileges for the service user, replace the user and hostname in the following example.

GRANT SELECT ON mysql.tables_priv TO 'username'@'maxscalehost';

Password encryption

MaxScale 1.4 upgrades the used password encryption algorithms to more secure ones. This requires that the password files are recreated with the maxkeys tool. For more information about how to do this, please read the installation guide:MariaDB MaxScale Installation Guide

SSL

The SSL configuration parameters are now a part of the listeners. If a service used the old style SSL configuration parameters, the values should be moved to the listener which is associated with that service.

Here is an example of an old style configuration.

[RW-Split-Router]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=jdoe
passwd=BD26E4139A15280CA882264AA1551C70
ssl=required
ssl_cert=/home/user/certs/server-cert.pem
ssl_key=/home/user/certs/server-key.pem
ssl_ca_cert=/home/user/certs/ca.pem
ssl_version=TLSv12

[RW-Split-Listener]
type=listener
service=RW-Split-Router
port=3306

And here is the new, 1.4 compatible configuration style.

[RW-Split-Router]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=jdoe
passwd=BD26E4139A15280CA882264AA1551C70

[RW-Split-Listener]
type=listener
service=RW-Split-Router
port=3306
ssl=required
ssl_cert=/home/user/certs/server-cert.pem
ssl_key=/home/user/certs/server-key.pem
ssl_ca_cert=/home/user/certs/ca.pem
ssl_version=TLSv12

Please also note that the enabled SSL mode is no longer supported due to the inherent security issues with allowing SSL and non-SSL connections on the same port. In addition to this, SSLv3 is no longer supported due to vulnerabilities found in it.

Upgrading MaxScale from 1.2 to 1.3

Binlog Router

The master server details are now provided with a master.ini file located in the binlog directory and it can be changed using a CHANGE MASTER TO command issued via a MySQL connection to MaxScale.

This file, properly filled, is now mandatory and without it the binlog router cannot connect to the master database.

Before starting binlog router after MaxScale 1.3 upgrade, please add relevant information to master.ini, example:

[binlog_configuration]
master_host=127.0.0.1
master_port=3308
master_user=repl
master_password=somepass
filestem=repl-bin

Additionally, the option servers=masterdb in the service definition is no longer required.

Upgrading MaxScale from 1.1 to 1.2

This document describes upgrading MaxScale from version 1.1.1 to 1.2 and the major differences in the new version compared to the old version. The major changes can be found in the Changelog.txt file in the installation directory and the official release notes in the ReleaseNotes.txt file.

Installation

Upgrading MaxScale will copy the MaxScale.cnf file in/usr/local/mariadb-maxscale/etc/ to /etc/ and renamed to maxscale.cnf. Binary log files are not automatically copied and should be manually moved from /usr/local/mariadb-maxscale to /var/lib/maxscale/.

File location changes

MaxScale 1.2 follows the FHS-standard and installs to /usr/ and /var/ subfolders. Here are the major changes and file locations.

Configuration files are located in /etc/ and use lowercase letters: /etc/maxscale.cnf
Binary files are in /usr/bin/
Libraries and modules are in /usr/lib64/maxscale/. If you are using custom modules, please make sure they are in this directory before starting MaxScale.
Log files are in the var/log/maxscale/ folder
MaxScale's PID file is located in /var/run/maxscale/maxscale.pid
Data files and other persistent files are in /var/lib/maxscale/

Running MaxScale without root permissions

MaxScale can run as a non-root user with the 1.2 version. RPM and DEB packages install the maxscale user and maxscale group which are used by the init scripts and systemd configuration files. If you are installing from a binary tarball, you can run the postinst script included in it to manually create these groups.

Upgrading MaxScale from 1.0 to 1.1

This document describes upgrading MaxScale from version 1.0.5 to 1.1.0 and the major differences in the new version compared to the old version. The major changes can be found in the Changelog.txt file in the installation directory and the official release notes in the ReleaseNotes.txt file.

Installation

If you are installing MaxScale from a RPM package, we recommend you back up your configuration and log files and that you remove the old installation of MaxScale completely. If you choose to upgrade MaxScale instead of removing it and re-installing it afterwards, the init scripts in /etc/init.d folder will be missing. This is due to the RPM packaging system but the script can be re-installed by running the postinst script found in the/usr/local/mariadb-maxscale folder.

# Re-install init scripts
cd /usr/local/mariadb-maxscale
./postinst

The 1.1.0 version of MaxScale installs into /usr/local/mariadb-maxscale instead of /usr/local/skysql/maxscale. This will cause external references to MaxScale's home directory to stop working so remember to update all paths with the new version.

MaxAdmin changes

The MaxAdmin client's default password in MaxScale 1.1.0 is mariadb instead of skysql.

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

MaxScale Cache

Cache

Overview

From MaxScale version 2.2.11 onwards, the cache filter is no longer considered experimental. The following changes to the default behaviour have also been made:

The default value of cached_data is now thread_specific (used to beshared).
The default value of selects is now assume_cacheable (used to beverify_cacheable).

The cache filter is a simple cache that is capable of caching the result of SELECTs, so that subsequent identical SELECTs are served directly by MaxScale, without the queries being routed to any server.

By default the cache will be used and populated in the following circumstances:

There is no explicit transaction active, that is, autocommit is used,
there is an explicitly read-only transaction (that is,START TRANSACTION READ ONLY) active, or
there is a transaction active and no statement that modifies the database has been performed.

In practice, the last bullet point basically means that if a transaction has been started with BEGIN, START TRANSACTION or START TRANSACTION READ WRITE, then the cache will be used and populated until the first UPDATE,INSERT or DELETE statement is encountered.

That is, in default mode the cache effectively causes the system to behave as if the isolation level would be READ COMMITTED, irrespective of what the isolation level of the backends actually is.

The default behaviour can be altered using the configuration parameter cache_in_transactions.

By default it is assumed that all SELECT statements are cacheable, which means that also statements like SELECT LOCALTIME are cached. Please check selects for how to change the default behaviour.

Limitations

All of these limitations may be addressed in forthcoming releases.

Prepared Statements

Resultsets of prepared statements are not cached.

Multi-statements

Multi-statements are always sent to the backend and their result isnot cached.

Security

The cache is not aware of grants.

The implication is that unless the cache has been explicitly configured who the caching should apply to, the presence of the cache may provide a user with access to data he should not have access to.

Please read the section Security for more detailed information.

However, from 2.5 onwards it is possible to configure the cache to cache the data of each user separately, which effectively means that there can be no unintended sharing. Please see users for how to change the default behaviour.

`information_schema`

When invalidation is enabled, SELECTs targeting tables in information_schema are not cached. The reason is that as the content of the tables changes as the side-effect of something else, the cache would not know when to invalidate the cache-entries.

Invalidation

Since MaxScale 2.5, the cache is capable of invalidating entries in the cache when a modification (UPDATE, INSERT or DELETE) that may affect those entries is made.

The cache invalidation works on the table-level, that is, a modification made to a particular table will cause all cache entries that refer to that table to be invalidated, irrespective of whether the modification actually has an impact on the cache entries or not. For instance, suppose the result of the following SELECT has been cached

SELECT * FROM t WHERE a=1;

An insert like

INSERT INTO t SET a=42;

will cause the cache entry containing the result of that SELECT to be invalidated even if the INSERT actually does not affect it. Please see invalidate for how to enable the invalidation.

When invalidation has been enabled MaxScale must be able to completely parse a SELECT statement for its results to be stored in the cache. The reason is that in order to be able to invalidate cache entries, MaxScale must know what tables a SELECT statement depends upon. Consequently, if (and only if) invalidation has been enabled and MaxScale fails to parse a statement, the result of that particular statement will not be cached.

When invalidation has been enabled, MaxScale will also parse all UPDATE, INSERT and DELETE statements, in order to find out what tables are modified. If that parsing fails, MaxScale will by default clear the entire cache. The reason is that unless MaxScale can completely parse the statement it cannot know what tables are modified and hence not what cache entries should be invalidated. Consequently, to prevent stale data from being returned, the entire cache is cleared. The default behaviour can be changed using the configuration parameter clear_cache_on_parse_errors.

Note that what threading approach is used has a big impact on the invalidation. Please see Threads, Users and Invalidation for how the threading approach affects the invalidation.

Note also that since the invalidation may not, depending on how the cache has been configured, be visible to all sessions of all users, it is still important to configure a reasonable soft and hard TTL.

Best Efforts

The invalidation offered by the MaxScale cache can be said to be ofbest efforts quality. The reason is that in order to ensure that the cache in all circumstances reflects the state in the actual database, would require that the operations involving the cache and the MariaDB server are synchronized, which would cause an unacceptable overhead.

What best efforts means in this context is best illustrated using an example.

Suppose a client executes the statement SELECT * FROM tbl and that the result is cached. Next time that or any other client executes the same statement, the result is returned from the cache and the MariaDB server will not be accessed at all.

If a client now executes the statement INSERT INTO tbl VALUES (...), the cached value for the SELECT statement above and all other statements that are dependent upon tbl will be invalidated. That is, the next time someone executes the statement SELECT * FROM tbl the result will again be fetched from the MariaDB server and stored to the cache.

However, suppose some client executes the statement SELECT COUNT(*) FROM tbl at the same time someone else executes the INSERT ... statement. A possible chain of events is as follows:

Timeline 1                 Timeline 2

Clients execute       INSERT ...                 SELECT COUNT(*) FROM tbl
MaxScale -> DB                                   SELECT COUNT(*) FROM tbl
MaxScale -> DB        INSERT ...

That is, the SELECT is performed in the database server before theINSERT. However, since the timelines are proceeding independently of each other, the events may be re-ordered as far as the cache is concerned.

MaxScale -> Cache     Delete invalidated values
MaxScale -> Cache                                Store result and invalidation key

That is, the cached value for SELECT COUNT(*) FROM tbl will reflect the situation before the insert and will thus not be correct.

The stale result will be returned until the value has reached its time-to-live or its invalidation is caused by some update operation.

Configuration

The cache is simple to add to any existing service. However, some experimentation may be required in order to find the configuration settings that provide the maximum benefit.

[Cache]
type=filter
module=cache
hard_ttl=30
soft_ttl=20
rules=...
...

[Cached-Routing-Service]
type=service
...
filters=Cache

Each configured cache filter uses a storage of its own. That is, if there are two services, each configured with a specific cache filter, then, even if queries target the very same servers the cached data will not be shared.

Two services can use the same cache filter, but then either the services should use the very same servers or a completely different set of servers, where the used table names are different. Otherwise there can be unintended sharing.

Settings

The cache filter has no mandatory parameters but a range of optional ones. Note that it is advisable to specify max_size to prevent the cache from using up all memory there is, in case there is very little overlap among the queries.

`storage`

Type: string
Mandatory: No
Dynamic: No
Default: storage_inmemory

The name of the module that provides the storage for the cache. That module will be loaded and provided with the value of storage_options as argument. For instance:

storage=storage_redis

See Storage for what storage modules are available.

`storage_options`

Type: string
Mandatory: No
Dynamic: No
Default:

NOTE Deprecated in 23.02.

A string that is provided verbatim to the storage module specified in storage, when the module is loaded. Note that the needed arguments and their format depend upon the specific module.

From 23.02 onwards, the storage module configuration should be provided using nested parameters.

`hard_ttl`

Type: duration
Mandatory: No
Dynamic: No
Default: 0s (no limit)

Hard time to live; the maximum amount of time the cached result is used before it is discarded and the result is fetched from the backend (and cached). See also soft_ttl.

hard_ttl=60s

`soft_ttl`

Type: duration
Mandatory: No
Dynamic: No
Default: 0s (no limit)

Soft time to live; the amount of time - in seconds - the cached result is used before it is refreshed from the server. When soft_ttl has passed, the result will be refreshed when the first client requests the value.

However, as long as hard_ttl has not passed, all other clients requesting the same value will use the result from the cache while it is being fetched from the backend. That is, as long as soft_ttl but not hard_ttl has passed, even if several clients request the same value at the same time, there will be just one request to the backend.

soft_ttl=60s

If the value of soft_ttl is larger than hard_ttl it will be adjusted down to the same value.

`max_resultset_rows`

Type: count
Mandatory: No
Dynamic: No
Default: 0 (no limit)

Specifies the maximum number of rows a resultset can have in order to be stored in the cache. A resultset larger than this, will not be stored.

max_resultset_rows=1000

`max_resultset_size`

Type: size
Mandatory: No
Dynamic: No
Default: 0 (no limit)

Specifies the maximum size of a resultset, for it to be stored in the cache. A resultset larger than this, will not be stored. The size can be specified as described here.

max_resultset_size=128Ki

Note that the value of max_resultset_size should not be larger than the value of max_size.

`max_count`

Type: count
Mandatory: No
Dynamic: No
Default: 0 (no limit)

The maximum number of items the cache may contain. If the limit has been reached and a new item should be stored, then an older item will be evicted.

Note that if cached_data is thread_specific then this limit will be applied to each cache separately. That is, if a thread specific cache is used, then the total number of cached items is #threads * the value of max_count.

max_count=1000

`max_size`

Type: size
Mandatory: No
Dynamic: No
Default: 0 (no limit)

The maximum size the cache may occupy. If the limit has been reached and a new item should be stored, then some older item(s) will be evicted to make space.

Note that if cached_data is thread_specific then this limit will be applied to each cache separately. That is, if a thread specific cache is used, then the total size is #threads * the value of max_size.

max_size=100Mi

`rules`

Type: path
Mandatory: No
Dynamic: Yes
Default: "" (no rules)

Specifies the path of the file where the caching rules are stored. A relative path is interpreted relative to the data directory of MariaDB MaxScale.

rules=/path/to/rules-file

Note that the rules will be reloaded, and applied if different, every time a dynamic configuration change is made. Thus, to cause a reloading of the rules, alter the rules parameter to the same value it has.

maxctrl alter filter MyCache rules='/path/to/rules-file'

`cached_data`

Type: enum
Mandatory: No
Dynamic: No
Values: shared, thread_specific
Default: thread_specific

An enumeration option specifying how data is shared between threads. The allowed values are:

shared: The cached data is shared between threads. On the one hand it implies that there will be synchronization between threads, on the other hand that all threads will use data fetched by any thread.
thread_specific: The cached data is specific to a thread. On the one hand it implies that no synchronization is needed between threads, on the other hand that the very same data may be fetched and stored multiple times.

cached_data=shared

Default is thread_specific. See max_count and max_size what implication changing this setting to shared has.

`selects`

Type: enum
Mandatory: No
Dynamic: Yes
Values: assume_cacheable, verify_cacheable
Default: assume_cacheable

An enumeration option specifying what approach the cache should take with respect to SELECT statements. The allowed values are:

assume_cacheable: The cache can assume that all SELECT statements, without exceptions, are cacheable.
verify_cacheable: The cache can not assume that all SELECT statements are cacheable, but must verify that.

selects=verify_cacheable

Default is assume_cacheable. In this case, all SELECT statements are assumed to be cacheable and will be parsed only if some specific rule requires that.

If verify_cacheable is specified, then all SELECT statements will be parsed and only those that are safe for caching - e.g. do not call any non-cacheable functions or access any non-cacheable variables - will be subject to caching.

If verify_cacheable has been specified, the cache will not be used in the following circumstances:

The SELECT uses any of the following functions: BENCHMARK,CONNECTION_ID, CONVERT_TZ, CURDATE, CURRENT_DATE, CURRENT_TIMESTAMP,CURTIME, DATABASE, ENCRYPT, FOUND_ROWS, GET_LOCK, IS_FREE_LOCK,IS_USED_LOCK, LAST_INSERT_ID, LOAD_FILE, LOCALTIME, LOCALTIMESTAMP,MASTER_POS_WAIT, NOW, RAND, RELEASE_LOCK, SESSION_USER, SLEEP,SYSDATE, SYSTEM_USER, UNIX_TIMESTAMP, USER, UUID, UUID_SHORT.
The SELECT accesses any of the following fields: CURRENT_DATE,CURRENT_TIMESTAMP, LOCALTIME, LOCALTIMESTAMP
The SELECT uses system or user variables.

Note that parsing all SELECT statements carries a performance cost. Please read performance for more details.

`cache_in_transactions`

Type: enum
Mandatory: No
Dynamic: No
Values: never, read_only_transactions, all_transactions
Default: all_transactions

An enumeration option specifying how the cache should behave when there are active transactions:

never: When there is an active transaction, no data will be returned from the cache, but all requests will always be sent to the backend. The cache will be populated inside explicitly read-only transactions. Inside transactions that are not explicitly read-only, the cache will be populated until the first non-SELECT statement.
read_only_transactions: The cache will be used and populated inside explicitly read-only transactions. Inside transactions that are not explicitly read-only, the cache will be populated, but not used until the first non-SELECT statement.
all_transactions: The cache will be used and populated inside explicitly read-only transactions. Inside transactions that are not explicitly read-only, the cache will be used and populated until the first non-SELECT statement.

cache_in_transactions=never

Default is all_transactions.

The values read_only_transactions and all_transactions have roughly the same effect as changing the isolation level of the backend to read_committed.

`debug`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

An integer value, using which the level of debug logging made by the cache can be controlled. The value is actually a bitfield with different bits denoting different logging.

0 (0b00000) No logging is made.
1 (0b00001) A matching rule is logged.
2 (0b00010) A non-matching rule is logged.
4 (0b00100) A decision to use data from the cache is logged.
8 (0b01000) A decision not to use data from the cache is logged.
16 (0b10000) Higher level decisions are logged.

Default is 0. To log everything, give debug a value of 31.

debug=31

`enabled`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Specifies whether the cache is initially enabled or disabled.

enabled=false

The value affects the initial state of the MaxScale user variables using which the behaviour of the cache can be modified at runtime. Please see Runtime Configuration for details.

`invalidate`

Type: enum
Mandatory: No
Dynamic: No
Values: never, current
Default: never

An enumeration option specifying how the cache should invalidate cache entries.

* `never`: No invalidation is performed. This is the default.
* `current`: When a modification is made, entries in the cache used by
  the current session are invalidated. Other sessions that use the same
  cache will also be affected, but sessions that use another cache will
  not.

The effect of current depends upon the value of cached_data. If the value is shared, that is, all threads share the same cache, then the effect of an invalidation is immediately visible to all sessions, as there is just one cache. However, if the value is thread_specific, then an invalidation will affect only the cache that the session happens to be using.

If it is important and sufficient that an application immediately sees a change that it itself has caused, then a combination of invalidate=current and cached_data=thread_specific can be used.

If it is important that an application immediately sees all changes, irrespective of who has caused them, then a combination of invalidate=current and cached_data=shared must be used.

`clear_cache_on_parse_errors`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

This boolean option specifies how the cache should behave in case of parsing errors when invalidation has been enabled.

true: If the cache fails to parse an UPDATE/INSERT/DELETE statement then all cached data will be cleared.
false: A failure to parse an UPDATE/INSERT/DELETE statement is ignored and no invalidation will take place due that statement.

The default value is true.

Changing the value to false may mean that stale data is returned from the cache, if an UPDATE/INSERT/DELETE cannot be parsed and the statement affects entries in the cache.

`users`

Type: enum
Mandatory: No
Dynamic: No
Values: mixed, isolated
Default: mixed

An enumeration option specifying how the cache should cache data for different users.

* `mixed`: The data of different users is stored in the same
  cache. This is the default and may cause that a user can
  access data he should not have access to.
* `isolated`: Each user has a unique cache and there can be
  no unintended sharing.

Note that if isolated has been specified, then each user will conceptually have a cache of his own, which is populated independently from each other. That is, if two users make the same query, then the data will be fetched twice and also stored twice. So, a isolated cache will in general use more memory and cause more traffic to the backend compared to a mixed cache.

`timeout`

Type: duration
Mandatory: No
Dynamic: No
Default: 5s

The timeout used when performing operations to distributed storages such as redis or memcached.

timeout=7000ms

Runtime Configuration

The cache filter can be configured at runtime by executing SQL commands. If there is more than one cache filter in a service, only the first cache filter will be able to process the variables. The remaining filters will not see them and thus configuring them at runtime is not possible.

`@maxscale.cache.populate`

Using the variable @maxscale.cache.populate it is possible to specify at runtime whether the cache should be populated or not. Its initial value is the value of the configuration parameter enabled. That is, by default the value is true.

The purpose of this variable is make it possible for an application to decide statement by statement whether the cache should be populated.

SET @maxscale.cache.populate=TRUE;
SELECT a, b FROM tbl;
SET @maxscale.cache.populate=FALSE;
SELECT a, b FROM tbl;

In the example above, the first SELECT will always be sent to the server and the result will be cached, provided the actual cache rules specifies that it should be. The second SELECT may be served from the cache, depending on the value of @maxscale.cache.use (and the cache rules).

The value of @maxscale.cache.populate can be queried

SELECT @maxscale.cache.populate;

but only after it has been explicitly set once.

`@maxscale.cache.use`

Using the variable @maxscale.cache.use it is possible to specify at runtime whether the cache should be used or not. Its initial value is the value of the configuration parameter enabled. That is, by default the value is true.

The purpose of this variable is make it possible for an application to decide statement by statement whether the cache should be used.

SET @maxscale.cache.use=TRUE;
SELECT a, b FROM tbl;
SET @maxscale.cache.use=FALSE;
SELECT a, b FROM tbl;

The first SELECT will be served from the cache, providing the rules specify that the statement should be cached, the cache indeed contains the result and the date is not stale (as specified by the TTL).

If the data is stale, the SELECT will be sent to the server and the cache entry will be updated, irrespective of the value of@maxscale.cache.populate.

If @maxscale.cache.use is true but the result is not found in the cache, and the result is subsequently fetched from the server, the result will not be added to the cache, unless@maxscale.cache.populate is also true.

The value of @maxscale.cache.use can be queried

SELECT @maxscale.cache.use;

but only after it has explicitly been set once.

`@maxscale.cache.soft_ttl`

Using the variable @maxscale.cache.soft_ttl it is possible at runtime to specify in seconds what soft ttl should be applied. Its initial value is the value of the configuration parameter soft_ttl. That is, by default the value is 0.

The purpose of this variable is make it possible for an application to decide statement by statement what soft ttl should be applied.

SET @maxscale.cache.soft_ttl=600;
SELECT a, b FROM unimportant;
SET @maxscale.cache.soft_ttl=60;
SELECT c, d FROM important;

When data is SELECTed from the unimportant table unimportant, the data will be returned from the cache provided it is no older than 10 minutes, but when data is SELECTed from the important table important, the data will be returned from the cache provided it is no older than 1 minute.

Note that @maxscale.cache.hard_ttl overrules @maxscale.cache.soft_ttl in the sense that if the former is less that the latter, then soft ttl will, when used, be adjusted down to the value of hard ttl.

The value of @maxscale.cache.soft_ttl can be queried

SELECT @maxscale.cache.soft_ttl;

but only after it has explicitly been set once.

`@maxscale.cache.hard_ttl`

Using the variable @maxscale.cache.hard_ttl it is possible at runtime to specify in seconds what hard ttl should be applied. Its initial value is the value of the configuration parameter hard_ttl. That is, by default the value is 0.

The purpose of this variable is make it possible for an application to decide statement by statement what hard ttl should be applied.

Note that as @maxscale.cache.hard_ttl overrules @maxscale.cache.soft_ttl, is is important to ensure that the former is at least as large as the latter and for best overall performance that it is larger.

SET @maxscale.cache.soft_ttl=600, @maxscale.cache.hard_ttl=610;
SELECT a, b FROM unimportant;
SET @maxscale.cache.soft_ttl=60, @maxscale.cache.hard_ttl=65;
SELECT c, d FROM important;

The value of @maxscale.cache.hard_ttl can be queried

SELECT @maxscale.cache.hard_ttl;

but only after it has explicitly been set once.

Client Driven Caching

With @maxscale.cache.populate and @maxscale.cache.use is it possible to make the caching completely client driven.

Provide no rules file, which means that all SELECT statements are subject to caching and that all users receive data from the cache. Set the startup mode of the cache to disabled.

[TheCache]
type=filter
module=cache
enabled=false

Now, in order to mark statements that should be cached, set@maxscale.cache.populate to true, and perform those SELECTs.

SET @maxscale.cache.populate=TRUE;
SELECT a, b FROM tbl1;
SELECT c, d FROM tbl2;
SELECT e, f FROM tbl3;
SET @maxscale.cache.populate=FALSE;

Note that those SELECTs must return something in order for the statement to be marked for caching.

After this, the value of @maxscale.cache.use will decide whether or not the cache is considered.

SET @maxscale.cache.use=TRUE;
SELECT a, b FROM tbl1;
SET @maxscale.cache.use=FALSE;

With @maxscale.cache.use being true, the cache is considered and the result returned from there, if not stale. If it is stale, the result is fetched from the server and the cached entry is updated.

By setting a very long TTL it is possible to prevent the cache from ever considering an entry to be stale and instead manually cause the cache to be updated when needed.

UPDATE tbl1 SET a = ...;
SET @maxscale.cache.populate=TRUE;
SELECT a, b FROM tbl1;
SET @maxscale.cache.populate=FALSE;

Threads, Users and Invalidation

What caching approach is used and how different users are treated has a significant impact on the behaviour of the cache. In the following the implication of different combinations is explained.

cached_data/users

mixed

isolated

thread_specific

No thread contention. Data/work duplicated across threads. May cause unintended sharing.

No thread contention. Data/work duplicated across threads and users. No unintended sharing. Requires the most amount of memory.

shared

Thread contention under high load. No duplicated data/work. May cause unintended sharing. Requires the least amount of memory.

Thread contention under high load. Data/work duplicated across users. No unintended sharing.

Invalidation

Invalidation takes place only in the current cache, so how visible the invalidation is, depends upon the configuration value ofcached_data.

cached_data=thread_specific

The invalidation is visible only to the sessions that are handled by the same worker thread where the invalidation occurred. Sessions of the same or other users that are handled by different worker threads will not see the new value before the TTL causes the value to be refreshed.

cache_data=shared

The invalidation is immediately visible to all sessions of all users.

Rules

The caching rules are expressed as a JSON object or as an array of JSON objects.

There are two decisions to be made regarding the caching; in what circumstances should data be stored to the cache and in what circumstances should the data in the cache be used.

Expressed in JSON this looks as follows

{
    store: [ ... ],
    use: [ ... ]
}

or, in case an array is used, as

[
    {
        store: [ ... ],
        use: [ ... ]
    },
    { ... }
]

The store field specifies in what circumstances data should be stored to the cache and the use field specifies in what circumstances the data in the cache should be used. In both cases, the value is a JSON array containing objects.

If an array of rule objects is specified, then, when looking for a rule that matches, the store field of each object are evaluated in sequential order until a match is found. Then, the use field of that object is used when deciding whether data in the cache should be used.

When to Store

By default, if no rules file have been provided or if the store field is missing from the object, the results of all queries will be stored to the cache, subject to max_resultset_rows and max_resultset_size cache filter parameters.

By providing a store field in the JSON object, the decision whether to store the result of a particular query to the cache can be controlled in a more detailed manner. The decision to cache the results of a query can depend upon

the database,
the table,
the column, or
the query itself.

Each entry in the store array is an object containing three fields,

{
    "attribute": <string>,
    "op": <string>
    "value": <string>
}

where,

the attribute can be database, table, column or query,
the op can be =, !=, like or unlike, and
the value a string.

If op is = or != then value is used as a string; if it is like or unlike, then value is interpreted as a pcre2 regular expression. Note though that if attribute is database, table or column, then the string is interpreted as a name, where a dot . denotes qualification or scoping.

The objects in the store array are processed in order. If the result of a comparison is true, no further processing will be made and the result of the query in question will be stored to the cache.

If the result of the comparison is false, then the next object is processed. The process continues until the array is exhausted. If there is no match, then the result of the query is not stored to the cache.

Note that as the query itself is used as the key, although the following queries

SELECT * FROM db1.tbl

and

USE db1;
SELECT * FROM tbl

target the same table and produce the same results, they will be cached separately. The same holds for queries like

SELECT * FROM tbl WHERE a = 2 AND b = 3;

and

SELECT * FROM tbl WHERE b = 3 AND a = 2;

as well. Although they conceptually are identical, there will be two cache entries.

Note that if a column has been specified in a rule, then a statement will match irrespective of where that particular column appears. For instance, if a rule specifies that the result of statements referring to the column a should be cached, then the following statement will match

SELECT a FROM tbl;

and so will

SELECT b FROM tbl WHERE a > 5;

Qualified Names

When using = or != in the rule object in conjunction with database,table and column, the provided string is interpreted as a name, that is, dot (.) denotes qualification or scope.

In practice that means that if attribute is database then value may not contain a dot, if attribute is table then value may contain one dot, used for separating the database and table names respectively, and if attribute is column then value may contain one or two dots, used for separating table and column names, or database, table and column names.

Note that if a qualified name is used as a value, then all parts of the name must be available for a match. Currently Maria DB MaxScale may not always be capable of deducing in what table a particular column is. If that is the case, then a value like tbl.field may not necessarily be a match even if the field is field and the table actually is tbl.

Implication of the default database

If the rules concerns the database, then only if the statement refers to no specific database, will the default database be considered.

Regexp Matching

The string used for matching the regular expression contains as much information as there is available. For instance, in a situation like

USE somedb;
SELECT fld FROM tbl;

the string matched against the regular expression will be somedb.tbl.fld.

Examples

Cache all queries targeting a particular database.

{
    "store": [
        {
            "attribute": "database",
            "op": "=",
            "value": "db1"
        }
    ]
}

Cache all queries not targeting a particular table

{
    "store": [
        {
            "attribute": "table",
            "op": "!=",
            "value": "tbl1"
        }
    ]
}

That will exclude queries targeting table tbl1 irrespective of which database it is in. To exclude a table in a particular database, specify the table name using a qualified name.

{
    "store": [
        {
            "attribute": "table",
            "op": "!=",
            "value": "db1.tbl1"
        }
    ]
}

Cache all queries containing a WHERE clause

{
    "store": [
        {
            "attribute": "query",
            "op": "like",
            "value": ".*WHERE.*"
        }
    ]
}

Note that this will actually cause all queries that contain WHERE anywhere, to be cached.

When to Use

By default, if no rules file have been provided or if the use field is missing from the object, all users may be returned data from the cache.

By providing a use field in the JSON object, the decision whether to use data from the cache can be controlled in a more detailed manner. The decision to use data from the cache can depend upon

the user.

Each entry in the use array is an object containing three fields,

{
    "attribute": <string>,
    "op": <string>
    "value": <string>
}

where,

the attribute can be user,
the op can be =, !=, like or unlike, and
the value a string.

If op is = or != then value is interpreted as a MariaDB account string, that is, % means indicates wildcard, but if op is like orunlike it is simply assumed value is a pcre2 regular expression.

For instance, the following are equivalent:

{
    "attribute": "user",
    "op": "=",
    "value": "'bob'@'%'"
}

{
    "attribute": "user",
    "op": "like",
    "value": "bob@.*"
}

Note that if op is = or != then the usual assumptions apply, that is, a value of bob is equivalent with 'bob'@'%'. If like or unlike is used, then no assumptions apply, but the string is used verbatim as a regular expression.

The objects in the use array are processed in order. If the result of a comparison is true, no further processing will be made and the data in the cache will be used, subject to the value of ttl.

If the result of the comparison is false, then the next object is processed. The process continues until the array is exhausted. If there is no match, then data in the cache will not be used.

Note that use is relevant only if the query is subject to caching, that is, if all queries are cached or if a query matches a particular rule in the store array.

Examples

Use data from the cache for all users except admin (actually 'admin'@'%'), regardless of what host the admin user comes from.

{
    "use": [
        {
            "attribute": "user",
            "op": "!=",
            "value": "admin"
        }
    ]
}

Security

As the cache is not aware of grants, unless the cache has been explicitly configured who the caching should apply to, the presence of the cache may provide a user with access to data he should not have access to. Note that the following applies only if users=mixed has been configured. If users=isolated has been configured, then there can never be any unintended sharing between users.

Suppose there is a table access that the user alice has access to, but the user bob does not. If bob tries to access the table, he will get an error as reply:

MySQL [testdb]> select * from access;
ERROR 1142 (42000): SELECT command denied to user 'bob'@'localhost' for table 'access'

If we now setup caching for the table, using the simplest possible rules file, bob will get access to data from the table, provided he executes a select identical with one alice has executed.

For instance, suppose the rules look as follows:

{
    "store": [
        {
            "attribute": "table",
            "op": "=",
            "value": "access"
        }
    ]
}

If alice now queries the table, she will get the result, which also will be cached:

MySQL [testdb]> select * from access;
+------+------+
| a    | b    |
+------+------+
|   47 |   11 |
+------+------+

If bob now executes the very same query, and the result is still in the cache, it will be returned to him.

MySQL [testdb]> select current_user();
+----------------+
| current_user() |
+----------------+
| bob@127.0.0.1  |
+----------------+
1 row in set (0.00 sec)

MySQL [testdb]> select * from access;
+------+------+
| a    | b    |
+------+------+
|   47 |   11 |
+------+------+

That can be prevented, by explicitly declaring in the rules that the caching should be applied to alice only.

{
    "store": [
        {
            "attribute": "table",
            "op": "=",
            "value": "access"
        }
    ],
    "use": [
        {
            "attribute": "user",
            "op": "=",
            "value": "'alice'@'%'"
        }
    ]
}

With these rules in place, bob is again denied access, since queries targeting the table access will in his case not be served from the cache.

Storage

There are two types of storages that can be used; local and shared.

The only local storage implementation is storage_inmemory that simply stores the cache values in memory. The storage is not persistent and is destroyed when MaxScale terminates. Since the storage exists in the MaxScale process, it is very fast and provides almost always a performance benefit.

Currently there are two shared storages; storage_memcached andstorage_redis that are implemented using memcached and redis respectively.

The shared storages are accessed across the network and consequently it isnot self-evident that their use will provide any performance benefit. Namely, irrespective of whether the data is fetched from the cache or from the server there will be a network hop and often that network hop is, as far as the performance goes, what costs the most.

The presence of a shared cache may provide a performance benefitif the network between MaxScale and the storage server (memcached or &#xNAN;Redis) is faster than the network between MaxScale and the database &#xNAN;server, if the used SELECT statements are heavy (that is, take a significant amount of time) to process for the database server, or

if the presence of the cache reduces the overall load of an otherwise overloaded database server.

As a general rule a shared storage should not be used without first assessing its value using a realistic workload.

`storage_inmemory`

This simple storage module uses the standard memory allocator for storing the cached data.

storage=storage_inmemory

This storage module takes no arguments.

`storage_memcached`

This storage module uses memcached for storing the cached data.

Multiple MaxScale instances can share the same memcached server and items cached by one MaxScale instance will be used by the other. Note that all MaxScale instances should have exactly the same configuration, as otherwise there can be unintended sharing.

storage=storage_memcached

storage_memcache has the following parameters:

server

Type: The Memcached server address specified as host[:port]
Mandatory: Yes
Dynamic: No

If no port is provided, then the default port 11211 will be used.

max_value_size

Type: size
Mandatory: No
Dynamic: No
Default: 1Mi

By default, the maximum size of a value stored to memcached is 1MiB, but that can be configured to something else, in which case this parameter should be set accordingly.

The value of max_value_size will be used for capping max_resultset_size, that is, if memcached has been configured to allow larger values than 1MiB but max_value_size has not been set accordingly, only resultsets up to 1MiB in size will be cached.

Example

From MaxScale 23.02 onwards, the storage configuration should be provided as nested parameters.

[Cache-Filter]
type=filter
module=cache
storage=storage_memcached
storage_memcached.server=192.168.1.31
storage_memcached.max_value_size=10M

Although deprecated in 23.02, the configuration can also be provided using storage_options:

storage_options="server=192.168.1.31,max_value_size=10M"

Limitations

Invalidation is not supported.
Configuration values given to max_size and max_count are ignored.

Security

Neither the data in the memcached server nor the traffic between MaxScale and the memcached server is encrypted. Consequently, anybody with access to the memcached server or to the network have access to the cached data.

`storage_redis`

This storage module uses redis for storing the cached data.

Note that Redis should be configured with no idle timeout or with a timeout that is very large. Otherwise MaxScale may have to repeatedly connect to Redis, which will hurt both the functionality and the performance.

Multiple MaxScale instances can share the same redis server and items cached by one MaxScale instance will be used by the other. Note that all MaxScale instances should have exactly the same configuration, as otherwise there can be unintended sharing.

storage=storage_redis

If storage_redis cannot connect to the Redis server, caching will silently be disabled and a connection attempt will be made after a timeout interval.

If a timeout error occurs during an operation, reconnecting will be attempted after a delay, which will be an increasing multiple of timeout. For example, if timeout is the default 5 seconds, then reconnection attempts will first be made after 10 seconds, then after 15 seconds, then 20 and so on. However, once 60 seconds have been reached, the delay will no longer be increased but the delay will stay at one minute. Note that each time a reconnection attempt is made, unless the reason for the timeout has disappeared, the client will be stalled for timeout seconds.

storage_redis has the following parameters:

server

Type: The Redis server address specified as host[:port]
Mandatory: Yes
Dynamic: No

If no port is provided, then the default port 6379 will be used.

username

Type: string
Mandatory: No
Dynamic: No
Default: ""

Please see authentication for more information.

password

Type: string
Mandatory: No
Dynamic: No
Default: ""

Please see authentication for more information.

ssl

Type: boolean
Mandatory: No
Dynamic: No
Default: false

Please see ssl for more information.

ssl_cert

Type: Path to existing readable file.
Mandatory: No
Dynamic: No
Default: ""

The SSL client certificate that MaxScale should use with the Redis server. The certificate must match the key defined in ssl_key.

Please see ssl for more information.

ssl_key

Type: Path to existing readable file.
Mandatory: No
Dynamic: No
Default: ""

The SSL client private key MaxScale should use with the Redis server.

Please see ssl for more information.

ssl_ca

Type: Path to existing readable file.
Mandatory: No
Dynamic: No
Default: ""

The Certificate Authority (CA) certificate for the CA that signed the certificate specified with ssl_cert.

Please see ssl for more information.

Authentication

If password is provided, MaxScale will authenticate against Redis when a connection has been created. The authentication is performed using the auth command, with only the password as argument, if no username was provided in the configuration, or username and password as arguments, if both were.

Note that if the authentication is in the Redis configuration file specified using requirepass, then only the password should be provided. If the Redis server version is 6 or higher and the Redis ACL system is used, then both username and password must be provided.

SSL

If ssl_key, ssl_cert and ssl_ca are provided, then SSL/TLS will be used in the communication with the Redis server, if ssl is set to true.

Note that the SSL/TLS support is only available in Redis from version 6 onwards and that the support is not by default built into Redis, but has to be specifically enabled at compile time as explained here.

Example

From MaxScale 23.02 onwards, the storage configuration should be provided as nested parameters.

[Cache-Filter]
type=filter
module=cache
storage=storage_redis
storage_redis.server=192.168.1.31
storage_redis.username=hello
storage_redis.password=world

Although deprecated in 23.02, the configuration can also be provided using storage_options:

storage_options="server=192.168.1.31,username=hello,password=world"

Limitations

There is no distinction between soft and hard ttl, but only hard ttl is used.
Configuration values given to max_size and max_count are ignored.

Invalidation

storage_redis supports invalidation, but the caveats documented here are of greater significance since also the communication between the cache and the cache storage is asynchronous and takes place over the network.

NOTE If invalidation is turned on after caching has been used (in non-invalidation mode), redis must be flushed as otherwise there will be entries in the cache that will not be affected by the invalidation.

$ redis-cli flushall

Security

The data in the redis server is not encrypted. Consequently, anybody with access to the redis server has access to the cached data.

Unless SSL has been enabled, anybody with access to the network has access to the cached data.

Example

In the following we define a cache MyCache that uses the cache storage modulestorage_inmemory and whose soft ttl is 30 seconds and whose hard ttl is45 seconds. The cached data is shared between all threads and the maximum size of the cached data is 50 mebibytes. The rules for the cache are in the filecache_rules.json.

Configuration

[MyCache]
type=filter
module=cache
storage=storage_inmemory
soft_ttl=30
hard_ttl=45
cached_data=shared
max_size=50Mi
rules=cache_rules.json

[MyService]
type=service
...
filters=MyCache

`cache_rules.json`

The rules specify that the data of the table sbtest should be cached.

{
    "store": [
        {
            "attribute": "table",
            "op": "=",
            "value": "sbtest"
        }
    ]
}

Performance

When the cache filter was introduced, the most significant factor affecting the performance of the cache was whether the statements needed to be parsed. Initially, all statements were parsed in order to exclude SELECT statements that use non-cacheable functions, access non-cacheable variables or refer to system or user variables. Later, the default value of the selects parameter was changed to assume_cacheable, to maximize the default performance.

With the default configuration, the cache itself will not cause the statements to be parsed. However, even with assume_cacheable configured, a rule referring specifically to a database, table or column will still cause the statement to be parsed.

For instance, a simple rule like

{
    "store": [
        {
            "attribute": "database",
            "op": "=",
            "value": "db1"
        }
    ]
}

cannot be fulfilled without parsing the statement.

If the rule is instead expressed using a regular expression

{
    "store": [
        {
            "attribute": "query",
            "op": "like",
            "value": "FROM db1\\..*"
        }
    ]
}

then the statement will not be parsed.

However, when the query classifier cache was introduced, the parsing cost was significantly reduced and currently the cost for parsing and regular expression matching is roughly the same.

In the following is a table with numbers giving a rough picture of the relative cost of different approaches.

In the table, regexp match means that the cacheable statements were picked out using a rule like

{
    "attribute": "query",
    "op": "unlike",
    "value": "FROM nomatch"
}

while exact match means that the cacheable statements were picked out using a rule like

{
    "attribute": "database",
    "op": "!=",
    "value": "nomatch"
}

The exact match rule requires all statements to be parsed.

As the purpose of the test is to illustrate the overhead of different approaches, the rules were formulated so that all SELECT statements would match.

Note that these figures were obtained by running sysbench, MaxScale and the server in the same computer, so they are only indicative.

selects

Rule

qps

assume_cacheable

none

100

assume_cacheable

regexp match

assume_cacheable

exact match

verify_cacheable

none

verify_cacheable

regexp match

verify_cacheable

exact match

For comparison, without caching, the qps is 33.

As can be seen, due to the query classifier cache there is no difference between exact and regex based matching.

Summary

For maximum performance:

Arrange the situation so that the default selects=assume_cacheable can be used, and use no rules.

Otherwise it is mostly a personal preference whether exact or regex based rules are used. However, one should always test with real data and real queries before choosing one over the other.

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

MaxScale MaxCtrl

MaxCtrl

MaxCtrl is a command line administrative client for MaxScale which uses the MaxScale REST API for communication. It has replaced the legacy MaxAdmin command line client that is no longer supported or included.

By default, the MaxScale REST API listens on port 8989 on the local host. The default credentials for the REST API are admin:mariadb. The users used by the REST API are the same that are used by the MaxAdmin network interface. This means that any users created for the MaxAdmin network interface should work with the MaxScale REST API and MaxCtrl.

For more information about the MaxScale REST API, refer to the REST API documentation and the Configuration Guide.

Limitations

MaxCtrl does not work when used from a SystemD unit with MemoryDenyWriteExecute=true.

.maxctrl.cnf

If the file ~/.maxctrl.cnf exists, maxctrl will use any values in the section [maxctrl] as defaults for command line arguments. For instance, to avoid having to specify the user and password on the command line, create the file .maxctrl.cnf in your home directory, with the following content:

[maxctrl]
u = my-name
p = my-password

Note that all access rights to the file must be removed from everybody else but the owner. MaxCtrl refuses to use the file unless the rights have been removed.

Another file from which to read the defaults can be specified with the -c flag.

Commands

list

list servers

Usage: list servers

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all servers in MaxScale.


  Field       | Description
  -----       | -----------
  Server      | Server name
  Address     | Address where the server listens
  Port        | The port on which the server listens
  Connections | Current connection count
  State       | Server state
  GTID        | Current value of @@gtid_current_pos
  Monitor     | The monitor for this server

list services

Usage: list services

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all services and the servers they use.


  Field             | Description
  -----             | -----------
  Service           | Service name
  Router            | Router used by the service
  Connections       | Current connection count
  Total Connections | Total connection count
  Targets           | Targets that the service uses

list listeners

Usage: list listeners [service]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List listeners of all services. If a service is given, only listeners for that service are listed.


  Field   | Description
  -----   | -----------
  Name    | Listener name
  Port    | The port where the listener listens
  Host    | The address or socket where the listener listens
  State   | Listener state
  Service | Service that this listener points to

list monitors

Usage: list monitors

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all monitors in MaxScale.


  Field   | Description
  -----   | -----------
  Monitor | Monitor name
  State   | Monitor state
  Servers | The servers that this monitor monitors

list sessions

Usage: list sessions

Options:
      --rdns     Perform a reverse DNS lookup on client IPs  [boolean] [default: false]
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

List all client sessions.


  Field     | Description
  -----     | -----------
  Id        | Session ID
  User      | Username
  Host      | Client host address
  Connected | Time when the session started
  Idle      | How long the session has been idle, in seconds
  Service   | The service where the session connected
  Memory    | Memory usage (not exhaustive)

list filters

Usage: list filters

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all filters in MaxScale.


  Field   | Description
  -----   | -----------
  Filter  | Filter name
  Service | Services that use the filter
  Module  | The module that the filter uses

list modules

Usage: list modules

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all currently loaded modules.


  Field   | Description
  -----   | -----------
  Module  | Module name
  Type    | Module type
  Version | Module version

list threads

Usage: list threads

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all worker threads.


  Field       | Description
  -----       | -----------
  Id          | Thread ID
  Current FDs | Current number of managed file descriptors
  Total FDs   | Total number of managed file descriptors
  Load (1s)   | Load percentage over the last second
  Load (1m)   | Load percentage over the last minute
  Load (1h)   | Load percentage over the last hour

list users

Usage: list users

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List network the users that can be used to connect to the MaxScale REST API.


  Field        | Description
  -----        | -----------
  Name         | User name
  Type         | User type
  Privileges   | User privileges
  Created      | When the user was created
  Last Updated | The last time the account password was updated
  Last Login   | The last time the user logged in

list commands

Usage: list commands

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all available module commands.


  Field    | Description
  -----    | -----------
  Module   | Module name
  Commands | Available commands

list queries

Usage: list queries

List queries options:
  -l, --max-length  Maximum SQL length to display. Use --max-length=0 for no limit.  [number] [default: 120]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

List all active queries being executed through MaxScale. In order for this command to work, MaxScale must be configured with 'retain_last_statements' set to a value greater than 0.

show

show server

Usage: show server <server>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about a server. The `Parameters` field contains the currently configured parameters for this server. See `--help alter server` for more details about altering server parameters.


  Field               | Description
  -----               | -----------
  Server              | Server name
  Source              | File where the object is stored in
  Address             | Address where the server listens
  Port                | The port on which the server listens
  State               | Server state
  Version             | Server version
  Uptime              | Server uptime in seconds
  Last Event          | The type of the latest event
  Triggered At        | Time when the latest event was triggered at
  Services            | Services that use this server
  Monitors            | Monitors that monitor this server
  Master ID           | The server ID of the master
  Node ID             | The node ID of this server
  Slave Server IDs    | List of slave server IDs
  Current Connections | Current connection count
  Total Connections   | Total cumulative connection count
  Max Connections     | Maximum number of concurrent connections ever seen
  Statistics          | Server statistics
  Parameters          | Server parameters

show servers

Usage: show servers

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about all servers.


  Field               | Description
  -----               | -----------
  Server              | Server name
  Source              | File where the object is stored in
  Address             | Address where the server listens
  Port                | The port on which the server listens
  State               | Server state
  Version             | Server version
  Uptime              | Server uptime in seconds
  Last Event          | The type of the latest event
  Triggered At        | Time when the latest event was triggered at
  Services            | Services that use this server
  Monitors            | Monitors that monitor this server
  Master ID           | The server ID of the master
  Node ID             | The node ID of this server
  Slave Server IDs    | List of slave server IDs
  Current Connections | Current connection count
  Total Connections   | Total cumulative connection count
  Max Connections     | Maximum number of concurrent connections ever seen
  Statistics          | Server statistics
  Parameters          | Server parameters

show service

Usage: show service <service>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about a service. The `Parameters` field contains the currently configured parameters for this service. See `--help alter service` for more details about altering service parameters.


  Field               | Description
  -----               | -----------
  Service             | Service name
  Source              | File where the object is stored in
  Router              | Router that the service uses
  State               | Service state
  Started At          | When the service was started
  Users Loaded At     | When the users for the service were loaded
  Current Connections | Current connection count
  Total Connections   | Total connection count
  Max Connections     | Historical maximum connection count
  Cluster             | The cluster that the service uses
  Servers             | Servers that the service uses
  Services            | Services that the service uses
  Filters             | Filters that the service uses
  Parameters          | Service parameter
  Router Diagnostics  | Diagnostics provided by the router module

show services

Usage: show services

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about all services.


  Field               | Description
  -----               | -----------
  Service             | Service name
  Source              | File where the object is stored in
  Router              | Router that the service uses
  State               | Service state
  Started At          | When the service was started
  Users Loaded At     | When the users for the service were loaded
  Current Connections | Current connection count
  Total Connections   | Total connection count
  Max Connections     | Historical maximum connection count
  Cluster             | The cluster that the service uses
  Servers             | Servers that the service uses
  Services            | Services that the service uses
  Filters             | Filters that the service uses
  Parameters          | Service parameter
  Router Diagnostics  | Diagnostics provided by the router module

show monitor

Usage: show monitor <monitor>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about a monitor. The `Parameters` field contains the currently configured parameters for this monitor. See `--help alter monitor` for more details about altering monitor parameters.


  Field               | Description
  -----               | -----------
  Monitor             | Monitor name
  Source              | File where the object is stored in
  Module              | Monitor module
  State               | Monitor state
  Servers             | The servers that this monitor monitors
  Parameters          | Monitor parameters
  Monitor Diagnostics | Diagnostics provided by the monitor module

show monitors

Usage: show monitors

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about all monitors.


  Field               | Description
  -----               | -----------
  Monitor             | Monitor name
  Source              | File where the object is stored in
  Module              | Monitor module
  State               | Monitor state
  Servers             | The servers that this monitor monitors
  Parameters          | Monitor parameters
  Monitor Diagnostics | Diagnostics provided by the monitor module

show session

Usage: show session <session>

Options:
      --rdns     Perform a reverse DNS lookup on client IPs  [boolean] [default: false]
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Show detailed information about a single session. The list of sessions can be retrieved with the `list sessions` command. The <session> is the session ID of a particular session.

The `Connections` field lists the servers to which the session is connected and the `Connection IDs` field lists the IDs for those connections.


  Field             | Description
  -----             | -----------
  Id                | Session ID
  Service           | The service where the session connected
  State             | Session state
  User              | Username
  Host              | Client host address
  Port              | Client network port
  Database          | Current default database of the connection
  Connected         | Time when the session started
  Idle              | How long the session has been idle, in seconds
  Parameters        | Session parameters
  Client TLS Cipher | Client TLS cipher
  Connections       | Ordered list of backend connections
  Connection IDs    | Thread IDs for the backend connections
  Queries           | Query history
  Log               | Per-session log messages
  Memory            | Memory usage (not exhaustive)

show sessions

Usage: show sessions

Options:
      --rdns     Perform a reverse DNS lookup on client IPs  [boolean] [default: false]
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Show detailed information about all sessions. See `--help show session` for more details.


  Field             | Description
  -----             | -----------
  Id                | Session ID
  Service           | The service where the session connected
  State             | Session state
  User              | Username
  Host              | Client host address
  Port              | Client network port
  Database          | Current default database of the connection
  Connected         | Time when the session started
  Idle              | How long the session has been idle, in seconds
  Parameters        | Session parameters
  Client TLS Cipher | Client TLS cipher
  Connections       | Ordered list of backend connections
  Connection IDs    | Thread IDs for the backend connections
  Queries           | Query history
  Log               | Per-session log messages
  Memory            | Memory usage (not exhaustive)

show filter

Usage: show filter <filter>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The list of services that use this filter is show in the `Services` field.


  Field       | Description
  -----       | -----------
  Filter      | Filter name
  Source      | File where the object is stored in
  Module      | The module that the filter uses
  Services    | Services that use the filter
  Parameters  | Filter parameters
  Diagnostics | Filter diagnostics

show filters

Usage: show filters

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information of all filters.


  Field       | Description
  -----       | -----------
  Filter      | Filter name
  Source      | File where the object is stored in
  Module      | The module that the filter uses
  Services    | Services that use the filter
  Parameters  | Filter parameters
  Diagnostics | Filter diagnostics

show listener

Usage: show listener <listener>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]




                                                           Field      | Description
                                                           -----      | -----------
                                                           Name       | Listener name
                                                           Source     | File where the object is stored in
                                                           Service    | Services that the listener points to
                                                           Parameters | Listener parameters

show listeners

Usage: show filters

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information of all filters.


  Field       | Description
  -----       | -----------
  Filter      | Filter name
  Source      | File where the object is stored in
  Module      | The module that the filter uses
  Services    | Services that use the filter
  Parameters  | Filter parameters
  Diagnostics | Filter diagnostics

show module

Usage: show module <module>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command shows all available parameters as well as detailed version information of a loaded module.


  Field       | Description
  -----       | -----------
  Module      | Module name
  Type        | Module type
  Version     | Module version
  Maturity    | Module maturity
  Description | Short description about the module
  Parameters  | All the parameters that the module accepts
  Commands    | Commands that the module provides

show modules

Usage: show modules

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Displays detailed information about all modules.


  Field       | Description
  -----       | -----------
  Module      | Module name
  Type        | Module type
  Version     | Module version
  Maturity    | Module maturity
  Description | Short description about the module
  Parameters  | All the parameters that the module accepts
  Commands    | Commands that the module provides

show maxscale

Usage: show maxscale

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

See `--help alter maxscale` for more details about altering MaxScale parameters.


  Field        | Description
  -----        | -----------
  Version      | MaxScale version
  Commit       | MaxScale commit ID
  Started At   | Time when MaxScale was started
  Activated At | Time when MaxScale left passive mode
  Uptime       | Time MaxScale has been running
  Config Sync  | MaxScale configuration synchronization
  Parameters   | Global MaxScale parameters
  System       | System Information

show thread

Usage: show thread <thread>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show detailed information about a worker thread.


  Field                  | Description
  -----                  | -----------
  Id                     | Thread ID
  State                  | The state of the thread
  Accepts                | Number of TCP accepts done by this thread
  Reads                  | Number of EPOLLIN events
  Writes                 | Number of EPOLLOUT events
  Hangups                | Number of EPOLLHUP and EPOLLRDUP events
  Errors                 | Number of EPOLLERR events
  Avg event queue length | Average number of events returned by one epoll_wait call
  Max event queue length | Maximum number of events returned by one epoll_wait call
  Max exec time          | The longest time spent processing events returned by a epoll_wait call
  Max queue time         | The longest time an event had to wait before it was processed
  Current FDs            | Current number of managed file descriptors
  Total FDs              | Total number of managed file descriptors
  Load (1s)              | Load percentage over the last second
  Load (1m)              | Load percentage over the last minute
  Load (1h)              | Load percentage over the last hour
  QC cache size          | Query classifier size
  QC cache inserts       | Number of times a new query was added into the query classification cache
  QC cache hits          | How many times a query classification was found in the query classification cache
  QC cache misses        | How many times a query classification was not found in the query classification cache
  QC cache evictions     | How many times a query classification result was evicted from the query classification cache
  Sessions               | The current number of sessions
  Zombies                | The current number of zombie connections, waiting to be discarded
  Memory                 | The current (partial) memory usage

show threads

Usage: show threads

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]
      --kind     The kind of threads to display, only the running or all.  [string] [choices: "running", "all"] [default: "running"]

Show detailed information about all worker threads.


  Field                  | Description
  -----                  | -----------
  Id                     | Thread ID
  State                  | The state of the thread
  Accepts                | Number of TCP accepts done by this thread
  Reads                  | Number of EPOLLIN events
  Writes                 | Number of EPOLLOUT events
  Hangups                | Number of EPOLLHUP and EPOLLRDUP events
  Errors                 | Number of EPOLLERR events
  Avg event queue length | Average number of events returned by one epoll_wait call
  Max event queue length | Maximum number of events returned by one epoll_wait call
  Max exec time          | The longest time spent processing events returned by a epoll_wait call
  Max queue time         | The longest time an event had to wait before it was processed
  Current FDs            | Current number of managed file descriptors
  Total FDs              | Total number of managed file descriptors
  Load (1s)              | Load percentage over the last second
  Load (1m)              | Load percentage over the last minute
  Load (1h)              | Load percentage over the last hour
  QC cache size          | Query classifier size
  QC cache inserts       | Number of times a new query was added into the query classification cache
  QC cache hits          | How many times a query classification was found in the query classification cache
  QC cache misses        | How many times a query classification was not found in the query classification cache
  QC cache evictions     | How many times a query classification result was evicted from the query classification cache
  Sessions               | The current number of sessions
  Zombies                | The current number of zombie connections, waiting to be discarded
  Memory                 | The current (partial) memory usage

show logging

Usage: show logging

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

See `--help alter logging` for more details about altering logging parameters.


  Field              | Description
  -----              | -----------
  Current Log File   | The current log file MaxScale is logging into
  Enabled Log Levels | List of log levels enabled in MaxScale
  Parameters         | Logging parameters

show commands

Usage: show commands <module>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command shows the parameters the command expects with the parameter descriptions.


  Field        | Description
  -----        | -----------
  Command      | Command name
  Parameters   | Parameters the command supports
  Descriptions | Parameter descriptions

show qc_cache

Usage: show qc_cache

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show contents (statement and hits) of query classifier cache.

show dbusers

Usage: show dbusers <service>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Show information about the database users of the service.


  Field  | Description
  -----  | -----------
  User   | The user name of the account
  Host   | The host of the account
  Plugin | Authentication plugin
  TLS    | Whether TLS is required from this user
  Super  | Does the user have a SUPER grant
  Global | Does the user have global database access
  Proxy  | Whether this is a proxy user
  Role   | The default role for this user

set

set server

Usage: set server <server> <state>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Set options:
      --force  If combined with the `maintenance` state, this forcefully closes all connections to the target server  [boolean] [default: false]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

If <server> is monitored by a monitor, this command should only be used to set the server into the `maintenance` or the `drain` state. Any other states will be overridden by the monitor on the next monitoring interval. To manually control server states, use the `stop monitor <name>` command to stop the monitor before setting the server states manually.

When a server is set into the `drain` state, no new connections to it are allowed but existing connections are allowed to gracefully close. Servers with the `Master` status cannot be drained or set into maintenance mode. To clear a state set by this command, use the `clear server` command.

To forcefully close all connections to a server, use `set server <name> maintenance --force`

clear

clear server

Usage: clear server <server> <state>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command clears a server state set by the `set server <server> <state>` command

enable

enable log-priority

Usage: enable log-priority <log>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The `debug` log priority is only available for debug builds of MaxScale.

disable

disable log-priority

Usage: disable log-priority <log>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The `debug` log priority is only available for debug builds of MaxScale.

create

create server

Usage: create server <name> <host|socket> [port] [params...]

Create server options:
      --services  Link the created server to these services  [array]
      --monitors  Link the created server to these monitors  [array]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The created server will not be used by any services or monitors unless the --services or --monitors options are given. The list of servers a service or a monitor uses can be altered with the `link` and `unlink` commands. If the <host|socket> argument is an absolute path, the server will use a local UNIX domain socket connection. In this case the [port] argument is ignored.

The recommended way of declaring parameters is with the new `key=value` syntax added in MaxScale 6.2.0. Note that for some parameters (e.g. `extra_port` and `proxy_protocol`) this is the only way to pass them. The redundant option parameters have been deprecated in MaxScale 22.08.

create monitor

Usage: create monitor <name> <module> [params...]

Create monitor options:
      --servers  Link the created monitor to these servers. All non-option arguments after --servers are interpreted as server names e.g. `--servers srv1 srv2 srv3`.  [array]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The list of servers given with the --servers option should not contain any servers that are already monitored by another monitor. The last argument to this command is a list of key=value parameters given as the monitor parameters. The redundant option parameters have been deprecated in MaxScale 22.08.

create service

Usage: service <name> <router> <params...>

Create service options:
      --servers   Link the created service to these servers. All non-option arguments after --servers are interpreted as server names e.g. `--servers srv1 srv2 srv3`.  [array]
      --filters   Link the created service to these filters. All non-option arguments after --filters are interpreted as filter names e.g. `--filters f1 f2 f3`.  [array]
      --services  Link the created service to these services. All non-option arguments after --services are interpreted as service names e.g. `--services svc1 svc2 svc3`.  [array]
      --cluster   Link the created service to this cluster (i.e. a monitor)  [string]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The last argument to this command is a list of key=value parameters given as the service parameters. If the --servers, --services or --filters options are used, they must be defined after the service parameters. The --cluster option is mutually exclusive with the --servers and --services options.

Note that the `user` and `password` parameters must be defined.

create filter

Usage: filter <name> <module> [params...]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The last argument to this command is a list of key=value parameters given as the filter parameters.

create listener

Usage: create listener <service> <name> <port> [params...]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The new listener will be taken into use immediately. The last argument to this command is a list of key=value parameters given as the listener parameters. These parameters override any parameters set via command line options: e.g. using `protocol=mariadb` will override the `--protocol=cdc` option. The redundant option parameters have been deprecated in MaxScale 22.08.

create user

Usage: create user <name> <password>

Create user options:
      --type  Type of user to create  [string] [choices: "admin", "basic"] [default: "basic"]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

By default the created user will have read-only privileges. To make the user an administrative user, use the `--type=admin` option. Basic users can only perform `list` and `show` commands.

create report

Usage: create report <file>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The generated report contains the state of all the objects in MaxScale as well as all other required information needed to diagnose problems.

destroy

destroy server

Usage: destroy server <name>

Destroy options:
      --force  Remove the server from monitors and services before destroying it  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The server must be unlinked from all services and monitor before it can be destroyed.

destroy monitor

Usage: destroy monitor <name>

Destroy options:
      --force  Remove monitored servers from the monitor before destroying it  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The monitor must be unlinked from all servers before it can be destroyed.

destroy listener

Usage: destroy listener { <listener> | <service> <listener> }

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Destroying a listener closes the listening socket, opening it up for immediate reuse. If only one argument is given and it is the name of a listener, it is unconditionally destroyed. If two arguments are given and they are a service and a listener, the listener is only destroyed if it is for the given service.

destroy service

Usage: destroy service <name>

Destroy options:
      --force  Remove filters, listeners and servers from service before destroying it  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The service must be unlinked from all servers and filters. All listeners for the service must be destroyed before the service itself can be destroyed.

destroy filter

Usage: destroy filter <name>

Destroy options:
      --force  Automatically remove the filter from all services before destroying it  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The filter must not be used by any service when it is destroyed.

destroy user

Usage: destroy user <name>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The last remaining administrative user cannot be removed. Create a replacement administrative user before attempting to remove the last administrative user.

destroy session

Usage: destroy session <id>

Destroy options:
      --ttl  Give session this many seconds to gracefully close  [number] [default: 0]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This causes the client session with the given ID to be closed. If the --ttl option is used, the session is given that many seconds to gracefully stop. If no TTL value is given, the session is closed immediately.

link

link service

Usage: link service <name> <target...>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command links targets to a service, making them available for any connections that use the service. A target can be a server, another service or a cluster (i.e. a monitor). Before a server is linked to a service, it should be linked to a monitor so that the server state is up to date. Newly linked targets are only available to new connections, existing connections will use the old list of targets. If a monitor (a cluster of servers) is linked to a service, the service must not have any other targets linked to it.

link monitor

Usage: link monitor <name> <server...>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Linking a server to a monitor will add it to the list of servers that are monitored by that monitor. A server can be monitored by only one monitor at a time.

unlink

unlink service

Usage: unlink service <name> <target...>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command unlinks targets from a service, removing them from the list of available targets for that service. New connections to the service will not use the unlinked targets but existing connections can still use the targets. A target can be a server, another service or a cluster (a monitor).

unlink monitor

Usage: unlink monitor <name> <server...>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command unlinks servers from a monitor, removing them from the list of monitored servers. The servers will be left in their current state when they are unlinked from a monitor.

start

start service

Usage: start service <name>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This starts a service stopped by `stop service <name>`

start listener

Usage: start listener <name>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This starts a listener stopped by `stop listener <name>`

start monitor

Usage: start monitor <name>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This starts a monitor stopped by `stop monitor <name>`

start services

Usage: start [services|maxscale]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command will execute the `start service` command for all services in MaxScale.

stop

stop service

Usage: stop service <name>

Stop options:
      --force  Close existing connections after stopping the service  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Stopping a service will prevent all the listeners for that service from accepting new connections. Existing connections will still be handled normally until they are closed.

stop listener

Usage: stop listener <name>

Stop options:
      --force  Close existing connections after stopping the listener  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Stopping a listener will prevent it from accepting new connections. Existing connections will still be handled normally until they are closed.

stop monitor

Usage: stop monitor <name>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Stopping a monitor will pause the monitoring of the servers. This can be used to manually control server states with the `set server` command.

stop services

Usage: stop [services|maxscale]

Stop options:
      --force  Close existing connections after stopping all services  [boolean] [default: false]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command will execute the `stop service` command for all services in MaxScale.

alter

alter server

Usage: alter server <server> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the server parameters, execute `show server <server>`.
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter monitor

Usage: alter monitor <monitor> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the monitor parameters, execute `show monitor <monitor>`
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter service

Usage: alter service <service> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the service parameters, execute `show service <service
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter service-filters

Usage: alter service-filters <service> [filters...]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The order of the filters given as the second parameter will also be the order in which queries pass through the filter chain. If no filters are given, all existing filters are removed from the service.

For example, the command `maxctrl alter service-filters my-service A B C` will set the filter chain for the service `my-service` so that A gets the query first after which it is passed to B and finally to C. This behavior is the same as if the `filters=A|B|C` parameter was defined for the service.

The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter filter

Usage: alter filter <filter> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the filter parameters, execute `show filter <filter>`. Some filters support runtime configuration changes to all parameters. Refer to the filter documentation for details on whether it supports runtime configuration changes and which parameters can be altered.

The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.
Note: To pass options with dashes in them, surround them in both single and double quotes:

      maxctrl alter filter my-namedserverfilter target01 '"->master"'

alter listener

Usage: alter listener <listener> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the listener parameters, execute `show listener <listener>`
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter logging

Usage: alter logging <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the logging parameters, execute `show logging`
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter maxscale

Usage: alter maxscale <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To display the MaxScale parameters, execute `show maxscale`.
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter user

Usage: alter user <name> <password>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Changes the password for a user. To change the user type, destroy the user and then create it again.

alter session

Usage: alter session <session> <key=value> ...

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Alter parameters of a session. To get the list of modifiable parameters, use `show session <session>`
The parameters should be given in the `key=value` format. This command also supports the legacy method
of passing parameters as `key value` pairs but the use of this is not recommended.

alter session-filters

Usage: alter session-filters <session> [filters...]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

The order of the filters given as the second parameter will also be the order in which queries pass through the filter chain. If no filters are given, all existing filters are removed from the session. The syntax is similar to `alter service-filters`.

rotate

rotate logs

Usage: rotate logs

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command is intended to be used with the `logrotate` command.

reload

reload service

Usage: reload service <service>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

reload tls

Usage: reload tls <service>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command reloads the TLS certificates for all listeners and servers as well as the REST API in MaxScale. The REST API JWT signature keys are also rotated by this command.

reload session

Usage: reload session <id>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command reloads the configuration of a session. When a session is reloaded, it internally restarts the MaxScale session. This means that new connections are created and taken into use before the old connections are discarded. The session will use the latest configuration of the service the listener it used pointed to. This means that the behavior of the session can change as a result of a reload if the configuration has changed. If the reloading fails, the old configuration will remain in use. The external session ID of the connection will remain the same as well as any statistics or session level alterations that were done before the reload.

reload sessions

Usage: reload sessions

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

This command reloads the configuration of all sessions. When a session is reloaded, it internally restarts the MaxScale session. This means that new connections are created and taken into use before the old connections are discarded. The session will use the latest configuration of the service the listener it used pointed to. This means that the behavior of the session can change as a result of a reload if the configuration has changed. If the reloading fails, the old configuration will remain in use. The external session ID of the connection will remain the same as well as any statistics or session level alterations that were done before the reload.

call

call command

Usage: call command <module> <command> [params...]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

To inspect the list of module commands, execute `list commands`

api

api get

Usage: get <resource> [path]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

API options:
      --sum     Calculate sum of API result. Only works for arrays of numbers e.g. `api get --sum servers data[].attributes.statistics.connections`.  [boolean] [default: false]
      --pretty  Pretty-print output.  [boolean] [default: false]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Perform a raw REST API call. The path definition uses JavaScript syntax to extract values. For example, the following command extracts all server states as an array of JSON values: maxctrl api get servers data[].attributes.state

api post

Usage: post <resource> <value>

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

API options:
      --sum     Calculate sum of API result. Only works for arrays of numbers e.g. `api get --sum servers data[].attributes.statistics.connections`.  [boolean] [default: false]
      --pretty  Pretty-print output.  [boolean] [default: false]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Perform a raw REST API call. The provided value is passed as-is to the REST API after building it with JSON.parse

api patch

Usage: patch <resource> [path]

Global Options:
  -c, --config     MaxCtrl configuration file  [string] [default: "~/.maxctrl.cnf"]
  -u, --user       Username to use  [string] [default: "admin"]
  -p, --password   Password for the user. To input the password manually, use -p '' or --password=''  [string] [default: "mariadb"]
  -h, --hosts      List of MaxScale hosts. The hosts must be in HOST:PORT format and each value must be separated by a comma.  [string] [default: "127.0.0.1:8989"]
  -t, --timeout    Request timeout in plain milliseconds, e.g '-t 1000', or as duration with suffix [h|m|s|ms], e.g. '-t 10s'  [string] [default: "10000"]
  -q, --quiet      Silence all output. Ignored while in interactive mode.  [boolean] [default: false]
      --tsv        Print tab separated output  [boolean] [default: false]
      --skip-sync  Disable configuration synchronization for this command  [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests  [boolean] [default: false]
      --tls-key                 Path to TLS private key  [string]
      --tls-passphrase          Password for the TLS private key  [string]
      --tls-cert                Path to TLS public certificate  [string]
      --tls-ca-cert             Path to TLS CA certificate  [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates  [boolean] [default: true]

API options:
      --sum     Calculate sum of API result. Only works for arrays of numbers e.g. `api get --sum servers data[].attributes.statistics.connections`.  [boolean] [default: false]
      --pretty  Pretty-print output.  [boolean] [default: false]

Options:
      --version  Show version number  [boolean]
      --help     Show help  [boolean]

Perform a raw REST API call. The provided value is passed as-is to the REST API after building it with JSON.parse

classify

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

MaxScale Configuration Guide

Introduction

This document describes how to configure MariaDB MaxScale and presents some possible usage scenarios. MariaDB MaxScale is designed with flexibility in mind, and consists of an event processing core with various support functions and plugin modules that tailor the behavior of the program.

Concepts

Glossary

Word

Description

connection routing

Connection routing is a method of handling requests in which MariaDB MaxScale will accept connections from a client and route data on that connection to a single database using a single connection. Connection based routing will not examine individual requests on a connection and it will not move that connection once it is established.

statement routing

Statement routing is a method of handling requests in which each request within a connection will be handled individually. Requests may be sent to one or more servers and connections may be dynamically added or removed from the session.

module

A module is a separate code entity that may be loaded dynamically into MariaDB MaxScale to increase the available functionality. Modules are implemented as run-time loadable shared objects.

connection failover

When a connection currently being used between MariaDB MaxScale and the database server fails a replacement will be automatically created to another server by MariaDB MaxScale without client intervention

backend database

A term used to refer to a database that sits behind MariaDB MaxScale and is accessed by applications via MariaDB MaxScale.

REST API

HTTP administrative interface

Objects

Server

A server represents an individual database server to which a client can be connected via MariaDB MaxScale. The status of a server varies during the lifetime of the server and typically the status is updated by some monitor. However, it is also possible to update the status of a server manually.

Status

Description

Running

The server is running.

Master

The server is the primary.

Slave

The server is a replica.

Draining

The server is being drained. Existing connections can continue to be used, but no new connections will be created to the server. Typically this status bit is turned on manually using maxctrl, but a monitor may also turn it on.

Drained

The server has been drained. The server was being drained and now the number of connections to the server has dropped to 0.

Auth Error

The monitor cannot login and query the server due to insufficient privileges.

Maintenance

The server is under maintenance. Typically this status bit is turned on manually using maxctrl, but it will also be turned on for a server that for some reason is blocking connections from MaxScale. When a server is in maintenance mode, no connections will be created to it and existing connections will be closed.

Slave of External Master

The server is a replica of a primary that is not being monitored.

Master Stickiness

The server is monitored by a galeramon with disable_master_failback=true. See for more information.

For more information on how to manually set these states via MaxCtrl, read the Administration Tutorial.

Monitor

A monitor module is capable of monitoring the state of a particular kind of cluster and making that state available to the routers of MaxScale.

Examples of monitor modules are mariadbmon that is capable of monitoring a regular primary-replica cluster and in addition of performing both switchover and failover, galeramon that is capable of monitoring a Galera cluster, and csmon that is capable of monitoring a Columnstore cluster.

Monitor modules have sections of their own in the MaxScale configuration file.

Filter

A filter module resides in front of routers in the request processing chain of MaxScale. That is, a filter will see a request before it reaches the router and before a response is sent back to the client. This allows filters to reject, handle, alter or log information about a request.

Examples of filters cache that provides query caching according to rules,regexfilter that can rewrite requests according to regular expressions, andqlafilter that logs information about requests.

Filters have sections of their own in the MaxScale configuration file that are referred to from services.

Limitations:

MaxScale: No limitations.
MaxScale Lite: At most 2 filters can be created.

Router

A router module is capable of routing requests to backend servers according to the characteristics of a request and/or the algorithm the router implements. Examples of routers are readconnroute that provides connection &#xNAN;routing, that is, the server is chosen according to specified rules when the session is created and all requests are subsequently routed to that server, and readwritesplit that provides statement routing, that is, each individual request is routed to the most appropriate server.

Routers do not have sections of their own in the MaxScale configuration file, but are referred to from services.

Service

A service abstracts a set of databases and makes them appear as a single one to the client. Depending on what router (e.g. readconnroute orreadwritesplit) the service uses, the servers are used in some particular way. If the service uses filters, then all requests will be pre-processed in some way before they reach the router.

Services have sections of their own in the MaxScale configuration file.

Limitations:

MaxScale: No limitations.
MaxScale Lite: At most 1 service can be created.

Listener

A listener defines a port MaxScale listens on. Connection requests arriving on that port will be forwarded to the service the listener is associated with. A listener may be associated with a single service, but several listeners may be associated with the same service.

Listeners have sections of their own in the MaxScale configuration file.

Include

An include section defines common parameters used in other configuration sections.

Administration

The administration of MaxScale can be divided in two parts:

Writing the MaxScale configuration file, which is described in the following section.
Performing runtime modifications using MaxCtrl

For detailed information about MaxCtrl please refer to the specific documentation referred to above. In the following it will only be explained how MaxCtrl relate to each other, as far as user credentials go.

Note: By default all runtime configuration changes are saved on disk and loaded on startup. Refer to the Dynamic Configuration section for more details on how it works and how to disable it.

MaxCtrl can connect using TCP/IP sockets. When connecting with MaxCtrl using TCP/IP sockets, the user and password must be provided and are checked against a separate user credentials database. By default, that database contains the useradmin whose password is mariadb.

Note that if MaxCtrl is invoked without explicitly providing a user and password then it will by default use admin and mariadb. That means that when the default user is removed, the credentials must always be provided.

Administration audit file

The REST API calls to MaxScale can be logged by enabling admin_audit.

For more detail see the admin audit configuration values admin_audit,admin_audit_file and admin_audit_exclude_methods below and Administration Tutorial.

Static Configuration Parameters

The following list of global configuration parameters can NOT be changed at runtime and can only be defined in a configuration file:

admin_auth
admin_enabled
admin_gui
admin_host
admin_pam_readonly_service
admin_pam_readwrite_service
admin_readonly_hosts
admin_readwrite_hosts
admin_port
admin_secure_gui
admin_ssl_ca
admin_ssl_version
admin_jwt_algorithm
admin_jwt_key
admin_jwt_issuer
auto_tune
cachedir
connector_plugindir
core_file
datadir
debug
execdir
language
libdir
load_persisted_configs
persist_runtime_changes
local_address
log_augmentation
log_warn_super_user
logdir
module_configdir
persistdir
piddir
query_retries
secretsdir
sharedir
sql_mode
substitute_variables
threads_max

All other parameters that relate to objects can be altered at runtime or can be changed by destroying and recreating the object in question.

Configuration

MaxScale by default reads configuration from the file /etc/maxscale.cnf. If the command line argument --configdir=<path> is given, maxscale.cnf is searched for in <path> instead. If the argument --config=<file> is given, configuration is read from the file <file>.

MaxScale also looks for a directory with the same name as the configuration file, followed by ".d" (for example /etc/maxscale.cnf.d). If found, MaxScale recursively reads all files with the ".cnf" suffix in the directory hierarchy. Other files are ignored.

After loading normal configuration files, MaxScale reads runtime-generated configuration files, if any, from the persisted configuration files directory.

Different configuration sections can be arranged with little restrictions. Global path settings such as logdir, piddir and datadir are only read from the main configuration file. Other global settings are also best left in the main file to ensure they are read before other configuration sections are parsed.

The configuration file format used is INI, similar to the MariaDB Server. The files contain sections and each section can contain multiple key-value pairs.

Comments are defined by prefixing a row with a hash (#). Trailing comments are not supported.

# This is a comment before a parameter
some_parameter=123

A parameter can be defined on multiple lines as shown below. A value spread over multiple lines is simply concatenated. The additional lines of the value definition need to have at least one whitespace character in the beginning.

[MyService]
type=service
router=readconnroute
servers=server1,
        server2,
        server3

Names

Section names may not contain whitespace and must not start with the characters@@.

As the object names are used to form URLs in the MaxScale REST API, they must be safe for use in URLs. This means that only alphanumeric characters (i.e. a-zA-Z and 0-9) and the special characters _.~- can be used.

Dynamic Configuration

By default all changes done at runtime via the MaxScale GUI, MaxCtrl or the REST API will be saved on disk, inside the persistdir directory. The changes done at runtime will override the configuration found in the static configuration files for that particular object.

This means that if an object that is found in /etc/maxscale.cnf is modified at runtime, all future changes to it must also be done at runtime. Any modifications done to /etc/maxscale.cnf after a runtime change has been made are ignored for that object.

To prevent the saving of runtime changes and to make all runtime changes volatile, add persist_runtime_changes=false and load_persisted_configs=false under the [maxscale] section. This will make MaxScale behave like the MariaDB server does: any changes done with SET GLOBAL statements are lost if the process is restarted.

Special Parameter Types

Booleans

Boolean type parameters interpret the values true, yes, on and 1 astrue values and false, no, off and 0 as false values. Starting with MaxScale 23.02, the REST API also accepts the same boolean values for boolean type parameters.

Sizes

Where specifically noted, a number denoting a size can be suffixed by a subset of the IEC binary prefixes or the SI prefixes. In the former case the number will be interpreted as a certain multiple of 1024 and in the latter case as a certain multiple of 1000. The supported IEC binary suffixes are Ki, Mi, Gi and Ti and the supported SI suffixes are k, M, G and T. In both cases, the matching is case-insensitive.

For instance, the following entries

max_size=1099511628000
max_size=1073741824Ki
max_size=1048576Mi
max_size=1024Gi
max_size=1Ti

are equivalent, as are the following

max_size=1000000000000
max_size=1000000000k
max_size=1000000M
max_size=1000G
max_size=1T

Durations

A number denoting a duration can be suffixed by one of the case-insensitive suffixes h, m or min, s and ms, for specifying durations in hours, minutes, seconds and milliseconds, respectively.

For instance, the following entries

soft_ttl=1h
soft_ttl=60m
soft_ttl=60min
soft_ttl=3600s
soft_ttl=3600000ms

are equivalent.

Note that if an explicit unit is not specified, then it is specific to the configuration parameter whether the duration is interpreted as seconds or milliseconds.

Not providing an explicit unit has been deprecated in MaxScale 2.4.

Percent

A number denoting a percent must be suffixed with %.

For instance

some_param=42%

Regular Expressions

Many modules have settings which accept a regular expression. In most cases, these settings are named either match or exclude, and are used to filter users or queries. MaxScale uses the PCRE2-library for matching regular expressions.

When writing a regular expression (regex) type parameter to a MaxScale configuration file, the pattern string should be enclosed in slashes e.g. ^select -> match=/^select/. This clarifies where the pattern begins and ends, even if it includes whitespace. Without slashes the configuration loader trims the pattern from the ends. The slashes are removed before compiling the pattern. For backwards compatibility, the slashes are not yet mandatory. Omitting them is, however, deprecated and will be rejected in a future release of MaxScale. Currently, binlogfilter, ccrfilter, qlafilter, tee and avrorouter accept parameters in this type of regular expression form. Some other modules may not handle the slashes yet correctly.

PCRE2 supports a complicated regular expression syntax. MaxScale typically uses regular expressions simply, only checking whether the pattern and subject match at some point. For example, using the QLAFilter and setting match=/SELECT/ causes the filter to accept any query with the text "SELECT" somewhere within. To force the pattern to only match at the beginning of the query, set match=/^SELECT/. To only match the end, setmatch=/SELECT$/.

Modules which accept regular expression parameters also often accept options which affect how the patterns are compiled. Typically, this setting is called options and accepts values such as ignorecase, case and extended.

ignorecase: Causes the regular expression matcher to ignore letter case, and is often on by default. When enabled, /SELECT/ would match both SELECT andselect.
extended: Ignores whitespace and # comments in the pattern. Note that this is not the same as the extended regular expression syntax that for examplegrep -E uses.
case: Turns on case-sensitive matching. This means that /SELECT/ will not match select.

These settings can also be defined in the pattern itself, so they can be used even in modules without pattern compilation settings. The pattern settings are (?i) for ignorecase and (?x) for extended. See the PCRE2 syntax documentation for more information.

Standard regular expression settings for filters

Many filters use the settings match, exclude and options. Since these settings are used in a similar way across these filters, the settings are explained here. The documentation of the filters link here and describe any exceptions to this generalized explanation.

These settings typically limit the queries the filter module acts on. match andexclude define PCRE2 regular expression patterns while options affects how both of the patterns are compiled. options works as explained above, accepting the valuesignorecase, case and extended, with ignorecase being the default.

The queries are matched as they arrive to the filter on their way to a routing module. Ifmatch is defined, the filter only acts on queries matching that pattern. If match is not defined, all queries are considered to match.

If exclude is defined, the filter only acts on queries not matching that pattern. Ifexclude is not defined, nothing is excluded.

If both are defined, the query needs to match match but not match exclude.

Even if a filter does not act on a query, the query is not lost. The query is simply passed on to the next module in the processing chain as if the filter was not there.

Enumerations

Enumeration type parameters have a pre-defined set of accepted values. For types declared as enum, only one value is accepted. For enum_mask types, multiple values can be defined by separating them with commas. All enumeration values in MaxScale are case-sensitive.

For example the router_options parameter in the readconnroute router is a mask type enumeration:

router_options=master,slave

Path Lists

A pathlist type parameter expects one or more filesystem paths separated by colons. The value must not include space between the separators.

Here is an example path list parameter that points to /tmp/something.log and/var/log/maxscale/maxscale.log:

path_list_parameter=/tmp/something.log:/var/log/maxscale/maxscale.log

Global Settings

The global settings, in a section named [MaxScale], allow various parameters that affect MariaDB MaxScale as a whole to be tuned. This section must be defined in the root configuration file which by default is /etc/maxscale.cnf.

`core_file`

Type: boolean
Default: true
Dynamic: No

This parameter specifies whether a core file should be generated if MaxScale crashes. The default is true although usually a core file is not needed, as MaxScale is capable of logging the full strack trace of all threads when it crashes.

`auto_tune`

Type: string list
Values: all or list of auto tunable parameters, separated by ,
Default: No
Mandatory: No
Dynamic: No

An auto tunable parameter is a parameter whose value can be derived from a particular server variable. With this parameter it can be specified whetherall or a specific set of parameters should automatically be set.

The current auto tunable parameters are:

MaxScale Parameter

Server Variable Dependency

80% of the smallest value of the servers used by the service

The smallest value of the servers used by the service

The values of the server variables are collected by monitors, which means that if the servers of a service are not monitored by a monitor, then the parameters of that service will not be auto tuned.

Note that even if auto_tune is set to all, the auto tunable parameters can still be set in the configuration file and modified with maxctrl. However, the specified value will be overwritten at the next auto tuning round, but only if the servers of the service are monitored by a monitor.

`threads`

Type: number or auto
Mandatory: No
Dynamic: No
Default: auto

This parameter controls the number of worker threads that are used for routing client traffic. The default is auto which uses as many threads as there are virtual CPU cores available to MaxScale, rounded up to the nearest integer. If no limitations have been set using CPU affinities or cgroup CPU quotas, this will be the same as the number of CPU cores. In general, as of 24.08, MaxScale will use the appropriate number of threads, also when it is running in a container.

The maximum value for threads is specified by threads_max.

# Valid options are:
#       threads=[<number of threads> | auto ]

[MaxScale]
threads=auto

From 23.02 onwards it is possible to change the number threads at runtime. Please see Threads for more details.

Additional threads will be created to execute other internal services within MariaDB MaxScale. This setting is used to configure the number of threads that will be used to manage the user connections.

`threads_max`

Type: positive integer
Default: 256
Dynamic: No

This parameter specifies the hard limit for the number of worker threads, which is specified using threads.

At startup, if the value of threads is larger than that of threads_max, the value of threads will be reduced to that. At runtime, an attempt to increase the value of threads beyond that of threads_max is an error.

`rebalance_period`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 0s

This duration parameter controls how often the load of the worker threads should be checked. The default value is 0, which means that no checks and no rebalancing will be performed.

rebalance_period=10s

Note that the value of rebalance_period should not be smaller than the value of rebalance_window whose default value is 10.

If the value of rebalance_period is significantly shorter than that of rebalance_window, it may lead to oscillation where work is constantly moved from one thread to another.

`rebalance_threshold`

Type: number
Mandatory: No
Dynamic: Yes
Default: 20

This integer parameter controls at which point MaxScale should start moving work from one worker thread to another.

If the difference in load between the thread with the maximum load and the thread with the minimum load is larger than the value of this parameter, then work will be moved from the former to the latter.

Although the load of a thread can vary between 0 and 100, the value of this parameter must be between 5 and 100.

rebalance_threshold=15

Note that rebalancing will not be performed unless rebalance_period has been specified.

`rebalance_window`

Type: number
Mandatory: No
Dynamic: Yes
Default: 10

This integer parameter controls how many seconds of load should be taken into account when deciding whether work should be moved from one thread to another.

The default value is 10, which means that the load during the last 10 seconds is considered when deciding whether work should be moved.

The minimum value is 1 and the maximum 60.

`skip_name_resolve`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

This parameter controls whether reverse domain name lookups are made to convert client IP addresses to hostnames. If enabled, client IP addresses will not be resolved to hostnames during authentication or for the REST API even if requested.

If you have database users that use a hostname in the host part of the user (i.e. 'user'@'my-hostname.org'), a reverse lookup on the client IP address is done to see if it matches the host. Reverse DNS lookups can be very slow which is why it is recommended that they are disabled and that users are defined using an IP address.

`host_cache_size`

Type: integer
Default: 128
Dynamic: Yes

How many hostname entries are stored in the reverse name lookup cache. Each thread in MaxScale has a cache for the reverse name resolution of client IP addresses to hostnames. Whenever the client authentication requires that a hostname lookup is done, the cache is consulted first. If an entry is found and it was updated less than 300 seconds ago, the cached result is used.

With host_cache_size=0, the cache is disabled and a fresh reverse name lookup is always done.

`auth_connect_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 10s

Duration, default 10s. This setting defines the connection timeout when attempting to fetch MariaDB/MySQL/Clustrix users from a backend server. The same value is also used for read and write timeouts. Increasing this value causes MaxScale to wait longer for a response from a server before user fetching fails. Other servers may then be attempted.

auth_connect_timeout=10s

The value is given as a duration. If no explicit unit is provided, the value is interpreted as seconds. In subsequent versions a value without a unit may be rejected. Since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected even if the given value is longer than a second.

`auth_read_timeout`

Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.

`auth_write_timeout`

Deprecated and ignored as of MaxScale 2.5.0. See auth_connect_timeout above.

`query_retries`

Type: number
Mandatory: No
Dynamic: No
Default: 1

The number of times an interrupted internal query will be retried. The default is to retry the query once. This feature was added in MaxScale 2.1.10 and was disabled by default until MaxScale 2.3.0.

An interrupted query is any query that is interrupted by a network error. Connection timeouts are included in network errors and thus is it advisable to make sure that the value of query_retry_timeout is set to an adequate value. Internal queries are only used to retrieve authentication data and monitor the servers.

`query_retry_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 10s

The total timeout in seconds for any retried queries. The default value is 5 seconds.

An interrupted query is retried for either the configured amount of attempts or until the configured timeout is reached.

The value is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

`passive`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Deprecated since MariaDB MaxScale 25.01. Use cooperative monitoring instead.

Controls whether MaxScale is a passive node in a cluster of multiple MaxScale instances.

This parameter is intended to be used with multiple MaxScale instances that use failover functionality to manipulate the cluster in some form. Passive nodes only observe the clusters being monitored and take no direct actions.

The following functionality is disabled when passive mode is enabled:

Automatic failover in the mariadbmon module
Automatic rejoin in the mariadbmon module
Launching of monitor scripts

NOTE: Even if MaxScale is in passive mode, it will still accept clients and route any traffic sent to it. The only operations affected by the passive mode are the ones listed above.

`ms_timestamp`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Enable or disable the high precision timestamps in logfiles. Enabling this adds millisecond precision to all logfile timestamps.

`syslog`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Log messages to the system journal. This logs messages using the native SystemD journal interface. The logs can be viewed with journalctl.

MaxScale 22.08 changed the default value of syslog from true tofalse. This was done to remove the redundant logging that it caused as bothsyslog and maxlog were enabled by default. This caused each message to be logged twice: once into the system journal and once into MaxScale's own logfile.

`maxlog`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Log messages to MariaDB MaxScale's log file. The name of the log file ismaxscale.log and it is located in the directory pointed by logdir.

`log_warning`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Log messages whose syslog priority is warning.

MaxScale logs warning level messages whenever a condition is encountered that the user should be notified of but does not require immediate action or it indicates a minor problem.

`log_notice`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Log messages whose syslog priority is notice.

These messages contain information that is helpful for the user and they usually do not indicate a problem. These are logged whenever something worth nothing happens in either MaxScale or in the servers it monitors.

`log_info`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Log messages whose syslog priority is info.

These messages provide detailed information about the internal workings of MariaDB MaxScale. These messages should only be enabled when there is a need to inspect the internal logic of MaxScale. A common use-case is to see why a particular query was handled in a certain way. Almost all modules log some messages on the info level and this can be very helpful when trying to solve routing related problems.

`log_debug`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Log messages whose syslog priority is debug.

These messages are intended for development purposes and are disabled by default. These are rarely useful outside of debugging core MaxScale issues.

Note: If MariaDB MaxScale has been built in release mode, then debug messages are excluded from the build and this setting will not have any effect. If an attempt to enable these is made, a warning is logged.

`trace_file_dir`

Type: path
Mandatory: No
Dynamic: No

Path to a directory where trace files will be generated to.

The trace logging offers a low overhead alternative to log_info that is designed to be placed on a local in-memory file system. By placing the files in a location that is not persistent, the overhead of writing to the files is minimal while still allowing the trace logs to be processed as normal log files.

If this parameter is defined along with trace_file_size, MaxScale will write all log messages from all log levels into a set of trace files located in this directory. The files are named maxscale.trace.N where N is an increasing number and whenever a new file is created the oldest one is removed if there are more than 10 trace files.

Starting with MaxScale 24.08.1, the maxscale.trace symlink will be created in the log directory that will point to the latest log file. This symlink can be used with tail -F to interactively monitor the trace stream or to copy the trace output directly into a compressed file:

# Note: to get a clean compressed file, kill the 'tail' process and instead of
# using Ctrl+C to kill 'gzip'.
tail -F /var/log/maxscale/maxscale.trace | gzip > maxscale.trace.gz

The trace files differ from the normal log file written by MaxScale in that they do not contain the local timestamp and instead contain a raw fractional UNIX timestamp. The format of the trace file is subject to change and it may in the future be identical to the normal log generated by MaxScale.

`trace_file_size`

Type: size
Mandatory: No
Dynamic: Yes

The desired amount of log data to keep in the trace files. Each individual trace file will be one tenth the size of trace_file_size and once they exceed this amount, a trace log rotation will occur. For example withtrace_file_size=100Mi, roughly 100MiB of log data is kept in 10 files with about 10MiB of data in each file.

Individual trace files may sometimes exceed this limit and under heavy load the system may end up temporarily using more space than is intended.

`log_warn_super_user`

Type: boolean
Mandatory: No
Dynamic: No
Default: false

When enabled, a warning is logged whenever a client with SUPER-privilege successfully authenticates. This also applies to COM_CHANGE_USER-commands. The setting is intended for diagnosing situations where a client interferes with a primary server switchover. Super-users bypass the read_only-flag which switchover uses to block writes to the primary.

`log_augmentation`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

Enable or disable the augmentation of messages. If this is enabled, then each logged message is appended with the name of the function where the message was logged. This is primarily for development purposes and hence is disabled by default.

# Valid options are:
#       log_augmentation=<0|1>
log_augmentation=1

To disable the augmentation use the value 0 and to enable it use the value 1.

`log_throttling`

Type: number, duration, duration
Mandatory: No
Dynamic: Yes
Default: 10, 1000ms, 10000ms

It is possible that a particular error (or warning) is logged over and over again, if the cause for the error persistently remains. To prevent the log from flooding, it is possible to specify how many times a particular error may be logged within a time period, before the logging of that error is suppressed for a while.

# A valid value looks like
#       log_throttling = X, Y, Z
#
# where the first value X is a positive integer and means the number of times
# a specific error may be logged within a duration of Y, before the logging
# of that error is suppressed for a duration of Z.
log_throttling=8, 2s, 15000ms

In the example above, the logging of a particular error will be suppressed for 15 seconds if the error has been logged 8 times in 2 seconds.

The default is 10, 1000ms, 10000ms, which means that if the same error is logged 10 times in one second, the logging of that error is suppressed for the following 10 seconds.

Whenever an error message that is being throttled is logged within the triggering window (the second argument), the suppression window is extended. This continues until there is a pause in the messages that is longer than the triggering window.

For example, with the default configuration the messages must pause for at least one second in order for the throttling to eventually stop. This mechanism prevents long-lasting error conditions from slowly filling up the log with short bursts of messages.

To disable log throttling, add an entry with an empty value

log_throttling=

or one where any of the integers is 0.

log_throttling=0, 0, 0

The durations can be specified as documented here. If no explicit unit is provided, the value is interpreted as milliseconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected.

Note that notice, info and debug messages are never throttled.

`logdir`

Type: path
Mandatory: No
Dynamic: No
Default: /var/log/maxscale

Set the directory where the logfiles are stored. The folder needs to be both readable and writable by the user running MariaDB MaxScale.

logdir=/var/log/maxscale/

`datadir`

Type: path
Mandatory: No
Dynamic: No
Default: /var/lib/maxscale

Set the directory where the data files used by MariaDB MaxScale are stored. Modules can write to this directory and for example the binlogrouter uses this folder as the default location for storing binary logs.

This is also the directory where the password encryption key is read from that is generated by maxkeys.

datadir=/var/lib/maxscale/

`secretsdir`

Type: path
Mandatory: No
Dynamic: No
Default: ""

The location where the .secrets file is read from. If secretsdir is not defined, the file is read from datadir.

This parameter was added in MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6 and 24.02.2.

`libdir`

Type: path
Mandatory: No
Dynamic: No
Default: OS Dependent

Set the directory where MariaDB MaxScale looks for modules. The library directory is the only directory that MariaDB MaxScale uses when it searches for modules. If you have custom modules for MariaDB MaxScale, make sure you have them in this folder.

The default value depends on the operating system. For RHEL versions the value is /usr/lib64/maxscale/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/

libdir=/usr/lib64/maxscale/

`sharedir`

Type: path
Mandatory: No
Dynamic: No
Default: /usr/share/maxscale

Sets the directory where static data assets are loaded.

The MaxScale GUI static files are located in the gui/ subdirectory. If the GUI files have been manually moved somewhere else, this path must be configured to point to the parent directory of the gui/ subdirectory.

The MaxScale REST API only serves files for the GUI that are located in thegui/ subdirectory of the configured sharedir. Any files whose real path resolves to outside of this directory are not served by the MaxScale GUI: this is done to prevent other files from being accessible via the MaxScale REST API. This means that path to the GUI source directory can contain symbolic links but all parts after the /gui/ directory must reside inside it.

`cachedir`

Type: path
Mandatory: No
Dynamic: No
Default: /var/cache/maxscale

Configure the directory MariaDB MaxScale uses to store cached data.

cachedir=/var/cache/maxscale/

`piddir`

Type: path
Mandatory: No
Dynamic: No
Default: /run/maxscale

Configure the directory for the PID file for MariaDB MaxScale. This file contains the Process ID for the running MariaDB MaxScale process.

MaxScale versions before 24.08.1 used the path /var/run/maxscale/ for the PID files. This was a legacy path according to the Filesystem Hierarchy Standard and starting with MaxScale 24.08.1, the appropriate modern PID file path is used.

`execdir`

Type: path
Mandatory: No
Dynamic: No
Default: /usr/bin

Configure the directory where the executable files reside. All internal processes which are launched will use this directory to look for executable files.

execdir=/usr/bin/

`connector_plugindir`

Type: path
Mandatory: No
Dynamic: No
Default: OS Dependent

Location of the MariaDB Connector-C plugin directory. The MariaDB Connector-C used in MaxScale can use this directory to load authentication plugins. The versions of the plugins must be binary compatible with the connector version that MaxScale was built with.

Starting with version 6.2.0, the plugins are bundled with MaxScale and the default value now points to the bundled plugins. The location where the plugins are stored depends on the operating system. For RHEL versions the value is/usr/lib64/maxscale/plugin/. For Debian and Ubuntu it is/usr/lib/x86_64-linux-gnu/maxscale/plugin/.

Older versions of MaxScale used /usr/lib/mysql/plugin/ as the default value.

connector_plugindir=/usr/lib64/maxscale/plugin/

`persistdir`

Type: path
Mandatory: No
Dynamic: No
Default: /var/lib/maxscale/maxscale.cnf.d/

Configure the directory where persisted configurations are stored. When a new object is created via MaxCtrl, it will be stored in this directory. Do not use this directory for normal configuration files, use /etc/maxscale.cnf.d/ instead. The user MaxScale is running as must be able to write into this directory.

persistdir=/var/lib/maxscale/maxscale.cnf.d/

`module_configdir`

Type: path
Mandatory: No
Dynamic: No
Default: /etc/maxscale.modules.d/

Configure the directory where module configurations are stored. Path arguments are resolved relative to this directory. This directory should be used to store module specific configurations.

Any configuration parameter that is not an absolute path will be interpreted as a relative path. The relative paths use the module configuration directory as the working directory.

For example, the configuration parameter file=my_file.txt would be interpreted as /etc/maxscale.modules.d/my_file.txt whereas file=/home/user/my_file.txt would be interpreted as /home/user/my_file.txt.

module_configdir=/etc/maxscale.modules.d/

`language`

Type: path
Mandatory: No
Dynamic: No
Default: /var/lib/maxscale/

Set the folder where the errmsg.sys file is located in. MariaDB MaxScale will look for the errmsg.sys file installed with MariaDB MaxScale from this folder.

language=/var/lib/maxscale/

`query_classifier`

Deprecated since MariaDB MaxScale 23.08.

`query_classifier_cache_size`

Type: size
Mandatory: No
Dynamic: Yes
Default: System Dependent

Specifies the maximum size of the query classifier cache. The default limit is 15% of available system memory. The available system memory may be less than the total system memory, if MaxScale is running in a container whose resources have been limited.

When the query classifier cache has been enabled, MaxScale will, after a statement has been parsed, store the classification result using the canonicalized version of the statement as the key.

If the classification result for a statement is needed, MaxScale will first canonicalize the statement and check whether the result can be found in the cache. If it can, the statement will not be parsed at all but the cached result is used.

The configuration parameter takes one integer that specifies the maximum size of the cache. The size of the cache can be specified as explained here.

# 1MB query classifier cache
query_classifier_cache_size=1MB

Note that MaxScale uses a separate cache for each worker thread. To obtain the amount of memory available for each thread, divide the cache size with the value of threads. If statements are evicted from the cache (visible in the diagnostic output), consider increasing the cache size.

Note also that limit is not a hard limit, but an approximate one. Namely, although the memory needed for storing the canonicalized statement and the classification result is correctly accounted for, there is additional overhead whose size is not exactly known and over which we do not have direct control.

Using maxctrl show threads it is possible to check what the actual size of the cache is and to see performance statistics.

Key

Meaning

QC cache size

The current size of the cache (bytes).

QC cache inserts

How many entries have been inserted into the cache.

QC cache hits

How many times the classification result has been found from the cache.

QC cache misses

How many times the classification result has not been found from the cache, but the classification had to be performed.

QC cache evictions

How many times a cache entry has had to be removed from the cache, in order to make place for another.

`query_classifier_args`

Deprecated since MariaDB MaxScale 23.08.

`substitute_variables`

Type: boolean
Mandatory: No
Dynamic: No
Default: false

Enable or disable the substitution of environment variables in the MaxScale configuration file. If the substitution of variables is enabled and a configuration line like

some_parameter=$SOME_VALUE

is encountered, then $SOME_VALUE will be replaced with the actual value of the environment variable SOME_VALUE. Note:Variable substitution will be made only if '$' is the first character &#xNAN;of the value. Everything following '$' is interpreted as the name of the environment variable.

Referring to a non-existing environment variable is a fatal error.

substitute_variables=true

The setting of substitute_variables will have an effect on all parameters in the all other sections, irrespective of where the [maxscale] section is placed in the configuration file. However, in the [maxscale] section, to ensure that substitution will take place, place thesubstitute_variables=true line first.

`sql_mode`

Type: enum
Mandatory: No
Dynamic: No
Values: default, oracle
Default: default

Specifies whether the query classifier parser should initially expect MariaDB or PL/SQL kind of SQL.

The allowed values are:default: The parser expects regular MariaDB SQL.oracle : The parser expects PL/SQL.

sql_mode=oracle

NOTE If sql_mode is set to oracle, then MaxScale will also assume that autocommit initially is off.

At runtime, MariaDB MaxScale will recognize statements like

set sql_mode=oracle;

and

set sql_mode=default;

and change mode accordingly.

NOTE If set sql_mode=oracle; is encountered, then MaxScale will also behave as if autocommit had been turned off and conversely, ifset sql_mode=default; is encountered, then MaxScale will also behave as if autocommit had been turned on.

Note that MariaDB MaxScale is not explicitly aware of the sql mode of the server, so the value of sql_mode should reflect the sql mode used when the server is started.

`local_address`

Type: string
Mandatory: No
Dynamic: No
Default: ""

What specific local address/interface to use when connecting to servers.

This can be used for ensuring that MaxScale uses a particular interface when connecting to servers, in case the computer MaxScale is running on has multiple interfaces.

local_address=192.168.1.254

If given as a hostname, MaxScale will perform name lookup on the address when starting and reuse the result.

`users_refresh_time`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 30s

How often, in seconds, MaxScale at most may refresh the users from the backend server.

MaxScale will at startup load the users from the backend server, but if the authentication of a user fails, MaxScale assumes it is because a new user has been created and will thus refresh the users. By default, MaxScale will do that at most once per 30 seconds and with this configuration option that can be changed. A value of 0 allows infinite refreshes and a negative value disables the refreshing entirely.

users_refresh_time=120s

In MaxScale 2.3.9 and older versions, the minimum allowed value was 10 seconds but, due to a bug, the default value was 0 which allowed infinite refreshes.

`users_refresh_interval`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 0s

How often, in seconds, MaxScale will automatically refresh the users from the backend server.

This configuration is used to periodically refresh the backend users, making sure they are up to date. The default value for this setting is 0, meaning the users are not periodically refreshed. However, they can still be refreshed in case of failed authentication depending on users_refresh_time.

users_refresh_interval=2h

`retain_last_statements`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

How many statements MaxScale should store for each session. This is for debugging purposes, as in case of problems it is often of value to be able to find out exactly what statements were sent before a particular problem turned up.

Note: See also dump_last_statements using which the actual dumping of the statements is enabled. Unless both of the parameters are defined, the statement dumping mechanism doesn't work.

retain_last_statements=20

`dump_last_statements`

Type: enum
Mandatory: No
Dynamic: Yes
Values: on_close, on_error, never
Default: never

With this configuration item it is specified in what circumstances MaxScale should dump the last statements that a client sent. The allowed values arenever, on_error and on_close. With never the statements are never logged, with on_error they are logged if the client closes the connection improperly, and with on_close they are always logged when a client session is closed.

dump_last_statements=on_error

Note that you need to specify with retain_last_statements how many statements MaxScale should retain for each session. Unless it has been set to another value than 0, this configuration setting will not have an effect.

`session_trace`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

How many log entries are stored in the session specific trace log. This log is written to disk when a session ends abnormally and can be used for debugging purposes. Currently the session trace log is written to the log in the following situations:

When MaxScale receives a fatal signal and is about to crash.
Whenever an unexpected response is read from a server
If the session is not closed gracefully (i.e. client doesn't send a COM_QUIT packet)
Whenever readwritesplit receives a response that is was not expecting.

It would be good to enable this if a session is disconnected and the log is not detailed enough. In this case the info log might reveal the true cause of why the connection was closed.

session_trace=20

Default is 0.

The session trace log is also exposed by REST API and is shown withmaxctrl show sessions.

The order in which the session trace messages are logged into the log changed in MaxScale 6.4.9 (MXS-4716). Newer versions will log the messages in the "normal log order" of older events coming first and newer events appearing later in the file. Older versions of MaxScale logged the trace dump in the reverse order with the newest messages first and oldest ones last.

`session_trace_match`

Type: regex
Mandatory: No
Dynamic: Yes
Default: None

If both session_trace and session_trace_match are defined, and a trace log entry of a session matches the regular expression, the trace log is written to disk. The check for the match is done when the session is stopping.

The most effective way to debug MaxScale related issues is to turn on log_info and observe the events written into the MaxScale log. The only problem with this approach is that it can cause a severe performance bottleneck and can easily fill up the disk as the amount of data written to it is significant. Withsession_trace and session_trace_match, the content that actually gets logged can be filtered to only what is needed.

For example, the following configuration would only log the trace log messages from sessions that execute SQL queries with syntax errors:

session_trace=1000
session_trace_match=/You have an error in your SQL syntax/

This could be used to easily identify which applications execute the queries without having to gather the info level log output from all the sessions that connect to MaxScale. For every session that ends up logging a syntax error message, the last 1000 lines of log output done by that session is written into the MaxScale log.

`writeq_high_water`

Type: size
Mandatory: No
Dynamic: Yes
Default: 65536

High water mark for network write buffer. When the size of the outbound network buffer in MaxScale for a single connection exceeds this value, network traffic throtting for that connection is started. The parameter accepts size type values. The default value was 16777216 bytes before 22.08.4.

More specifically, if the client side write queue is above this value, it will block traffic coming from backend servers. If the backend side write queue is above this value, it will block traffic from client.

The buffer that this parameter controls is the buffer internal to MaxScale and is not the kernel TCP send buffer. This means that the total amount of buffered data is determined by both the kernel TCP buffers and the value ofwriteq_high_water.

Network throttling is only enabled when writeq_high_water is non-zero. In MaxScale 23.02 and earlier, also writeq_low_water had to be non-zero.

`writeq_low_water`

Type: size
Mandatory: No
Dynamic: Yes
Default: 1024

Low water mark for network write buffer. Once the traffic throttling is enabled, it will only be disabled when the network write buffer is belowwriteq_low_water bytes. The parameter accepts size type values. The default value was 8192 bytes before 22.08.4.

The value of writeq_high_water must always be greater than the value ofwriteq_low_water.

`persist_runtime_changes`

Type: boolean
Default: true
Dynamic: No

Persist changes done at runtime. This parameter was added in MaxScale 22.08.0.

When persist_runtime_changes is enabled, runtime configuration changes done with the GUI, MaxCtrl or via the REST API cause a new configuration file to be saved in /var/lib/maxscale/maxscale.cnf.d/. If load_persisted_configs is enabled, these files will be applied on top of any existing values found in static configuration files whenever MaxScale is starting up.

`load_persisted_configs`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Load persisted runtime changes on startup. This parameter was added in MaxScale 2.3.6.

All runtime configuration changes are persisted in generated configuration files located by default in /var/lib/maxscale/maxscale.cnf.d/ and are loaded on startup after main configuration files have been read. To make runtime configurations volatile (i.e. they are lost when maxscale is restarted), useload_persisted_configs=false. All changes are still persisted since it stores the current runtime state of MaxScale. This makes problem analysis easier if an unexpected outage happens.

`max_auth_errors_until_block`

Type: number
Mandatory: No
Dynamic: Yes
Default: 10

The maximum number of authentication failures that are tolerated before a host is temporarily blocked. The default value is 10 failures. After a host is blocked, connections from it are rejected for 60 seconds. To disable this feature, set the value to 0.

Note that the configured value is not a hard limit. The number of tolerated failures is between max_auth_errors_until_block and threads * max_auth_errors_until_block where max_auth_errors_until_block is the configured value of this parameter and threads is the number of configured threads.

`debug`

Type: string
Mandatory: No
Dynamic: No
Default: ""

Define debug options from the --debug command line option. Either the command line option or the parameter should be used, not both. The debug options are only for testing purposes and are not to be used in production.

REST API Configuration

The MaxScale REST API is an HTTP interface that provides JSON format data intended to be consumed by monitoring applications and visualization tools.

The following options must be defined under the [maxscale] section in the configuration file.

`admin_host`

Type: string
Mandatory: No
Dynamic: No
Default: "127.0.0.1"

The network interface where the REST API listens on. The default value is the IPv4 address 127.0.0.1 which only listens for local connections.

`admin_port`

Type: number
Mandatory: No
Dynamic: No
Default: 8989

The port where the REST API listens on. The default value is port 8989.

`admin_auth`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Enable REST API authentication using HTTP Basic Access authentication. This is not a secure method of authentication without HTTPS but it does add a small layer of security.

For more information, read the REST API documentation.

`admin_ssl_key`

Type: path
Mandatory: No
Dynamic: No
Default: ""

The path to the TLS private key in PEM format for the admin interface.

If the admin_ssl_key and admin_ssl_cert options are all defined, the admin interface will use encrypted HTTPS instead of plain HTTP.

`admin_ssl_cert`

Type: path
Mandatory: No
Dynamic: No
Default: ""

The path to the TLS public certificate in PEM format. See admin_ssl_key documentation for more details.

`admin_ssl_ca_cert`

Deprecated since MariaDB MaxScale 22.08. See admin_ssl_ca.

`admin_ssl_ca`

Type: path
Mandatory: No
Dynamic: No
Default: ""

The path to the TLS CA certificate in PEM format. If defined, the client certificate, if provided, will be validated against it. This parameter is optional starting with MaxScale 2.3.19.

NOTE Up until MariaDB MaxScale 6, the parameter was called admin_ssl_ca_cert, which is still accepted as an alias for admin_ssl_ca.

`admin_ssl_version`

Type: enum_mask
Mandatory: No
Dynamic: No
Values: MAX, TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3, TLSv10, TLSv11, TLSv12, TLSv13
Default: MAX

This parameter controls the enabled TLS versions in the REST API. Accepted values are:

TLSv10
TLSv11
TLSv12
TLSv13 (not supported on OpenSSL 1.0)
MAX

MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer releases accept also the following alias values:

TLSv1.0
TLSv1.1
TLSv1.2
TLSv1.3 (not supported on OpenSSL 1.0)

The default value is MAX which negotiates the highest level of encryption that both the client and server support. The list of supported TLS versions depends on the operating system and what TLS versions the GnuTLS library supports.

For example, to enable only TLSv1.1 and TLSv1.3, useadmin_ssl_version=TLSv1.1,TLSv1.3.

This parameter was added in MaxScale 2.5.7.

Older versions of MaxScale interpreted admin_ssl_version as the minimum allowed TLS version. In those versions, admin_ssl_version=TLSv1.2 allowed both TLSv1.2 and TLSv1.3. In MaxScale 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer versions, the value is a enumeration of accepted TLS protocol versions. In these versions, admin_ssl_version=TLSv1.2 only allows TLSv1.2. To retain the old behavior, specify all the accepted values withadmin_ssl_version=TLSv1.2,TLSv1.3

`admin_ssl_cipher`

Type: string
Mandatory: No
Dynamic: No

Additional TLS cipher settings. The configured value is prepended to admin_ssl_version and the resulting string is given as is to gnutls_priority_init. If left undefined, NORMAL is used.

Adding unrecognized elements to this setting will cause REST-API startup to fail with the error:

REST API HTTP daemon error: Setting priorities to ... failed: The request is invalid.

The value should typically start with a collection of ciphersuites, such as "NORMAL" or "SECURE256". Then, add or remove algorithms with more specific cipher definitions such as "+AES-128-GCM" or "-AES-128-GCM".

admin_ssl_cipher=SECURE256:-ECDHE-RSA:-AES-256-CCM:+AES-128-GCM

`admin_enabled`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Enable or disable the admin interface. This allows the admin interface to be completely disabled to prevent access to it.

`admin_gui`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Enable or disable the admin graphical user interface.

MaxScale provides a GUI for administrative operations via the REST API. When the GUI is enabled, the root REST API resource (i.e. http://localhost:8989/) will serve the GUI. When disabled, the REST API will respond with a 200 OK to the request. By disabling the GUI, the root resource can be used as a low overhead health check.

`admin_secure_gui`

Type: boolean
Mandatory: No
Dynamic: No
Default: true

Whether to serve the GUI only over secure HTTPS connections.

To be secure by default, the GUI is only served over HTTPS connections as it uses a token authentication scheme. This also controls whether the/auth endpoint requires an encrypted connection.

To allow use of the GUI without having to configure TLS certificates for the MaxScale REST API, set this parameter to false.

`admin_log_auth_failures`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Log authentication failures for the admin interface.

`admin_pam_readwrite_service`

Type: string
Mandatory: No
Dynamic: No
Default: ""

Use Pluggable Authentication Modules (PAM) for REST API authentication. This setting and admin_pam_readonly_service accept a PAM service name which is used during authentication if normal authentication fails.admin_pam_readwrite_service should accept users who can do any MaxCtrl/REST-API-operation. admin_pam_readonly_service should accept users who can only do read operations. Because REST-API does not support back and forth communication between the client and MaxScale, the PAM services must be simple. They should only ask for the password and nothing else.

If only admin_pam_readwrite_service is configured, both read and write operations can be authenticated by PAM. If only admin_pam_readonly_service is configured, only read operations can be authenticated by PAM. If both are set, the service used is determined by the requested operation. Leave or set both empty to disable PAM for REST-API.

`admin_pam_readonly_service`

Type: string
Mandatory: No
Dynamic: No
Default: ""

See admin_pam_readwrite_service.

`admin_readwrite_hosts`

Type: string
Mandatory: No
Dynamic: No
Default: %

Limit REST-API logins to specific source addresses/hosts. Supports a comma-separated list of addresses and hostnames. Addresses can be given in CIDR-notation. Admin clients still need to supply credentials as usual. By default, all source addresses are allowed. admin_readwrite_hosts lists the hosts from which any operation is allowed.

admin_readwrite_hosts=192.168.1.1,127.0.0.1/21

When listing hostnames, % and _ act as wildcards, similar to the hostname component in MariaDB Server user accounts. localhost is a reserved hostname and will not match any connection (use 127.0.0.1 for loopback connections).

When checking the source host of the incoming REST-API client, MaxScale first compares against addresses and address masks. If a match was not found and the setting values contain hostnames, reverse name lookup is performed on the client address. The lookup can take a while in rare cases. To prevent such slowdown, use only IP-addresses in the host lists.

skip_name_resolve cannot be enabled if admin_readwrite_hosts oradmin_readonly_hosts includes hostname patterns, as these would not work.

`admin_readonly_hosts`

Works similar to admin_readwrite_hosts. Lists the hosts from which only read operations are allowed. An admin client can do a read operation if their source address matches either admin_readwrite_hosts or admin_readonly_hosts.

admin_readonly_hosts=mydomain%.com

`admin_jwt_algorithm`

Type: enum
Mandatory: No
Dynamic: No
Values: auto, HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ED25519, ED448
Default: auto

The signature algorithm used by the MaxScale REST API when generating JSON Web Tokens.

For more information about the tokens and how they work, refer to the REST API documentation.

If a symmetric algorithm is used (i.e. HS256, HS384 or HS512), MaxScale will generate a random encryption key on startup and use that to sign the messages. The symmetric key can also be retrieved from an Encryption Key Manager if the admin_jwt_key parameter is defined.

If an asymmetric algorithm (i.e. public key authentication) is used, both theadmin_ssl_cert and admin_ssl_key parameters must be defined and they must contain a private key and a public certificate of the correct type. If the wrong key type, key length or elliptic curve is used, MaxScale will refuse to start.

Asymmetric key algorithms make it possible for the clients of the REST API to validate that the token was indeed generated by the correct entity.

Symmetric algorithms make it easy to share the same tokens between multiple MaxScale instances as the shared secret can be stored in a key management system.

The possible values for this parameter are:

auto
MaxScale will attempt to detect the best algorithm to use for signatures. The algorithm used depends on the private key type: RSA keys usePS256, EC keys use the ES256, ES384 or ES512 depending on the curve, Ed25519 keys use ED25519 and Ed448 keys uses ED448. If MaxScale cannot auto-detect the key type, it falls back to HS256 as the default algorithm.
HS256, HS384 or HS512
HMAC with SHA-2 Functions. Ifadmin_jwt_key is not defined, uses a random encryption key of the correct size.
RS256, RS384 or RS512
Digital Signature with RSASSA-PKCS1-v1_5. Requires at least a 2048-bit RSA key.
PS256, PS384 or PS512
Digital Signature with RSASSA-PSS. Requires at least a 2048-bit RSA key.
ES256, ES384 or ES512
Digital Signature with ECDSA. Requires an EC key with the correct curve: P-256 for ES256, P-384 for ES384 and P-512 for ES512.
ED25519 or ED448
Edwards-curve Digital Signature Algorithm (EdDSA). Requires a Ed25519 key for ED25519 or a Ed448 key for ED448.

`admin_jwt_key`

Type: string
Mandatory: No
Dynamic: No
Default: ""

The ID for the encryption key used to sign the JSON Web Tokens. If configured, an Encryption Key Manager must also be configured and it must contain the key with the given ID. If no key is defined, MaxScale will use a random encryption key whenever a symmetric signature algorithm is used.

Currently, the encryption key is only read on startup. This means that the tokens will be signed by the latest key version that is available on startup: rotating the encryption key in the key management system will not cause the JWTs to be signed with newer versions of the key.

`admin_jwt_max_age`

Type: duration
Mandatory: No
Dynamic: No
Default: 24h

The maximum lifetime of a token generated by the /auth endpoint.

If a client requests for a token with a lifetime that exceeds the configured value, the token lifetime is silently truncated to this value. This can be used to control the maximum length of a MaxGUI session.

This also acts as the effective maximum age of any database connection created from the /sql endpoint.

`admin_oidc_url`

Type: string
Mandatory: No
Dynamic: No
Default: ""

The URL to a OpenID Connect server that is used for JWT validation.

If defined, any tokens signed by this server are accepted as valid bearer tokens for the MaxScale REST API. The "sub" field of the token is assumed to be the username of an administrative user in MaxScale and the "account" claim is assumed to be the type of the user: "admin" for administrative users with full access to the REST-API and "basic" for users with read-only access to the REST-API. This means that all users must be first created with maxctrl create user before the tokens are accepted if the OIDC provider is not able to add the"account" claim.

If this URL is changed at runtime, the new certificates will not be fetched until a maxctrl reload tls command is executed.

`admin_verify_url`

Type: string
Mandatory: No
Dynamic: No
Default: ""

URL to a server to which the REST API token verification is delegated.

If the URL is defined, any tokens passed to the REST API will be validated by doing a GET request to the URL with the client's token as a bearer token. TheReferer header of the request is set to the URL being requested by the client and the custom X-Referrer-Method header is set to the HTTP method being used (PUT, GET etc.).

Note: When admin_verify_url is used and the remote server cannot be accessed, all REST API access that uses tokens will be disabled. The only way to use the REST API with tokens is to remove admin_verify_url from the configuration which requires restarting MaxScale. The REST API still accepts HTTP Basic Access authentication even if the remote server cannot be reached.

By delegating the authentication and authorization of the REST API to an external server, users can implement custom access control systems for the MaxScale REST API.

`admin_jwt_issuer`

Type: string
Mandatory: No
Dynamic: No
Default: maxscale

The issuer ("iss") claim of all JWTs generated by MaxScale. This can be set to a custom value to uniquely identify which MaxScale issued a JWT. This is especially useful for cases where the MaxScale GUI is used from behind a reverse proxy.

`admin_audit`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Enable logging of incoming REST API calls.

`admin_audit_file`

Type: string
Mandatory: No
Dynamic: Yes
Default: /var/log/maxscale/admin_audit.csv

The file where the REST API auditing information is logged.

If a non-default value is used, the directory where the file resides must exist. For example, with /var/log/maxscale/audit_files/audit.csv, the directory /var/log/maxscale/audit_files must exist.

`admin_audit_exclude_methods`

Type: enum
Mandatory: No
Dynamic: Yes
Values: GET, PUT, POST, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE
Default: No exclusions

List of comma separated HTTP methods to exclude from logging Currently MaxScale does not use CONNECT or TRACE.

Resetting to log all methods can be done in the configuration file by writing admin_audit_exclude_methods= or at runtime withmaxctrl alter maxscale admin_audit_exclude_methods=. Remember that once a runtime change has been made, the entry for that setting is ignored in the main configuration file (usually maxscale.cnf).

`config_sync_cluster`

Type: monitor
Mandatory: No
Dynamic: Yes
Default: None

This parameter controls which cluster (i.e. monitor) is used to synchronize configuration changes between MaxScale instances. The first server labeledMaster will be used for the synchronization.

By default configuration synchronization is not enabled and it must be explicitly enabled by defining a monitor name for config_sync_cluster.

When config_sync_cluster is defined, config_sync_user andconfig_sync_password must also be defined.

For a detailed description of this feature, refer to the Configuration Synchronization section.

`config_sync_user`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

The username for the account that is used to synchronize configuration changes across MaxScale instances. Both this parameter and config_sync_password are required if config_sync_cluster is configured.

This account must have the following grants:

GRANT SELECT, INSERT, UPDATE, CREATE ON `mysql`.`maxscale_config`

The mysql.maxscale_config table can be pre-created in which case the CREATE grant is not needed by the user configured in config_sync_user. The following SQL is used to create the table.

CREATE TABLE IF NOT EXISTS mysql.maxscale_config(
  cluster VARCHAR(256) PRIMARY KEY,
  version BIGINT NOT NULL,
  config JSON NOT NULL,
  origin VARCHAR(254) NOT NULL,
  nodes JSON NOT NULL
) ENGINE=InnoDB;

If the database where the table is created is changed with config_sync_db, the grants must be adjusted to target that database instead.

`config_sync_password`

Type: password
Mandatory: No
Dynamic: Yes
Default: None

The password for config_sync_user. Both this parameter and config_sync_user are required if config_sync_cluster is configured. This password can optionally be encrypted using maxpasswd.

`config_sync_db`

Type: string
Mandatory: No
Dynamic: No
Default: mysql

The database where the maxscale_config table is created. By default the table is created in the mysql database. This parameter was added in MaxScale versions 6.4.6 and 22.08.5.

As tables in the mysql database cannot have triggers on them, the database must be changed to a user-created one in order to create triggers on the table. An example use-case for triggers on this table is to track all configuration changes done to MaxScale by inserting them into a separate table.

`config_sync_interval`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 5s

How often to synchronize the configuration with the cluster.

As the synchronization involves selecting the configuration version from the database, this value should not be set to an unreasonably low value. The default value of 5 second should provide a good compromise between responsiveness and how much load it places on the database.

`config_sync_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 10s

Timeout for all SQL operations done during the configuration synchronization. If an operation exceeds this timeout, the configuration change is treated as failed and an error is reported to the client that did the change.

`key_manager`

Type: enum
Dynamic: Yes
Values: none, file, kmip, vault
Default: none

The encryption key manager to use. The available encryption key managers are:

none - No key manager, encryption keys are not available.
file - File-based key manager
kmip - KMIP key manager
vault - HashiCorp Vault key manager. This key manager is only included on systems with GCC 9 or newer which means it cannot be used on Ubuntu 18.04.

Refer to the Encryption Key Managers section for more information on how to configure the key managers. The key managers each have their configuration in their own namespace and must have their name as a prefix.

For example to configure the file key manager, the following must be used:

key_manager=file
file.keyfile=/path/to/keyfile

Events

MaxScale logs warnings and errors for various reasons and often it is self- evident and generally applicable whether some occurrence should warrant a warning or an error, or perhaps just an info-level message.

However, there are events whose seriousness is not self-evident. For instance, in some environments an authentication failure may simply indicate that someone has made a typo, while in some other environment that can only happen in case there has been a security breech.

To handle events like these, MaxScale defines events whose logging facility and level can be controlled by the administrator. Given an eventX, its facility and level are controlled in the following manner:

event.X.facility=LOG_LOCAL0
event.X.level=LOG_ERR

The above means that if event X occurs, then that is logged using the facility LOG_LOCAL0 and the level LOG_ERR.

The valid values of facilityare the facility values reported byman syslog, e.g.LOG_AUTH,LOG_LOCAL0andLOG_USER. Likewise, the valid values forlevelare the ones also reported byman syslog, e.g.LOG_WARNING,LOG_ERRandLOG_CRIT`.

Note that MaxScale does not act upon the level, that is, even if the level of a particular event is defined to be LOG_EMERG, MaxScale will not shut down if that event occurs.

The default facility is LOG_USER and the default level is LOG_WARNING.

Note that you may also have to configure rsyslog to ensure that the event can be logged to the intended log file. For instance, if the facility is chosen to be LOG_AUTH, then /etc/rsyslog.conf should contain a line like

auth,authpriv.*                 /var/log/auth.log

for the logged events to end up in /var/log/auth.log, where the initialauth is the relevant entry.

The available events are:

'authentication_failure'

This event occurs when there is an authentication failure.

event.authentication_failure.facility=LOG_AUTH
event.authentication_failure.level=LOG_CRIT

Service

A service represents the database service that MariaDB MaxScale offers to the clients. In general a service consists of a set of backend database servers and a routing algorithm that determines how MariaDB MaxScale decides to send statements or route connections to those backend servers.

A service may be considered as a virtual database server that MariaDB MaxScale makes available to its clients.

Several different services may be defined using the same set of backend servers. For example a connection based routing service might be used by clients that already performed internal read/write splitting, whilst a different statement based router may be used by clients that are not written with this functionality in place. Both sets of applications could access the same data in the same databases.

A service is identified by a service name, which is the name of the configuration file section and a type parameter of service.

[Test-Service]
type=service

In order for MariaDB MaxScale to forward any requests it must have at least one service defined within the configuration file. The definition of a service alone is not enough to allow MariaDB MaxScale to forward requests however, the service is merely present to link together the other configuration elements.

`router`

Type: router
Mandatory: Yes
Dynamic: No

The router parameter of a service defines the name of the router module that will be used to implement the routing algorithm between the client of MariaDB MaxScale and the backend databases. Additionally routers may also be passed a comma separated list of options that are used to control the behavior of the routing algorithm. The two parameters that control the routing choice are router and router_options. The router options are specific to a particular router and are used to modify the behavior of the router. The read connection router can be passed options of master, slave or synced, an example of configuring a service to use this router and limiting the choice of servers to those in slave state would be as follows.

router=readconnroute
router_options=slave

To change the router to connect on to servers in the master state as well as slave servers, the router options can be modified to include the master state.

router=readconnroute
router_options=master,slave

A more complete description of router options and what is available for a given router is included with the documentation of the router itself.

`filters`

Type: filter list
Mandatory: No
Dynamic: Yes
Default: None

The filters option allow a set of filters to be defined for a service; requests from the client are passed through these filters before being sent to the router for dispatch to the backend server. The filters parameter takes one or more filter names, as defined within the filter definition section of the configuration file. Multiple filters are separated using the | character.

filters=counter | QLA

The requests pass through the filters from left to right in the order defined in the configuration parameter.

`targets`

Type: target list
Mandatory: No
Dynamic: Yes
Default: None

The targets parameter is a comma separated list of server and/or service names that comprise the routing targets of the service. This parameter was added in MaxScale 2.5.0.

targets=My-Service,server2

This parameter allows nested service configurations to be defined without having to configure listeners for all services. For example, one use-case is to use multiple readwritesplit services behind a schemarouter service to have both the sharding of schemarouter with the high-availability of readwritesplit.

NOTE: The targets parameter is mutually exclusive with the cluster andservers parameters.

`servers`

Type: server list
Mandatory: No
Dynamic: Yes
Default: None

The servers parameter in a service definition provides a comma separated list of the backend servers that comprise the service. The server names are those used in the name section of a block with a type parameter of server (see below).

servers=server1,server2,server3

NOTE: The servers parameter is mutually exclusive with the cluster andtargets parameters.

`cluster`

Type: monitor
Mandatory: No
Dynamic: Yes
Default: None

The servers the service uses are defined by the monitor specified as value of this configuration parameter.

cluster=TheMonitor

NOTE: The cluster parameter is mutually exclusive with the servers andtargets parameters.

`user`

Type: string
Mandatory: Yes
Dynamic: Yes

This setting defines the user the service uses to fetch user account information from backends. A password is specified using password.

user=maxscale
password=Mhu87p2D

See MySQL protocol authentication documentation for more information (such as required grants) and troubleshooting tips regarding user account management and client authentication.

`password`

Type: string
Mandatory: Yes
Dynamic: Yes

This settings defines the password the service uses to fetch user account information from backends. The password may be either a plain text password or an encrypted password. The user is specified using user.

user=maxscale
password=Mhu87p2D

See MySQL protocol authentication documentation for more information (such as required grants) and troubleshooting tips regarding user account management and client authentication.

From 23.08.0 onwards, MaxScale will remember the previous password when the password is changed. If the fetching of the user account information fails using the new password, it will be attempted using the previous one. The purpose of this change is to make it a smoother operation to change the password of the service user. The steps are as follows:

$ maxctrl alter service MyService password=TheNewPassword
MariaDB [(none)]> set password for TheServiceUser = password('TheNewPassword');

Since the old password is remembered and used if the new password does not work, it is no longer necessary to perform those steps simultaneously.

`enable_root_user`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

This parameter controls the ability of the root user to connect to MariaDB MaxScale and hence onwards to the backend servers via MariaDB MaxScale.

`localhost_match_wildcard_host`

Deprecated and ignored.

`version_string`

Type: string
Mandatory: No
Dynamic: No
Default: None

This parameter sets a custom version string that is sent in the MySQL Handshake from MariaDB MaxScale to clients.

Example:

version_string=10.11.2-MariaDB-RWsplit

If not set, MaxScale will attempt to use a version string from the backend databases by selecting the version string of the database with the lowest version number. If the selected version is from the MariaDB 10 series, a 5.5.5- prefix will be added to it similarly to how the MariaDB 10 series versions added it.

If MaxScale has not been able to connect to a single database and the versions are unknown, the default value of 5.5.5-10.4.32 <MaxScale version>-maxscale is used where <MaxScale version> is the version of MaxScale.

`auth_all_servers`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

This parameter controls whether only a single server or all of the servers are used when loading the users from the backend servers.

By default MaxScale uses the first server labeled as Master as the source of the authentication data. When this option is enabled, the authentication data is loaded from all the servers and combined into one big data set.

Note: This parameter was deprecated in MaxScale 24.02.0 but it was then un-deprecated as there were still uses for it. Modules that required this to function correctly (e.g. schemarouter) now automatically enable it.

`strip_db_esc`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Note: This parameter has been deprecated in MaxScale 23.08. The stripping of escape characters is in all known cases the correct thing to do.

This setting controls whether escape characters (\) are removed from database names when loading user grants from a backend server. When enabled, a grant such as grant select on test_.* to 'user'@'%'; is read as grant select on test_.* to 'user'@'%';

This setting has no effect on database-level grants fetched from a MariaDB Server. The database names of a MariaDB Server are compared using the LIKE operator to properly handle wildcards and escaped wildcards. This setting may affect database names in table and column level grants, although these typically do not contain backlashes.

Some visual database management tools automatically escape some characters and this might cause conflicts when MaxScale tries to authenticate users.

`log_auth_warnings`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Enable or disable the logging of authentication failures and warnings. If enabled, messages about failed authentication attempts will be logged with details about who tried to connect to MariaDB MaxScale and from where.

`log_warning`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

When enabled, this allows a service to log warning messages even if the global log level configuration disables them.

Note that disabling the service level logging does not override the global logging configuration: with log_warning=false in the service andlog_warning=true globally, warnings will still be logged for all services.

`log_notice`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

When enabled, this allows a service to log notice messages even if the global log level configuration disables them.

`log_info`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

When enabled, this allows a service to log info messages even if the global log level configuration disables them.

`log_debug`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

When enabled, this allows a service to log debug messages even if the global log level configuration disables them.

Debug messages are only enabled for debug builds. Enabling log_debug in a release build does nothing.

`wait_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 28800s (>= MaxScale 24.02.5, 25.01.2), 0s (<= MaxScale 24.02.4, 25.01.1)
Auto tune: Yes

The wait_timeout parameter is used to disconnect sessions to MariaDB MaxScale that have been idle for too long. The session timeout is set to 28800 seconds by default. A value of zero is interpreted as no timeout.

This parameter used to be called connection_timeout and this name is still accepted as an alias for wait_timeout. The old name has been deprecated in MaxScale 23.08.

The default value of wait_timeout changed from 0s to 28800s in MaxScale versions 24.02.5 and 25.01.2 to match the default value of MariaDB (MXS-5530).

Note that since the granularity of the timeout is seconds, a timeout specified in milliseconds will be rejected, even if the duration is longer than a second.

This parameter only takes effect in top-level services. A top-level service is the service where the listener that the client connected to points (i.e. the value of service in the listener). If a service defines other services in itstargets parameter, the wait_timeout for those is not used.

The value of wait_timeout in MaxScale should be lower than the lowestwait_timeout value on the backend servers. This way idle clients are disconnected by MaxScale before the backend servers have to close them. Any client-side idle timeouts (e.g. maximum lifetime for connection pools) should be lower than wait_timeout in both MaxScale and MariaDB. This way the client application will end up closing the connection itself which most of the time results in better and more helpful error messages.

Warning: If a connection is idle for longer than the configured connection timeout, it will be forcefully disconnected and a warning will be logged in the MaxScale log file.

Example:

[Test-Service]
wait_timeout=300s

`max_connections`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0 in MaxScale, 15 in MaxScale Lite.
Minimum: 0 in MaxScale, 1 in MaxScale Lite.
Maximum: Unlimited in MaxScale, 15 in MaxScale Lite.

The maximum number of simultaneous connections MaxScale should permit to this service. Any attempt to make more connections after the limit is reached will result in a "Too many connections" error being returned.

A value of 0 means no limit, which is the default for MaxScale. MaxScale Lite is limited to a maximum of 15 connections per service.

Warning: In MaxScale 2.5, it is possible that the number of concurrent connections temporarily exceeds the value of max_connections. This has been fixed in MaxScale 6.

Example:

[Test-Service]
max_connections=100

`session_track_trx_state`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

*Note: This parameter has been deprecated in MaxScale 23.08 as the feature is now used automatically if needed. In addition, the session tracking no longer needs to be enabled in MariaDB for the transaction state tracking to work correctly.

Enable transaction state tracking by offloading it to the backend servers. Getting the transaction state from the server will be more accurate for stored procedures or multi-statement SQL that modifies the transaction state non-atomically.

In general, it is better to avoid using this type of SQL as tracking the transaction state via the server responses is not compatible with features such as transaction_replay in readwritesplit. session_track_trx_state should only be enabled if the default transaction tracking done by MaxScale does not produce the desired outcome.

This is only supported by MariaDB versions 10.3 or newer. The following must be configured in the MariaDB server in order for this feature to work. Not configuring the MariaDB server with it can result in the transaction state being wrong in MaxScale which can result in data inconsistency.

session_track_state_change = ON
session_track_transaction_info = CHARACTERISTICS

`retain_last_statements`

Type: number
Mandatory: No
Dynamic: Yes
Default: -1

How many statements MaxScale should store for each session of this service. This overrides the value of the global setting with the same name. Ifretain_last_statements has been specified in the global section of the MaxScale configuration file, then if it has not been explicitly specified for the service, the global value holds, otherwise the service specific value rules. That is, it is possible to enable the setting globally and turn it off for a specific service, or just enable it for specific services.

The value of this parameter can be changed at runtime using maxctrl and the new value will take effect for sessions created thereafter.

maxctrl alter service MyService retain_last_statements 5

`connection_keepalive`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 300s
Auto tune: Yes

Keep idle connections alive by sending pings to backend servers. This feature was introduced in MaxScale 2.5.0 where it was changed from a readwritesplit-specific feature to a generic service feature. The default value for this parameter is 300 seconds. To disable this feature, set the value to 0.

The keepalive interval is specified as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.5. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the keepalive is seconds, a keepalive specified in milliseconds will be rejected, even if the duration is longer than a second.

The parameter value is the interval in seconds between each keepalive ping. A keepalive ping will be sent to a backend server if the connection has been idle for longer than the configured keepalive interval.

Starting with MaxScale 2.5.21 and 6.4.0, the keepalive pings are not sent if the client has been idle for longer than the configured value ofconnection_keepalive. Older versions of MaxScale sent the keepalive pings regardless of the client state.

If the value of connection_keepalive is changed at runtime, the change in the value takes effect immediately.

As the connection keepalive pings must be done only when there's no ongoing query, all requests and responses must be tracked by MaxScale. In the case ofreadconnroute, this will incur a small drop in performance. For routers that rely on result tracking (e.g. readwritesplit and schemarouter), the performance will be the same with or without connection_keepalive.

If you want to avoid the performance cost and you don't need the connection keepalive feature, you can disable it with connection_keepalive=0s.

`force_connection_keepalive`

Type: boolean
Mandatory No
Dynamic: Yes
Default: false

By default, connection keepalive pings are only sent if the client is either executing a query or has been idle for less than the duration configured inconnection_keepalive. When this parameter is enabled, keepalive pings are unconditionally sent to any backends that have been idle for longer thanconnection_keepalive seconds. This option was added in MaxScale 6.4.9 and can be used to emulate the pre-2.5.21 behavior if long-lived application connections rely on the old unconditional keepalive pings.

Note: if force_connection_keepalive is enabled and connection_keepalive in MaxScale is set to a lower value than the wait_timeout on the database, the client idle timeouts that wait_timeout control are no longer effective. This happens because MaxScale unconditionally sends the pings which make the client behave like it is not idle and thus the connections will never be killed due towait_timeout.

`net_write_timeout`

Type: durations
Mandatory No
Dynamic: Yes
Default: 0s

This parameter controls how long a network write to the client can stay buffered. This feature is disabled by default.

When net_write_timeout is configured and data is buffered on the client network connection, if the time since the last successful network write exceeds the configured limit, the client connection will be disconnected.

`max_sescmd_history`

Type: number
Mandatory: No
Dynamic: Yes
Default: 50

max_sescmd_history sets a limit on how many distinct session commands are stored in the session command history. When the history limit is exceeded, the history is either pruned to the last max_sescmd_history command (whenprune_sescmd_history is enabled) or the history is disabled and server reconnections are no longer possible.

The required history size can be estimated by counting the total number of session state modifying commands (e.g SET NAMES) that are used by a client. Note that connectors usually add some commands that aren't visible to the application developer which means a safety margin should be added. A good rule of thumb is to count the expected number of statements and double that number. The default value of 50 is a value that'll work for most applications that do not rely heavily on user variables.

Starting with MaxScale versions 21.06.18, 22.08.15, 23.02.12, 23.08.8, 24.02.4 and 24.08.1, binary protocol prepared statements do not count towards themax_sescmd_history limit. In practice this means that all binary protocol prepared statements opened by the client are also kept open by MaxScale and are restored whenever a reconnection to a server happens. The limits imposed bymax_sescmd_history apply to other text protocol commands e.g. SET NAMES. Note that text protocol prepared statements count as text protocol commands and are thus potentially pruned when history pruning happens. If an application uses a lot of PREPARE stmt FROM <sql> commands, it is recommended that the value ofmax_sescmd_history is increased accordingly.

In older versions of MaxScale, binary protocol prepared statements were limited by max_sescmd_history and were also pruned by prune_sescmd_history but this caused problems when the binary protocol prepared statment were pruned while they were still open from the client's point of view. In older versions, the recommended value of max_sescmd_history is the number of state modifying commands plus the maximum number of open prepared statments that any application may use.

This parameter was moved into the MaxScale core in MaxScale 6.0. The parameter can be configured for all routers that support the session command history. Currently only readwritesplit and schemarouter support it.

In addition to limiting the number of commands to store, it also acts as a hard limit on the number of packets that may be queued up on a backend before it is closed. Packets are queued while the TCP socket is being opened and when prepared statements are being prepared. In certain rare cases, a slow server may fall behind and not catch up to the rest of the cluster and a backlog of packets forms. In these cases, if more than max_sescmd_history packets are queued, the connection to the server is closed.

`prune_sescmd_history`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

This option enables pruning of the session command history when it exceeds the value configured in max_sescmd_history. When this option is enabled, only a set number of statements are stored in the history. This limits the per-session memory use while still allowing safe reconnections.

This parameter is intended to be used with pooled connections that remain in use for a very long time. Most connection pool implementations do not reset the session state and instead re-initialize it with new values. This causes the session command history to grow at roughly a constant rate for the lifetime of the pooled connection.

Starting with MaxScale 23.08, the session command history is also simplified before being stored. The simplification is done by removing repeated occurrences of the same command and only executing the latest one of them. The order in which the commands are executed still remains the same but inter-dependencies between commands are not preserved.

For example, the following set of commands demonstrates how the history simplification works and how inter-dependencies can be lost.

SET @my_planet='Earth';                            -- This command will be removed by history simplification
SET @my_home='My home is: ' || @my_planet;         -- Command #1 in the history
SET @my_planet='Earth';                            -- Command #2 in the history

In the example, the value of @my_home has a dependency on the value of@my_planet which is lost when the same statement is executed again and the history simplification removes the earlier one.

This same problem can occur even in older versions of MaxScale that used a sliding window of the history when the window moves past the statement that later statement depended on. If inter-dependent session commands are being used, the history pruning should be disabled.

Each client-side session that uses a pooled connection only executes a finite amount of session commands. By retaining a shorter history that encompasses all session commands the individual clients execute, the session state of a pooled connection can be accurately recreated on another server.

When the session command history pruning is enabled, there is a theoretical possibility that upon server reconnection the session states of the connections are inconsistent. This can only happen if the length of the stored history is shorter than the list of relevant statements that affect the session state. In practice the default value of 50 session commands is a fairly reasonable value and the risk of inconsistent session state is relatively low.

In case the default history length is too short for safe pruning, set the value of max_sescmd_history to the total number of commands that affect the session state plus a safety margin of 10. The safety margin reserves some extra space for new commands that might be executed due to changes in the client side application.

Starting with MaxScale 24.02.1, the execution of simple session commands done with binary protocol prepared statements are also stored in the history. A simple session command in the binary protocol is one that:

Takes no parameters
Modifies the session state
Is executed while the original prepared statement is still in the history

The same limitations that apply to the text protocol session commands apply to the binary protocol session commands.

`disable_sescmd_history`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

This option disables the session command history. This way no history is stored and if a replica server fails, the router will not try to replace the failed replica. Disabling session command history will allow long-lived connections without causing a constant growth in the memory consumption.

This parameter should only be used when either the memory footprint must be as small as possible or when the pruning of the session command history is not acceptable.

`user_accounts_file`

Type: path
Mandatory: No
Dynamic: No
Default: ""

Defines path to a file with additional user accounts for incoming clients. Default value is empty, which disables the feature.

user_accounts_file=/home/root/users.json

In addition to querying the backends, MaxScale can read users from a file. This feature is useful when backends have limitations on the type of users that can be created, or if MaxScale needs to allow users to log in even when backends are down (e.g. binlog router). The users read from the file are only present on MaxScale, so logging into backends can still fail. The format of the file is protocol-specific. The following only applies to MariaDB-protocol, which is also the only protocol supporting this feature.

The file contains json text. Three objects are read from it: user, db androles_mapping, none of which are mandatory. These objects must be arrays which contain user information similar to the mysql.user, mysql.db andmysql.roles_mapping tables on the server. Each array element must define at least the string fields user and host, which define the user account to add or modify.

The elements in the user-array may contain the following additional fields. If a field is not defined, it is assumed either empty (string) or false (boolean).

password: String. Password hash, similar to the equivalent column on server.
plugin: String. Authentication plugin used by client, similar to server.
authentication_string: String. Additional authentication info, similar to server.
default_role: String. Default role of user, similar to server.
super_priv: Boolean. True if user has SUPER grant.
global_db_priv: Boolean. True if user can access any database on login.
proxy_priv: Boolean. True if user has a PROXY grant.
is_role: Boolean. True if user is a role.

The elements in the db-array must contain the following additional field:

db: String. Database which the user can access. Can contain % and _ wildcards.

The elements in the roles_mapping-array must contain the following additional field:

role: String. Role the user can access.

When users are read from both servers and the file, the server takes priority. That is, if user 'joe'@'%' is defined on both, the file-version is discarded. The file can still affect the database grants and roles of 'joe'@'%', as thedb and roles_mapping-arrays are read separately and added to existing grant and role lists.

An example users file is below.

{
    "user": [
        {
            "user": "test1",
            "host": "%",
            "global_db_priv": true
        },
        {
            "user": "test2",
            "host": "127.0.0.1",
            "password": "*032169CDF0B90AF8C00992D43D354E29A2EACB42",
            "plugin": "mysql_native_password",
            "default_role": "role2"
        },
        {
            "user": "",
            "host": "%",
            "plugin": "pam",
            "proxy_priv": true
        }
    ],
    "db": [
        {
            "user": "test2",
            "host": "127.0.0.1",
            "db": "test"
        }
    ],
    "roles_mapping": [
        {
            "user": "test2",
            "host": "127.0.0.1",
            "role": "role2"
        }
    ]
}

`user_accounts_file_usage`

Type: enum
Mandatory: No
Dynamic: No
Values: add_when_load_ok, file_only_always
Default: add_when_load_ok

Defines when user_accounts_file is read. The value is an enum, either "add_when_load_ok" (default) or "file_only_always".

"add_when_load_ok" means that the file is only read when users are successfully read from a server. The file contents are then added to the server-based data. If reading from server fails (e.g. servers are down), the file is ignored.

"file_only_always" means that users are not read from the servers at all and the file contents is all that matters. The state of the servers is ignored. This mode can be useful with the binlog router, as it allows clients to log in and fetch binary logs from MaxScale even when backend servers are down.

user_accounts_file_usage=file_only_always

`idle_session_pool_time`

Type: duration
Mandatory: No
Dynamic: Yes
Default: -1s

Normally, MaxScale only pools backend connections when a session is closed (controlled by server settings persistpoolmax andpersistmaxtime). Other sessions can use the pooled connections instead of creating new connections to backends. If connection sharing is enabled, MaxScale can pool backend connections also from running sessions, and re-attach a pooled connection when a session is doing a query. This effectively allows multiple sessions to share backend connections.

idle_session_pool_time defines the amount of time a session must be idle before its backend connections may be pooled. To enable connection sharing, setidle_session_pool_time to zero or greater. The value can be given in seconds or milliseconds.

This feature has a significant drawback: when a backend connection is reused, it needs to be restored to the correct state. This means reauthenticating and replaying session commands. This can add a significant delay before the connection is actually ready for a query. If the session command history size exceeds the value of max_sescmd_history, connection sharing is disabled for the session.

This feature should only be used when limiting the backend connection count is a priority, even at the cost of query delay and throughput. This feature only works when the following server settings are also set in MaxScale configuration:

max_routing_connections
persistpoolmax
persistmaxtime

Since reusing a backend connection is an expensive operation, MaxScale only pools connections when another session requires them. idle_session_pool_time thus effectively limits the frequency at which a connection can be moved from one session to another. Setting idle_session_pool_time=0ms causes MaxScale to move connections as soon as possible.

idle_session_pool_time=900ms

See below for more information on configuring connection sharing.

Details, limitations and suggestions for connection sharing

As noted above, when a connection is pooled and reused its state is lost. Although session variables and prepared statements are restored by replaying session commands, some state information cannot be transferred.

The most common such state is a transaction. When a transaction is on, connection sharing is disabled for that session until the transaction completes. Other similar situations may not be properly detected, and it's the responsibility of the user to avoid introducing such state to the session when using connection sharing. This means that the following should not be used:

Statements such as LOCK TABLES and GET LOCK or any other statement that introduces state into the connection.
Temporary tables and some problematic user or session variables such asLAST_INSERT_ID(). For LAST_INSERT_ID(), the value returned by the connector must be used instead of the variable.
Stored procedures that cause session level side-effects.

Several settings affect connection sharing and its effectiveness. Reusing a connection is an expensive operation so its frequency should be minimized. The important configuration settings in addition to idle_session_pool_time are MaxScale server settings persistpoolmax,persistmaxtime and max_routing_connections. The service settings max_sescmd_history,prune_sescmd_history and multiplex_timeout also have an effect. These settings should be tuned according to the use case.

persistpoolmax limits how many connections can be kept in a pool for a given server. If the pool is full, no more connections are detached from sessions even if they are idle and required. The pool size should be large enough to contain any connections being transferred between sessions, but not be greater thanmax_routing_connections. Using the value of max_routing_connections is a reasonable starting point.

persistmaxtime limits the time a connection may stay in the pool. This should be high enough so that pooled connections are not unnecessarily closed. Cleaning up clearly unneeded connections from the pool may be useful whenmax_routing_connections is restrictively tuned. Because each MaxScale routing thread has its own connection pool, one thread can monopolize access to a server. For example, if the pool of thread 1 has 100 connections to ServerA with max_routing_connections=100, other threads can no longer connect to the server. In such a situation, reducing persistmaxtime of ServerA may help as it would cause unneeded connections in the pool to be closed faster. Such connection slots then become available to other routing threads. Reducing the number of routing threads may also help, as it reduces pool fragmentation. This may reduce overall throughput, though. When using connection sharing, backend connections are only in the pool momentarily. Consequently,persistmaxtime can be set quite low, e.g. 10s.

If a client session exceeds max_sescmd_history (default 50), pooling is disabled for that session. If many sessions do this andmax_routing_connections is set, other sessions will stall as they cannot find a backend connection. This can be avoided with prune_sescmd_history. However, pruning means that old session commands will not be replayed when a pooled connection is reused. If the pruned commands are important (e.g. statement preparations), the session may fail later on.

If the number of clients actively running queries is greater thanmax_routing_connections, query throughput will suffer as clients will need to take turns. In this situation, it's imperative to minimize the number of backend connections a single session uses. The settings to achieve this depend on the router. For ReadWriteSplit the following should be used:

max_slave_connections=1
lazy_connect=1
transaction_replay=true

The above settings mean that MaxScale can process roughly (number of replica servers X max_routing_connections) read queries simultaneously. Write queries will still need to take turns as there is only one primary server.

The following configuration snippet shows example server and service configurations for connection sharing with ReadWriteSplit.

[server1]
type=server
max_routing_connections=1000 #this should be based on MariaDB Server capacity
persistpoolmax=1000 #same as above
persistmaxtime=10
#other server settings...

[myservice]
type=service
max_slave_connections=1
transaction_replay=true
idle_session_pool_time=500ms
lazy_connect=1
#other service settings...

`multiplex_timeout`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 60s

When connection sharing (as described above) is on, clients may have to wait for their turn to use a backend connection. If too much time passes without a connection becoming available, MaxScale returns an error to the client, usually also ending the session. multiplex_timeout sets this timeout. Increase it if queries are failing with "Timed out when waiting for a connection". Decrease it if failing early is preferable to stalling.

multiplex_timeout=33s

Server

Server sections define the backend database servers MaxScale uses. A server is identified by its section name in the configuration file. The only mandatory parameter of a server is type, but address and port are also usually defined. A server may be a member of one or more services. A server may only be monitored by at most one monitor.

[MyMariaDBServer1]
type=server
address=127.0.0.1
port=3000

Limitations:

MaxScale: No limitations.
MaxScale Lite: At most 3 servers can be created.

`address`

Type: string
Mandatory: Yes, if socket is not provided.
Dynamic: Yes
Default: ""

The IP-address or hostname of the machine running the database server. MaxScale uses this address to connect to the server.

Either address or socket must be defined, but not both. If the address is given as a hostname, MaxScale will perform name lookup on the hostname when starting and update the result every minute and when the address changes.

`port`

Type: number
Mandatory: No
Dynamic: Yes
Default: 3306

The port the backend server listens on for incoming connections. MaxScale uses this port to connect to the server.

`socket`

Type: string
Mandatory: Yes, if address is not provided.
Dynamic: Yes
Default: ""

The absolute path to a UNIX domain socket the MariaDB server is listening on.

`private_address`

Type: string
Mandatory: No
Dynamic: Yes
Default: ""

Alternative IP-address or hostname for the server. This is currently only used by MariaDB Monitor to detect and set up replication. See MariaDB Monitor documentation for more information.

`monitoruser`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This setting together with monitorpasswd define server-specific credentials for monitoring the server. Monitors typically use the credentials in their own configuration sections to connect to all servers. If server-specific settings are given, the monitor uses those instead.

monitoruser=mymonitoruser
monitorpw=mymonitorpasswd

`monitorpw`

Type: string
Mandatory: No
Dynamic: Yes
Default: None

This setting together with monitoruser define server-specific credentials for monitoring the server. Monitors typically use the credentials in their own configuration sections to connect to all servers. If server-specific settings are given, the monitor uses those instead.

monitoruser=mymonitoruser
monitorpw=mymonitorpasswd

monitorpw may be either a plain text password or an encrypted password. See the section encrypting passwords for more information.

`extra_port`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

An alternative port used for administrative connections to the server. If this setting is defined, MaxScale uses it for monitoring the server and to fetch user accounts. Client sessions will still use the normal port.

Defining extra_port allows MaxScale to connect even when max_connections on the backend server has been reached. Extra-port connections have their own connection limit, which is one by default. This needs to be increased to allow both monitor and user account manager to connect.

If the connection to the extra-port fails due to connection number limit or if the port is not open on the server, normal port is used.

For more information, see and .

`persistpoolmax`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

Sets the size of the server connection pool. Disabled by default. When enabled, MaxScale places unused connections to the server to a pool and reuses them later. Connections typically become unused when a session closes. If the size of the pool reaches persistpoolmax, unused connections are closed instead.

Every routing thread has its own pool. As of version 6.3.0, MaxScale will round up persistpoolmax so that every thread has an equal size pool.

When a MariaDB-protocol connection is taken from the pool to be used in a new session, the state of the connection is dependent on the router. ReadWriteSplit restores the connection to match the session state. Other routers do not.

`persistmaxtime`

Type: duration
Mandatory: No
Dynamic: Yes
Default: 0s

The persistmaxtime parameter defaults to zero but can be set to a duration as documented here. If no explicit unit is provided, the value is interpreted as seconds in MaxScale 2.4. In subsequent versions a value without a unit may be rejected. Note that since the granularity of the parameter is seconds, a value specified in milliseconds will be rejected, even if the duration is longer than a second.

A DCB placed in the persistent pool for a server will only be reused if the elapsed time since it joined the pool is less than the given value. Otherwise, the DCB will be discarded and the connection closed.

`max_routing_connections`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0 in MaxScale, 15 in MaxScale Lite.
Minimum: 0 in MaxScale, 1 in MaxScale Lite.
Maximum: Unlimited in MaxScale, 15 in MaxScale Lite.

Maximum number of routing connections to this server. Connections held in a pool also count towards this maximum. Does not limit monitor connections or user account fetching. A value of 0 means no limit, which is the default for MaxScale. MaxScle Lite is limited to a maximum of 15 connections per server.

Since every client session can generate a connection to a server, the server may run out of memory when the number of clients is high enough. This setting limits server memory use caused by MaxScale. The effect depends on if the service setting idle_session_pool_time, i.e. connection sharing, is enabled or not.

If connection sharing is not on, max_routing_connections simply sets a limit. Any sessions attempting to exceed this limit will fail to connect to the backend. The client can still connect to MaxScale, but queries will fail.

If connection sharing is on, sessions exceeding the limit will be put on hold until a connection is available. Such sessions will appear unresponsive, as queries will hang, possibly for a long time. The timeout is controlled by multiplex_timeout.

max_routing_connections=1234

`proxy_protocol`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

If proxy_protocol is enabled, MaxScale will send a PROXY protocol header when connecting client sessions to the server. The header contains the original client IP address and port, as seen by MaxScale. The server will then read the header and perform authentication as if the connection originated from this address instead of MaxScale's IP address. With this feature, the user accounts on the backend server can be simplified to only contain the actual client hosts and not the MaxScale host.

NOTE: If you use a cloud load balancer like AWS ELB that supports the proxy protocol in front of a MaxScale, you need to configure proxy_protocol_networks in MaxScale. This also needs to be done whenever one MaxScale may connect to another Maxscale and the connecting MaxScale has proxy_protocol enabled.

PROXY protocol will be supported by MariaDB 10.3, which this feature has been tested with. To use it, enable the PROXY protocol in MaxScale for every compatible server and configure the MariaDB servers themselves to accept the protocol headers from MaxScale's IP address. On the server side, the protocol should be enabled only for trusted IPs, as it allows the sender to spoof the connection origin. If a proxy header is sent to a server not expecting it, the connection will fail. Usually PROXY protocol should be enabled for every server in a cluster, as they typically have similar grants.

Other SQL-servers may support PROXY protocol as well, but the implementation may be highly restricting. Strict adherence to the protocol requires that the backend server does not allow mixing of un-proxied and proxied connections from a given IP. MaxScale requires normal connections to backends for monitoring and authentication data queries, which would be blocked. To bypass this restriction, the server monitor needs to be disabled and the service listener needs to be configured to disregard authentication errors (skip_authentication=true). Server states also need to be set manually in MaxCtrl. These steps are not required for MariaDB 10.3, since its implementation is more flexible and allows both PROXY-headered and headerless connections from a proxy-enabled IP.

`disk_space_threshold`

Type: Custom
Mandatory: No
Dynamic: No
Default: None

This parameter specifies how full a disk may be, before MaxScale should start logging warnings or take other actions (e.g. perform a switchover). This functionality will only work with MariaDB server versions 10.1.32, 10.2.14 and 10.3.6 onwards, if the DISKS information schema plugin has been installed.

NOTE: Since MariaDB 10.4.7, MariaDB 10.3.17 and MariaDB 10.2.26, the information will be available only if the monitor user has the FILE privilege.

A limit is specified as a path followed by a colon and a percentage specifying how full the corresponding disk may be, before action is taken. E.g. an entry like

/data:80

specifies that the disk that has been mounted on /data may be used until 80% of the total space has been consumed. Multiple entries can be specified by separating them by a comma. If the path is specified using *, then the limit applies to all disks. However, the value of * is only applied if there is not an exact match.

Note that if a particular disk has been mounted on several paths, only one path need to be specified. If several are specified, then the one with the smallest percentage will be applied.

Examples:

disk_space_threshold=*:80
disk_space_threshold=/data:80
disk_space_threshold=/data1:80,/data2:60,*:90

The last line means that the disk mounted at /data1 may be used up to 80%, the disk mounted at /data2 may be used up to 60% and all other disks mounted at any paths may be used up until 90% of maximum capacity, before MaxScale starts to warn to take action.

Note that the path to be used, is one of the paths returned by:

> use information_schema;
> select * from disks;
+-----------+----------------------+-----------+----------+-----------+
| Disk      | Path                 | Total     | Used     | Available |
+-----------+----------------------+-----------+----------+-----------+
| /dev/sda3 | /                    |  47929956 | 34332348 |  11139820 |
| /dev/sdb1 | /data                | 961301832 |    83764 | 912363644 |
...

There is no default value, but this parameter must be explicitly specified if the disk space situation should be monitored.

`rank`

Type: enum
Mandatory: No
Dynamic: Yes
Values: primary, secondary
Default: primary

This parameter controls the order in which servers are used. Valid values for this parameter are primary and secondary. The default value isprimary.

This behavior depends on the router implementation but the general rule of thumb is that primary servers will be used before secondary servers.

Readconnroute will always use primary servers before secondary servers as long as they match the configured server type.

Readwritesplit will pick servers that have the same rank as the current primary. Read the readwritesplit documentation on server ranks for a detailed description of the behavior.

The following example server configuration demonstrates how rank can be used to exclude DR-site servers from routing.

[main-site-primary]
type=server
address=192.168.0.11
rank=primary

[main-site-replica]
type=server
address=192.168.0.12
rank=primary

[DR-site-primary]
type=server
address=192.168.0.21
rank=secondary

[DR-site-replica]
type=server
address=192.168.0.22
rank=secondary

The main-site-primary and main-site-replica servers will be used as long as they are available. When they are no longer available, the DR-site-primary andDR-site-replica will be used.

`priority`

Type: number
Mandatory: No
Dynamic: Yes
Default: 0

Server priority. Currently only used by galeramon to choose the order in which nodes are selected as the current primary server. Refer to the Server Priorities section of the galeramon documentation for more information on how to use it.

Starting with MaxScale 2.5.21, this parameter also accepts negative values. In older versions, the parameter only accepted non-negative values.

`replication_custom_options`

Type: string
Default: None
Dynamic: Yes

Server-specific custom string added to "CHANGE MASTER TO"-commands sent by MariaDB Monitor. Overrides replication_custom_options setting set in the monitor. This setting affects the server where the command is ran at, not the source of the replication. That is, if monitor sends a "CHANGE MASTER TO"- command to server A telling it to replicate from server B, the setting value from MaxScale configuration for server A would be used.

See MariaDB Monitor documentation for more information.

Monitor

Monitor sections are used to define the monitoring module that watches a set of servers. Each server can only be monitored by one monitor.

Common monitor parameters can be found here.

Listener

A listener defines a port MaxScale listens on for incoming connections. Accepted connections are linked with a MaxScale service. Multiple listeners can feed the same service. Mandatory parameters are type, service and protocol.address is optional, it limits connections to a certain network interface only. socket is also optional and is used for Unix socket connections.

The network socket where the listener listens may have a backlog of connections. The size of this backlog is controlled by thenet.ipv4.tcp_max_syn_backlog and net.core.somaxconn kernel parameters.

Increasing the size of the backlog by modifying the kernel parameters helps with sudden connection spikes and rejected connections. For more information see listen(2).

[MyListener1]
type=listener
service=MyService1
port=3006

`service`

Type: service
Mandatory: Yes
Dynamic: No

The service to which the listener is associated. This is the name of a service that is defined elsewhere in the configuration file.

`protocol`

Type: protocol
Mandatory: No
Dynamic: No
Default: mariadb

The name of the protocol module used for communication between the client and MaxScale. The same protocol is also used for backend communication.

Usually this does not need to be defined as the default protocol is the MariaDB network protocol that is used by SQL connections.

For NoSQL client connections, the protocol must be set toprotocol=nosqlprotocol. For more details on how to configure the NoSQL protocol, refer to the NoSQL Protocol module documentation.

`address`

Type: string
Mandatory: No
Dynamic: No
Default: "::"

This sets the address the listening socket is bound to. The address may be specified as an IP address in 'dot notation' or as a hostname. If left undefined the listener will bind to all network interfaces.

`port`

Type: number
Mandatory: Yes, if socket is not provided.
Dynamic: No
Default: 0

The port the listener listens on. If left undefined a default port for the protocol is used.

`socket`

Type: string
Mandatory: Yes, if port is not provided.
Dynamic: No
Default: ""

If defined, the listener uses Unix domain sockets to listen for incoming connections. The parameter value is the name of the socket to use.

If you want to use both network ports and UNIX domain sockets with a service, define two separate listeners that connect to the same service.

`authenticator`

Type: string
Mandatory: No
Dynamic: No
Default: ""

The authenticator module to use. Each protocol module defines a default authentication module, which is used if the setting is left undefined. MariaDB and PostgreSQL protocols support multiple authenticators and they can be used simultaneously by giving a comma-separated list e.g.authenticator=PAMAuth,mariadbauth,gssapiauth

`authenticator_options`

Type: string
Mandatory: No
Dynamic: No
Default: ""

This defines additional options for authentication. As of MaxScale 2.5.0, onlyMariaDBClient and its authenticators support additional options. The value of this parameter should be a comma-separated list of key-value pairs. See authenticator specific documentation for more details.

`sql_mode`

Type: enum
Mandatory: No
Dynamic: Yes
Values: default, oracle
Default: default

Specify the sql mode for the listener similarly to global sql_mode setting. If both are used this setting will override the global setting for this listener.

`proxy_protocol_networks`

Define an IP-address or a subnetwork which may send a proxy protocol header when connecting. The proxy header contains the original client IP-address and port, and MaxScale will use that information in its internal bookkeeping. This means the client is authenticated as if it was connecting from the host in the proxy header. If proxy protocol is also enabled in MaxScale server settings, MaxScale will relay the original client address and port to the server. See server settings for more information.

This setting may be useful if a compatible load balancer is relaying client connections to MaxScale. If proxy headers are used, both MaxScale and the backends will know where the client originally came from.

The proxy_protocol_networks-setting works similarly to the equivalent setting in . The value can be a single IP or subnetwork, or a comma-separated list of them. Subnetworks are given in CIDR-format, e.g. "192.168.0.0/16". "*" is a valid value, allowing anyone to send the header. "localhost" allows proxy headers from domain socket connections.

Only trusted IPs should be added to the list, as the proxy header may affect authentication results.

proxy_protocol_networks=192.168.0.1,198.168.0.0/16

Similar to MariaDB Server, MaxScale will also accept normal connections even if proxy_protocol_networks is configured for the listener.

`connection_init_sql_file`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

Path to a text file with sql queries. Any sessions created from the listener will send the contents of the file to backends after authentication. Each non-empty line in the file is interpreted as a query. Each query must succeed for the backend connection to be usable for client queries. The queries should not return any data.

connection_init_sql_file=/home/dba/init_queries.txt

Example query file:

set @myvar = 'mytext';
set @myvar2 = 4;

`user_mapping_file`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

Path to a json-text file with user and group mapping, as well as server credentials. Only affects MariaDB-protocol based listeners. Default value is empty, which disables the feature.

user_mapping_file=/home/root/mapping.json

Should not be used together with PAM Authenticator settings pam_backend_mapping or pam_mapped_pw_file, as these may overwrite the mapped credentials. Is most powerful when combined with service settinguser_accounts_file, as then MaxScale can accept users that do not exist on backends and map them to backend users.

This file functions very similar to . Both user-to-user and group-to-user mappings can be defined. Also, the password and authentication plugin for the mapped users can be added. The file is only read during listener creation (typically MaxScale start) or when a listener is modified during runtime. When a client logs into MaxScale, their username is searched from the mapping data. If the name matches either a name mapping or a Linux group mapping, the username is replaced by the mapped name. The mapped name is then used when logging into backends. If the file also contains credentials for the mapped user, then those are used. Otherwise, MaxScale tries to log in with an empty password and default MariaDB authentication.

Three arrays are read from the file: user_map, group_map andserver_credentials, none of which are mandatory.

Each array element in the user_map-array must define the following fields:

original_user: String. Incoming client username.
mapped_user: String. Username the client is mapped to.

Each array element in the group_map-array must define the following fields:

original_group: String. Incoming client Linux group.
mapped_user: String. Username the client is mapped to.

Each array element in the server_credentials-array can define the following fields:

mapped_user: String. The mapped username this password is for.
password: String. Backend server password. Can be encrypted with maxpasswd.
plugin: String, optional. Authentication plugin to use. Must be enabled on the listener. Defaults to empty, which results in standard MariaDB authentication.

When a client successfully logs into MaxScale, MaxScale first searches for name-based mapping. The incoming client does not need to be a Linux user for name-based mapping to take place. If the name is not found, MaxScale checks if the client is a Linux user with a group membership matching an element in the group mapping array. If the client is a member of more than 100 groups, this check may fail.

If a mapping is found, MaxScale searches the credentials array for a matching username, and uses the password and plugin listed. The plugin need not be the same as the one the original user used. Currently, "mysql_native_password" and "pam" are supported as mapped plugins.

An example mapping file is below.

{
    "user_map": [
        {
            "original_user": "bob",
            "mapped_user": "janet"
        },
        {
            "original_user": "karen",
            "mapped_user": "janet"
        }
    ],
    "group_map": [
        {
            "original_group": "visitors",
            "mapped_user": "db_user"
        }
    ],
    "server_credentials": [
        {
            "mapped_user": "janet",
            "password": "secret_pw",
            "plugin": "mysql_native_password"
        },
        {
            "mapped_user": "db_user",
            "password": "secret_pw2",
            "plugin": "pam"
        }
    ]
}

`connection_metadata`

Type: stringlist
Default: character_set_client=auto,character_set_connection=auto,character_set_results=auto,max_allowed_packet=auto,system_time_zone=auto,time_zone=auto,tx_isolation=auto,maxscale=auto
Dynamic: Yes
Mandatory: No

Metadata that's sent to all connecting clients. The value must be a comma-separated list of key-value arguments. The keys or values cannot contain commas in them.

Any values that are set to auto will be substituted with the value of the corresponding MariaDB system variable. Any system variables that do not not exist or have empty or null values will not be sent to the client. The system variable values are read from the first Master server that's reachable from the listener's service. If no Master server is reachable, the value is read from the first Slave server and if no Slave servers are available, from the first Running server. If no running servers are available, the system variables are not sent.

The exception to this is the maxscale=auto value where the auto will be replaced with the MaxScale version string. This is useful for detecting whether a client is connected to MaxScale. To make MaxScale completely transparent to the client application, the maxscale=auto value can be removed fromconnection_metadata.

MaxScale will always send a metadata value for threads_connected that contains the current number of connections to the service that the listener points to and for connection_id that contains the 64-bit connection ID value. The values can be overridden by defining them with some value, for example,connection_metadata=threads_connected=0,connection_id=0.

The metadata is implemented using the session state information that is embedded in the OK packets that are generated by MaxScale. The values are encoded as system variables changes. This information can be accessed by all connectors that support reading the session state information. One example of this is the MariaDB Connector/C that implements it with the mysql_session_track_get_first and mysql_session_track_get_next functions.

The following example demonstrates the use of connection_metadata:

connection_metadata=redirect_url=localhost:3306,service_name=my-service,max_allowed_packet=auto

The configuration has three variables, redirect_url, service_name andmax_allowed_packet that have the values localhost:3306, my-service andauto. The auto value is special and gets replaced with themax_allowed_packet value from the MariaDB server. This means that the final metadata that is sent to the client would be redirect_url=localhost:3306,service_name=my-service and max_allowed_packet=16777216.

Version-specific Behavior

If the connection_metadata variable list contains the tx_isolation variable and the backend MariaDB server from which the variable is retrieved is MariaDB 11 or newer, the value is renamed to transaction_isolation. The tx_isolation parameter was deprecated in favor of transaction_isolation in MariaDB 11 (MDEV-21921).

Include

An include section defined common parameters used in other configuration sections. Consider the following configuration.

[Monitor1]
type=monitor
module=mariadbmon
user=the_user
password=the_password
handle_events=false
monitor_interval=2000ms
backend_connect_timeout = 3s
backend_connect_attempts = 5
servers=Server1, Server2

[Monitor2]
type=monitor
module=mariadbmon
user=the_user
password=the_password
handle_events=false
monitor_interval=2000ms
backend_connect_timeout = 3s
backend_connect_attempts = 5
servers=Server3, Server4

The two monitor sections are identical except for the servers setting. If they otherwise should remain identical, a change must be made in two places. With an include section the situation can be simplified.

[Monitor-Common]
type=include
module=mariadbmon
user=the_user
password=the_password
handle_events=false
monitor_interval=2000ms
backend_connect_timeout = 3s
backend_connect_attempts = 5

[Monitor1]
type=monitor
@include=Monitor-Common
servers=Server1, Server2

[Monitor2]
type=monitor
@include=Monitor-Common
servers=Server3, Server3

With an include section, all common settings can be defined in one place, and then included to any number of other sections using the@include parameter.

The @include parameter takes a list of section names, so the settings can be distributed across several include sections.

@include=Some-Common-Attributes, Other-Common-Attributes

It is permissible to specify in the including section, parameters that have already been specified in the included section and they will take precedence. For instance, if Monitor2 in the example above should have a longer backend connect timeout it can be specified as follows.

[Monitor2]
type=monitor
@include=Monitor-Common
servers=Server3, Server3
backend_connect_timeout = 5s

Note that an included section must be an include section and that an include section cannot include another include section. For instance, both of the following sections would cause an error at startup.

[Monitor-Common]
type=include
@include=Base-Common
...

[Monitor2]
type=monitor
@include=Monitor1
...

Note also that if an included parameter is changed using maxctrl, it will be changed only on the actual object the change is applied on, not on the include section where the parameter is originally specified.

Available Protocols

Protocol modules in MaxScale define what kind of clients can connect to a listener and what type of backend servers are supported. Protocol is defined in listener settings, and affects both the listener and any services the listener is linked to.

`MariaDB` or `MariaDBClient`

Implements MariaDB protocol. The listener will accept MariaDB/MySQL connections from clients and route the client queries through a linked MaxScale service to backend servers. The backends used by the service should be MariaDB servers or compatible.

`CDC`

See Change Data Capture Protocol for more information.

`Postgresql` or `Postgresprotocol`

Implements Postgresql protocol. The listener will accept Postgresql connections from clients and route the client queries through a linked MaxScale service to backend servers. The backends used by the service should be PostgreSQL servers or compatible.

`nosqlprotocol`

Accepts MongoDB® connections, yet stores and fetches results to/from MariaDB servers. See NoSQL documentation for more information.

TLS/SSL encryption

This section describes configuration parameters for both servers and listeners that control the TLS/SSL encryption method and the various certificate files involved in it.

To enable TLS/SSL for a listener, you must set the ssl parameter totrue and provide at least the ssl_cert and ssl_key parameters.

To enable TLS/SSL for a server, you must set the ssl parameter totrue. If the backend database server has certificate verification enabled, the ssl_cert and ssl_key parameters must also be defined.

Custom CA certificates can be defined with the ssl_ca parameter. Ifssl_verify_peer_certificate is enabled yet ssl_ca is not set, MaxScale will load CA certificates from the system default location.

After this, MaxScale connections between the server and/or the client will be encrypted. Note that the database must also be configured to use TLS/SSL connections if backend connection encryption is used.

Note: MaxScale does not allow mixed use of TLS/SSL and normal connections on the same port.

If TLS encryption is enabled for a listener, any unencrypted connections to it will be rejected. MaxScale does this to improve security by preventing accidental creation of unencrypted connections.

The separation of secure and insecure connections differs from the MariaDB Server which allows both secure and insecure connections on the same port. As MaxScale is the gateway through which all connections go, MaxScale enforces a stricter security policy than MariaDB Server. Multiple listeners with different configurations can be created to enable different encryption schemes.

TLS encryption must be enabled for listeners when they are created. For servers, the TLS can be enabled after creation but it cannot be disabled or altered.

Starting with MaxScale 2.5.20, if the TLS certificate given to MaxScale has the X509v3 extended key usage information, MaxScale will check it and refuse to use a certificate with the wrong usage. This means that a certificate with only clientAuth can only be used with servers and a certificate with only serverAuth can only be used with listeners. In order to use the same certificate for both listeners and servers, it must have both the clientAuth and serverAuth usages.

Settings for TLS/SSL Encryption

`ssl`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

This enables SSL connections when set to true. The legacy values required anddisabled were removed in MaxScale 6.0.

If enabled, the certificate files mentioned above must also be supplied. MaxScale connections to will then be encrypted with TLS/SSL.

Starting with MaxScale 21.06.18, 22.08.15, 23.02.12, 23.08.8, 24.02.4 and 24.08.1, if ssl is disabled for a listener, MariaDB user accounts that require ssl cannot log in through that listener. Any user account with a non-emptyssl_type-field in mysql.user-table is blocked. This includes users created with REQUIRE SSL or REQUIRE X509.

`ssl_key`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

A string giving a file path that identifies an existing readable file. The file must be the SSL client private key MaxScale should use. This is a required parameter for listeners but an optional parameter for servers.

`ssl_cert`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

A string giving a file path that identifies an existing readable file. The file must be the SSL client certificate MaxScale should use with the server. The certificate must match the key defined in ssl_key. This is a required parameter for listeners but an optional parameter for servers.

`ssl_ca_cert`

Deprecated since MariaDB MaxScale 22.08. See ssl_ca.

`ssl_ca`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

A string giving a file path that identifies an existing readable file. The file must be a Certificate Authority (CA) certificate. It will be used to verify that the peer certificate (sent by either client or a MariaDB Server) is valid. The CA certificate can consist of a certificate chain.

NOTE Up until MariaDB MaxScale 6, the parameter was called ssl_ca_cert, which is still accepted as an alias for ssl_ca.

`ssl_version`

Type: enum_mask
Mandatory: No
Dynamic: No
Values: MAX, TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3, TLSv10, TLSv11, TLSv12, TLSv13
Default: MAX

This parameter controls the allowed TLS version. Accepted values are:

TLSv10
TLSv11
TLSv12
TLSv13 (not supported on OpenSSL 1.0)
MAX

MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2 and all newer releases accept also the following alias values:

TLSv1.0
TLSv1.1
TLSv1.2
TLSv1.3 (not supported on OpenSSL 1.0)

The default setting (MAX) allows all supported versions. MaxScale supports TLSv1.0, TLSv1.1, TLSv1.2 and TLSv1.3 depending on the OpenSSL library version. TLSv1.0 and TLSv1.1 are considered deprecated and should not be used, so settingssl_version=TLSv1.2,TLSv1.3 or ssl_version=TLSv1.3 is recommended.

In MaxScale versions 6.4.13, 22.08.11, 23.02.7, 23.08.3 and earlier, this setting defined the only allowed TLS version, e.g. ssl_version=TLSv12 would only enable TLSv12. The interpretation changed in MaxScale versions 6.4.14, 22.08.12, 23.02.8, 23.08.4 to enable the user to disable old versions while allowing multiple recent TLS versions. In these versions, ssl_version=TLSv1.2 enabled both TLSv1.2 and TLSv1.3.

The interpretation changed again in MaxScale versions 6.4.16, 22.08.13, 23.02.10, 23.08.6, 24.02.2. In these versions the value of ssl_version is an enumeration of accepted TLS protocol versions. This means thatadmin_ssl_version=TLSv1.2 again only allows TLSv1.2. To retain the behavior from the previous releases where the newer versions were automatically enabled, the protocol versions must be explicitly listed, for exampleadmin_ssl_version=TLSv1.2,TLSv1.3. The change was done to make thessl_version behave identically to how the MariaDB parameter works.

`ssl_cipher`

Type: string
Mandatory: No
Dynamic: Yes
Default: ""

Set the list of TLS ciphers. By default, no explicit ciphers are defined and the system defaults are used. Note that this parameter does not modify TLSv1.3 ciphers.

`ssl_cert_verify_depth`

Type: number
Mandatory: No
Dynamic: Yes
Default: 9

The maximum length of the certificate authority chain that will be accepted. The default value is 9, same as the OpenSSL default. The configured value must be larger than 0.

`ssl_verify_peer_certificate`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: false

Peer certificate verification. This functionality is disabled by default. In versions prior to 2.3.17 the feature was enabled by default.

When this feature is enabled, the peer (client or MariaDB Server) must send a certificate. The certificate sent by the peer is verified against the configured Certificate Authority to ensure the peer is who they claim to be. For listeners, this behaves as if REQUIRE X509 was defined for all users.

`ssl_verify_peer_host`

Type: boolean
Mandatory No
Dynamic: Yes
Default: false

Peer host verification.

When this feature is enabled, the peer (client or MariaDB Server) hostname or IP is verified against the certificate sent by the peer. If the IP address or the hostname does not match the one in the certificate, the connection is closed.

If the peer does not provide a certificate, host verification is skipped. To require peer certificates, also enable ssl_verify_peer_certificate. For servers, the combination of

ssl_verify_peer_certificate=true
ssl_verify_peer_host=true

behaves like the --ssl-verify-server-cert command line option for themysql client.

`ssl_crl`

Type: path
Mandatory: No
Dynamic: Yes
Default: ""

A string giving a file path that identifies an existing readable file. The file must be a Certificate Revocation List in the PEM format that defines the revoked certificates. This parameter is only accepted by listeners.

Example SSL enabled server configuration

[server1]
type=server
address=10.131.24.62
port=3306
ssl=true
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.max-client.pem
ssl_key=/usr/local/mariadb/maxscale/ssl/key.max-client.pem
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem

This example configuration requires all connections to this server to be encrypted with SSL. The paths to the certificate files and the Certificate Authority file are also provided.

Example SSL enabled listener configuration

[RW-Split-Listener]
type=listener
service=RW-Split-Router
port=3306
ssl=true
ssl_cert=/usr/local/mariadb/maxscale/ssl/crt.maxscale.pem
ssl_key=/usr/local/mariadb/maxscale/ssl/key.csr.maxscale.pem
ssl_ca_cert=/usr/local/mariadb/maxscale/ssl/crt.ca.maxscale.pem

This example configuration requires all connections to be encrypted with SSL. The paths to the certificate files and the Certificate Authority file are also provided.

Module Types

Routing Modules

The main task of MariaDB MaxScale is to accept database connections from client applications and route the connections or the statements sent over those connections to the various services supported by MariaDB MaxScale.

Currently a number of routing modules are available, these are designed for a range of different needs.

Connection based load balancing:

ReadConnRoute

Read/Write aware statement based router:

ReadWriteSplit

Simple sharding on database level:

SchemaRouter

Binary log server:

Binlogrouter

Monitor Modules

Monitor modules are used by MariaDB MaxScale to internally monitor the state of the backend databases in order to set the server flags for each of those servers. The router modules then use these flags to determine if the particular server is a suitable destination for routing connections for particular query classifications. The monitors are run within separate threads of MariaDB MaxScale and do not affect MariaDB MaxScale's routing performance.

The use of monitors in MaxScale is not absolutely mandatory: it is possible to run MariaDB MaxScale without a monitor module. In this case an external monitoring system must the status of each server via MaxCtrl or the REST API. Only do this if you know what you are doing.

Filter Modules

Filters provide a means to manipulate or process requests as they pass through MariaDB MaxScale between the client side protocol and the query router. A full explanation of each filter's functionality can be found in its documentation.

The Filter Tutorial document shows how you can add a filter to a service and combine multiple filters in one service.

Encrypting Passwords

Passwords stored in the maxscale.cnf file may optionally be encrypted for added security. This is done by creation of an encryption key on installation of MariaDB MaxScale. Encryption keys may be created manually by executing the maxkeys utility with the argument of the filename to store the key. The default location MariaDB MaxScale stores the keys is /var/lib/maxscale. The passwords are encrypted using 256-bit AES CBC encryption.

# Usage: maxkeys [PATH]
maxkeys /var/lib/maxscale/

Changing the encryption key for MariaDB MaxScale will invalidate any currently encrypted keys stored in the maxscale.cnf file.

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.

Creating Encrypted Passwords

Encrypted passwords are created by executing the maxpasswd command with the location of the .secrets file and the password you require to encrypt as an argument.

# Usage: maxpasswd PATH PASSWORD
maxpasswd /var/lib/maxscale/ MaxScalePw001
61DD955512C39A4A8BC4BB1E5F116705

The output of the maxpasswd command is a hexadecimal string, this should be inserted into the maxscale.cnf file in place of the ordinary, plain text, password. MariaDB MaxScale will determine this as an encrypted password and automatically decrypt it before sending it the database server.

[Split-Service]
type=service
router=readwritesplit
servers=server1,server2,server3,server4
user=maxscale
password=61DD955512C39A4A8BC4BB1E5F116705

Runtime Configuration Changes

Read the following documents for different methods of altering the MaxScale configuration at runtime.

MaxCtrl
create
destroy
add
remove
alter
REST API documentation

All changes to the configuration done via MaxCtrl are persisted as individual configuration files in /var/lib/maxscale/maxscale.cnf.d/. The content of these files will override any configurations found in the main configuration file or any auxiliary configuration files.

Refer to the Dynamic Configuration section for more details on how this mechanism works and how to disable it.

Configuration Synchronization

The configuration synchronization mechanism is intended for synchronizing configuration changes done on one MaxScale to all other MaxScales. This is done by propagating the changes via the database cluster used by Maxscale.

When configuring configuration synchronization for the first time, the same static configuration files should be used on all MaxScale instances that use the same cluster: the value of config_sync_cluster must be the same on all MaxScale instances and the cluster (i.e. the monitor) pointed by it and its servers must be the same in every configuration.

Whenever the MaxScale configuration is modified at runtime, the latest configuration is stored in the database cluster in the mysql.maxscale_config table. The table is created when the first modification to the configuration is done. A local copy of the configuration is stored in the data directory to allow MaxScale to function even if a connection to the cluster cannot be made. By default this file is stored at /var/lib/maxscale/maxscale-config.json.

Whenever MaxScale starts up, it checks if a local version of this configuration exists. If it does and it is a valid cached configuration, the static configuration file as well as any other generated configuration files are ignored. The exception is the [maxscale] section of the main static configuration file which is always read.

Each configuration has a version number with the initial configuration being version 0. Each time the configuration is modified, the version number is incremented. This version number is used to detect when MaxScale needs to update its configuration.

Error Handling in Configuration Synchronization

When doing a configuration change on the local MaxScale, if the configuration change completes on MaxScale but fails to be committed to the database, MaxScale will attempt to revert the local configuration change. If this attempt fails, MaxScale will discard the cached configuration and abort the process.

When synchronizing with the cluster, if MaxScale fails to apply a configuration retrieved from the cluster, it attempts to revert the configuration to the previous version. If successful, the failed configuration update is ignored. If the configuration update that fails cannot be reverted, the MaxScale configuration will be in an indeterminate state. When this happens, MaxScale will discard the cached configuration and abort the process.

When loading a locally cached configuration during startup, if any errors are found in the cached configuration, it is discarded and the MaxScale process will attempt to restart by exiting with code 75 from the main process. If MaxScale is being used as a SystemD service, this will automatically trigger a restart of MaxScale and no further actions are needed.

The most common reason for a failed configuration update is missing files. For example, if a configuration update adds encrypted connections to a server and the TLS certificates it uses were not copied over to all MaxScale nodes before the change was done, the operation will fail on all nodes that do not have these files.

If the synchronization of the configuration change fails at the step when the database transaction is being committed, the new configuration can be momentarily visible to the local MaxScale. This means the changes are not guaranteed to be atomic on the local MaxScale but are atomic from the cluster's point of view.

Synchronization of Encrypted Passwords

Starting with MaxScale 6.4.9, any passwords that are transmitted by the configuration synchronization are encrypted if password encryption has been enabled in MaxScale. This means that all MaxScale nodes in the same configuration cluster must be configured to use password encryption and they need to all use the same encryption keys that were created with maxkeys.

Managing Configuration Synchronization

The output of maxctrl show maxscale contains the Config Sync field with information about the current configuration state of the local Maxscale as well as the state of any other nodes using this cluster.

├──────────────┼─────────────────────────────────────────────────────────────┤
│ Config Sync  │ {                                                           │
│              │     "checksum": "3dd6b467760d1d2023f2bc3871a60dd903a3341e", │
│              │     "nodes": {                                              │
│              │         "maxscale": "OK",                                   │
│              │         "maxscale2": "OK"                                   │
│              │     },                                                      │
│              │     "origin": "maxscale",                                   │
│              │     "status": "OK",                                         │
│              │     "version": 2                                            │
│              │ }                                                           │
├──────────────┼─────────────────────────────────────────────────────────────┤

The version field is the logical configuration version and the origin is the node that originates the latest configuration change. The checksum field is the checksum of the logical configuration and can be used to compare whether two Maxscale instances are in the same configuration state. The nodes field contains the status of each MaxScale instance mapped to the hostname of the server. This field is updated whenever MaxScale reads the configuration from the cluster and can thus be used to detect which MaxScales have updated their configuration.

The mysql.maxscale_config table where the configuration changes are stored must not be modified manually. The only case when the table should be modified is when resetting the configuration synchronization.

To reset the configuration synchronization:

Stop all MaxScale instances
Remove the cached configuration file stored at/var/lib/maxscale/maxscale-config.json on all MaxScale instances
Drop the mysql.maxscale_config table
Start all MaxScale instances

To disable configuration synchronization, remove config_sync_cluster from the configuration file or set it to an empty string: config_sync_cluster="". This can be done at runtime with MaxCtrl by passing an empty string toconfig_sync_cluster:

maxctrl alter maxscale config_sync_cluster ""

If MaxScale cannot create a connection to the database cluster, configuration changes are not possible until communication with the database is possible. To override this behavior and force the changes to be done, use the --skip-sync option for maxctrl or the sync=false HTTP parameter for the REST API. Any updates done with --skip-sync will overwritten by changes coming from the cluster.

Limitations in Configuration Synchronization

Only the MaxScale configuration is synchronized. Any external files (TLS certificates, configuration files for modules or data generated by MaxScale) are not synchronized. For example, the rule files for the cache filter must be synchronized separately if the filter itself is modified.

Starting with MaxScale 22.08, the Maintenance and Draining states of servers and modifications to the administrative users will be synchronized. In older versions servers had to be put into maintenance mode and users had to be modified separately on each MaxScale.

(MXS-3619) External files are not synchronized.
(MXS-4276) The --export-config option will not export the cluster configuration and instead exports only the static configuration files. To start a new MaxScale based off of a clustered configuration, copy the static configuration files as well as the JSON configuration in /var/lib/maxscale/maxscale-config.json to the new MaxScale instance.

Backing Up Configuration Changes

The combination of configuration files can be done either manually (e.g. rsync) or with the maxscale --export-config=FILE command line option. See maxscale --help for more information about how to use the--export-config flag.

For example, to export the current runtime configuration, run the following command.

maxscale --export-config=/tmp/maxscale.cnf.combined

This will create the /tmp/maxscale.cnf.combined file and write the current configuration into the it. This allows new MaxScale instances to be easily set up without requiring copying of all runtime configuration files. The user executing the command must be able to read all MaxScale configuration files as well as create and write the provided filename.

Encryption Key Managers

The encryption key managers are how MaxScale retrieves symmetric encryption keys from a key management system. Some parts of MaxScale require the key_manager to be configured in order to work. The key manager that is used is selected with the key_manager parameter and the key manager itself is configured by placing the parameters in the [maxscale] section.

The encryption key managers can be enabled at runtime using maxctrl alter maxscale but cannot be disabled once enabled. To disable the encryption key management, stop Maxscale, remove any persisted configuration files and removekey_manager as well as any key manager options from the static configuration files.

File-based Key Manager

The encryption keys are stored in a text file stored on a local filesystem.

The file uses the same format as the MariaDB server : a file consisting of an encryption key ID number and the hex-encoded encryption key separated by a semicolon. Read for more details on how to create the file.

For example, to configure encryption for the nosqlprotocol shared credentials using the file-based encryption key:

Create the key file with (echo -n '1;' ; openssl rand -hex 32) | cat > /var/lib/maxscale/encryption.key
Give MaxScale read permissions on it with chown maxscale:maxscale /var/lib/maxscale/encryption.key
Configure MaxScale with the following:

[maxscale]
key_manager=file
file.keyfile=/var/lib/maxscale/encryption.key

[NoSQL-Listener]
type=listener
service=My-Service
protocol=nosqlprotocol
nosqlprotocol.authentication_key_id=1
nosqlprotocol.authentication_user=my_user
nosqlprotocol.authentication_password=my_password

# Add services, servers, monitors etc.

Start MaxScale

Limitations

Key versioning is not supported

Settings for File-based Key Manager

file.keyfile

Type: path
Mandatory: Yes
Dynamic: Yes

Path to the file that contains the encryption keys. The user MaxScale runs as (almost always maxscale) must be able to read this file. Encryption keys are read from disk only during startup or when any global MaxScale parameter is modified at runtime.

KMIP Key Manager

Encryption keys are read from a KMIP server.

The KMIP key manager has been verified to work with the PyKMIP server.

Limitations

Key versioning is not supported
Encryption keys are not cached locally: whenever MaxScale needs an encryption key, it retrieves it from the KMIP server.

Settings for KMIP Key Manager

kmip.host

Type: string
Mandatory: Yes
Dynamic: Yes

The host where the KMIP server is.

kmip.port

Type: integer
Mandatory: Yes
Dynamic: Yes

The port on which the KMIP server listens on.

kmip.cert

Type: path
Mandatory: Yes
Dynamic: Yes

The client public certificate used when connecting to the KMIP server.

kmip.key

Type: path
Mandatory: Yes
Dynamic: Yes

The client private key used when connecting to the KMIP server.

kmip.ca

Type: path
Default: ""
Dynamic: Yes

The CA certificate to use. By default the system default certificates are used.

HashiCorp Vault Key Manager

Encryption keys are read from a local or remote Vault server using the secret engine included in the Vault. This key manager supports versioned keys. Only version 2 key-value stores are supported.

The encryption keys use the same format as the MariaDB : The key-value secret for each encryption key ID must contain the field data which must contain a hex-encoded string that is either 32, 48 or 64 characters long.

An easy way to generate a correct encryption key is to use the vault andopenssl command line clients. The following command creates a 256-bit encryption key using openssl and stores it using the key ID 1:

$ openssl rand -hex 32|vault kv put secret/1 data=-
== Secret Path ==
secret/data/1

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-23T06:50:55.29063873Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Limitations

Encryption keys are not cached locally: whenever MaxScale needs an encryption key, it retrieves it from the Vault server.

Settings for HashiCorp Vault Key Manager

vault.token

Type: password
Mandatory: Yes
Dynamic: Yes

The authentication token used to connect to the Vault server. This can be encrypted using maxpasswd, similar to how other passwords are encrypted.

vault.host

Type: string
Default: localhost
Dynamic: Yes

The host where the Vault server is.

vault.port

Type: integer
Default: 8200
Dynamic: Yes

The port on which the Vault server listens on.

vault.ca

Type: path
Default: ""
Dynamic: Yes

The CA certificate to use. By default the system default certificates are used.

vault.tls

Type: boolean
Default: true
Dynamic: Yes

Whether to use encrypted connections (i.e. HTTPS or HTTP) when communicating with the Vault server.

vault.mount

Type: string
Default: secret
Dynamic: Yes

The Key-Value mount where the secret is stored. By default the secret mount is used which is present by default in most Vault installations.

vault.timeout

Type: duration
Default: 30s
Dynamic: Yes

The connection and request timeout used with the Vault server.

Threads

For routing, MaxScale uses asynchronous I/O and a fixed number of threads (aka routing workers), whose number up until 23.02 was fixed at startup. From 23.02 onwards the number of threads can be altered at runtime, which is convenient, for instance, if MaxScale is running in a container whose properties are changed during the lifetime of the container.

A thread can be in three different states:

Active: The thread is routing client traffic and is listening for new connections.
Draining: The thread is routing client traffic but is not listening for new connections.
Dormant: The thread is not routing client traffic (all sessions have ended), and is not listening for new connections, and is waiting to be terminated.

All threads start as Active and may become Draining if the number of threads is reduced. A draining thread will eventually become Dormant, unless the number of threads is increased while the thread is still Draining.

Note that it is not possible to terminate a specific thread, but it is only possible to specify the number of threads that MaxScale should use, and that the threads will be terminated from the end. This has implications if the number of threads is reduced by more than 1, as a Dormant thread will not be terminated before it is the last thread.

In the following, MaxScale has been started with threads=4.

$ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬────────┬────────┬─────┐
│ Id                     │ 0      │ 1      │ 2      │ 3      │ All │
├────────────────────────┼────────┼────────┼────────┼────────┼─────┤
│ State                  │ Active │ Active │ Active │ Active │ N/A │
├────────────────────────┼────────┼────────┼────────┼────────┼─────┤
...

All threads are Active. If we now decrease the number of threads

$ bin/maxctrl alter maxscale threads=2
OK
$ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬──────────┬──────────┬─────────┐
│ Id                     │ 0      │ 1      │ 2        │ 3        │ All     │
├────────────────────────┼────────┼────────┼──────────┼──────────┼─────────┤
│ State                  │ Active │ Active │ Draining │ Draining │ N/A     │
├────────────────────────┼────────┼────────┼──────────┼──────────┼─────────┤
...

we will see that the threads 2 and 3 are now Draining. The reason is that threads 2 and 3 still handle client sessions. If some client sessions now end, the situation may become like

┌────────────────────────┬────────┬────────┬─────────┬──────────┬────────┐
│ Id                     │ 0      │ 1      │ 2       │ 3        │ All    │
├────────────────────────┼────────┼────────┼─────────┼──────────┼────────┤
│ State                  │ Active │ Active │ Dormant │ Draining │ N/A    │
├────────────────────────┼────────┼────────┼─────────┼──────────┼────────┤
...

That is, thread 2 is Dormant and thread 3 is Draining. All client sessions that were handled by thread 2 have ended and the thread is ready to be terminated. However, as thread 3 is still Draining, thread 2 will not be terminated but stay Dormant.

If the sessions handled by thread 3 end, then it will become Dormant at which point first thread 3 will be terminated and immediately after that thread 2.

$ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬──────┐
│ Id                     │ 0      │ 1      │ All  │
├────────────────────────┼────────┼────────┼──────┤
│ State                  │ Active │ Active │ N/A  │
├────────────────────────┼────────┼────────┼──────┤
...

If the situation is like

$ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬─────────┬──────────┬────────┐
│ Id                     │ 0      │ 1      │ 2       │ 3        │ All    │
├────────────────────────┼────────┼────────┼─────────┼──────────┼────────┤
│ State                  │ Active │ Active │ Dormant │ Draining │ N/A    │
├────────────────────────┼────────┼────────┼─────────┼──────────┼────────┤
...

that is, the number of threads was 4 but has been reduced to 2, and while thread 2 has become drained it stays as Dormant since thread 3 is stillDraining, it is possible to make thread 2 Active again by increasing the number of threads to 3.

$ bin/maxctrl alter maxscale threads=3
OK
wikman@johan-P53s:maxscale $ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬────────┬──────────┬────────┐
│ Id                     │ 0      │ 1      │ 2      │ 3        │ All    │
├────────────────────────┼────────┼────────┼────────┼──────────┼────────┤
│ State                  │ Active │ Active │ Active │ Draining │ N/A    │
├────────────────────────┼────────┼────────┼────────┼──────────┼────────┤
...

Once the sessions of thread 3 ends, we will have

$ bin/maxctrl show threads
┌────────────────────────┬────────┬────────┬────────┬──────┐
│ Id                     │ 0      │ 1      │ 2      │ All  │
├────────────────────────┼────────┼────────┼────────┼──────┤
│ State                  │ Active │ Active │ Active │ N/A  │
├────────────────────────┼────────┼────────┼────────┼──────┤
...

Error Reporting

MariaDB MaxScale is designed to be executed as a service, therefore all error reports, including configuration errors, are written to the MariaDB MaxScale error log file. By default, MariaDB MaxScale will log to a file in/var/log/maxscale and the system log.

Limitations

The current limitations of MaxScale are listed in the Limitations document.

Performance Optimization

Tune query_classifier_cache_size to allow maximal use of the query classifier cache. Increase the value and/or system memory until the set of unique SQL patterns fits into memory. By default at most 15% of the system memory is used for this cache. To detect if the SQL statements fit into memory, monitor the QC cache evictions value in maxctrl show threads to see how many evictions take place. If it keeps increasing, increase the size of the query classifier cache. Using the query classifier cache with a CPU bound workload gives a roughly 20% improvement in performance compared to when it is turned off.
A faster CPU with more CPU cores is better. This is true for most applications but especially for MaxScale as it is mostly limited by the speed of the CPU. Using threads=auto is recommended (the default starting with MaxScale 6).
Network throughput between the client, MaxScale and the database nodes governs how much traffic can be handled. The client-to-MaxScale network is likely to be saturated first: having multiple MaxScales in front of the cluster is an easy way of solving this problem.
Certain MaxScale modules store data on disk. A faster disk improves their performance but depending on the module, this might not be a big enough of a problem to worry about. Filters like the qlafilter that write information to disk for every SQL query can cause performance bottlenecks.

MaxScale Diagnostics using MaxCtrl

From 22.08.2 onwards, maxctrl show maxscale shows a System object with information about the system MaxScale is running on. The fields are:

Field

Meaning

machine.cores_physical

The number of physical CPU cores on the machine.

machine.cores_available

The number of CPU cores available to MaxScale. This number may be smaller than machine.cores_physical, if CPU affinities are used and only a subset of the physical cores are available to MaxScale.

machine.cores_virtual

The number of virtual CPU cores available to MaxScale. This number may be a decimal and smaller than machine.cores_available, if MaxScale is running in a container whose CPU quota and period has been restricted. Note that if MaxScale is not, or fails to detect it is running in a container, the value shown will be identical with machine.cores_available.

machine.memory_physical

The amount of physical memory on the machine.

machine.memory_available

The amount of memory available to MaxScale. This number may be smaller than machine.memory_physical, if MaxScale is running in a container whose memory has been restricted. Note that if MaxScale is not, or fails to detect it is running in a container, the value shown will be identical with machine.memory_physical. Note also that the amount is available to all processes running in the same container, not just to MaxScale.

maxscale.query_classifier_cache_size

The maximum size of the MaxScale query classifier cache.

maxscale.threads

The number of routing threads used by MaxScale.

In addition there is an os object that contains what the Linux command uname displays.

Configuration

threads

If threads has not been specified at all in the MaxScale configuration file, or if its value is auto, then MaxScale will use as many routing threads as there are physical cores on the machine. This is the right choice, if MaxScale is running on a dedicated machine or in a container that has not been restricted in any way.

However, if the number of cores available to MaxScale have been restricted or if MaxScale is running in a container whose CPU quota and period have been limited, then it will lead to MaxScale using more routing threads than what is appropriate in the environment where it is running.

If machine.cores_virtual is less than machine.cores_physical, then threads should be specified explicitly in the MaxScale configuration file and its value should be that of machine.cores_virtual rounded up to the nearest integer. If that value is 1 it may be beneficial to check whether 2 gives better performance.

query_classifier_cache_size

If query_classifier_cache_size has not been specified in the MaxScale configuration file, then MaxScale will use at most 15% of the amount of physical memory in the machine for the cache. This is a good starting point, if MaxScale is running on a dedicated machine or in a container that has not been restricted in any way. Note that the amount specifies how much memory the cache at maximum is allowed to use, not what would immediately be allocated for the cache.

However, if the amount of memory available to MaxScale has been restricted, which may be the case if MaxScale is running in a container, this may cause the cache to grow beyond what is available, which will lead to a crash or MaxScale being killed.

If the value of machine.memory_available is less than that ofmachine.memory_physical, then query_classifier_cache_size should be explicitly set to 15% of maxscale.memory_available. The value can be larger, but must not be a bigger share of machine.memory_available than what is reasonable.

Example

$ maxctrl show maxscale
...
├──────────────┼────────────────────────────────────────────────────────────────────────────┤
│ System       │ {                                                                          │
│              │     "machine": {                                                           │
│              │         "cores_available": 8,                                              │
│              │         "cores_physical": 8,                                               │
│              │         "cores_virtual": 4,                                                │
│              │         "memory_available": 20858544128,                                   │
│              │         "memory_physical": 41717088256                                     │
│              │     },                                                                     │
│              │     "maxscale": {                                                          │
│              │         "query_classifier_cache_size": 6257563238,                         │
│              │         "threads": 8                                                       │
│              │     },                                                                     │
│              │     "os": {                                                                │
│              │         "machine": "x86_64",                                               │
│              │         "nodename": "johan-P53s",                                          │
│              │         "release": "5.4.0-125-generic",                                    │
│              │         "sysname": "Linux",                                                │
│              │         "version": "#141~18.04.1-Ubuntu SMP Thu Aug 11 20:15:56 UTC 2022"  │
│              │     }                                                                      │
│              │ }                                                                          │
└──────────────┴────────────────────────────────────────────────────────────────────────────┘

As can be seen, maxscale.threads is larger than machine.cores_virtual and thus,threads=4 should explicitly be specified in the MaxScale configuration file.

maxscale.query_classifier_cache_size is the default 15% of machine.memory_physical but as machine.memory_available is just half of that, something likequery_classifier_cache_size=3100000000 (~15% of machine.memory_available) should be added to the configuration file.

[maxscale]
threads=4
query_classifier_cache_size=3100000000
...

Troubleshooting

For a list of common problems and their solutions, read the MaxScale Troubleshooting article on the MariaDB documentation.

Systemd Watchdog

If MaxScale is running as a systemd service, the systemd Watchdog will be enabled by default. To configure it, change the WatchdogSec option in the Service section of the maxscale systemd configuration file located in/lib/systemd/system/maxscale.service:

WatchdogSec=30s

It is not recommended to use a watchdog timeout less than 30 seconds. When enabled MaxScale will check that all threads are running and notify systemd with a "keep-alive ping".

Systemd reference: systemd.service.html

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

MaxScale

MariaDB MaxScale

Quickstart Guides

MariaDB MaxScale Guide

Quickstart Guide: MariaDB MaxScale Overview

1. What is MariaDB MaxScale?

2. Core Functionalities and Benefits

Further Resources:

MariaDB MaxScale Installation Guide

Quickstart Guide: MariaDB MaxScale

Key concepts

Installation

Basic configuration

Complete configuration

Start and enable MaxScale

Basic usage and verification

Further Resources:

MariaDB MaxScale Authenticators Guide

Quickstart Guide: MariaDB MaxScale Authentication Modules

1. What are MaxScale Authentication Modules?

2. How Authentication Works in MaxScale

3. Available Authentication Plugins

4. Basic Configuration Concepts

Further Resources:

MariaDB MaxScale Limitations Guide

Quickstart Guide: MariaDB MaxScale Limitations

1. Configuration File Line Length

2. Assumptions about MariaDB Server Configuration

3. Transaction Boundary Detection and XA Transactions

4. ETL Feature Dependency

Important General Considerations:

Further Resources:

MaxScale Architecture

About MariaDB MaxScale

About MariaDB MaxScale

Installing MariaDB MaxScale

MariaDB MaxScale Overview

Overview

Scheduled Releases

Latest Software Releases

Available Documentation

Security

Architecture

What's New

MaxScale Management

Installation & Configuration

MaxScale Installation Guide

MariaDB MaxScale Installation Guide

Install MariaDB MaxScale From MariaDB Repositories

Install MariaDB MaxScale From a RPM/DEB Package

Install MariaDB MaxScale Using a Tarball

Building MariaDB MaxScale From Source Code

Assumptions

Memory allocation behavior

Configuring MariaDB MaxScale

Encrypting Passwords

Administration Of MariaDB MaxScale

Copying or Backing Up MaxScale

Building MaxScale From Source

Building MariaDB MaxScale from Source Code

Quickstart

Required Packages

Configuring the Build

Running unit tests

Building MariaDB MaxScale packages

Installing optional components

Installing MaxScale Using a Tarball

Installing MariaDB MaxScale using a tarball

Installing as root in /usr/local

Installing in any Directory

MaxScale MaxGUI Guide

MariaDB MaxScale MaxGUI Guide

Introduction

Enabling MaxGUI

Securing the GUI

Authentication

Pages

Dashboard

Detail

Visualization

Installing as root in `/usr/local`