Release Notes for MariaDB MaxScale 23.08.5


MariaDB MaxScale is an advanced database proxy and query router. MaxScale is a component of MariaDB database products.

MariaDB MaxScale 23.08.5 was released on 2024-03-11. This release is of General Availability (GA) maturity.

Fixed Security Vulnerabilities

CVE (with link)



libmicrohttpd has been updated to version 0.9.76 (MXS-4751)

MaxGUI Enhancements

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

Enhancements in this release include:

  • Entity Relationship Diagrams (ERD) can be created in the Workspace. (MXS-3735)

  • Visualization of response time distribution (response_time_distribution in the REST API) (MXS-3761)

  • Query Editor displays additional detail (schema object insights) after clicking on a table, procedure, trigger, view, or stored function. Detail includes indexes and foreign keys. (MXS-3991)

Built-in Caching in nosqlprotocol

For nosqlprotocol, internal caching support has been added for increased efficiency. (MXS-3664)

  • Starting with this release, nosqlprotocol.internal_cache uses keys created from NoSQL protocol requests and stores NoSQL protocol responses.

  • The internal cache can be configured by using the following nested configuration syntax:



The LDI filter enables data loading from S3 API-compatible object storage such as AWS S3, Google Cloud Storage, or locally-run storage like MinIO. (MXS-4618)

  • File paths that start with S3:// or gs:// are interpreted as S3 object files.

  • For example, after filter setup, the following SQL statement would would load the file my-data.csv from the bucket my-bucket into the table t1:

    LOAD DATA INFILE 'S3://my-bucket/my-data.csv' INTO TABLE t1
  • For additional information, see LDI filter documentation.

Notable Changes

Common Configuration Blocks

Configuration blocks can be defined which are common to multiple sections, and then be included in those sections by name.

  • This can be useful in cases where multiple monitors are configured the same except for their list of servers.

  • For example:

    backend_connect_timeout = 3s
    backend_connect_attempts = 5
    servers=Server1, Server2
    servers=Server3, Server3

Switchover Improvements

With MariaDB Monitor (mariadbmon), during a switchover MariaDB Monitor initiates a new connection to the master with a long timeout, ignoring the limit of backend_read_timeout. (MXS-2744)

  • This reduces the probability of timeout when executing long-running statements such as SET GLOBAL read_only=1

  • When kicking-out super and read-only admin users, the monitor prevent writes with FLUSH TABLES WITH READ LOCK

  • For additional information, see MariaDB Monitor documentation.

Manual Forced Switchover

Manual forced switchover can be initiated with the MaxCtrl switchover-force command. (MXS-3983)

  • switchover-force swaps a running primary with a replica, ignoring most errors.

  • This command can be useful where an automatic switchover may not happen. For example, manual forced switchover may be needed if the primary server responds to pings but does not perform other commands.

  • switchover-force should be used with caution because it may lead to diverging replication on the old primary.

Safer Transaction Replay

With readwritesplit router with transaction_replay enabled, default transaction replay behavior has changed. (MXS-4505)

  • transaction_replay_safe_commit controls whether to replay transactions that were about to be committed to the server.

  • The new default behavior is not to replay transactions that were being committed to the server when the connection was lost.

Partial Results and Replay

With readwritesplit router, if a query in a transaction is interrupted and the result was partially delivered to the client, the query will be re-executed and the part of the result already delivered to the client will be discarded. (MXS-4549)

fast_universal Causal Reads

With readwritesplit router, the behavior of causal_reads=universal and causal_reads=fast can be combined with causal_reads=fast_universal (MXS-4123)

  • fast_universal uses the same mechanism to retrieve GTID position as universal

  • fast_universal behaves like fast when routing queries.

schemawriter Cache Invalidation

With schemawriter router, the database map cache can be cleared manually using maxctrl (MXS-4215)

  • Syntax:

    maxctrl call command schemarouter clear <service>
  • This makes it possible to schedule the clearing of the caches for busy systems where the update of the map takes a long time.

schemawriter Stale Cache Usage

With schemawriter router, stale entries in the database map can be used up to max_staleness seconds. (MXS-4216)

  • This reduces the impact that a shard update causes to the client applications.

PAM Authentication Sandboxing

PAM authentication can be run in a suid sandbox subprocess. (MXS-3753)

  • This behavior is enabled with PAM Authenticator when pam_mode is suid.

  • For additional information, see PAM Authenticator documentation.

Service Password Changeover

When a service password is changed, MaxScale remembers and will use the previous password if the new password does not work. (MXS-4232)

  • This makes it easier to perform a password changeover, since the password in the backend and the password in MaxScale do not need to be changed simultaneously.

regex Matching Limits

The PCRE2 library used by MaxScale now limits heap memory to 1GB and limits matches to 500000. This change prevents catastrophic backtracking when a regular expression uses nested recursion. (MXS-3531)


admin_jwt_issuer configures the value of the iss field in JWT generated by the MaxScale REST API, allowing clients to see who issued the token. (MXS-4277)

  • Prior to this release, the issuer was maxscale for all tokens.

Logging Improvement

Logging due to log_info no longer results in log entries containing extra newlines that are present in the logged SQL statement. (MXS-4385)

  • Prior to this release, SQL statements were logged verbatim. If the SQL statement contained extra newlines, the log entry would also include those newlines.

  • Starting with this release, newlines are replaced with the text \n so that the log line does not contain extra newlines.

MaxGUI UI Improvement

When adding a new query tab, the new query tab automatically uses the current active database of the current active query tab. (MXS-4364)

Region-Aware Bootstrap for MariaDB Xpand

With Xpand monitor, it is possible to limit the nodes that the monitor dynamically detects to those in a specific region.

  • For additional information, see region_name and region_oid in Xpand monitor documentation.

MariaDB Xpand LDAP Support

In support of LDAP features added in MariaDB Xpand 23.09.1, the MariaDB Authenticator (mariadbauth) includes a passthrough authentication mode.

  • Enabled with authenticator_options=clear_pw_passthrough=true

  • Since passwords are sent in clear-text, the MaxScale listener should be configured for SSL (TLS).

  • For additional information, see MariaDB Authenticator documentation.

Early Connection Metadata

The connection_metadata listener parameter controls the set of metadata variables sent to the client during connection creation. (MXS-4635)

  • By default, the following values are sent:

    • character_set_client system variable

    • character_set_connection system variable

    • character_set_results system variable

    • max_allowed_packet system variable

    • system_time_zone system variable

    • time_zone system variable

    • tx_isolation system variable

    • threads_connected, with the current number of connections

    • connection_id, with the real 64-bit connection ID

  • Compatible MariaDB Connectors will use this information from MaxScale instead of querying the values of the variables from the database server. This will speed up connection creation.

Renamed Features

  • connection_timeout configuration parameter has been renamed to wait_timeout

    • connection_timeout is an alias to wait_timeout

    • The use of the old name (connection_timeout) is deprecated.

  • For readwritesplit router, the max_slave_replication_lag parameter has been renamed to max_replication_lag

    • max_slave_replication_lag is an alias to max_replication_lag

    • The use of the old name (max_slave_replication lag) is deprecated.

Deprecated Features

  • query_classifier configuration parameter is deprecated and ignored.

  • query_classifier_args configuration parameter is deprecated and ignored.

  • strip_db_esc configuration parameter is deprecated.

    • The default behavior of stripping escape characters is in all known cases the correct behavior. This parameter is never required.

Issues Fixed

Can result in unexpected behavior

  • log_throttling is not disabled if log_info is enabled, which can cause omission of log messages. (MXS-4749)

  • Connection IDs are missing from error messages. (MXS-4735)

  • With readwritesplit router, slave_selection_criteria does not accept lowercased versions of enumeration values. (MXS-4724)

  • Graphs in MaxGUI can refresh continually, even when refresh is stopped. (MXS-4477)

Upgrade Notes

  • Before upgrading to MariaDB MaxScale 23.08.1, back up any existing configuration files.


In alignment to the MariaDB Corporation Engineering Policy, MariaDB MaxScale 23.08.5 is provided for:

  • CentOS 7 (x86_64)

  • Debian 10 (x86_64, ARM64)

  • Debian 11 (x86_64, ARM64)

  • Debian 12 (x86_64, ARM64)

  • Red Hat Enterprise Linux 7 (x86_64)

  • Red Hat Enterprise Linux 8 (x86_64, ARM64)

  • Red Hat Enterprise Linux 9 (x86_64, ARM64)

  • Rocky Linux 8 (x86_64, ARM64)

  • Rocky Linux 9 (x86_64, ARM64)

  • SUSE Linux Enterprise Server 15 (x86_64, ARM64)

  • Ubuntu 20.04 (x86_64, ARM64)

  • Ubuntu 22.04 (x86_64, ARM64)