1 of 100

MariaDB MaxScale 21.06

This version of MariaDB MaxScale enhanced data integration and consistency. It introduced the Kafka CDC connector for streaming changes and simplified causal reads for replica servers.

MariaDB MaxScale 21.06 About

This release enhanced data integration and read-after-write consistency. It introduced the Kafka CDC router to stream database changes and a causal reads feature for replica servers.

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}

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 limitiations

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

Follow the Jira issue to track the progress on this limitation.

XA transactions are not detected as transactions by MaxScale. This means that all XA commands will be treated as unknown commands and will be treated as operations that potentially modify the database (in the case of readwritesplit, the statements are routed to the master).

MaxScale will not track the XA transaction state which means that any SELECT queries done inside an XA transaction can be routed to servers that are not part of the XA transaction.

This limitation can be avoided on the client side by disabling autocommit before any XA transactions are done. The following example shows how a simple XA transaction is done via MaxScale by disabling autocommit for the duration of the XA transaction.

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

Database Firewall limitations (dbfwfilter)

The Database Firewall filter does not support multi-statements. Using them will result in an error being sent to the client.

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.

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

MariaDB MaxScale 21.06 Authenticators

Secure your MaxScale deployment by configuring authenticators. These modules manage client authentication against backend MariaDB servers, supporting various mechanisms for robust security.

MaxScale 21.06 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 master 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.

Authenticator options

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

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

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

Authenticator options

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

Implementation details

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

GSSAPI authentication

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

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

Building the module

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

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

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

Authenticator options

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

`log_password_mismatch`

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

MariaDB MaxScale 21.06 Connectors

This section details connectors for MariaDB MaxScale 21.06. Learn about the Change Data Capture (CDC) APIs that allow applications to consume a real-time stream of database events.

MaxScale 21.06 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-relase
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}

MariaDB MaxScale 21.06 Design Documents

Explore the internal architecture of MariaDB MaxScale. This section contains the detailed design documents and specifications used by developers for core features and modules.

MariaDB MaxScale 21.06 Filters

Filters are powerful modules that intercept and process database traffic in MaxScale. Use them to log, transform, block, or reroute queries to add control, security, and monitoring.

MaxScale 21.06 Binlog Filter

This filter was introduced in MariaDB MaxScale 2.3.0.

Overview

The binlogfilter can be combined with a binlogrouter service to selectively replicate the binary log events to slave 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.

Configuration

`match`

Type:
Mandatory: No
Dynamic: Yes
Default: None

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

`exclude`

Type:
Mandatory: No
Dynamic: Yes
Default: None

Exclude queries that match the regex.

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

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

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

`rewrite_src`

Type:
Mandatory: No
Dynamic: Yes
Default: None

See the next entry, rewrite_dest, for more information.

`rewrite_dest`

Type:
Mandatory: No
Dynamic: Yes
Default: None

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

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

When statement rewriting is enabled must be used. The filter will disallow replication for all slaves 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.

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

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

MaxScale 21.06 Consistent Critical Read Filter

This filter was introduced in MariaDB MaxScale 2.1.

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 master server where data is guaranteed to be in an up-to-date state. Writes from one session do not, by default, propagate to other sessions.

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

Controlling the Filter with SQL Comments

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

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

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

Filter Parameters

The CCR filter has no mandatory parameters.

`time`

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

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

`count`

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

The number of SQL statements to route to master 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 master. 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`, `ignore`

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

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

`options`

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

Regular expression options for match and ignore.

`global`

Type:
Mandatory: No
Dynamic: Yes
Default: false

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

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

Example Configuration

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

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

This prevents read scaling until the modifications have been replicated to the slaves. For best performance, the value of time should be slightly greater than the actual replication lag between the master and its slaves. 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 master.

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

MaxScale 21.06 Insert Stream Filter

This filter was introduced in MariaDB MaxScale 2.1.

Insert Stream Filter

Overview

The insertstream filter converts bulk inserts into CSV data streams that are consumed by the backend server via the LOAD DATA LOCAL INFILE mechanism. This leverages the speed advantage of LOAD DATA LOCAL INFILE over regular inserts while also reducing the overall network traffic by condensing the inserted values into CSV.

Note: This is an experimental filter module

Filter Parameters

This filter has no parameters.

Details of Operation

The filter translates all INSERT statements done inside an explicit transaction into LOAD DATA LOCAL INFILE streams. The file name used in the request will always be maxscale.data.

The following example is translated into a LOAD DATA LOCAL INFILE request followed by two CSV rows.

BEGIN;
INSERT INTO test.t1 VALUES (1, "hello"), (2, "world");
COMMIT;

Multiple inserts to the same table are combined into a single stream. This allows for efficient bulk loading with simple insert statements.

The following example will use only one LOAD DATA LOCAL INFILE request followed by four CSV rows.

BEGIN;
INSERT INTO test.t1 VALUES (1, "hello"), (2, "world");
INSERT INTO test.t1 VALUES (3, "foo"), (4, "bar");
COMMIT;

Non-INSERT statements executed inside the transaction will close the streaming of the data. Avoid interleaving SELECT statements with INSERT statements inside transactions.

The following example has to use two LOAD DATA LOCAL INFILE requests, each followed by two CSV rows.

Note: Avoid doing this!

BEGIN;
INSERT INTO test.t1 VALUES (1, "hello"), (2, "world");
SELECT * FROM test.t1;
INSERT INTO test.t1 VALUES (3, "foo"), (4, "bar");
COMMIT;

Estimating Network Bandwidth Reduction

The more inserts that are streamed, the more efficient this filter is. The saving in network bandwidth in bytes can be estimated with the following formula:

((20 + t) * n) + (n * (m * 2)) - 108 - t = x

n = Number of INSERT statements
m = Number of values in each insert statement
t = Length of table name
x = Number of bytes saved

Positive values indicate savings in network bandwidth usage.

Example Configuration

The filter has no parameters so it is extremely simple to configure. The following example shows the required filter configuration.

[Insert-Stream]
type=filter
module=insertstream

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

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

Filter Parameters

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() - global script only, called when MaxScale is started
- The global script will be loaded in this function and executed once on a global level before calling the createInstance function in the Lua script.
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(string) - 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 calls the clientReply function of the Lua scripts.
string diagnostic() - global script only, print diagnostic information
- This will call the matching diagnostics entry point in the Lua script. If the Lua function returns a string, it will be printed to the client.

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 three functions that can be called from the Lua script.

string lua_qc_get_type_mask()
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 lua_qc_get_operation()
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 lua_get_canonical()
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 id_gen()
This function generates unique integers that can be used to distinct sessions from each other.

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.

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

MaxScale 21.06 Maxrows

This filter was introduced in MariaDB MaxScale 2.1.

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

Filter Parameters

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 21.06 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 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 chapter in the PCRE2 manual.

Configuration

The following demonstrates a minimal configuration.

Filter Parameters

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

`match`

Type:
Mandatory: Yes
Dynamic: Yes

Defines the text in the SQL statements that is replaced.

`options`

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

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

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

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

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

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

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

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

MaxScale 21.06 Throttle

This filter was added in MariaDB MaxScale 2.3

Throttle
- Overview
- Configuration

Overview

The throttle filter replaces and extends on the limit_queries functionality of the Database Firewall filter.

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.

Filter Parameters

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

Filter Parameters

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}

MariaDB MaxScale 21.06 Getting Started

This is your starting point for MariaDB MaxScale 21.06. Find essential guides for installation, learn the basics of configuration, and explore tutorials to get up and running quickly.

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
SQLite3 version 3.3 or later
OpenSSL version 1.0.1 or later
GNUTLS
libxml2
libatomic
libcurl
Tcl
pcre2
jansson
libmicrohttpd
Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl

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

Argument Name

Explanation

CMAKE_INSTALL_PREFIX

Location where MariaDB MaxScale will be installed to. Set this to /usr if you want MariaDB MaxScale installed into the same place the packages are installed.

BUILD_TESTS

Build unit tests

WITH_SCRIPTS

Install systemd and init.d scripts

PACKAGE

Enable building of packages

TARGET_COMPONENT

Which component to install, default is the 'core' package. Other targets are 'experimental', which installs experimental packages and 'all' which installs all components.

TARBALL

Build tar.gz packages, requires PACKAGE=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 invokation. 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

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 /var/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 /var/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 adviseable 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}

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

MaxScale 21.06 Monitors

MariaDB MaxScale 21.06 Protocols

Protocol modules interpret client-server communication for MaxScale. This section covers the available modules, including the standard MariaDB protocol, NoSQL, and Change Data Capture (CDC).

MaxScale 21.06 Change Data Capture (CDC) Protocol

CDC is a new protocol that allows compatible clients to authenticate and register for Change Data Capture events. The new protocol must be use in conjunction with AVRO router which currently converts MariaDB binlog events into AVRO records. Change Data Capture protocol is used by clients in order to interact with stored AVRO file and also allows registered clients to be notified with the new events coming from MariaDB 10.0/10.1 database.

Creating Users

The users and their hashed passwords are stored in /var/cache/maxscale/<service name>/cdcusers where <service name> is the name of the service.

For example, the following service entry will look into /var/cache/maxscale/CDC-Service/ for a file called cdcusers. If that file is found, the users in that file will be used for authentication.

If the cdcusers file cannot be found, the service user (maxuser:maxpwd in the example) can be used to connect through the CDC protocol.

For more details, refer to the .

Protocol Phases

Connection and Authentication

Client connects to MaxScale CDC protocol listener.
Send the authentication message which includes the user and the SHA1 of the password

In the future, optional flags could be implemented.

Registration

Sending UUID
Specify the output format (AVRO or JSON) for data retrieval.

Data Request

Send CDC commands to retrieve router statistics or to query for data events

Protocol Details

Authentication

The authentication starts when the client sends the hexadecimal representation of the username concatenated with a colon (:) and the SHA1 of the password.

bin2hex(username + ':' + SHA1(password))

For example the user foobar with a password of foopasswd should send the following hexadecimal string

Server returns OK on success and ERR on failure.

Registration

REGISTER

REGISTER UUID=UUID, TYPE={JSON | AVRO}

Example:

Server returns OK on success and ERR on failure.

Change Data Capture Commands

REQUEST-DATA

REQUEST-DATA DATABASE.TABLE[.VERSION] [GTID]

This command fetches data from specified table in a database and returns the output in the requested format (AVRO or JSON). Data records are sent to clients and if new AVRO versions are found (e.g. mydb.mytable.0000002.avro) the new schema and data will be sent as well.

The data will be streamed until the client closes the connection.

Clients should continue reading from network in order to automatically gets new events.

Example:

Example Client

MaxScale includes an example CDC client application written in Python 3. You can find the source code for it .

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

MaxScale 21.06 Change Data Capture (CDC) users

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

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

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

Creating new CDC users

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

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

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

bash$ cdc_users.py [-h] USER PASSWORD

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

bash$ cdc_users.py user1 pass1 >> /var/lib/maxscale/avro-service/cdcusers

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

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

MaxScale 21.06 MariaDB Protocol Module

The mariadbprotocol module implements the MariaDB client-server protocol.

The legacy protocol names mysqlclient, mariadb and mariadbclient are all aliases to mariadbprotocol.

MariaDB Protocol Module
- Configuration
  - allow_replication

Configuration

Protocol level parameters are defined in the listeners. They must be defined using the scoped parameter syntax where the protocol name is used as the prefix.

[MyListener]
type=listener
service=MyService
protocol=mariadbprotocol
mariadbprotocol.allow_replication=false
port=3306

For the MariaDB protocol module, the prefix is always mariadbprotocol.

`allow_replication`

Type: boolean
Mandatory: No
Dynamic: Yes
Default: true

Whether the use of the replication protocol is allowed through this listener. If disabled with mariadbprotocol.allow_replication=false, all attempts to start replication will be rejected with a ER_FEATURE_DISABLED error (error number 1289).

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

MariaDB MaxScale 21.06 Reference

Access detailed technical information for MariaDB MaxScale 21.06. This section is your complete reference for configuration settings, command-line tools, hint syntax, and more.

MaxScale 21.06 Hint Syntax

Refer to the documentation for the MaxScale hint syntax.

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

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

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

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}

MariaDB MaxScale 21.06 Release Notes

Review the official release notes for MariaDB MaxScale 21.06. This section details new features like the Kafka CDC router and causal reads, as well as all bug fixes and functional changes. Sources

MariaDB MaxScale 21.06.20 Release Notes

Release 21.06.20 is a GA release.

This document describes the changes in release 21.06.20, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-5618 Maxctrl interactive mode doesn't use --tls-verify-server-cert=false
MXS-5608 optimistic_trx causes a query to hang
MXS-5599 Processing of conditional headers is incorrect
MXS-5598 MaxCtrl fails to read large inputs from stdin
MXS-5590 REST-API always sends a Connection: close header
MXS-5582 Add a Service with a CLUSTER as its target breaks CONFIG SYNC
MXS-5577 Aborted connection on backend mariadb with persistpool maxscale
MXS-5576 Maxctrl config permission check error message is misleading
MXS-5567 Wrong password in interactive mode is only seen after the first command
MXS-5566 --secretsdir has no default value
MXS-5563 Using PKCS#1 private key in the REST-API results in cryptic errors
MXS-5556 Trailing parts of large session command are not routed correctly
MXS-5542 kafkacdc commits offsets when it probes GTIDs from Kafka
MXS-5541 Logs Archive page doesn't show useful API error
MXS-5525 Masking with functions uses wrong rule settings

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code of MaxScale is tagged at GitHub with a tag, which is identical with the version of MaxScale. For instance, the tag of version X.Y.Z of MaxScale is maxscale-X.Y.Z. Further, the default branch is always the latest GA version of MaxScale.

The source code is available here.

MariaDB MaxScale 21.06.16 Release Notes -- 2024-06-03

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

Release 21.06.16 is a GA release.

This document describes the changes in release 21.06.16, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

New Features

Add "enforce_read_only_servers" feature to MariaDB Monitor

Bug fixes

Master Stickiness state is not documented
ability to setup .secrets file location
max_slave_connections=0 may create slave connections after a switchover
ssl_version in MaxScale and tls_version in MariaDB behave differently
Password encryption format change in 2.5 is not documented very well
The values of ssl_version in MaxScale and tls_version in MariaDB accept different values
Warning about missing slashes around regular expressions is confusing
Problem in hostname matching when using regex (%) for user authentication
cooperative_monitoring_locks can leave stale locks on a server if network breaks
Maxscale key limitations
enforce_read_only_slaves can set master to read_only
gdb-stacktrace is incorrectly presented as a debug option
During Failover Passive MaxScale route writes to the Old Master
Session commands that are executed early are not validated
--basedir is broken
MariaDB Monitor command reset-replication can be started on a secondary MaxScale
MaxScale should log a warning if failover may lose transactions

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 21.06.17 Release Notes -- 2024-09-09

Release 21.06.17 is a GA release.

This document describes the changes in release 21.06.17, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

Large batches of session commands may leave sessions alive for a long time
MaxScale does not drop supplementary groups if --user is used
LICENSE.TXT is a dangling symlink in RPMs
Erroneous "Cluster gtid domain is unknown" error message during failover
Reads with max_slave_connections=0 after a switchover do not discard stale connections
CMake 3.28.3 warnings
Default logrotate config in .deb / docu missing params
/maxscale/logs/data may return no data if maxlog=0 and syslog=1
Multi-statement commands may end up being stored in the session command history
Two cache filters in same service causes errors on session creation
MaxScale does not have time to open the file during rotation for a new binlog
Post reboot binlog router entered stuck state
postinst script prints output while installing
23.08.6 build ppc64le fails
Memory leak in namedserverfilter
comment filter uses the wrong module name
DEALLOCATE PREPARE is not routed to all nodes
MaxScale detects wrong server character set

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 21.06.19 Release Notes

Release 21.06.19 is a GA release.

This document describes the changes in release 21.06.19, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

External CVEs resolved.

Fixed by Container Image vulnerability CVE-2024-21538 (MXS)

Bug fixes

Early mismatched responses to session commands do not close connections
Session commands with max_slave_connections=0 after switchover do not discard stale connections
The "INSERT INTO...RETURNING" syntax breaks causal_reads
Documentation regarding mixing of cooperative_monitoring_locks and passive is unclear
Relationship selections auto-cleared when creating a new monitor object
readwritesplit enables multi-statements regardless of the state of causal_reads
idle_session_pool_time=0s does not fairly share connections
Need Documentation updates for Maxscale install recommendation
MaxCtrl warnings are very verbose
Errors during loading of users lack the service name
maxctrl list queries fails
Encrypted passwords cannot be used with maxctrl
Log message: Unknown prepared statement handler given to MaxScale
Backend connections with fail with EAGAIN
Failed authentication warnings do not mention lack of client-side SSL as the reason of the failure
MaxScale 24.02.04 not closing DB Connections properly
Duration types that only take seconds return ms as units instead of s
retry_failed_reads is not affected by delayed_retry_timeout
Debug assertion on very large binary protocol prepared statements
Some log messages are not logged when session_trace is used
NVL and NVL2 are not detected as builtin functions outside of sql_mode=ORACLE
Kafkacdc errors for wrong GTID positions are not clear
Errors due to max_connections being exceeded are always fatal errors

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.1.0 Release Notes -- 2021-07-15

Release 6.1.0 is a GA release.

This document describes the changes in release 6.1.0, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-3661 The list of servers might get duplicated for routers using mariadbmon
MXS-3660 MaxScale crashes if backend connection creation fails on a system error
MXS-3658 If the monitor is dynamic, both static and volatile servers will be used.

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.1.1 Release Notes

Release 6.1.1 is a GA release.

This document describes the changes in release 6.1.1, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-3697 MaxCtrl config file check fails when executed from the root directory

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.1.3 Release Notes -- 2021.10.01

Release 6.1.3 is a GA release.

This document describes the changes in release 6.1.3, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

maxscale 6.1.2 killed by SystemD watchdog

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.2.1 Release Notes -- 2022-01-13

Release 6.2.1 is a GA release.

This document describes the changes in release 6.2.1, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

New Features

Invent a configuration option to allow transaction replay ignore checksum check
Make transaction_replay less strict
Per service log_info

Bug fixes

Altering xpandmon at runtime fails
create_one_connection_for_sescmd() doesn't correctly replace m_current_master
Debug assertion in mariadb_backend.cc
Debug assertion during transaction replay
Debug assert in xpandmon
Transaction replay time limits are unpredictable
Linking a service at runtime to an xpandmon doesn't work
connection stalled after executing a stored procedure with OUT parameter
MaxScale logs a warning when users are loaded from a Xpand cluster
Some log messages do not contain the session ID
Session commands are not retried with delayed_retry
Can't connect to MaxScale when schema uses utf8mb4 chars >= U0080
Crash during set server maintenance --force
Autocommit tracking doesn't work correctly
Monitor parameters table is not modifiable (GUI)
Skip http_proxy when address is localhost
MaxScale crashes (double free or corruption)
Unexpected result state
Add multi-threaded stack traces
MaxScale crashes when executing CDC process to kafka
When reading password from stdin via redirect, interactive use is no longer possible
read/write split service incorrectly times out valid sessions on master if timeout happens on replica
LIMIT should be added for each select query automatically
Using the binlog router as the source for KafkaCDC router is unreliable
Use virtual scroll on maxscale log view to fix memory issue

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.2.3 Release Notes -- 2022-03-09

Release 6.2.3 is a GA release.

This document describes the changes in release 6.2.3, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-4038 maxctrl reload service does not bypass the users refresh rate limit
MXS-4035 Cache warns too aggressively of statements that cannot be cached.
MXS-4030 Query Editor: Y axis dropdown doesn't show accurate table columns
MXS-4021 Monitor is not shown in MaxGUI's dashboard if the monitor is stopped
MXS-4011 maxscale.cnf.template on MaxScale 6.x refers to 2.5 documentation
MXS-4008 Query classifier cache does not properly record all used memory
MXS-4007 Active operation count is wrong after failed causal read
MXS-4005 Crash on server failure with causal_reads=local
MXS-4004 Race condition in KILL command execution
MXS-4002 KILL commands leave no trace in the log
MXS-4001 The Cache filter cannot cope with the Redis server closing the connection
MXS-4000 Binlogrouter creates malformed replication events
MXS-3988 Document implications of changed auth_all_servers default on schemarouter
MXS-3984 COM_CHANGE_USER from 'user' to 'user' succeeded on MaxScale yet failed on backends
MXS-3979 Not all state transitions are written to the log
MXS-3957 Remove the Don't Limit option for max_rows value of the Query Editor
MXS-3954 Got below signal 11 error after upgrading maxscale version maxscale 6.2.1
MXS-3945 Sync marker mismatch while reading Avro file
MXS-3931 Check certificates with extendedKeyUsage options set for correct purpose flags
MXS-3808 Improve Rest API performance

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.2.4 Release Notes -- 2022-03-30

Release 6.2.4 is a GA release.

This document describes the changes in release 6.2.4, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

New Features

Name threads for better CPU usage view
Provide more feedback on TLS cipher mismatch

Bug fixes

Query Editor: Query history isn't cleared after passing the retention period
Query Editor: Connection to [::]:9999 failed. Error 2002: Can't connect to server on '::' (113)
The cache does not handle multi-statements properly.
Add maxctrl command for dumping the whole REST API output
Creating a listener in the GUI requires defining the service twice
Mariadbmon constantly logs errors if event scheduler is disabled
Query Editor: Column names should be auto adjust in the Data Preview
Expected status message in the context of queued command, but received a ARRAY

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.3.0 Release Notes -- 2022-04-14

Release 6.3.0 is a GA release.

This document describes the changes in release 6.3.0, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

New Features

MXS-3968 Add support for SSL
MXS-3925 Implement authentication
MXS-3902 Limit total number of connections to backend
MXS-3844 Cooperative Monitor Indicator
MXS-3806 Provide filtering for the KafkaCDC Router
MXS-3413 The persistence of on-the-fly parameter changes needs to be somehow exposed, and more manageable.

Bug fixes

MXS-4082 SQL endpoint doesn't show errors for resultsets
MXS-4080 Query Cache detects wrong parse error in INSERT or DELETE
MXS-4078 maxctrl commands exception with file .maxctrl.cnf
MXS-4074 Status of boostrap servers not always the same as the status of corresponding runtime servers
MXS-4071 A horizontal scrollbar appears in some dialogs
MXS-4064 Address field truncated in GUI
MXS-4053 The cache does not handle multi-statements properly.
MXS-4027 Query Editor Chart is Not Hiding Or need close button For the Chart
MXS-3977 The servers table in monitor details page shouldn't be sorted by default
MXS-3962 Automatically generated dynamic config contains default values for unmodified params

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.4.0 Release Notes -- 2022-06-09

Release 6.4.0 is a GA release.

This document describes the changes in release 6.4.0, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

Schemarouter performance degrades as the number of tables increases
Schemarouter duplicate checks are excessively slow
connection_keepalive sends pings even if client is idle
Race condition in binlogrouter
/etc/maxscale.cnf.d/ is not created by package installation
Maxscale prints user/pass with CHANGE MASTER command in logfile while failover.
namedserverfilter does not work with targets parameter
Queries on already established connections hanging for 15min when Redis server disconnected hard
connection_keepalive=0 causes a memory leak

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.1 Release Notes -- 2022-07-14

Release 6.4.1 is a GA release.

This document describes the changes in release 6.4.1, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

HTTPS requests don't include Path=/ in cookies
The state of the bootstrap nodes is not updated properly
MaxScale w/SSL doesn't work on FIPS RHEL7
Some non-multi-statement queries are classified as multi-statement ones
maxctrl call command leaves stale errors
Hang in RWSplitSession::correct_packet_sequence
Unmodifiable parameters aren't prevented from being modified
Bad create monitor command leaves a ghost monitor
Listeners created at runtime require ssl_ca_cert when it should not be required
Filter diagnostics are not shown in maxctrl show filters
Servers with priority=0 are selected as Master
Debug assertion when cat session ends
Galeramon doesn't work with max_slave_replication_lag
Log warning if reverse name resolution takes significant time

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.10 Release Notes -- 2023-08-30

Release 6.4.10 is a GA release.

This document describes the changes in release 6.4.10, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-4726 Session command response verification unnecessarily stores PS IDs for readconnroute
MXS-4717 information_schema is not invalidated as needed
MXS-4706 Cache does not invalidate when a table is ALTERed, DROPed or RENAMEd

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.4.12 Release Notes -- 2023-11-03

Release 6.4.12 is a GA release.

This document describes the changes in release 6.4.12, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-4847 Crash on maxctrl list sessions

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.4.13 Release Notes -- 2023-11-30

Release 6.4.13 is a GA release.

This document describes the changes in release 6.4.13, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

GUI failed to create a monitor in a monitored server detail page
Broken slave promoted to master when no other servers are available

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.14 Release Notes -- 2024-02-09

Release 6.4.14 is a GA release.

This document describes the changes in release 6.4.14, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

New Features

ssl_version should specify minimum version

Bug fixes

Session commands ignore delayed_retry_timeout
Tables in information_schema are treated as a normal tables
GUI doesn't validate object name uniqueness accurately
Use-after-free after service deletion
History length of sessions is not visible in the REST-API
Very fast client and server may end up busy-looping a worker
The "New messages available" button in the GUI Logs Archive does not disappear after being clicked.
Memory growth for long-running sessions that use COM_CHANGE_USER
Memory growth for long-running sessions that use prepared statements
Memory leak when closing SSL connection
Query classifier cache total-size book-keeping may be wrong
readconnroute performance regression in 6.4
Undefined behavior with module commands that take no arguments
MonitorWorker::call_run_one_tick() called more often than intended
maxctrl show qc_cache can easily overwhelm MaxScale
Reducing the size of the query classifier cache does not cause excess entries to be freed.
QC cache memory accounting on CentOS 7 is wrong
5.5.5- prefix should not be added if all backends are MariaDB 11

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.2 Release Notes -- 2022-09-02

Release 6.4.2 is a GA release.

This document describes the changes in release 6.4.2, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-4258 Add permission for SHOW DATABASES for Xpand Service to work
MXS-4240 MXS-4239 readconnroute module routing read queries to inconsistent slave node
MXS-4239 Maxscale shows replication status as [Slave, Running] even when replication credentials are wrong
MXS-4237 Schemarouter duble free crash
MXS-4219 Settings of bootstrap servers are not correctly propagated to dynamic servers
MXS-4218 Configuration synchronization fails if static global parameters are different
MXS-4211 MaxScale throws std::out_of_range on invalid listener parameter
MXS-4209 KILL command doesn't work correctly if persistent connections are enabled
MXS-4198 MaxScale fails to validate its own certificate when the chain of trust is unknown to OpenSSL
MXS-4196 Readconnroute load balancing behavior is not well documented
MXS-4183 Multiplexing fails with "Timed out when waiting for a connection"

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.4.4 Release Notes -- 2022-11-29

Release 6.4.4 is a GA release.

This document describes the changes in release 6.4.4, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

Warning for xpandmon for 'leaving' / 'late, leaving' being an unknown sub-state
UPDATE with user variable breaks replication
Maxscale: KafkaCDC writes to current_gtid.txt causes high disk utilisation.
fields parameter breaks REST-API filtering
Authentication failures during shard mapping are not handled correctly
Crash in handleError
LOAD DATA LOCAL INFILE and changing autocomit causing stuck
MAXGUI - Out of memory in client PC browser.
/maxscale/logs/data endpoint doesn't filter syslog contents correctly
Full SASL support is not enabled for kafka modules
Smartrouter interrupts the wrong query
Database grants in user_accounts_file should add the database to the list of known databases

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.5 Release Notes -- 2023-01-13

Release 6.4.5 is a GA release.

This document describes the changes in release 6.4.5, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the upgrading document for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on our Jira.

Bug fixes

MXS-4474 MaxScale hangs with warning about "Worker 1 attempted to send a message to worker 1"
MXS-4471 Table selection doesn't tolerate node failures
MXS-4470 COM_INIT_DB isn't routed to all shards
MXS-4469 Schemarouter routing logic documentation is out of date
MXS-4467 Explicit transactions without a default database do not work as expected with schemarouter
MXS-4460 Crash during query replay with service-to-service configuration
MXS-4454 Schemarouter should prefer targets which have databases in them for session commands
MXS-4453 Schemarouter selects an invalid target for queries that do not target a specific shard
MXS-4450 6.4 no longer provides full certificate chain in TLS HELLO
MXS-4440 Lost connection to backend server: network error (server1: 104, Connection reset by peer)
MXS-4439 Maxscale is failing with Resource temporarily unavailable errors
MXS-4435 Log rotation causes errors in qlafilter
MXS-4423 Rebalancing is not always initiated from the affected worker/thread

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the Limitations document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded here.

Source Code

The source code is available here.

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

MariaDB MaxScale 6.4.6 Release Notes -- 2023-03-29

Release 6.4.6 is a GA release.

This document describes the changes in release 6.4.6, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

RHEL8 Packages for 23.02.1 and 22.08.5
Binlogrouter breaks if event size exceeds INT_MAX
Maxscale ignores lower_case_table_names=1 on config file
Dynamic filter capabilities do not work
"Unknown prepared statement handler" error when connection_keepalive is disabled on a readconnroute service
Empty regex // is not treated as empty
transaction replay retries repeatedly after failing checksum
Wrong server version assumption
MaxScale leaks sessions if they are closed when writeq throttling is enabled
skip_name_resolve is not modifiable at runtime
Uncaught exception in binlogrouter
IP wildcard values are not permitted in host values while using data masking
config_sync_cluster always uses the mysql database
Replication breaks if binlogfilter excludes events
PHP program reports different collation_connection when connecting via Maxscale
Attempting to create a table with the name "DUAL" crashes MaxScale
Memory leak in smartrouter
Hang in smartrouter under heavy load
Improve match/exclude documentation for avrorouter and kafkacdc
QLA filter not properly logging USE DBx command.
pinloki_start_stop is unstable
The rpl_state in binlogrouter is not atomic

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.7 Release Notes -- 2023-05-24

Release 6.4.7 is a GA release.

This document describes the changes in release 6.4.7, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

Bug fixes

Partially executed multi-result queries are not treated as partial results
Query classifier does not recognize BEGIN NOT ATOMIC ... END
Readwritesplit prefers idle primary over busy replicas
Qlafilter logs responses from non-matched queries
AVX instructions end up being executed on startup
Query canonicalization does not work on scientific numbers
maxctrl classify sends malformed SQL
transaction_replay_max_size default is 1GiB instead of 1MiB
Not all passwords were obfuscated in the maxctrl report
qlafilter with options=extended does not log query nor date
Regular expression documentation is inaccurate and lacking
The statement canonicalizer cannot handle comments within statements
KB pages reference mysqlauth and mysqlauth is deprecated for mariadbauth

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 6.4.8 Release Notes -- 2023-07-31

Release 6.4.8 is a GA release.

This document describes the changes in release 6.4.8, when compared to the previous release in the same series.

If you are upgrading from an older major version of MaxScale, please read the for this MaxScale version.

For any problems you encounter, please consider submitting a bug report on .

New Features

Provide a way to show details about all supported MaxScale modules via REST API and/or MaxCtrl

Bug fixes

ssl parameters specified on the bootstrap server are not copied to the rest
REST-API documentation is wrong about which server parameters can be modified
causal_reads=local is serialized as causal_reads=true
Listener creation error is misleading
xpandmon diagnostics are not useful
Galeramon use_priority example is incorrect
Document supported wire protocol versions
Cache filter hangs if statement consists of multiple packets.
Post reboot binlog router entered stuck state
Add human readable message text to API errors like 404
Setting session_track_trx_state=true leads to OOM kiled.
Documentation claims that netmask support is limited to numbers 255 and 0
MongoDB monitoring promoted when connecting to NoSQL service
qlafilter log event notifications are sometimes lost
GUI is unable to create a listener with other protocols than MariaDBProtocol
readconnroute documentation page contains a typo "max_slave_replication_lag"
Harden BLR binlog file-index handling
Connection in Query Editor is closed after 1 hour of being idle

Known Issues and Limitations

There are some limitations and known issues within this version of MaxScale. For more information, please refer to the document.

Packaging

RPM and Debian packages are provided for the supported Linux distributions.

Packages can be downloaded .

Source Code

The source code is available .

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

MariaDB MaxScale 21.06 REST API

Manage MaxScale programmatically using the REST API. This interface allows for the dynamic administration and monitoring of resources like servers, services, listeners, and filters.

MariaDB MaxScale 21.06 Routers

Routers are the core of a MaxScale service, intelligently directing database traffic. This version adds the KafkaCDC router and enhances others with features like causal reads.

MaxScale 21.06 Cat

The cat router is a special router that concatenates result sets.

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.

Configuration

The router has no special parameters. To use it, define a service withrouter=cat and add the servers you want to use.

Behavior

The order the servers are defined in is the order in which the servers are queried. This means that the results are ordered based on the servers parameter of the service. The result will only be completed once all servers have executed this.

All commands executed via this router will be executed on all servers. This means that an INSERT through the cat router will send it to all servers. In the case of commands that do not return resultsets, the response of the last server is sent to the client. This means that if one of the earlier servers returns a different result, the client will not see it.

As the intended use-case of the router is to mainly reduce multiple result sets into one, it has no mechanisms to prevent writes from being executed on slave servers (which would cause data corruption or replication failure). Take great care when performing administrative operations though this router.

If a connection to one of the servers is lost, the client connection will also be closed.

Example

Here is a simple example service definition that uses the servers from the tutorial and the credentials from the .

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

MaxScale 21.06 HintRouter

HintRouter was introduced in 2.2 and is still beta.

Overview

The HintRouter module is a simple router intended to operate in conjunction with the NamedServerFilter. The router looks at the hints embedded in a packet buffer and attempts to route the packet according to the hint. The user can also set a default action to be taken when a query has no hints or when the hints could not be applied.

If a packet has multiple hints attached, the router will read them in order and attempt routing. Any successful routing ends the process and any further hints are ignored for the packet.

Configuration

The HintRouter is a rather simple router and only accepts a few configuration settings.

This setting defines what happens when a query has no routing hint or applying the routing hint(s) fails. If also the default action fails, the routing will end in error and the session closes. The different values are:

Value

Description

Note that setting default action to anything other than all means that session variable write commands are by default not routed to all backends.

Defines the default backend name if default_action=named. <server-name> must be a valid backend name.

<limit> should be an integer, -1 by default. Defines how many backend slave servers a session should attempt to connect to. Having less slaves defined in the services and/or less successful connections during session creation is not an error. The router will attempt to distribute slaves evenly between sessions by assigning them in a round robin fashion. The session will always try to connect to a master regardless of this setting, although not finding one is not an error.

Negative values activate default mode, in which case this value is set to the number of backends in the service - 1, so that the sessions are connected to all slaves.

If the hints or the default_action point to a named server, this setting is probably best left to default to ensure that the specific server is connected to at session creation. The router will not attempt to connect to additional servers after session creation.

Examples

A minimal configuration doesn't require any parameters as all settings have reasonable defaults.

If packets should be routed to the master server by default and only a few connections are required, the configuration might be as follows.

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

MariaDB MaxScale 21.06

MariaDB MaxScale 21.06 About

About MariaDB MaxScale

Installing MariaDB MaxScale

Limitations and Known Issues within MariaDB MaxScale

Configuration limitations

Multiple MaxScales on same server

Security limitiations

MariaDB 10.2

MariaDB Default Values

Query Classification

Prepared Statements

Protocol limitations

Limitations with MySQL/MariaDB Protocol support (MariaDBClient)

Authenticator limitations

Limitations in the MySQL authenticator (MariaDBAuth)

Filter limitations

Database Firewall limitations (dbfwfilter)

Tee filter limitations (tee)

Monitor limitations

Limitations with Galera Cluster Monitoring (galeramon)

Router limitations

MariaDB MaxScale 21.06 Authenticators

MaxScale 21.06 Authentication Modules

User account management

Required grants

Limitations and troubleshooting

Wildcard database grants

Authenticator options

skip_authentication

match_host

lower_case_table_names

MaxScale 21.06 GSSAPI Client Authenticator

Preparing the GSSAPI system

Authenticator options

principal_name

gssapi_keytab_path

Implementation details

GSSAPI authentication

Building the module

MaxScale 21.06 MariaDB/MySQL Authenticator

Authenticator options

log_password_mismatch

cache_dir

inject_service_user

MariaDB MaxScale 21.06 Connectors

MaxScale 21.06 Maxscale CDC Connector

Usage

API Overview

Examples

Dependencies

RHEL/CentOS 7

Debian Stretch and Ubuntu Xenial

Debian Jessie

openSUSE Leap 42.3

Building and Packaging

MariaDB MaxScale 21.06 Design Documents

MariaDB MaxScale 21.06 Filters

MaxScale 21.06 Binlog Filter

Overview

Configuration

match

exclude

rewrite_src

rewrite_dest

Example Configuration

MaxScale 21.06 Consistent Critical Read Filter

Overview

Controlling the Filter with SQL Comments

Filter Parameters

time

count

match, ignore

options

global

Example Configuration

MaxScale 21.06 Insert Stream Filter

Overview

Filter Parameters

Details of Operation

`skip_authentication`

`match_host`

`lower_case_table_names`

`principal_name`

`gssapi_keytab_path`

`log_password_mismatch`

`cache_dir`

`inject_service_user`

`match`

`exclude`

`rewrite_src`

`rewrite_dest`

`time`

`count`

`match`, `ignore`

`options`

`global`

`global_script`

`session_script`

`match`

`options`

`replace`

`source`

`user`

`log_file`

`log_trace`

`sampling_duration`

`continuous_duration`

Installing as root in `/usr/local`