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 or use the interface.

Bugs can be reported in the MariaDB Jira

Installing MariaDB MaxScale

Information about installing MariaDB MaxScale, either from a repository or by building from source code, is included in the .

The same guide also provides basic information on running MariaDB MaxScale. More detailed information about configuring MariaDB MaxScale can be found in the .

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

About MariaDB MaxScale

• About MariaDB MaxScale

• Changelog

Getting Started

Upgrading MariaDB MaxScale

Reference

Tutorials

The main tutorial for MariaDB MaxScale consist of setting up MariaDB MaxScale for the environment you are using with either a connection-based or a read/write-based configuration.

These tutorials are for specific use cases and module combinations.

Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments.

Routers

The routing module is the core of a MariaDB MaxScale service. The router documentation contains all module specific configuration options and detailed explanations of their use.

The following routers are only available in MaxScale Enterprise.

Filters

Here are detailed documents about the filters MariaDB MaxScale offers. They contain configuration guides and example use cases. Before reading these, you should have read the filter tutorial so that you know how they work and how to configure them.

The following filters are only available in MaxScale Enterprise.

Monitors

Common options for all monitor modules.

Module specific documentation.

Protocols

Documentation for MaxScale protocol modules.

The MaxScale CDC Connector provides a C++ API for consuming data from a CDC system.

Authenticators

A short description of the authentication module type can be found in the document.

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

Refer to the documentation for the MaxScale hint syntax.

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

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.

clear_pw_passthrough

Boolean, default value is "false". Activates passthrough-mode. In this mode, MaxScale does not check client credentials at all and defers authentication to the backend server. This feature is primarily meant to be used with Xpand LDAP- authentication, although it may be useful in any situation where MaxScale cannot check the existence of client user account nor authenticate the client.

When a client connects to a listener with this setting enabled, MaxScale will change authentication method to "mysql_clear_password", causing the client to send their cleartext password to MaxScale. MaxScale will then attempt to use the password to authenticate to backends. The authentication result of the first backend to respond will be sent to the client. The backend may ask MaxScale for either cleartext password or standard ("mysql_native_password") authentication token. MaxScale can work with both backend plugins since it has the original password.

This feature is incompatible with service setting lazy_connect. Either leave it unspecified or set lazy_connect=false in the linked service. Also, multiple client authenticators are not allowed on the listener when passthrough-mode is on.

Because passwords are sent in cleartext, the listener should be configured for ssl.

log_password_mismatch

• Type:

• 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}

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.

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

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

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

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

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

The mariadbprotocol module implements the MariaDB client-server protocol.

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

This page has moved .

Note: The password encryption format changed in MaxScale 2.5. All encrypted passwords created with MaxScale 2.4 or older need to be re-encrypted.

There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys, use the maxkeys command.

By default the key file will be generated in /var/lib/maxscale. If a different directory is required, it can be given as the first argument to the program. For more information, see maxkeys --help.

Once the keys have been created the maxpasswd command can be used to generate the encrypted password.

The username and password, either encrypted or plain text, are stored in the service section using the user and

This document describes how to configure a MariaDB primary-replica cluster monitor to be used with MaxScale.

Configuring the Monitor

Define the monitor that monitors the servers.

The mandatory parameters are the object type, the monitor module to use, the list of servers to monitor and the username and password to use when connecting to the servers. The monitor_interval parameter controls for how long the monitor waits between each monitoring loop.

The C++ connector for the MariaDB MaxScaleCDC 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 that demonstrates basic usage of the MaxScale CDC Connector.

Dependencies

The CDC connector depends on:

• OpenSSL

RHEL/CentOS 7

Debian Stretch and Ubuntu Xenial

Debian Jessie

openSUSE Leap 42.3

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}

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}

Register as a client to the service.

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}

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

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 the_my_simple_cmd_ contains the parsed arguments received from the caller of the command.

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

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:

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 replica servers a session should attempt to connect to. Having less replicas defined in the services and/or less successful connections during session creation is not an error. The router will attempt to distribute replicas evenly between sessions by assigning them in a round robin fashion. The session will always try to connect to a primary 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 replicas.

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 primary 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}

This document describes how to configure a Galera cluster monitor.

Configuring the Monitor

Define the monitor that monitors the servers.

[Galera-Monitor]
type=monitor
module=galeramon
servers=dbserv1, dbserv2, dbserv3
user=monitor_user
password=my_password
monitor_interval=2000ms

The mandatory parameters are the object type, the monitor module to use, the list of servers to monitor and the username and password to use when connecting to the servers. The monitor_interval parameter controls for how long the monitor waits between each monitoring loop.

This monitor module will assign one node within the Galera Cluster as the current primary and other nodes as replica. Only those nodes that are active members of the cluster are considered when making the choice of primary node. The primary node will be the node with the lowest value of wsrep_local_index.

Monitor User

The monitor user does not require any special grants to monitor a Galera cluster. To create a user for the monitor, execute the following SQL.

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

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}

Maxrows

This filter was introduced in MariaDB MaxScale 2.1.

This filter was added in MariaDB MaxScale 2.3

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

The goal of this tutorial is to configure a system that appears to the client as a single database. MariaDB MaxScale will split the statements such that write statements are sent to the primary server and read statements are balanced across the replica servers.

Setting up MariaDB MaxScale

This tutorial is a part of . Please read it and follow the instructions. Return here once basic setup is complete.

The first step is to define the servers that make up the cluster. These servers will be used by the services and are monitored by the monitor.

The address and port parameters tell where the server is located.

Enabling TLS

To enable encryption for the MaxScale-to-MariaDB communication, add ssl=true to the server section. To enable server certificate verification, addssl_verify_peer_certificate=true

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.

• Limitations and Known Issues within MariaDB MaxScale

  • Configuration limitations

    • Multiple MaxScales on same server

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 limitations

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

Transaction Boundary Detection

If a module in MaxScale requires tracking of transaction boundaries but does not require query classification, a custom parser is used to detect them. Currently the only situation in which this parser is used is when a readconnroute service uses the cache filter.

The custom parser detects a subset of the full SQL syntax used to start transactions. This means that more complex statements will not be fully parsed and will cause the transaction state to not match the real state on the database. For example, SET @my_var = (SELECT 1), autocommit = 0 is not parsed by the custom parser and causes the autocommit modification to not be noticed.

XA Transactions

MaxScale will treat statements executed after XA START and before XA END as if they were executed in a normal read-write transaction started with START TRANSACTION. This means that only XA transactions in the ACTIVE state will be routed as transactions and all statements after XA END are routed normally.

XA transactions and normal transactions are mutually exclusive in MariaDB. This means that a START TRANSACTION command will fail if the connection already has an open XA transaction. MaxScale currently only inspects the SQL and deduces the transaction state from that. If a transaction fails to start due to an open XA transaction, the state in MaxScale and in MariaDB can be different and MaxScale will keep routing statements as if they were inside of a transaction. However, as this is an unlikely scenario, usually no action needs to be taken.

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

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

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.

ETL Limitations

The ETL feature in MaxScale always uses the MariaDB Connector/ODBC driver to perform the data loading into MariaDB. The recommended minimum version of the connector is 3.1.18. Older versions of the driver suffer from problems that may manifest as crashes or memory leaks. The driver must be installed on the system in order for the ETL feature to work.

The data loading into MariaDB is done with autocommit, unique_checks andforeign_key_checks disabled inside of a single transaction. This is done to leverage the optimizations done for InnoDB that allows faster insertions into empty tables. When loading data into MariaDB versions 10.5 or older, this can translate into long rollback times in case the ETL operation fails.

ETL Limitations with PostgreSQL as the Source

For ETL operations that migrate data from PostgreSQL, we recommend using the official PostgreSQL ODBC driver. Use of other PostgreSQL ODBC drivers is possible but not recommended: correct configuration of the driver is necessary to prevent the driver from consuming too much memory.

Limitations in Automatic SQL Generation

• Triggers on tables are not migrated automatically.

• Check constraints are defined using the native PostgreSQL syntax. Incompatibilities must be manually fixed.

• All indexes specific to PostgreSQL will be converted into normal indexes in MariaDB.

• The GEOMETRY type is assumed to be the type provided by PostGIS. It is converted into a MariaDB GEOMETRY

ETL Limitations with Generic ODBC Targets

It is the responsibility of the end-user to correctly configure the ODBC driver. Some drivers read the whole resultset into memory by default which will result in MaxScale running out of memory

• ETL operations that operate on more than one catalog are not supported.

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

This filter was introduced in MariaDB MaxScale 2.3.0.

• Binlog Filter

  • Overview

  • Configuration

Overview

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

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

• OpenSSL version 1.0.1 or later

• GNUTLS

• Node.js 14 or newer for building MaxCtrl and the GUI (webpack), Node.js 10 or newer for running MaxCtrl

• PAM

• SASL2 (cyrus-sasl)

• SQLite3 version 3.3 or later

• Tcl

• git

• jansson

• libatomic

• libcurl

• libmicrohttpd

• libuuid

• libxml2

• libssh

• pcre2

• zstd

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)

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.

Required Packages

For a definitive list of packages, consult the 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).

Note: You can look into 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 invocation. 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.

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}

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

• unixODBC

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:

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:

and make maxscale the owner of them:

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 for details.

When the configuration file has been created, MariaDB MaxScale can be started.

The -d flag causes maxscale not to turn itself into a daemon, which is advisable 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.

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.

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 for details.

When the configuration file has been created, MariaDB MaxScale can be started.

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

to find out the appropriate flags.

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

• MariaDB MaxScale MaxGUI Guide

• Introduction

• Enabling MaxGUI

Introduction

MaxGUI is a browser-based interface for MaxScale REST-API and query execution.

Enabling MaxGUI

To enable MaxGUI in a testing mode, add admin_host=0.0.0.0 andadmin_secure_gui=false under the [maxscale] section of the MaxScale configuration file. Once enabled, MaxGUI will be available on port 8989:http://127.0.0.1:8989/

Securing the GUI

To make MaxGUI secure, set admin_secure_gui=true and configure both theadmin_ssl_key and admin_ssl_cert parameters.

See and for instructions on how to harden your MaxScale installation for production use.

Authentication

MaxGUI uses the same credentials as maxctrl. The default username is admin with mariadb as the password.

Internally, MaxGUI uses as the authentication method for persisting the user's session. If the Remember me checkbox is ticked, the session will persist for 24 hours. Otherwise, the session will expire as soon as MaxGUI is closed.

To log out, simply click the username section in the top right corner of the page header to access the logout menu.

Pages

Dashboard

This page provides an overview of MaxScale configuration which includes Monitors, Servers, Services, Sessions, Listeners, and Filters.

By default, the refresh interval is 10 seconds.

Detail

This page shows information on each and allow to edit its parameter, relationships and perform other manipulation operations.

Access this page by clicking on the MaxScale object name on the

Visualization

This page visualizes MaxScale configuration and clusters.

• Configuration: Visualizing MaxScale configuration.

• Cluster: Visualizing a replication cluster into a tree graph and provides manual cluster manipulation operations such asswitchover, reset-replication, release-locks, failover, rejoin . At the moment, it supports only servers monitored by Monitor using module.

Access this page by clicking the graph icon on the sidebar navigation.

Settings

This page shows and allows editing of MaxScale parameters.

Access this page by clicking the gear icon on the sidebar navigation.

Logs Archive

Realtime MaxScale logs can be accessed by clicking the logs icon on the sidebar navigation.

Workspace

The "Workspace" page offers a versatile set of tools for effectively managing data and database interactions. It includes the following key tasks:

1. Run Queries

Execute queries on various servers, services, or listeners to retrieve data and perform database operations. Visualize query results using different graph types such as line, bar, or scatter graphs. Export query results in formats like CSV or JSON for further analysis and sharing.

2. Data Migration

The "Data Migration" feature facilitates seamless transitions from PostgreSQL to MariaDB. Transfer data and database structures between the two systems while ensuring data integrity and consistency throughout the process.

3. Create an ERD

Generating Entity-Relationship Diagrams (ERDs) to gain insights regarding data structure, optimizing database design for both efficiency and clarity.

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

The goal of this tutorial is to configure a system that has two ports available, one for write connections and another for read connections. The read connections are load- balanced across replica servers.

Setting up MariaDB MaxScale

This tutorial is a part of the MariaDB MaxScale Tutorial. Please read it and follow the instructions. Return here once basic setup is complete.

Configuring services

We want two services and ports to which the client application can connect. One service routes client connections to the primary server, the other load balances between replica servers. To achieve this, we need to define two services in the configuration file.

Create the following two sections in your configuration file. The section names are the names of the services and should be meaningful. For this tutorial, we use the names_Write-Service_ and Read-Service.

router defines the routing module used. Here we use readconnroute for connection-level routing.

A service needs a list of servers to route queries to. The server names must match the names of server sections in the configuration file and not the hostnames or addresses of the servers.

The router_options-parameter tells the readconnroute-module which servers it should route a client connection to. For the write service we use the master-type and for the read service the slave-type.

The user and password parameters define the credentials the service uses to populate user authentication data. These users were created at the start of the .

For increased security, see .

Configuring the Listener

To allow network connections to a service, a network ports must be associated with it. This is done by creating a separate listener section in the configuration file. A service may have multiple listeners but for this tutorial one per service is enough.

The service parameter tells which service the listener connects to. For the_Write-Listener_ we set it to Write-Service and for the Read-Listener we set it to Read-Service.

A listener must define the network port to listen on.

The optional address-parameter defines the local address the listener should bind to. This may be required when the host machine has multiple network interfaces. The default behavior is to listen on all network interfaces (the IPv6 address ::).

Starting MariaDB MaxScale

For the last steps, please return to .

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

This filter was introduced in MariaDB MaxScale 2.1.

This document provides an overview of the readconnroute router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions.

This filter adds routing hints to a service. The filter has no parameters.

• Hintfilter

• Hint Syntax

  • Comments and comment types

Hint Syntax

Note: If a query has more than one comment only the first comment is processed. Always place any MaxScale related comments first before any other comments that might appear in the query.

Comments and comment types

The client connection will need to have comments enabled. For example themariadb and mysql command line clients have comments disabled by default and they need to be enabled by passing the --comments or -c option to it. Most, if not all, connectors keep all comments intact in executed queries.

For comment types, use either -- (notice the whitespace after the double hyphen) or # after the semicolon or /* ... */ before the semicolon.

Inline comment blocks, i.e. /* .. */, do not require a whitespace character after the start tag or before the end tag but adding the whitespace is advised.

Hint body

All hints must start with the maxscale tag.

The hints have two types, ones that define a server type and others that contain name-value pairs.

Routing destination hints

These hints will instruct the router to route a query to a certain type of a server.

Route to primary

A master value in a routing hint will route the query to a primary server. This can be used to direct read queries to a primary server for a up-to-date result with no replication lag.

Route to replica

A slave value will route the query to a replica server. Please note that the hints will override any decisions taken by the routers which means that it is possible to force writes to a replica server.

Route to named server

A server value will route the query to a named server. The value of<server name> needs to be the same as the server section name in maxscale.cnf. If the server is not used by the service, the hint is ignored.

Route to last used server

A last value will route the query to the server that processed the last query. This hint can be used to force certain queries to be grouped to the same server.

Name-value hints

These control the behavior and affect the routing decisions made by the router. Currently the only accepted parameter is the readwritesplit parametermax_slave_replication_lag. This will route the query to a server with a lower replication lag than this parameter's value.

Hint stack

Hints can be either single-use hints, which makes them affect only one query, or named hints, which can be pushed on and off a stack of active hints.

Defining named hints:

Pushing a hint onto the stack:

Popping the topmost hint off the stack:

You can define and activate a hint in a single command using the following:

You can also push anonymous hints onto the stack which are only used as long as they are on the stack:

Prepared Statements

The hintfilter supports routing hints in prepared statements for both thePREPARE and EXECUTE SQL commands as well as the binary protocol prepared statements.

Binary Protocol

With binary protocol prepared statements, a routing hint in the prepared statement is applied to the execution of the statement but not the preparation of it. The preparation of the statement is routed normally and is sent to all servers.

For example, when the following prepared statement is prepared with the MariaDB Connector-C function mariadb_stmt_prepare and then executed withmariadb_stmt_execute the result is always returned from the primary:

Support for binary protocol prepared statements was added in MaxScale 6.0 ().

The protocol commands that the routing hints are applied to are:

• COM_STMT_EXECUTE

• COM_STMT_BULK_EXECUTE

• COM_STMT_SEND_LONG_DATA

• COM_STMT_FETCH

Support for direct execution of prepared statements was added in MaxScale 6.2.0. For example the MariaDB Connector-C uses direct execution whenmariadb_stmt_execute_direct is used.

Text Protocol

Text protocol prepared statements (i.e. the PREPARE and EXECUTE SQL commands) behave differently. If a PREPARE command has a routing hint, it will be routed according to the routing hint. Any subsequent EXECUTE command will not be affected by the routing hint in the PREPARE statement. This means they must have their own routing hints.

The following example is the recommended method of executing text protocol prepared statements with hints:

The PREPARE is routed normally and will be routed to all servers. TheEXECUTE will be routed to the primary as a result of it having the route to master hint.

Examples

Routing SELECT queries to primary

In this example, MariaDB MaxScale is configured with the readwritesplit router and the hint filter.

Behind MariaDB MaxScale is a primary server and a replica server. If there is replication lag between the primary and the replica, read queries sent to the replica might return old data. To guarantee up-to-date data, we can add a routing hint to the query.

The first INSERT query will be routed to the primary. The following SELECT query would normally be routed to the replica but with the added routing hint it will be routed to the primary. This way we can do an INSERT and a SELECT right after it and still get up-to-date data.

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

• Regex Filter

  • Overview

  • Configuration

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

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 cannot 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}

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.

• Transaction Performance Monitoring Filter

  • Overview

  • Configuration

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.

Filter Options

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:

<timestamp> | <server_name> | <user_name> | <latency of the transaction> | <latencies of individual statements in the transaction> (delimited by 'query_delimiter') | <actual SQL statements>

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}

There are five main components that you need to make sure are completed before you go into production:

• Encrypting Plaintext Passwords

• Securing the GUI Interface

• Managing Users & Passwords

• Enabling Audit Logging

• Encrypting Database Connections

Encrypting Plaintext Passwords

Ensuring the security of your MaxScale setup involves stringent control over the key file permissions. Utilizing is an effective approach to generate a secure key file.

This generates a keyfile in /var/lib/maxscale

See for more information about maxkeys.

Once generated, this key file can be relocated to a secure location. This key file serves a dual purpose: it enables the encryption of passwords and facilitates MaxScale in decrypting those encrypted passwords.

To maintain confidentiality, it is crucial to adjust the ownership and permissions of the key file appropriately using chown. This step ensures that the key file remains secure and inaccessible to unauthorized users.

Following the secure setup of the key file, you can proceed to encrypt the plaintext passwords of users already created in your databases.

These encrypted passwords can then replace the plaintext passwords in your MaxScale configuration (CNF) files. This enhances the overall security of your database system by reducing the risk that passwords are accidentally shared.

Securing the GUI Interface

To enhance the security of your MaxScale environment, it’s crucial to configure the GUI host address properly. The default setting, 0.0.0.0, allows unrestricted access from any network, which poses a significant security risk. Instead, you should set the admin_host to a more secure address. Additionally, you can change the default port (8989) to another port for added security. For example, you can restrict access to the localhost by setting:

Alternatively, you can specify an internal network IP address to limit access within your internal network, such as:

If you need to allow external access, ensure that the network is adequately secured and that only authorized users can access the MaxScale interface. Consult with your network administrator to determine the most appropriate and secure configuration.

Enabling TLS Encryption

To further secure your MaxScale setup, enable TLS encryption for data in transit. Follow these steps to configure SSL:

1. Set Up SSL Keys and Certificates:

• Generate SSL keys and certificates. See

• Add them to the MaxScale configuration file.

2. Update the MaxScale Configuration:

• Enable secure connections by setting admin_secure_gui to true.

• Specify the paths to the SSL certificate and key files in your CNF file:

3. Verify Encryption:

• Use the Maxctrl command to verify that TLS encryption is functioning correctly:

4. Update Default Credentials:

• It’s essential to change the default admin passwords. Create a new user with a strong password and remove the default admin user for enhanced security.

Managing Users & Passwords

MaxScale allows you to manage user access to its GUI, offering different permission levels to suit various operational needs. Currently, MaxScale supports two primary roles: admin and basic. This functionality is particularly useful for organizations with hierarchical structures or distinct departments, enabling you to grant status view access without allowing execution or manipulation capabilities.

Creating and Deleting Users

To create or delete users in the MaxScale GUI, you can use the maxctrl command. Here’s an example of creating a user with administrative privileges:

To remove an existing user, such as the default admin user, you can use the following command:

Managing Users in the GUI

The MaxScale GUI also provides functionality to manage user access and update the admin password. Through the GUI, you can:

• Add Users: Create users with basic or admin access.

• Modify User Permissions: Change roles as needed to adapt to evolving security requirements.

• Update Admin Password: Enhance security by regularly updating the admin password.

By leveraging these features, you can ensure that your MaxScale environment remains secure and that user access is appropriately managed according to your organization’s needs.

Enabling Audit Logging

Turn on admin auditing to log all login, connection, and configuration changes. Choose an audit file location and set up log rotation.

Enabling and Managing Admin Auditing in MaxScale

Admin auditing in MaxScale provides comprehensive tracking of all administrative activities, including logins, connections, and modifications. These activities are recorded in an audit file for enhanced security and traceability.

To enable admin auditing, add the following configuration to your MaxScale configuration file:

This configuration activates auditing and specifies the location of the audit file. Ensure that the specified directory exists before restarting MaxScale.

Setting Up and Managing Audit Logs

1. Enable Auditing:

• Add the configuration lines to your MaxScale configuration file.

• Verify the directory specified in admin_audit_file exists.

2. Audit File Management:

• Implement log rotation to manage the size and number of audit files. This can be achieved using standard Linux log rotation tools. See

For manual log rotation, you can use the following MaxCtrl command:

Encrypting Database Connections

Configuring SSL Encryption for MaxScale with an Encrypted MariaDB Server

If you have already implemented encryption on your MariaDB server, it’s crucial to extend this encryption configuration to MaxScale to ensure secure communication. Once encryption is enabled on your MariaDB server, follow these steps to configure MaxScale to utilize SSL.

Steps to Configure SSL in MaxScale:

1. Enable SSL:

• Add ssl=true to each server section in your MaxScale configuration file.

2. Verify Peer Certificates:

• Add ssl_verify_peer_certificate=true to ensure that MaxScale verifies the server’s SSL certificates, providing an additional layer of security.

Your MaxScale configuration file should look something like this:

These settings instruct MaxScale to use SSL for connections to the MariaDB server and to verify peer certificates, enhancing the security of data in transit.

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

This document is designed as a quick introduction to setting up MariaDB MaxScale.

The installation and configuration of the MariaDB Server is not covered in this document. See the following MariaDB documentation articles for more information on setting up a primary-replica-cluster or a Galera-cluster: and .

This tutorial assumes that one of the standard MaxScale binary distributions is used and that MaxScale is installed using default options.

Building from source code in GitHub is covered in Building from Source.

Installing MaxScale

The precise installation process varies from one distribution to another. Details on package installation can be found in the .

Creating a user account for MaxScale

MaxScale checks that incoming clients are valid. To do this, MaxScale needs to retrieve user authentication information from the backend databases. Create a special user account for this purpose by executing the following SQL commands on the primary server of your database cluster. The following tutorials will use these credentials.

MariaDB versions 10.2.2 to 10.2.10 also require GRANT SELECT ON mysql.* TO 'maxscale'@'%';

Creating client user accounts

Because MariaDB MaxScale sits between the clients and the backend databases, the backend databases will see all clients as if they were connecting from MaxScale's address. This usually means that two sets of grants for each user are required.

For example, assume that the user 'jdoe'@'client-host' exists and MaxScale is located at_maxscale-host_. If 'jdoe'@'client-host' needs to be able to connect through MaxScale, another user, 'jdoe'@'maxscale-host', must be created. The second user must have the same password and similar grants as 'jdoe'@'client-host'.

The quickest way to do this is to first create the new user:

Then do a SHOW GRANTS query:

Then copy the same grants to the 'jdoe'@'maxscale-host' user.

An alternative to generating two separate accounts is to use one account with a wildcard host ('jdoe'@'%') which covers both hosts. This is more convenient but less secure than having specific user accounts as it allows access from all hosts.

Creating the configuration file

MaxScale reads its configuration from /etc/maxscale.cnf. A template configuration is provided with the MaxScale installation.

A global maxscale section is included in every MaxScale configuration file. This section sets the values of various global parameters, such as the number of threads MaxScale uses to handle client requests. To set thread count to the number of available cpu cores, set the following.

Configuring the servers

Read the mini-tutorial for server configuration instructions.

Configuring the monitor

The type of monitor used depends on the type of cluster used. For a primary-replica cluster read . For a Galera cluster read .

Configuring the services and listeners

This part is covered in two different tutorials. For a fully automated read-write-splitting setup, read the . For a simple connection based setup, read the .

Starting MaxScale

After configuration is complete, MariaDB MaxScale is ready to start. For systems that use systemd, use the systemctl command.

For older SysV systems, use the service command.

If MaxScale fails to start, check the error log in /var/log/maxscale/maxscale.log to see if any errors are detected in the configuration file.

Checking MaxScale status with MaxCtrl

The maxctrl-command can be used to confirm that MaxScale is running and the services, listeners and servers have been correctly configured. The following shows expected output when using a read-write-splitting configuration.

MariaDB MaxScale is now ready to start accepting client connections and route queries to the backend cluster.

More options can be found in the , and .

For more information about MaxCtrl and how to secure it, see the .

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

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

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.

This tutorial is a short introduction to the , how to set it up and how it interacts with the binlogrouter.

The first part configures the services and sets them up for the binary log to Avro file conversion. The second part of this tutorial uses the client listener interface for the avrorouter and shows how to communicate with the service over the network.

Configuration

What Are Filters?

The filter mechanism in MariaDB MaxScale is a means by which processing can be inserted into the flow of requests and responses between the client connection to MariaDB MaxScale and the MariaDB MaxScale connection to the backend database servers. The path from the client side of MariaDB MaxScale out to the actual database servers can be considered a pipeline, filters can then be placed in that pipeline to monitor, modify, copy or block the content that flows through that pipeline.