February 16, 2017

MariaDB MaxScale 2.1: Power to the Modules

The 2.1 version of MaxScale introduced a new concept of module commands. This blog post takes a look at what they are, why they were implemented and where you see them when you use MaxScale.

The Idea Behind Module Commands

The core concept of the module commands was driven by the need to do things with modules that couldn’t be done with all modules of that type. One example of this need is the dbfwfilter firewall filter module. The module needs to be able to provide a mechanism which is capable of testing the validity of the rules as well as updating them out on the fly. We could have introduced a reload function into the filter API but only a few filters would ever implement it. But what if a filter needs to be able to do even more specific tasks which do not apply to other modules of the same type?

As the type and variety of modules in MaxScale starts to grow, so do the requirements that those module place on the MaxScale core. At this point, we have realized that we need a way to allow modules to expose module specific functionality to end users regardless of the module API they use. And so the idea of a module command was born.

How Module Commands Were Implemented

The module command implementation is relatively simple. It allows modules to register commands that are exposed to the user via the administrative interface. All the module needs to do is to declare the parameters the command expects, document the parameters and give a function which is called when the module command is executed. Everything else is handled by the MaxScale core.

Calling Module Commands

The user can then call these commands via the administrative interface. The use of module commands is intended to be very similar to the use of the built in maxadmin commands and it should feel familiar to the users of MaxScale.

Two new commands were added to MaxAdmin itself: list commands and call command. The former lists all registered module commands and the latter calls a module command. The execution of call command always takes at least two arguments, the module and command names.

Example Use of Module Commands

The best way to show how module commands work is to show them in action. One of the MaxScale modules that implements module commands is the dbfwfilter database firewall.

Micro-Tutorial: Dbfwfilter Module Commands

A practical example of using module commands is the reloading of the firewall rules in the dbfwfilter module when changes occur in the database.
The module registers two commands. Here’s the output of maxadmin list commands when the dbfwfilter module has been loaded.

Command: dbfwfilter rules
Parameters: FILTER

    FILTER - Filter to inspect

Command: dbfwfilter rules/reload
Parameters: FILTER [STRING]

    FILTER - Filter to reload
    [STRING] - Path to rule file

The rules commands shows diagnostic information about the active rules. The rules/reload command reloads the rules from a file and optionally changes the location of the rule file. The following filter configuration will use the rules file to detect which types of queries should be allowed. The action=allow parameter tells the filter to let all queries pass that match a rule.


Using the following rule file for the dbfwfilter will only allow statements that target the name or address columns.

rule allowed_columns allow columns name address
users %@% match any rules allowed_columns

But what if we need to alter the client application to allow statements to the email column? In older versions this would require a restart of MaxScale so that the rules could be reloaded. With the 2.1 version of MaxScale, you can alter the rules and reload them at runtime. To do this, we add the email column to the rule file.

rule allowed_columns allow columns name address email
users %@% match any rules allowed_columns

Then we reload the rules by calling the rules/reload command of the dbfwfilter. The rules/reload command can be called by executing the call command MaxAdmin command and giving it the filter name as a parameter.

maxadmin call command dbfwfilter rules/reload Database-Firewall

Once the command is complete, the dbfwfilter has reloaded and taken the new rules into use. With this new functionality in the dbfwfilter, online modifications to both the client applications and backend databases can be made without interruptions to the service.


Module commands make the usage of MaxScale's modules easier as it allows modules to perform custom actions. The example shows a practical use-case that makes the use of MaxScale more convenient by leveraging the module command system.

For more information on the implementation of the module commands, read the MaxScale documentation on module commands. You can find a list of modules that implement module commands in the MariaDB MaxScale 2.1.0 Beta Release Notes.

Please try out the new module commands by downloading the MariaDB MaxScale 2.1.0 beta and give us your feedback on our mailing list maxscale@googlegroups.com or on #maxscale@FreeNode.
About Markus Mäkelä

Markus Mäkelä is a Software Engineer working on MariaDB MaxScale. He graduated from Metropolia University of Applied Sciences in Helsinki, Finland.

Read all posts by Markus Mäkelä