Release Notes for MariaDB MaxScale 22.08.2

Overview

MariaDB MaxScale is an advanced database proxy and query router.

MariaDB MaxScale 22.08.2 was released on 2022-10-20. This release is of General Availability (GA) maturity.

This document describes the changes in MaxScale 22.08.2 when compared to MaxScale 22.08.1.

Notable Changes

  • The Kafka Importer Router (kafkaimporter) can create tables with storage engines other than InnoDB. (MXS-4333)

    • The new engine parameter specifies the name of the storage engine.

    • When the router creates a table, the value of the engine parameter is specified as the ENGINE table option in the CREATE TABLE.

    • When the storage engine is not InnoDB, the table is created without the generated column and the check constraint, because not all storage engines support these InnoDB features.

    • For example, the router creates a table like the following:

      CREATE TABLE IF NOT EXISTS my_table (data JSON NOT NULL) ENGINE=ENGINE_PARAMETER_VALUE;

  • The REST API can authenticate using an OpenID Connect (OIDC) provider. (MXS-4271)

    • The new admin_oidc_url parameter specifies the URL of the OpenID Connect (OIDC) server. The REST API validates JSON Web Tokens (JWTs) at the specified OIDC server:

      • If this parameter is defined, any JWT bearer tokens signed by the OIDC server are accepted as valid bearer tokens for the MaxScale REST API.

      • The "sub" field of the JWT bearer token is assumed to be the username of an administrative user in MaxScale. Before a token can be accepted, a corresponding MaxScale user must be created with the maxctrl create user command.

      • If the OIDC server URL is changed at runtime, new certificates are not be fetched until the maxctrl reload tls command is executed.

    • The new admin_verify_url parameter specifies the URL of a server to which the REST API token verification is delegated. By delegating the authentication and authorization of the REST API to an external server, users can implement custom access control systems for the MaxScale REST API. If the URL is defined, any tokens passed to the REST API will be validated by doing a GET request to the URL with the client's token as a bearer token:

      • The Referrer header of the request is set to the URL being requested by the client.

      • The custom X-Referrer-Method header is set to the HTTP method being used, such as PUT or GET.

      • When admin_verify_url is used and the remote server cannot be accessed, all REST API access that uses tokens will be disabled. The only way to use the REST API with tokens is to remove admin_verify_url from the configuration which requires restarting MaxScale. The REST API still accepts HTTP Basic Access authentication even if the remote server cannot be reached.

  • The output of the maxctrl show maxscale command includes new information about the system. (MXS-4161)

    • The output includes a new System object that contains details about the available resources on the system. The new fields are:

      Field

      Description

      machine.cores_physical

      • Number of physical CPU cores

      machine.cores_available

      • Number of CPU cores available to MaxScale

      • Can be smaller than machine.cores_physical when CPU affinities are used and only a subset of the physical CPU cores are available to MaxScale

      machine.cores_virtual

      • Number of virtual CPU cores available to MaxScale

      • Can be smaller than machine.cores_available when MaxScale is running in a container whose CPU quota and period has been restricted

      • If MaxScale is not running in a container, or fails to detect that it is in a container, the value is identical to machine.cores_available

      machine.memory_physical

      • Amount of physical memory

      machine.memory_available

      • Amount of memory available to MaxScale

      • Can be smaller than machine.memory_physical when MaxScale is running in a container whose memory has been restricted

      • If MaxScale is not running in a container, or fails to detect that it is in a container, the value is identical to machine.memory_physical

      maxscale.query_classifier_cache_size

      • Maximum size of MaxScale's query classifier cache

      maxscale.threads

      • Number of routing threads used by MaxScale

      os

      • Contains details about the operating system provided by the uname command

  • A new causal reads mode for Read/Write Split Router (readwritesplit) allows global causal reads scope without a timeout before routing the statement to the primary server. (MXS-4122)

  • When log_info is enabled, MaxScale logs a message if a server is put into maintenance mode or if the server is drained. (MXS-4044)

    • When a server is put into maintenance mode, the following log message is written:

      Server 'SERVERNAME' is going into maintenance.

    • When a server is removed from maintenance mode, the following log message is written:

      Server 'SERVERNAME' is coming out of maintenance.

    • When a server is being drained, the following log message is written:

      Server 'SERVERNAME' is being drained.

    • When a server is no longer being drained, the following log message is written:

      Server 'SERVERNAME' is no longer being drained.

  • The REST API can be used to monitor memory usage. (MXS-3822)

    • The /maxscale/threads endpoint has been extended, so that the attributes object contains a memory object which contains the following fields:

      • query_classifier is the memory used by the thread-specific query classifier

      • sessions is the memory used by the sessions handled by the thread

      • zombies is the memory used by connections ready to be closed but that have not yet been closed

      • total is the sum of the previous values

    • The new /maxscale/memory endpoint has been implemented and reports the memory usage for the process and separately for each thread.

    • The maxctrl show threads command has also been extended to show memory usage of each thread.

  • The output of the maxctrl show service command has been extended to show the timestamp of the last service reload. (MXS-3649)

  • The output of the maxctrl list servers command has been extended to show the monitors associated with each server. (MXS-3384)

  • With MaxGUI, when data is filtered (such as in the SCHEMAS tree, result table, or other places), the text is highlighted. (MXS-3946)

Issues Fixed

Can result in a hang or crash

Can result in unexpected behavior

  • When MaxScale is configured to use HTTPS and MaxCtrl is executed without the --secure option, the error message is unclear. (MXS-4321)

    • In previous releases, the following error message would be raised:

      Error: socket hang up

    • Starting with this release, the following error message is raised:

      If MaxScale is configured to use HTTPS, use the --secure option.

  • When using MaxCtrl with the MaxScale REST API, if an object name looks like a number, MaxCtrl automatically and incorrectly converts the object name to a number. (MXS-4313)

    • Starting with this release, object names are explicitly converted to strings.

  • The MaxScale REST API accepts empty values for id which allows users to be created with empty names. (MXS-4312)

  • MariaDB Monitor (mariadbmon) spams the log with connection errors if the server is both [Maintenance] and [Down]. (MXS-4304)

  • When the MaxScale REST API generates JWTs (JSON Web Tokens), the aud field is used to store the username instead of the sub field. (MXS-4279)

    • Starting with this release, to retain backwards compatibility with external applications, MaxScale still sets the aud field to the same value as the sub field, but MaxScale no longer reads the username from the aud field.

  • In binary packages, librdkafka is built without SASL support enabled, which impacts the Kafka CDC Router (kafkacdc) and the Kafka Importer Router (kafkaimporter). (MXS-4348)

  • When using the MaxScale REST API, token authentication does not work correctly with PAM users. (MXS-4355)

  • When using the MaxScale REST API, the /maxscale/logs/data endpoint does not filter syslog contents correctly. (MXS-4353)

  • When using MaxGUI, the "History/Snippets" tab does not filter correctly when applied to the action and date columns. (MXS-4338)

  • Although the ssl_ca_cert parameter was deprecated and replaced with the ssl_ca parameter, listeners do not accept the new parameter name. (MXS-4325)

  • When using MaxGUI, the "Preview Data" tab shows 2 execution times. (MXS-4316)

  • When a query executes the CONVERT() function, the parser used by MaxScale's query classifier does not recognize the function's data type parameter, which can cause the query to be incorrectly classified and routed. (MXS-4307)

  • When using MaxGUI, the "Disconnect" button in the reconnection dialog doesn't close the connection bound to the worksheet. (MXS-4303)

  • When using MaxGUI with multiple "Query" tabs open, if a tab with unsaved changes is closed and the user chooses to save the unsaved changes using the dialog box, the changes from the current active tab are saved, rather than the changes from the closed tab. (MXS-4299)

  • When a switchover is requested with MariaDB Monitor (mariadbmon), the monitor waits for replica (slave) servers to catch up if all replica servers are lagging more than the value of the switchover_timeout parameter. (MXS-4295)

    • Starting with this release, MariaDB Monitor refuses to perform a switchover when all replica servers are lagging more than the value of the switchover_timeout parameter.

  • When the Read/Write Split Router (readwritesplit) is used with causal_reads=universal configured, a memory leak occurs. (MXS-4293)

  • When the Read/Write Split Router (readwritesplit) is used with causal_reads=universal configured, read-only transactions are not synchronized. (MXS-4292)

  • When the Masking Filter (masking) is configured, the filter fails to parse a SELECT statement with a WHERE clause that contains more than 1000 comparisons. (MXS-4290)

    • In previous releases, the following error was raised:

      Error : (conn=65) The statement could not be fully parsed and will hence be rejected (masking filter)

    • Starting with this release, the default maximum expression depth has been changed from 1000 to 4096.

  • When autocommit is disabled and a session command fails, the session command is automatically retried, but the transaction started by the session command could be started on the replica server or executed twice before the transaction is migrated to the primary server. (MXS-4289)

  • With MaxGUI, the query editor connections are not bound to the "Query" tabs properly. If there are multiple "Query" tabs open, the active tab may not use the expected connection. (MXS-4281)

  • When a query contains a LIMIT clause, the parser used by MaxScale's query classifier expects an IN clause to follow the LIMIT. (MXS-4280)

    • In previous releases, the following warning was raised:

      warning: (4) [qc_sqlite] The function 'in' is not found in the canonical statement 'DELETE FROM tab LIMIT ?' created from the statement 'DELETE FROM tab LIMIT 100'.

  • When using MaxGUI, the current connection name in the dropdown disappears when a new connection fails to connect. (MXS-4278)

  • When using MaxGUI, users that are not INET users (such as PAM users) are redirected to a non-existent page at login, which results in a 404 error code. (MXS-4253)

  • When using MaxGUI, the "Stop" button does not always stop the query and can cause the Query Editor to use a lot of memory. (MXS-4251)

Interface Changes

Removals and Deprecations

Platforms

In alignment to the MariaDB Corporation Engineering Policy, MariaDB MaxScale 22.08.2 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)