MariaDB MaxScale Installation Guide

We recommend to install MaxScale on a separate server, to ensure that there can be no competition of resources between MaxScale and a MariaDB Server that it manages.

Install MariaDB MaxScale From MariaDB Repositories

The recommended approach is to use the MariaDB package repository to install MaxScale. After enabling the repository by following the instructions, MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install maxscale.

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

• For SLES, use zypper install maxscale.

Install MariaDB MaxScale From a RPM/DEB Package

Download the correct MaxScale package for your CPU architecture and operating system from the MariaDB Downloads page. MaxScale can be installed with the following commands.

• For RHEL/Rocky Linux/Alma Linux, use dnf install /path/to/maxscale-*.rpm

• For Debian and Ubuntu, use apt install /path/to/maxscale-*.deb.

• For SLES, use zypper install /path/to/maxscale-*.rpm.

Install MariaDB MaxScale Using a Tarball

MaxScale can also be installed using a tarball. This may be required if you are using a Linux distribution for which there exist no installation package or if you want to install many different MaxScale versions side by side. For instructions on how to do that, please refer to Install MariaDB MaxScale using a Tarball.

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

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 vm.overcommit_memory having the value 0, which is also the default on most systems.

With vm.overcommit_memory being 0, memory allocations made by an application never fail, but instead the application may be killed by the so-called OOM (out-of-memory) killer if, by the time the application actually attempts to use the allocated memory, there is not available free memory on the system.

If the value is 2, then a memory allocation made by an application may fail and unless the application is prepared for that possibility, it will likely crash with a SIGSEGV. As MaxScale is not prepared to handle memory allocation failures, it will crash in this situation.

The current value of vm.overcommit_memory can be checked with this command:

sysctl vm.overcommit_memory

Alternatively, use this command:

cat /proc/sys/vm/overcommit_memory

Configuring MariaDB MaxScale

The MaxScale Tutorial 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 Configuration Guide and the module specific documents found in the reference.

Encrypting Passwords

Read the Encrypting Passwords 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, maxctrl, that interacts with a running MariaDB MaxScale and allows the status of MariaDB MaxScale to be monitored and give some control of the MariaDB MaxScale functionality.

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

tar -caf maxscale-backup.tar.gz /etc/maxscale.cnf /etc/maxscale.cnf.d/ /var/lib/maxscale/

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 MariaDB MaxScale from Source Code

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

• CMake version 3.16 or later (Packaging requires CMake 3.25.1 or later)

• GCC version 4.9 or later

• OpenSSL version 1.1.1 or later

• GNUTLS

• Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl

• PAM

• SASL2 (cyrus-sasl)

• SQLite3 version 3.3 or later

• Tcl

• git

• jansson

• libatomic

• libcurl

• libmicrohttpd

• libuuid

• libxml2

• libssh

• pcre2

• zstd

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

• libuuid (binlogrouter)

• boost (binlogrouter)

• Bison 2.7 or later (dbfwfilter)

• Flex 2.5.35 or later (dbfwfilter)

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

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

Required Packages

For a definitive list of packages, consult the install_build_deps.sh script.

Configuring the Build

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

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

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

Running unit tests

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

Building MariaDB MaxScale packages

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

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

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

make
LD_LIBRARY_PATH=$PWD/server/core/ make package

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

$ 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

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:

$ sudo mkdir /var/log/maxscale
$ sudo mkdir /var/lib/maxscale
$ sudo mkdir /run/maxscale
$ sudo mkdir /var/cache/maxscale

and make maxscale the owner of them:

$ sudo chown maxscale /var/log/maxscale
$ sudo chown maxscale /var/lib/maxscale
$ sudo chown maxscale /run/maxscale
$ sudo chown maxscale /var/cache/maxscale

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

When the configuration file has been created, MariaDB MaxScale can be started.

$ sudo bin/maxscale --user=maxscale -d

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.

$ sudo bin/maxscale --user=maxscale --basedir=/usr/local/maxscale -d

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.

$ tar -xzvf maxscale-x.y.z.OS.tar.gz

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

When the configuration file has been created, MariaDB MaxScale can be started.

$ cd maxscale-x.y.z.OS
$ bin/maxscale -d --basedir=.

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

$ bin/maxscale --help

to find out the appropriate flags.

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

Overview

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

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

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

• It does not use TLS by default.

• It used a hard-coded user (admin) and password (mariadb) by default.

Configuring MaxScale's REST API for Remote Connections

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

For example:

1. Restart the MaxScale instance.

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

• REST API

  • Configuring the REST-API

  • Creating a REST API User

• TLS

• MaxGUI

• Operations

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

Overview

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

• Setting a server to maintenance mode.

• Reconfiguring monitors.

• Reconfiguring routers.

• And much more.

Tools Supported by MaxScale

MaxScale supports different administrative interfaces for different kinds of environments and preferences:

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

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

1. if the default configuration is not sufficient.

2. Use MaxCtrl to execute the command:

Replace admin with the actual user.

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

Overview

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

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

MaxCtrl is a command-line utility that can perform administrative tasks using MaxScale's REST API. It can be used to set a server to maintenance mode.

Setting a Server to Maintenance Mode

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

2. Use MaxCtrl to execute the set server command with the maintenance option:

Replace server1 with the name of the specific server.

1. If the specified server is a primary server, then MaxScale will allow open transactions to complete before closing any connections.

Forcing a Server to Maintenance Mode

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

1. Replace server1 with the specific server name. When --force is used, MaxScale immediately closes all connections, even if the server is a primary server with open transactions.

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

Overview

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

MariaDB MaxScale MaxGUI Guide

Introduction

Limitations and Known Issues within MariaDB MaxScale

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

Overview

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

Overview

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

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

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

Overview

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

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

Overview

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

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

MaxGUI is a graphical utility that can perform administrative tasks using MaxScale's

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 release notes of the releases you are upgrading from and upgrading to.

Before starting the upgrade, any existing configuration files should be backed up.

Upgrading MariaDB MaxScale from 25.01 to 25.10

Service User Grants

The service users now require a SELECT grant on the mysql.global_priv table in order to be able to support authentication of users with multiple authentication mechanisms. If this grant is not given to the service users, a warning is logged. The following SQL shows how the grant is given to a user:

Monitor timeouts

In MaxScale 25.10, only one monitor backend timeout remains: . This replaces the old backend_connect_timeout, backend_write_timeout and backend_read_timeout, using the same value for all underlying timeouts. backend_connect_timeout is still supported as an alias for backend_timeout, but any values given to backend_write_timeout and backend_read_timeout are ignored.

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

The functionality that previously was enabled with:

Should now be implemented with:

optimistic_trx

The optimistic_trx parameter has been replaced with the use of the filter module.

The functionality that previously was enabled with:

Should now be implemented with:

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

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

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:

should be replaced with:

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 .

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.

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

must be changed, for instance, to

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,

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

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

should be changed to

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

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.

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.

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.

And here is the new, 1.4 compatible configuration style.

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:

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

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.

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}

These instructions detail the upgrade to MariaDB MaxScale 25.01 in a MaxScale Instance configuration on a range of .

MariaDB MaxScale is an advanced database proxy and query router.

Term Definitions

Backing Up Configuration

Upgrades can move or change configuration files. Before starting an upgrade, always back up your configuration files to ensure you can revert to the working system in the event that you encounter any issues during the upgrade.

To back up a configuration file, create a copy:

Upgrade

MariaDB Corporation provides package repositories for YUM (RHEL, CentOS, Rocky Linux), APT (Debian, Ubuntu), and ZYpp (SLES).

Stop the MaxScale Process

Before upgrading MariaDB MaxScale, first stop the current process.

For distributions that use systemd (most supported OSes), you can manage the Server process using the systemctl command:

Upgrade MaxScale

Upgrade MaxScale following the instructions for your Linux distribution:

Configuration

Configuration parameters can change between releases of MariaDB MaxScale, which can have unexpected results.

1. Determine which parameters have changed by reviewing all the changes made between your current release and the upgrade release.

2. Change the specific parameters in maxscale.cnf.

Changes in MaxScale Versions

Starting the MaxScale Instance

MariaDB MaxScale installations includes configuration to start, stop, restart, enable/disable on boot, and check the status of the MaxScale Instance using the operating system default process management system.

For distributions that use systemd (most supported OSes), you can manage the MaxScale process using the systemctl command:

Testing

When you have MariaDB MaxScale up and running, you should test it to ensure that it is working and that weren't any issues during startup.

Checking MaxScale Status

Check that MaxScale is running properly by using the utility:

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

Profiling Release Mode Binaries

The instructions on the 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/

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:

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:

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

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

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

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

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.

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

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:

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.

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}

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.