293 lines
11 KiB
Plaintext
293 lines
11 KiB
Plaintext
/** \mainpage MaxScale by MariaDB Corporation
|
|
|
|
The MariaDB Corporation MaxScale is an intelligent proxy that allows forwarding of
|
|
database statements to one or more database servers using complex rules,
|
|
a semantic understanding of the database statements and the roles of
|
|
the various servers within the backend cluster of databases.
|
|
|
|
MaxScale is designed to provide load balancing and high availability
|
|
functionality transparently to the applications. In addition it provides
|
|
a highly scalable and flexibile architecture, with plugin components to
|
|
support different protocols and routing decissions.
|
|
|
|
MaxScale is implemented in C and makes extensive use of the
|
|
asynchronous I/O capabilities of the Linux operating system. The epoll
|
|
system is used to provide the event driven framework for the input and
|
|
output via sockets.
|
|
|
|
The protocols are implemented as external shared object modules which
|
|
can be loaded at runtime. These modules support a fixed interface,
|
|
communicating the entries points via a structure consisting of a set of
|
|
function pointers. This structure is called the "module object".
|
|
|
|
The code that routes the queries to the database servers is also loaded
|
|
as external shared objects and are referred to as routing modules.
|
|
|
|
An Google Group exists for MaxScale that can be used to discuss ideas,
|
|
issues and communicate with the MaxScale community.
|
|
Send email to [maxscale@googlegroups.com](mailto:maxscale@googlegroups.com)
|
|
or use the [forum](http://groups.google.com/forum/#!forum/maxscale) interface
|
|
|
|
Bugs can be reported in the MariaDB Corporation bugs database
|
|
[bug.mariadb.com](http://bugs.mariadb.com)
|
|
|
|
\section Building Building MaxScale
|
|
|
|
Edit the file build_gateway.inc in your MaxScale directory and set
|
|
the ROOT_PATH to the directory in which you have installed the
|
|
MaxScale source code. Set the INC_PATH/MYSQL_ROOT/MYSQL_HEADERS variables
|
|
to the location in which you have installed the developer package
|
|
for MariaDB or checked out the source code of MariaDB and the
|
|
location of your MariaDB include files.
|
|
|
|
The include files, static embedded library and other files may come
|
|
from the RPMs packages:
|
|
|
|
MariaDB-5.5.34-centos6-x86_64-common.rpm
|
|
MariaDB-5.5.34-centos6-x86_64-compat.rpm
|
|
MariaDB-5.5.34-centos6-x86_64-devel.rpm
|
|
|
|
Please backup any existing my.cnf file before installing the RPMs
|
|
|
|
Install the RPM files using:
|
|
|
|
rpm -i MariaDB-5.5.34-centos6-x86_64-common.rpm MariaDB-5.5.34-centos6-x86_64-compat.rpm MariaDB-5.5.34-centos6-x86_64-devel.rpm
|
|
|
|
Note, if you wish to relocate the package to avoid an existing MariaDB
|
|
or MySQL installation you will need to use the --force option in addition
|
|
to the --relocate option.
|
|
|
|
rpm -i --force --relocate=/usr/=$PREFIX/usr/ MariaDB-5.5.34-centos6-x86_64-common.rpm MariaDB-5.5.34-centos6-x86_64-compat.rpm MariaDB-5.5.34-centos6-x86_64-devel.rpm
|
|
|
|
You can also use the included 'unpack_rpm.sh' script to unpack the RPMs without installing them.
|
|
|
|
./unpack_rpm <location of MariaDB RPMs> <extraction destination>
|
|
|
|
This README assumes $PREFIX = $HOME.
|
|
|
|
MaxScale may be built with the embedded MariaDB library either linked
|
|
dynamically or statically.
|
|
|
|
To build with the embedded libmysqld linked dynamically from an
|
|
existing MariaDB source setup
|
|
|
|
set DYNLIB := Y
|
|
copy the libmysqld.so in $(HOME)/usr/lib64/dynlib
|
|
|
|
To build with the embedded libmysqld linked statically
|
|
|
|
If DYNLIB is not set MaxScale will be built using the static library
|
|
found in $(HOME)/usr/lib64
|
|
|
|
This libmysqld.a comes from the RPM or it is copied from an existing
|
|
MariaDB setup. The file embedded_priv.h is not available in the RPM
|
|
packages, please get it from an existing MariaDB setup and copy it
|
|
to one of the path in MYSQL_HEADERS
|
|
|
|
|
|
The ERRMSG variable points to the errmsg.sys file that is required
|
|
by the embedded library.
|
|
|
|
Example:
|
|
|
|
ERRMSG := $(HOME)/usr/share/mysql
|
|
|
|
|
|
Please note the errmsg.sys file is NOT included in the RPMs at the
|
|
current time, it must be taken from an existing MariaDB setup. The
|
|
version of the errmsg.sys file must match the version of the developer
|
|
package you are using. A version mismatch will cause the library to fail
|
|
to initialise.
|
|
|
|
You may get the one in the 'english' folder:
|
|
|
|
Example /usr/local/mariadb/share/english/errmsg.sys
|
|
|
|
|
|
Go to the MaxScale directory and do:
|
|
|
|
make depend
|
|
|
|
to update all the dependency files and then do:
|
|
|
|
make
|
|
|
|
make install
|
|
|
|
You may set the DEST variable for the target install location, example:
|
|
|
|
make DEST=/some/path
|
|
|
|
make DEST=/some/path install
|
|
|
|
|
|
If DEST is not set the default install location is:
|
|
|
|
DEST=$(HOME)/usr/local/skysql
|
|
|
|
This should get you all the things built that you need.
|
|
|
|
Other make targets are available
|
|
|
|
clean - Removes compiled code and shared objects
|
|
install - Installs the binary and the modules in the location defined by the
|
|
make variable DEST
|
|
|
|
ctags - Build tags files for the vi editor
|
|
|
|
documentation - Build the doxygen documentation
|
|
|
|
depend - Update the dependencies used by the makefiles
|
|
|
|
Two files are required for the libmysqld library that is used within MaxScale,
|
|
errmsg,sys and a my.cnf file with the following:
|
|
|
|
External libraries/packages required:
|
|
|
|
openssl and openssl-devel
|
|
libaio
|
|
|
|
Note: on CentOS 6 do:
|
|
|
|
ln -s /lib64/libaio.so.1 /lib64/libaio.so
|
|
|
|
[mysqld]
|
|
max_connections=4096
|
|
|
|
Please check errmsg.sys is found in the MaxScale install_dir DEST/MaxScale/mysql
|
|
|
|
\section Building Building MaxScale with CMake
|
|
|
|
You can also build MaxScale with CMake which makes the build process a bit more simple.
|
|
|
|
All the same dependencies are required as with the normal MaxScale build with the addition of CMake
|
|
version 2.6 for regular builds and 2.8.12 or newer if you wish to generate packages.
|
|
|
|
CMake tries to find all the required directories and files on its own but if it can't find them or you wish to
|
|
explicitly state the locations you can pass additional options to CMake by using the -D flag. To confirm the variable
|
|
values, you can run CMake in interactive mode by using the -i flag or use a CMake GUI (for example, ccmake for command line).
|
|
|
|
It is highly recommended to make a separate build directory to build into. This keeps the source and build trees clean and
|
|
makes it easy to get rid of everything you built by simply deleting the build directory.
|
|
|
|
To build MaxScale using CMake:
|
|
|
|
cd <path to MaxScale source>
|
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
cmake ..
|
|
|
|
make
|
|
|
|
make install
|
|
|
|
This generates the required makefiles in the current directory, compiles and links all the programs and installs
|
|
all the required files in their right places.
|
|
|
|
If you have your headers and libraries in non-standard locations, you can define those locations at configuration time as such:
|
|
|
|
cmake -D<variable>=<value>
|
|
|
|
By default, MaxScale installs to '/usr/local/skysql/maxscale' and places init.d scripts and ldconfig files into their folders. Change the INSTALL_DIR
|
|
variable to your desired installation directory and set INSTALL_SYSTEM_FILES=N to prevent the init.d script and ldconfig file installation.
|
|
|
|
If you run into any trouble while configuring CMake, you can always remove the 'CMakeCache.txt' file to clear CMake's
|
|
internal cache. This resets all values to their defaults and can be used to fix a 'stuck' configuration of CMake. This
|
|
is also a good reason why you should always build into a separate directory, because you can safely wipe the build directory clean without the
|
|
danger of deleting important files when something goes wrong.
|
|
|
|
The default values that CMake uses can be found in the 'macros.cmake' file. If you wish to change these, edit the 'macros.cmake' file
|
|
or define the variables manually at configuration time.
|
|
|
|
All the variables that control the CMake build process:
|
|
|
|
INSTALL_DIR=<path> Installation directory
|
|
|
|
BUILD_TYPE=<type> Type of the build. One of None, Debug, DebugSymbols, Optimized. (default None)
|
|
DebugSymbols enables debugging symbols, Debug enables debugging symbols and code, Optimized builds an optimized version.
|
|
|
|
INSTALL_SYSTEM_FILES=[Y|N] Install startup scripts and ld configuration files
|
|
EMBEDDED_LIB=<path> Path to the embedded library location (libmysqld.a for static and libmysqld.so for dynamic)
|
|
MYSQL_DIR=<path> Path to MySQL headers
|
|
ERRMSG=<path> Path to errmsg.sys file
|
|
STATIC_EMBEDDED=[Y|N] Whether to link the static or the dynamic verson of the library
|
|
GCOV=[Y|N] Generate gcov output
|
|
OLEVEL=<0-3> Level of optimization
|
|
BUILD_TESTS=[Y|N] Build tests
|
|
DEPS_OK=[Y|N] Check dependencies, use N when you want to force a recheck of values
|
|
DEBUG_OUTPUT=[Y|N] Produce debugging output when configuring CMake
|
|
RABBITMQ_LIBRARIES=<path> Path to RabbitMQ-C libraries
|
|
RABBITMQ_HEADERS=<path> Path to RabbitMQ-C headers
|
|
MYSQLCLIENT_LIBRARIES=<path> Path to MySQL client libraries
|
|
MYSQLCLIENT_HEADERS=<path> Path to MySQL client headers
|
|
|
|
\section Running Running MaxScale
|
|
|
|
MaxScale consists of a core executable and a number of modules that implement
|
|
the different protocols and routing algorithms. These modules are built as
|
|
shared objects that are loaded on demand. In order for MaxScale to find these
|
|
modules it will search using a predescribed search path. The rules are:
|
|
|
|
1. Look in the current directory for the module
|
|
|
|
2. Look in $MAXSCALE_HOME/modules
|
|
|
|
3. Look in /usr/local/skysql/MaxScale/modules
|
|
|
|
Configuration is read by default from the file
|
|
$MAXSCALE_HOME/etc/MaxScale.cnf, /etc/MaxScale.cnf, an example file
|
|
is included in the root of the source tree. The default value of
|
|
MAXSCALE_HOME can be overriden by use of the -c flag on the command
|
|
line. This should be immediately followed by the path to the MaxScale
|
|
home directory.
|
|
|
|
The -f flag can be used to set the name and the location of the configuration
|
|
file. Without path expression the file is read from $MAXSCALE_HOME/etc directory.
|
|
|
|
\section Testing Running MaxScale testsuite
|
|
|
|
To run "make testall" you need to have three mysqld servers running
|
|
on localhost:
|
|
|
|
* a master on port 3000, with server_id=2
|
|
* a slave on port 3001, server_id doesn't matter
|
|
* a slave on port 3002, server_id doesn't matter
|
|
|
|
On the master full privileges on the databases "test" and "FOO"
|
|
are needed, on the saves SELECT permissions on test.* should
|
|
be sufficient.
|
|
|
|
You can use different port numbers but you'll have to change
|
|
the server settings at the end of server/test/MaxScale_test.cnf then.
|
|
|
|
You also always need to edit the top level test.inc file,
|
|
this file contains appropriate default values for the
|
|
test setup as described above, these are only given as
|
|
comments though ...
|
|
|
|
You can then run the full testsuite using
|
|
|
|
make testall
|
|
|
|
in the top level directory. After testing has finished you
|
|
can find a full testlog in test/test_maxscale.log
|
|
|
|
You may also find additional information in the following
|
|
component specific logs:
|
|
|
|
utils/test/testutils.log
|
|
query_classifier/test/testqclass.log
|
|
server/test/MaxScale/log/skygw_msg1.log
|
|
server/test/MaxScale/log/skygw_err1.log
|
|
server/test/MaxScale/log/skygw_trace1.log
|
|
server/test/MaxScale/log/skygw_debug1.log
|
|
server/test/testserver.log
|
|
server/core/test/testhash.log
|
|
test/test_maxscale.log
|
|
|
|
|
|
*/
|