Introduction

After MaxScale has been installed, test that MaxScale starts by executing sudo systemctl start maxscale, followed by sudo systemctl status maxscale.

Stop MaxScale with sudo systemctl stop maxscale. The log file is written at /var/log/maxscale/maxscale.log. If the startup failed, the log should explain why. With the default configuration file, MaxScale does not yet do anything interesting.

A functional configuration of MaxScale should include a listener, a service, a monitor and one or more servers. An incoming client connects to a listener port. Once the connection is established, the listener passes the client to a service. The service then handles all client traffic, from authentication to disconnection. Client queries are routed to servers and query results from servers back to the client. A monitor regularly checks the status of the servers.


MaxScale configuration files use the common file format. The files contain sections and each section can contain multiple key-value pairs. The MaxScale installer creates an example configuration file to /etc/maxscale.cnf.

Configure a Read-Write Service

Let's modify the example configuration file to include a service that routes all queries to one server. For this, you will need to have a running MariaDB Server accessible in the network. One option is to run a MariaDB Server . Once the server is running, log in to it with an administrative account and create a user account for MaxScale itself to use when monitoring the server and fetching user accounts. The following example creates user maxscale with all privileges.

Next, edit /etc/maxscale.cnf. Perform the following modifications:

1. In the section [server1], set correct address and port. These should match the running MariaDB Server.

2. In the section [MariaDB-Monitor], set user to maxscale and password to maxscale_passwd (or whatever user/password was created earlier).

The configuration file should now have the following effective contents.

Then, start MaxScale. If MaxScale started successfully, run maxctrl list servers in the terminal. If MaxScale can successfully connect to the server, the output should be approximately:

Next, check the log file at /var/log/maxscale/maxscale.log. It should have a message like:

If the monitor cannot connect to the server, the State is Down. In this case, check the log for error messages. Similarly, if the service cannot load user account information, an error is logged.

If everything is working properly, connect as client to the MaxScale listener port, configured to 4006.

Other user accounts on the server should work as well if their host patterns allow connections from MaxScale's IP address.

Extend Read-Write Service

The Read-Write Service configured above only uses one server. To enable read-write splitting, a replication cluster with a primary server and one or more replicas is required. Setting up such a cluster is outside the scope of this document, see for more information.

Once the replicas are set up, add them to the MaxScale configuration file as separate sections: [server2], [server3] etc., similar to [server1]. Remember to set the addresses and ports. Then, add the server names to the servers-settings of the monitor:

Then, restart MaxScale to take the configuration into use and run maxctrl list servers once more. If replication is working and MaxScale can connect to all the servers, the output should be as below. If this is not the case, check the log again for error messages.

Run maxctrl show servers to get more detailed information about the servers such as connection and query counts, and maxctrl show monitors to see monitor-related information such as replication status.

Connect to the listener port again with mariadb -h127.0.0.1 -P4006 -umaxscale -pmaxscale_passwd and run the query select @@server_id; a few times. It should give the server id of a replica, alternating if multiple are available. This demonstrates that read queries are sent to the replicas. Writes and other queries that depend on the primary are sent to the primary only, e.g. select @@last_insert_id,@@server_id;. Reads inside transactions are also ran on the primary to maintain transaction consistency.

Add a filter

Filters are components added to the query processing chain that can act on the query. A typical use-case is logging. To add a log filter, add the following to the configuration file:

Then, add the filter to the service:

Again, restart MaxScale to take the configuration into use. MaxScale will now log any client queries passing through MaxScale to /var/log/maxscale/query_log.unified.

Test the GUI

Add admin_secure_gui=false to the [maxscale]-section of the configuration file and restart MaxScale. This allows access to the GUI without configuring SSL certificates. Then, open a web browser and navigate to http://127.0.0.1:8989. A login screen should open, use username admin and password mariadb to access the GUI. The GUI can show MaxScale and server status, show and modify MaxScale configuration, perform SQL queries and much more. See for more information on the GUI.

Further reading

The lists all global configuration parameters. The explains the ReadWriteSplit-router and its features, such as transaction replay and causal reads. The explains monitor features such as failover and switchover.

Quickstart Guide: MariaDB MaxScale Overview

MariaDB MaxScale is an advanced, open-source database proxy, router, and load balancer designed to enhance the scalability, high availability, and security of your MariaDB deployments. It acts as an intelligent intermediary between your applications and your MariaDB servers, abstracting the underlying database topology.

1. What is MariaDB MaxScale?

MaxScale is not a database itself, but a sophisticated gateway that understands the MariaDB protocol. It intercepts client connections and routes them to the appropriate backend MariaDB servers based on configured rules, health checks, and workload types. This allows for flexible and dynamic management of database traffic without requiring changes to the application code.

2. Core Functionalities and Benefits

MariaDB MaxScale provides several key functionalities that contribute to optimizing MariaDB environments:

• Intelligent Routing and Load Balancing:

  • ReadWriteSplit Router: This is a primary feature that automatically distinguishes between read (SELECT) and write (INSERT, UPDATE, DELETE, DDL) statements. It intelligently routes all write statements to the designated primary server and distributes read statements across multiple replica servers, significantly improving read scalability and reducing the load on the primary.

  • Other Routers: MaxScale offers various routers for different use cases, such as routing to specific databases, connection-based routing, or custom routing logic.

By abstracting the database topology and intelligently managing connections, MariaDB MaxScale helps organizations achieve higher availability, better performance, and enhanced security for their MariaDB deployments.

Further Resources:

Quickstart Guide: MariaDB MaxScale Limitations

While MariaDB MaxScale is a powerful tool for managing MariaDB deployments, it's essential to be aware of its limitations to ensure proper configuration and avoid unexpected behavior. This guide highlights key considerations when deploying and using MaxScale.

1. Configuration File Line Length

• Limitation: Older versions of MaxScale (2.1.2 and earlier) had a strict line length limit of 1024 characters in the configuration file (maxscale.cnf).

• Consideration: Ensure your MaxScale configuration lines do not exceed this limit for older versions. Modern versions (e.g., 2.3.0 and later) have significantly increased this limit (to 16,777,216 characters), making it less of a concern for current deployments. Always check the documentation for your specific MaxScale version.

2. Assumptions about MariaDB Server Configuration

• Limitation: MaxScale operates under the assumption that certain MariaDB Server configuration parameters are set to their default values. A critical example is the assumption that autocommit is enabled for new connections.

• Consideration: If your backend MariaDB servers deviate from default autocommit settings or other assumed defaults, it could lead to unexpected behavior in how MaxScale manages connections and routes queries, particularly with transaction handling. Always verify that your MariaDB server configurations align with MaxScale's expectations as outlined in its documentation.

3. Transaction Boundary Detection and XA Transactions

• Limitation: MaxScale uses a custom SQL parser to deduce transaction boundaries. This parser may not fully comprehend or correctly classify highly complex SQL statements or certain edge cases. This can lead to a mismatch between MaxScale's understanding of a connection's transaction state and the actual state on the backend database.

• Specific Issue with XA Transactions: If a START TRANSACTION command fails internally on the backend due to an already open XA transaction (e.g., using XA START), MaxScale's parser might not correctly detect this failure. It could mistakenly assume a new transaction has started, leading to discrepancies in transaction state awareness, especially with the readwritesplit router.

4. ETL Feature Dependency

• Limitation: The ETL (Extract, Transform, Load) feature within MaxScale relies on the MariaDB Connector/ODBC driver for its functionality.

• Consideration: To ensure stability and avoid potential crashes or memory leaks when using MaxScale's ETL capabilities, it is highly recommended to use MariaDB Connector/ODBC driver version 3.1.18 or later. Always ensure all components are compatible.

Important General Considerations:

• Query Classification: MaxScale's ability to route queries correctly relies on its query classification. If queries are ambiguous or use non-standard SQL, they might be misrouted.

• Prepared Statements: While supported, complex interactions with prepared statements can sometimes expose nuances in parsing or routing.

• Protocol Specifics: MaxScale aims for broad compatibility, but subtle differences in client or server protocol implementations might arise.

Understanding these limitations helps in designing a robust MaxScale deployment and troubleshooting potential issues effectively.

Further Resources:

Quickstart Guide: MariaDB MaxScale Authentication Modules

MariaDB MaxScale incorporates robust authentication modules to manage client access and ensure secure communication with your backend MariaDB servers. Understanding these modules is crucial for securing your database deployments when using MaxScale.

1. What are MaxScale Authentication Modules?

MaxScale's authentication modules (often referred to as "authenticator plugins") are components that handle client authentication. They determine how incoming clients verify their identity to MaxScale and, in turn, how MaxScale authenticates itself to the backend MariaDB servers. This process is similar to how authentication works directly with MariaDB Server using the MySQL protocol.

2. How Authentication Works in MaxScale

MaxScale employs a User Account Manager (UAM) for services that use a MariaDB protocol listener.

• The UAM is responsible for storing and managing user account information.

• It typically queries the mysql database on your backend MariaDB servers (usually the primary) to retrieve user account details.

• Using this information, the UAM authenticates connecting clients, verifies their passwords, and checks their database access rights.

• The user

3. Available Authentication Plugins

MaxScale supports various authentication schemes through different plugins:

• Standard MySQL Password: This is the most common authentication method, verifying user credentials against those stored in the backend MariaDB server's mysql.user table (or similar).

• GSSAPI (Generic Security Service Application Programming Interface): Provides secure authentication methods, often used in enterprise environments with Kerberos or similar systems.

• PAM (Pluggable Authentication Modules): Allows MaxScale to integrate with PAM, enabling authentication against external systems like Unix system users, LDAP, or Active Directory.

4. Basic Configuration Concepts

Authentication options are primarily defined within the listener configuration of your MaxScale service in the maxscale.cnf file.

a. Specifying the Authenticator:

The authenticator parameter specifies which authentication plugin to use for a particular listener.

Example maxscale.cnf snippet (simplified):

Ini, TOML

b. Authenticator Options (authenticator_options):

Additional settings can be passed to the authenticator plugin using authenticator_options. These are comma-separated key-value pairs.

Common authenticator_options:

• skip_authentication=true: (Use with extreme caution, typically only for development/testing). This option bypasses password checks for connecting clients. Clients will still need a valid username in the backend database, but their password will not be verified.

• match_host=false: Disables host matching for user accounts. By default, MariaDB (and thus MaxScale's UAM) matches user accounts based on both username and host (e.g., 'user'@'localhost'). Setting this to false means only the username needs to match.

Example with options:

Ini, TOML

By configuring these authentication modules, you can control how clients connect to your MariaDB through MaxScale, enforce security policies, and integrate with existing authentication infrastructure.

Further Resources:

Quickstart Guide: MariaDB MaxScale

MariaDB MaxScale is an advanced, open-source database proxy that provides intelligent routing, load balancing, high availability, and security features for your MariaDB and MySQL deployments. It acts as an intermediary, forwarding database statements to one or more backend database servers based on configured rules and server roles, all transparently to your applications.

Further Resources: