IMPORTANT NOTE: The instructions in this article are deprecated. For the most up to date information on MaxScale please see the Documentation section in the MaxScale GitHub repository or check out the MaxScale forum on Google Groups
What is MaxScale?
MaxScale is an open-source, database-centric router that currently works with MariaDB and MySQL. It has a pluggable architecture designed to increase flexibility and aid customisation as well as a lightweight, high-speed networking core designed to facilitate throughput. MaxScale runs between the client application and the database cluster and currently offers connection and statement-based load balancing, query filtering, rewriting and logging facilities.
I’ve put together these instructions so that anyone having one spare host and a MySQL replication cluster (Master replicating to a handful of slaves) could fetch the sources, build, install and run MaxScale in ten minutes.
Installing MaxScale with this guide
The need for this post became obvious after receiving an increasing amount of questions which were related to linking, library versions and paths in MaxScale. Moreover, I know that there are many who want to make things with their bare hands so it is good to have something which hopefully makes the whole process smoother.
The host MaxScale will be installed is assumed to be fresh, CentOS6.5 which has nothing but the operating system installed. It is especially important that there is nothing from other MySQL installations left in the host because everything in what follows, is installed carelessly to system directories. Using headers, libraries or error files from different versions leads almost certainly to unplanned behavior.
Setting up MySQL replication cluster (or any other cluster types MaxScale supports) is not covered here. So I assume you already have a master/slave replication successfully set up.
The text refers to source branches by their names. Same instructions should apply to other branches as well as to the one used here.
yum install git mkdir src ; cd src mkdir git ; cd git mkdir release-1.0beta ; cd release-1.0beta git init git remote -v add maxscale https://github.com/skysql/MaxScale git pull -v maxscale master git checkout -b release-1.0beta git pull -v maxscale release-1.0beta
Get and set up MariaDB
[mariadb] name = MariaDB baseurl = http://yum.mariadb.org/5.5/centos6-amd64 gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB gpgcheck=1
yum install MariaDB-server yum install MariaDB-devel
yum -y install make gcc gcc-c++ ncurses-devel bison glibc-devel openssl-devel libaio libaio-devel telnet
edit build_gateway.inc in the root directory and set :
ROOT_PATH := $(HOME)/src/git/release-1.0beta INC_PATH := /usr/include ERRMSG := /usr/share/mysql/english/ mkdir ~/usr mkdir ~/usr/lib64 ln -s /usr/lib64/libmysqld.a ~/usr/lib64/ make DYNLIB=N DEST=~/bin/release-1.0beta clean depend all install
cp ~/bin/release-1.0beta/etc/MaxScale_template.cnf ~/bin/release-1.0beta/etc/MaxScale.cnf
In the configuration file ~/bin/release-1.0beta/MaxScale.cnf , set correct values to at least to the following sections :
[MySQL Monitor] user=myuser passwd=mypwd [RW Split Router] user=myuser passwd=mypwd [Read Connection Router] user=myuser passwd=mypwd [server1] address=(ip #1) port=3306 [server2] address=(ip #2) port=3306 [server3] address=(ip #3) port=3306
Backend database servers
Start three mariadb servers – 1 Master and 2 Slaves. Execute the following in each:
GRANT ALL PRIVILEGES ON *.* TO myuser@(ip #1) IDENTIFIED BY 'mypwd' WITH GRANT OPTION GRANT ALL PRIVILEGES ON *.* TO myuser@'%' IDENTIFIED BY 'mypwd' WITH GRANT OPTION
cd ~/bin/release-1.0beta/bin ./maxkeys ~/bin/release-1.0beta/etc/.secrets ./maxscale -d -c ../
from 0..compiled 8:50:72 (almost nine minutes) from compiled to running 11:46:23
If you have taken all the steps listed above and have trouble getting MaxScale started or you encounter some unexpected behavior, you may find help from error and message logs.
When MaxScale starts it prints essential information to the terminal window, which helps in problem resolution.
SkySQL MaxScale 1.0.0 Fri Jul 4 16:05:32 2014 ------------------------------------------------------ Info : MaxScale will be run in the terminal process. See the log from the following log files : Error log : /home/raatikka/bin/release-1.0beta/log/skygw_err1.log Message log : /home/raatikka/bin/release-1.0beta/log/skygw_msg1.log Trace log : /home/raatikka/bin/release-1.0beta/log/skygw_trace1.log Debug log : /home/raatikka/bin/release-1.0beta/log/skygw_debug1.log Home directory : /home/raatikka/bin/release-1.0beta Configuration file : /home/raatikka/bin/release-1.0beta/etc/MaxScale.cnf Data directory : /home/raatikka/bin/release-1.0beta/data22732 MaxScale PID 22732 in pidfile /home/raatikka/bin/release-1.0beta/log/maxscale.pid Listening MySQL connections at 0.0.0.0:4004 Listening MySQL connections at 0.0.0.0:4006 Listening MySQL connections at 0.0.0.0:4008 Listening http connections at 0.0.0.0:6444 Listening telnet connections at 0.0.0.0:4442
Refer to The Configuration and Usage Scenarios document for further information about different setups you can come up with.
My goal in this post was to make it easier to build your own MaxScale router and get it running during your next coffee break. Hope you’ll find interest to see what’s it capable of. More resources and discussion can be found from #maxscale channel on freenet, and through the links below.
- Source Code: https://github.com/SkySQL/MaxScale
- Binary packages: http://downloads.skysql.com/files/SkySQL/MaxScale/maxscale-1.0-beta
- GoogleGroup: https://groups.google.com/forum/#!forum/maxscale