Release Notes for MariaDB MaxScale 22.08.1

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 created

  • MM - month when the release series was created

  • PATCH - number of the maintenance release, starting with 0, 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, specify syslog=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 "Rebuild a Replica Node with MariaDB Enterprise Server".

ColumnStore Commands with MariaDB Monitor (mariadbmon)

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:

  • The user interface indicates when operations are unavailable due to lack of privileges. (MXS-3783)

  • A "Stop Query" button is included in the Query Editor. (MXS-3918)

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 is 0s (0 seconds), which means that old files are not automatically purged.

  • When the max_data_age parameter is set to a duration greater than 0s (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 and max_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 is 0, 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 service

    connection_timeout

    The smallest wait_timeout value of the servers used by the service

  • The 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 with maxctrl. However, the specified value will be overwritten at the next auto-tuning round, but only if the servers of the service are monitored by a monitor.

Read/Write Split Router (readwritesplit)

Causal Reads

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 is true, which means that a JSON schema object is sent in the stream whenever the table schema changes.

  • When the send_schema parameter is false, 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 or Drain 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

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 and nosqlprotocol.authorization_enabled parameters to true

    • The database user account for authentication and authorization is configured by setting the nosqlprotocol.user and nosqlprotocol.password parameters

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

    1. The nosqlprotocol protocol module waits until the primary server used by the service linked to the NoSQL Listener is available.

    2. The nosqlprotocol protocol module connects to the primary server using the database user account specified by the nosqlprotocol.user and nosqlprotocol.password parameters.

    3. The nosqlprotocol protocol module executes SHOW GRANTS to determine the user account's database privileges.

    4. The nosqlprotocol protocol module translates the user account's database privileges into the equivalent NoSQL role.

    5. The nosqlprotocol protocol module creates a NoSQL user in the account database.

  • After implicit bootstrapping occurs, the credentials specified by the nosqlprotocol.user and nosqlprotocol.password parameters can be used to connect to the NoSQL Listener. The nosqlprotocol protocol module only uses the nosqlprotocol.user and nosqlprotocol.password parameters during implicit bootstrapping, so they can be removed from the configuration after bootstrapping has occurred.

Proxy Protocol

Query Log All Filter (qlafilter)

  • The log_data parameter supports the server value. (MXS-2882)

  • When using the Query Log All filter (qlafilter), setting the log_data parameter to log_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 KILL statement must be executed.

Memory Usage

  • The maxctrl list sessions and maxctrl 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

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

ignore_external_masters

Removed

detect_replication_lag

Removed

detect_standalone_master

Removed

detect_stale_master

Removed, replaced by master_conditions

detect_stale_slave

Removed, replaced by slave_conditions.

Deprecated Parameters

Old parameter

New parameter

Notes

admin_ssl_ca_cert

admin_ssl_ca

admin_ssl_ca_cert is an alias for admin_ssl_ca. admin_ssl_ca_cert is deprecated and will be dropped in the future.

ssl_ca_cert

ssl_ca

ssl_ca_cert is an alias for ssl_ca. ssl_ca_cert is deprecated and will be dropped in the future.

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)