hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update MariaDB-MaxScale-Installation-Guide.md

Browse Source 
Updated links, removed redundant chapters about cluster types and replaced
them with a link to the main tutorial, added maxctrl to the administration section.
This commit is contained in:
Markus Mäkelä
2018-07-07 09:47:16 +03:00
committed by GitHub
parent 2df5763b6c
commit 2b5825b040
1 changed files with 18 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
Documentation/Getting-Started/MariaDB-MaxScale-Installation-Guide.md
View File

@ -1,75 +1,14 @@
# MariaDB MaxScale Installation Guide # MariaDB MaxScale Installation Guide
## First Steps With MariaDB MaxScale ## Normal Installation
In this introduction to MariaDB MaxScale the aim is to take the reader Download the MaxScale package from the MariaDB Downloads page:
from the point of installation to making the decision as to which of
the various setups that are possible with MariaDB MaxScale should be
the initial configuration to use. One of the problems that new users to
MariaDB MaxScale suffer is deciding exactly what they should consider
as a base configuration to start exploring what MariaDB MaxScale
is capable of. MariaDB MaxScale is highly configurable,
with new plugins expanding the capabilities of MariaDB MaxScale,
whilst this makes it a very adaptable tool it does lead to an initial
hurdle in configuring MariaDB MaxScale.
## Installation * [https://mariadb.com/downloads/mariadb-tx/maxscale](https://mariadb.com/downloads/mariadb-tx/maxscale)
MariaDB MaxScale can be installed either using the MariaDB Enterprise Repository Select your operating system and download the package. You can also use
or directly from a downloaded package. [the MariaDB package repository](https://mariadb.com/kb/en/library/mariadb-package-repository-setup-and-usage/)
to install MaxScale.
### Using the MariaDB Enterprise Repository
* Go to [https://mariadb.com/my_portal/download](https://mariadb.com/my_portal/download).
* Sign in or create an account for you.
* Select your operating system and follow the instructions.
### From a Downloaded Package
The MaxScale package can be downloaded from the following locations:
* [https://mariadb.com/my_portal/download/maxscale](https://mariadb.com/my_portal/download/maxscale)
* [https://mariadb.com/downloads/maxscale](https://mariadb.com/downloads/maxscale)
Select your operating system and download the package.
Depending on your OS, the package will either be a _deb_ or an _rpm_.
An _rpm_ is installed as follows
```
$ sudo yum install path-to-maxscale-package.rpm
```
and a _deb_ as follows
```
$ sudo dpkg -i path-to-maxscale-package.deb
$ sudo apt-get install -f
```
### Starting MariaDB MaxScale
Before starting MariaDB MaxScale, you need to create a configuration file for it;
please see further [down](#configuring-mariadb-maxscale).
Once a configuration file has been created you can start MariaDB MaxScale:
```
systemctl start maxscale.service
```
If your system does not support systemd you can start MariaDB MaxScale using the
installed init.d script.
```
service maxscale start
```
Starting with version 2.0.3, MaxScale also supports Upstart.
An example configuration file is installed into the `/etc/` folder.
This file should be changed according to your needs.
## Install MariaDB MaxScale Using a Tarball ## Install MariaDB MaxScale Using a Tarball
@ -87,90 +26,13 @@ To do this, refer to the separate document
## Configuring MariaDB MaxScale ## Configuring MariaDB MaxScale
The first step in configuring your MariaDB MaxScale is to determine [The MaxScale Tutorial](../Tutorials/MaxScale-Tutorial.md) covers the first
what it is you want to achieve with your MariaDB MaxScale and what environment steps in configuring your MariaDB MaxScale installation. Follow this tutorial
it will run in. The later is probably the easiest starting point for choosing to learn how to configure and start using MaxScale.
which configuration route you wish to take.
There are two distinct database environments which the first GA release
of MariaDB MaxScale supports; MariaDB Master/Slave Replication clusters and Galera Cluster.
For more details, refer to the [Configuration Guide](Configuration-Guide.md). For a detailed list of all configuration parameters, refer to the
[Configuration Guide](Configuration-Guide.md) and the module specific documents
### Master/Slave Replication Clusters listed in the [Documentation Contents](../Documentation-Contents.md#routers).
There are two major configuration options available to use MariaDB MaxScale
with a MariaDB Replication cluster; connection routing with separate read and
write connections, or read/write splitting with a single connection.
A separate tutorial is available for each of these configurations that
describes how to build the configuration file for MariaDB MaxScale that
will work with your environment.
Using a MariaDB Master/Slave Replication cluster will provide one node server
within the cluster that is the master server and the remainder of the servers
will be slaves. The slaves are read replicas of the master.
In a replication cluster like this all write operations must be performed
on the master.
This can provide not just added security of your data, but also read scalability.
In an application environment with a substantial proportions of read operations,
directing those read operations to the slave servers can increase
the total load which the system can handle by offloading the master server
from the burden of these read operations.
Making the choice between these two setups is relatively simple,
if you have an application that understands that there are some database servers
that it can only read from and one it must send all of the writes to,
then the connection routing option can be used.
Applications that are not written to separate read and write statements must use
a service within MariaDB MaxScale that will split the incoming stream of SQL statements
into operations that can be executed on the master and those that can be set to the slave.
These applications should use the statement based routing provided by
the Read/Write Splitter router.
### Galera Cluster
A Galera Cluster provides a true multi-master cluster option for MariaDB and MySQL
database environments. In such a setup any node that is part of the cluster
can be used to both execute read and write operations.
MariaDB MaxScale again offers two different configurations that can be used with Galera;
a connection balancing configuration or a statement splitting mechanism that can be used
to isolate write operations to a single node within the cluster.
Again there is a tutorial guide available for both of these major configurations.
The connection based load balancing configuration is used in an environment in which
you have a cluster that you want to be available to an application without
the application needing to be aware of the cluster configuration or state of
the database nodes.
MariaDB MaxScale will monitor the nodes within the database cluster and will
route connections from the application to database nodes that
are active members of the cluster.
MariaDB MaxScale will also keep track of the number of connections to each
database node keep equal numbers of connections to each node,
at the time the connection is established.
It is also possible to use the Read/Write Splitter with Galera.
Although it is not necessary to segregate the write operations to a single node,
there are advantages in doing this if you have an application where the write load
is not too great to be handled by a single node in the cluster.
Galera Cluster uses an optimistic locking strategy that will allow transactions
to progress independently on each node within the cluster.
It is only when the transaction commits that the transaction is checked for conflicts
with other transactions that are committing on the other nodes.
At this stage the commit can fail with a deadlock detection error.
This can be inconvenient for applications and, some older applications,
that are not aware that the transaction can fail at this stage
may not check for this failure.
Using the Read/Write Splitter will allow this to be avoided since
it will isolate the write to one node and no deadlock detection will occur.
MariaDB MaxScale provides a monitoring module that will maintain pseudo states
of master and slave for the Galera cluster that allows for this type of configuration.
### Other MariaDB MaxScale Configuration
As well as the four major configuration choices outlined above there are also other
configurations sub-options that may be mixed with those to provide a variety of different
configuration and functionality. The MariaDB MaxScale filter concept allows the basic configurations
to be built upon in a large variety of ways. A separate filter tutorial is available
that discusses the concept and gives some examples of ways to use filters.
## Encrypting Passwords ## Encrypting Passwords
@ -178,30 +40,13 @@ Read the [Encrypting Passwords](Configuration-Guide.md#encrypting-passwords)
section of the configuration guide to set up password encryption for the section of the configuration guide to set up password encryption for the
configuration file. configuration file.
## Running MariaDB MaxScale
MariaDB 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 MariaDB MaxScale to find these
modules it will search using a configurable search path. The priority of these paths are:
1. Look in the directory defined with --libdir=PATH during startup
2. Look in the directory defined with libdir=PATH in the configuration file under the [maxscale] section
3. Look in default directory in /usr/lib64/maxscale
Configuration is read by default from the file /etc/maxscale.cnf. An example file is
included in in the installation and can be found in the /usr/share/maxscale folder within
the MariaDB MaxScale installation. The -f flag can be used on the command line to set
the name and the location of the configuration file. The -C flag can be used to set
the directory where the configuration file is searched for. Without the -f or -C flags,
the file is read from the /etc directory.
## Administration Of MariaDB MaxScale ## Administration Of MariaDB MaxScale
There are various administration tasks that may be done with MariaDB MaxScale, There are various administration tasks that may be done with MariaDB MaxScale.
a client command, maxadmin, is available that will interact with a running Two command line tools are available, `maxctrl` and `maxadmin`, that will interact with a running
MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and MariaDB MaxScale and allow the status of MariaDB MaxScale to be monitored and
give some control of the MariaDB MaxScale functionality. give some control of the MariaDB MaxScale functionality.
There is [a separate reference guide](../Reference/MaxAdmin.md) for the maxadmin utility There are a separate reference guides for the [maxctrl](../Reference/MaxCtrl.md) and [maxadmin](../Reference/MaxAdmin.md) utilities.
and also [a short administration tutorial](../Tutorials/Administration-Tutorial.md)
that covers the common administration tasks that need to be done with MariaDB MaxScale. [The administration tutorial](../Tutorials/Administration-Tutorial.md)
covers the common administration tasks that need to be done with MariaDB MaxScale.