How to Install, Configure, and Test MaxScale for MySQL Read/Write Splitting and Failover

Background

After configuring a MySQL master‑slave replication topology, read/write separation and load balancing across slaves are often required. MaxScale, a MariaDB‑developed proxy, provides a plugin‑based solution for these needs.

Architecture

MaxScale consists of five plugin categories:

Authentication plugins – cache user credentials from the MySQL user table and validate incoming connections.

Protocol plugins – handle client‑to‑proxy and proxy‑to‑server protocol translation.

Routing plugins – decide how client queries are forwarded; they implement read/write splitting and load balancing.

Monitoring plugins – continuously check server health and exclude slow or unreachable nodes.

Logging & filtering plugins – provide simple firewall capabilities and SQL filtering.

Installation (CentOS 7 example)

Prepare three servers (one master, two slaves) and configure MySQL replication.

Download MaxScale from https://downloads.mariadb.com/files/MaxScale and select the appropriate package for the OS.

Install required libraries and the MaxScale RPM:

yum install libaio.x86_64 libaio-devel.x86_64 novacom-server.x86_64 libedit -y
rpm -ivh maxscale-1.4.3-1.centos.7.x86_64.rpm

Create monitoring and routing users on the master:

mysql> CREATE USER scalemon@'%' IDENTIFIED BY "111111";
mysql> GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO scalemon@'%';
mysql> CREATE USER maxscale@'%' IDENTIFIED BY "111111";
mysql> GRANT SELECT ON mysql.* TO maxscale@'%';

Edit /etc/maxscale.cnf to define the three servers, their addresses, ports, and the users created above. Duplicate the [server1] block for [server2] and [server3] and adjust address and port accordingly. Also configure the [MySQL Monitor] and [Read-Write Service] sections to use the created users.

Start MaxScale: maxscale --config=/etc/maxscale.cnf Verify that MaxScale is listening (default client port 4006, admin port 6603) with netstat -ntelp and connect to the admin console:

maxadmin --user=admin --password=mariadb

Basic Test

Create a test user on the master:

mysql> GRANT ALL PRIVILEGES ON *.* TO rtest@"%" IDENTIFIED BY "111111";

Connect through MaxScale: mysql -h <em>MaxScale_IP</em> -P 4006 -u rtest -p111111 Read‑only queries are routed to a slave, while a transaction forces routing to the master.

Handling Slave Failures

Enable detailed logging by adding to the [maxscale] section:

log_info=1
logdir=/tmp/

Restart MaxScale after editing the configuration.

Scenario 1 – One Slave Fails

Stop replication on a slave (e.g., mysql> STOP SLAVE;). MaxScale marks the server as lost_slave and stops routing queries to it. All reads are automatically directed to the remaining healthy slave. When the slave is started again ( START SLAVE;), MaxScale detects the new_slave state and reintegrates it into the routing pool.

Scenario 2 – All Slaves Fail

If all slaves are down, MaxScale initially reports that no master is available and client connections fail. Adding the option detect_stale_master=true to the [MySQL Monitor] section and restarting MaxScale makes the proxy continue routing all client traffic to the master, keeping the database service available. When the slaves recover, MaxScale automatically resumes load‑balanced reads.

Key Configuration Parameters

log_info=1

– enables informational logging. logdir=/tmp/ – directory for log files. detect_stale_master=true – forces MaxScale to keep the master usable when all slaves are unavailable.

Conclusion

MaxScale provides transparent read/write splitting and load balancing for MySQL clusters. It automatically excludes failed slaves and can be configured to keep the master operational when all slaves are down, offering robust failover without manual intervention.