MariaDB MaxScale Documentation

Routing modules accept database connections from clients and route them to supported services. Available modules include:

• ReadConnRoute: Connection-based load balancing.
• ReadWriteSplit: Read/Write aware statement-based routing.
• SchemaRouter: Simple sharding on the database level.
• Binlogrouter: Binary log server routing.

MaxCtrl is the command-line administrative client for MaxScale. It communicates with MaxScale via the MaxScale REST API.

By default, the REST API listens on port 8989 on localhost. The default credentials for the REST API are admin:mariadb. The users used by the REST API are identical to those used by the MaxAdmin network interface; any users created for MaxAdmin will work with MaxCtrl.

The maxscale-system-test suite consists of system-level tests where every individual test is implemented as a separate executable file.

Configuration for backends (such as IP addresses, usernames, and passwords) is provided via environment variables rather than static configuration files. This allows the test runner to inject dynamic connection details into the test executables.

A filter resource in MaxScale represents a specific filter instance. Filters are modular components that can be shared across multiple services, and a single service can utilize multiple filters.

Key Constraints:

• Naming: In all URIs, :name or :filter must be the exact name of the filter in MaxScale.
• Relationships: Filters only have relationships with services. Because the filter-to-service relationship is ordered (filters are applied in the order they are listed in the service configuration), you cannot define these relationships when creating a filter. You must manage the service $\rightarrow$ filter relationship via the services resource instead.
• Deletion: A filter can only be destroyed if no service is currently using it (i.e., its data.relationships object is empty). To bypass this, use the force=yes parameter.

SmartRouter is the query router for the SmartQuery framework. It enables Hybrid Transactional and Analytical Processing (HTAP) by providing a single entry point for mixed workloads.

SmartRouter automatically routes queries to the most appropriate cluster based on the query type:

• Transactional (OLTP) queries are routed to the primary/master cluster.
• Analytical (OLAP) queries are routed to optimized analytical clusters (e.g., ColumnStore).

This allows a client to execute both transactional and analytical queries over the same connection without manually switching between different service endpoints.

The Top N Filter is a MariaDB MaxScale filter module that monitors SQL statements passing through it. It measures the duration of each statement (the time from when the statement is sent until the first result is returned) and tracks the top $N$ slowest queries.

Upon the closure of a client session, the filter writes a report to a file containing the SQL text and a list of the slowest queries sorted by execution time.

The readwritesplit router increases the read-only processing capability of a cluster by splitting query loads into read and write queries.

• Write queries: All write queries are routed to a single node (the primary).
• Read queries: Read queries (those that do not modify data) are spread across multiple nodes.

Use Cases:

• Primary-Replica clusters: Automatically detects changes in the primary server and routes writes to the current primary.
• Galera clusters: Can be used for resilient setups by designating one Galera node as the Write-Primary for all write queries, while spreading the read load across all nodes in the cluster.