MaxScale Modules – What’s in 1.0 Beta?

MaxScale is a modular proxy application, the modules can be considered as the building blocks of your proxy implementation within your MySQL database environment. It is important to know what building blocks you have at your disposal. The release of version 1.0 as a beta means that the number of available modules has grown once again. Normally I post about the incremental changes in what is available, but I thought that maybe it was a good time to post a short summary of all the modules. This is not designed to be comprehensive documentation for the functionality available, merely as a summary of what is available.

Routing Modules

Routers are perhaps the most important modules within MaxScale, since they make the decisions as to where to send requests. However they are incapable of functioning autonomously and require monitor and protocol modules in order to fulfil a useful function.

There are two classes of router within MaxScale, real query routers and pseudo routers that are used as ways to expose internal MaxScale state. There are two important query routers included in the release, the readconnrouter and readwritesplit modules.


The readconnroute module should perhaps be renamed, it is a general purpose routing module that is used for all forms of connection routing, not just for read only connections. It will distribute connections amongst a set of servers using the constraints passed in the routing options. The following routing options are available;

  • master – only route to a server which has the master status bit set
  • slave – only route to a server that has the slave status bit set
  • synced – only route to a server that has the synced status bit set

If no routing options are given then the router will distribute the connections over all the servers that are currently running. Servers that are down or in maintenance mode will not have connections routed to them.

In a hierarchical MySQL replication tree the master node is treated as the node nearest the root of the tree that has the master bit set. Any intermediate nodes, which have both the master and slave bits set, will be treated as a slave node.

The synced option is reserved for use with Galera clusters and ensures that connections are not routed to servers that a not a fully fledged member of the cluster. In addition the Master/Slave states may be used in Galera along with the special monitor module that elects one of the Galera nodes as a master.

The distribution of connections within a set of servers may not be even, but will honour any weighting bias that is introduced via the weightby setting of the service and the individual server weights.

Read/Write Splitter

The Read/Write Splitter is a much more sophisticated routing module, it examines the incoming request and determines if that request should be sent to a read/write server or if it may be sent to a read only server; i.e. a master or a slave in MySQL replication environment. The Read/Write Splitter is not however limited to MySQL Replication, it may also be used with Galera Clusters.

When used with Galera the monitor module will elect one of the nodes in the Galera cluster as the master to which all writes will be routed. The read load may then be spread across all of the other nodes within the Galera Cluster. This provides a means to use Galera in a pure HA mode, with read load balancing, rather than a true multi-master configuration.

The Read/Write Splitter is able to balance the load on the slave servers using several different criteria, these as chosen by the use of a router option setting in the MaxScale service. The options available are;

  • least number of connections from all MaxScale services
  • least number of connection from this MaxScale service
  • least number of current operations currently in progress
  • least lagging behind the master

The server weighting mechanism may also be applied to the first three of these methods in order to define a non-uniform distribution within the chosen balancing criteria is required.

In addition it is possible to define a maximum replication lag, in terms of seconds behind master, which a slave must adhere to in order to be chosen as an acceptable destination for read only statements to be sent.

Pseudo Routers

MaxScale 1.0 beta also comes with a number of pseudo routers.


The CLI module is a simple information provider used by the maxadmin client interface in order to execute statistics gathering and administration commands. This is not a router in the true sense, but rather a way to expose internal MaxScale data.


The debugcli router is closely related to the CLI router and provides an interface for developers to access internal MaxScale data structures.


Monitors provide data to the rest of the modules within MaxScale which will be used by them to determine the current state of the servers within the system and hence the best destination to send requests. It is possible to use MaxScale without any monitors, setting the server states manually, however this looses many of the advantages of using MaxScale. There are currently two monitors available in the 1.0 beta version of MaxScale.


A monitor module that is designed to monitor MySQL replication configurations. It will detect the master and slave status of each server it is monitoring and will build the relationships between these nodes in order to give MaxScale modules access to the replication hierarchy information. In addition the mysqlmon module will measure the replication lag for data written to the master before it is available on each of the slaves.


This monitor module is designed to monitor Galera clusters and provide information regarding the membership of the Galera cluster for each of the servers. In addition the Galera monitor is able to nominate a single server within a Galera cluster as a master node and the remainder as slaves. This allows Galera to be used as a highly available database with a single writable master and read only slaves with a very fast failover response.


Filters provide a means to extend the MaxScale functionality by adding small modules into the processing pipeline of the MaxScale service. They allow for examination and modification of SQL requests, four such modules are included in the 1.0Beta release.


The qlafilter is a simple query logging filter that writes copies of a query to a per user connection log file. The qlafilter has mechanisms to limit those queries that are logged using regular expressions, connection source address and connection user name.


The regexfilter provides a means to alter SQL statements as they pass through MaxScale. It uses regular expressions to match and replace content as it traverses MaxScale.


A filter that will duplicate all or some of the requests to a second service within MaxScale. The tee filter also has mechanisms to limit those queries that are logged using regular expressions, connection source address and connection user name.


The top filter is a logging filter that will record the top N longest running SQL statements in your connection. When the connection is closed a log file per connection will be written. The number of statements that are retained by this filter is controllable via a configuration parameter for the filter. The top filter uses the same mechanisms to limit those queries that are measured as those available for the QLA and Tee filters, regular expressions, connection source address and connection user name.

Protocol Modules

Protocol modules are, as the name suggests, responsible for the protocol aspect of interface to or from external systems and MaxScale. The most important protocol modules are those used for the communication from the client application to MaxScale and the MaxScale to database server communication path.


The protocol module used for client applications which normally directly connect to a MySQL database to connect to MaxScale.


The protocol module MaxScale uses to connect to the backend MySQL databases.


Terminal protocol used to connect the debug interface to MaxScale. This is only used for the debug interface and will never be used to carry database traffic.


The protocol used by the MaxScale administration interface to connect to MaxScale.


An experimental HTTP protocol for use by HTTP requests for REST style interfaces.