Release Notes for MariaDB MaxScale 22.08.1
This page is part of MariaDB's Documentation.
The parent of this page is: Release Notes for MariaDB MaxScale 22.08
Topics on this page:
Overview
MariaDB MaxScale is an advanced database proxy and query router.
MariaDB MaxScale 22.08.1 was released on 2022-09-12. This release is of General Availability (GA) maturity.
This document describes the changes in MaxScale 22.08.1
when compared to MaxScale 6.4.2
.
Release Versioning Change
Starting with the 22.08 release series, a YY.MM.PATCH
numbering scheme is used:
YY
- year when the release series was createdMM
- month when the release series was createdPATCH
- number of the maintenance release, starting with0
, and incremented for each maintenance release on that series
The prior release series was MaxScale 6.
Major Changes
Logging Behavior
Default logging behavior has changed: (MXS-4192)
Prior to this release, by default MaxScale logs to
syslog
in addition to the MaxScale log.Starting with this release, by default MaxScale only logs to the MaxScale log and no longer logs to
syslog
.To retain the behavior of prior releases, in your MaxScale configuration, under the
[maxscale]
section, specifysyslog=true
:[maxscale] syslog=true
Group Change Handling with Xpand Monitor (xpandmon
)
Xpand Monitor (
xpandmon
) handles Xpand Group Changes explicitly. (MXS-3490)Prior to this release, Xpand Monitor treats Group Change errors in the same way as any other error, so the monitor would abandon the current node and try to connect to other nodes. Xpand Monitor would repeatedly attempt to connect to nodes at regular intervals until the Group Change ended.
Starting with this release, Xpand Monitor detects when a monitor operation fails due to a Group Change. Xpand Monitor sets the state of all nodes to "Down" until the Group Change is completed to prevent other components (such as routers) from attempting to take corrective action before the Group Change really is over. During the Group Change, the monitor will not log errors related to it not being able to connect to Xpand, as that is to be expected until the Group Change is over.
When a Group Change begins, the monitor writes the following message to the MaxScale log:
Group change detected.
When a query is executed during a Group Change and
log_info
is enabled, the monitor writes the following message to the MaxScale log:MONITOR_NAME: Group Change detected on NODE_NAME: NODE_QUERY_RESPONSE_TEXT
When a Group Change finishes, the monitor writes the following message to the MaxScale log:
Group change now finished.
Rebuild Server with MariaDB Monitor (mariadbmon
)
MariaDB Monitor (
mariadbmon
) can use MariaDB Enterprise Backup (mariadb-backup
) to clone the contents of a server. (MXS-2542)The rebuild operation is a monitor module command that can be launched with MaxCtrl
The rebuild operation replaces the contents of a database server with the contents of another server.
MariaDB Monitor performs this operation by running MariaDB Enterprise Backup on both the source and target servers using SSH.
For example, to rebuild a replica node, execute
maxctrl call command mariadbmon async-rebuild-server
:maxctrl call command mariadbmon async-rebuild-server MONITOR_NAME TARGET_NODE [ SOURCE_NODE ]
Replace
MONITOR_NAME
with the name of the monitor.Replace
TARGET_NODE
with the name of the target node.Optionally, replace
SOURCE_NODE
with the name of the source node. If the source node is not specified, then a source node is auto-selected. When auto-selecting, the monitor prefers to pick an up-to-date replica server.
For additional information, see "
".
ColumnStore Commands with MariaDB Monitor (mariadbmon
)
MariaDB Monitor (
mariadbmon
) can execute commands for MariaDB Enterprise ColumnStore. (MXS-3217)MariaDB Monitor can fetch cluster status, add and remove nodes, start and stop the cluster, and set the cluster read-only or read-write.
To execute the commands, execute
maxctrl call command mariadbmon COMMAND_NAME PARAMETERS
For additional information, see "MariaDB Monitor: ColumnStore Commands".
MaxGUI Enhancements
Support has been added to MaxGUI for:
ColumnStore operations (MXS-3216)
Drag and drop control of replication (MXS-3642)
Killing a session (MXS-4087)
Managing MaxScale users (updating, adding, deleting MaxScale users) (MXS-3853)
Multiple query tabs within the Worksheet, so multiple queries can be run from one worksheet (MXS-4025)
Saving and editing .sql files in the Query Editor (MXS-3723)
Showing filter diagnostics (MXS-4167)
Storing queries as snippets in the Query Editor (MXS-3725)
Additionally, the MaxGUI user interface has been enhanced:
Dynamic Reload of SSL/TLS Certificates
SSL/TLS certificates can be updated without server restart: (MXS-3982, MXS-4041)
The new
maxctrl reload tls
command reloads the TLS certificates of servers, listeners, and the REST API.Prior to this release, changes to certificates required restart of MaxScale.
Avrorouter Changes
Automatic Purge
Avrorouter (
avrorouter
) can automatically purge old files. (MXS-4010)The
max_data_age
parameter has been added to configure this functionality. The parameter can be set to a time duration.The default value for the
max_data_age
parameter is0s
(0 seconds), which means that old files are not automatically purged.When the
max_data_age
parameter is set to a duration greater than0s
(0 seconds), the Avrorouter (avrorouter
) will automatically purge any files that only have data that is older than the specified duration. This means that all data files with at least one event that is newer than the configured limit will not be removed, even if the ages of all the other events are above the limit.Purge operations are only done when a file rotation takes place (either manual or automatic) or when a schema change is detected.
MariaDB recommends configuring the
max_data_age
andmax_file_size
parameters together to provide automatic removal of stale data.Automatic file purging only works with the direct replication mode. The legacy file based replication mode does not support this.
File Rotation
Avrorouter (
avrorouter
) can automatically rotate files based on file size. (MXS-4010)The
max_file_size
parameter can be used to configure this functionality. This parameter can be set to a file size limit.The default value for the
max_file_size
parameter is0
, which means that files are not automatically rotated based on file size.When the size of a single Avro data file exceeds the configured value of the
max_file_size
parameter, the Avrorouter (avrorouter
) rotates the file and creates a new file. This is done by closing the existing file and creating a new one with the next version number. This uses the size of the file as reported by the operating system. The check for the file size is done after a transaction has been processed which means that large transactions can still cause the file size to exceed the given limit.File rotation only works with the direct replication mode. The legacy file based replication mode does not support this.
Configuration Auto Tuning
MaxScale can automatically tune the value of some MaxScale parameters based on the values of server-side settings. (MXS-3398)
The
auto_tune
parameter can be used to configure this functionality. This parameter can be set to'all'
to automatically tune all supported parameters or to a comma-separated list of MaxScale parameters to automatically tune.The current auto-tunable parameters are:
MaxScale Parameter
Server-side Dependency
connection_keepalive
80% of the smallest
wait_timeout
value of the servers used by the serviceconnection_timeout
The smallest
wait_timeout
value of the servers used by the serviceThe values of the server system variables are collected by monitors, which means that if the servers of a service are not monitored by a monitor, then the parameters of that service will not be auto-tuned.
Even if
auto_tune
is set to'all'
, the auto tunable parameters can still be set in the configuration file and modified withmaxctrl
. However, the specified value will be overwritten at the next auto-tuning round, but only if the servers of the service are monitored by a monitor.
Read/Write Split Router (readwritesplit
)
Causal Reads
Support added for causal reads in a multi-MaxScale environment using the Read/Write Split Router (
readwritesplit
) with thecausal_reads
parameter.Previous releases supported causal reads only in a single MaxScale environment. (MXS-3663)
For additional information, see "Ensuring Causal Consistency with MaxScale's Read/Write Split Router".
Kafka CDC Router (kafkacdc
)
Disable JSON Schema Updates
Kafka CDC Router (
kafkacdc
) can be configured to skip sending schema updates. (MXS-4052)The
send_schema
parameter can be used to configure this functionality.The default value for the
send_schema
parameter istrue
, which means that a JSON schema object is sent in the stream whenever the table schema changes.When the
send_schema
parameter isfalse
, a JSON schema object is not sent in the stream whenever the table schema changes.
Configuration Synchronization
MaxScale synchronizes additional details between MaxScale nodes when
config_sync_cluster
is configured. (MXS-3619)When a server is changed to the
Maintenance
orDrain
states, the state change is synchronized to other MaxScale nodes.When administrative users are changed, the change is synchronized to other MaxScale nodes.
NoSQL Listener (nosqlprotocol
)
Multi-MaxScale
The
nosqlprotocol
protocol module can be used in a multi-MaxScale setup. (MXS-4145)
Implicit Bootstrapping
The
nosqlprotocol
protocol module can optionally create a default NoSQL user at startup. (MXS-4242)Starting with this release, authentication and authorization for NoSQL Listeners can be implicitly bootstrapped.
Implicit bootstrapping occurs at startup when there are no NoSQL users in the account database, and the following parameters are configured:
Authentication and authorization are configured by setting the
nosqlprotocol.authentication_required
andnosqlprotocol.authorization_enabled
parameters totrue
The database user account for authentication and authorization is configured by setting the
nosqlprotocol.user
andnosqlprotocol.password
parametersFor example, the following example configuration shows the parameters required for implicit bootstrapping:
[SERVICE_NAME] type=service ... [LISTENER_NAME] type=listener service=SERVICE_NAME protocol=nosqlprotocol port=17017 nosqlprotocol.authentication_required=true nosqlprotocol.authorization_enabled=true nosqlprotocol.user=USER_NAME nosqlprotocol.password=USER_PASSWORD
When implicit bootstrapping occurs at startup, the
nosqlprotocol
protocol module performs the following procedure:The
nosqlprotocol
protocol module waits until the primary server used by the service linked to the NoSQL Listener is available.The
nosqlprotocol
protocol module connects to the primary server using the database user account specified by thenosqlprotocol.user
andnosqlprotocol.password
parameters.The
nosqlprotocol
protocol module executes to determine the user account's database privileges.The
nosqlprotocol
protocol module translates the user account's database privileges into the equivalent NoSQL role.The
nosqlprotocol
protocol module creates a NoSQL user in the account database.
After implicit bootstrapping occurs, the credentials specified by the
nosqlprotocol.user
andnosqlprotocol.password
parameters can be used to connect to the NoSQL Listener. Thenosqlprotocol
protocol module only uses thenosqlprotocol.user
andnosqlprotocol.password
parameters during implicit bootstrapping, so they can be removed from the configuration after bootstrapping has occurred.
Proxy Protocol
When
proxy_protocol
is enabled, more MaxScale components use the proxy protocol when they internally open a connection to a server. (MXS-4067)This includes, but is not limited to, the following MaxScale components:
Query Log All Filter (qlafilter
)
The
log_data
parameter supports theserver
value. (MXS-2882)When using the Query Log All filter (
qlafilter
), setting thelog_data
parameter tolog_data=server
logs the server where a query was routed.
REST API Endpoints
The
/v1/maxscale/tasks/
endpoint has been removed from the REST API.
Routing Threads Maximum
The maximum number of routing threads has been increased to 256. The maximum in previous versions was 100. (MXS-3605)
To set the number of routing threads, use the
threads
parameter.
MaxCtrl Command Changes for Session Handling
Destroy Session
The new
maxctrl destroy-session
command is available for killing a session. (MXS-3152)The new command requires the session ID to be specified. The session ID can be obtained using
maxctrl list sessions
.Prior to this release, to kill a session, a direct connection to the database must be made, and the
statement must be executed.
Memory Usage
The
maxctrl list sessions
andmaxctrl show session
commands provide information about the memory usage of a session. (MXS-2724)Prior to this release, the commands provide no memory usage information.
Starting with this release, the commands provide information that can be used for detecting anomalous behavior.
Example output:
├───────────────────┼──────────────────────────────────┤ │ Memory │ { │ │ │ "connection_buffers": 67226, │ │ │ "last_queries": 0, │ │ │ "session_history": 774, │ │ │ "total": 68000, │ │ │ "variables": 0 │ │ │ } │ └───────────────────┴──────────────────────────────────┘
Reload
The new
maxctrl reload session
andmaxctrl reload sessions
commands are available to reload existing sessions. (MXS-2347)Session reload enables an existing session to use servers added since the session was started. By default, sessions use servers present at the time the session was started. With this feature, sessions for long-running client connections can use servers added since the session was started.
maxctrl reload session SESSION_ID
reloads the session with the specified session ID.maxctrl reload sessions
reloads all sessions.
Rewrite Filter (rewritefilter
)
rewritefilter
is a new Filter that rewrites queries based on a query template. (MXS-3394)The rewrite rules can be made using a template file that can be in rewrite-file format (
rf
) or JSON file format.For example, the rewrite-file format (
rf
) can look like the following:%% # This is a comment line. # Add options in the form "name: value" here regex_grammar: Native ignore_whitespace: true % match text % replace text
And the JSON file format can look like the following:
{ "templates": [ { "regex_grammar": "Native", "ignore_whitespace": true, "match_template": "match text", "replace_template": "replace text" } ] }
For additional information, see "MaxScale Rewrite Filter".
User Management
Listing users with
maxctrl list users
and/or with the REST API shows creation date, last password update, and last login in the output.Users created in previous versions of MaxScale will show empty values for timestamps that aren't found.
The last login timestamp isn't stored on disk, so it shows the values at the last restart of MaxScale. (MXS-3912)
Removals and Deprecations
Database Firewall Filter (dbfwfilter
) Removal
Previously deprecated in MaxScale 6, the Database Firewall Filter (
dbfwfilter
) has been removed in MaxScale 22.08.
Removed Parameters
The following MariaDB Monitor (mariadbmon
) parameters have been removed:
Parameter | Notes |
---|---|
| Removed |
| Removed |
| Removed |
| Removed, replaced by |
| Removed, replaced by |
Deprecated Parameters
Old parameter | New parameter | Notes |
---|---|---|
| ||
|
Platforms
In alignment to the MariaDB Corporation Engineering Policy, MariaDB MaxScale 22.08.1 is provided for:
CentOS 7 (x86_
64) Debian 9 (x86_
64, ARM64) Debian 10 (x86_
64, ARM64) Debian 11 (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 18.04 (x86_
64, ARM64) Ubuntu 20.04 (x86_
64, ARM64) Ubuntu 22.04 (x86_
64, ARM64)