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

Merge branch '2.2' into develop

Browse Source
This commit is contained in:
Markus Mäkelä
2018-03-14 14:30:50 +02:00
parent ec1a4de480 d7c1d76065
commit 9f5d2244ea
31 changed files with 1881 additions and 1095 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
Documentation/Documentation-Contents.md
View File

@ -34,21 +34,19 @@ The main tutorial for MariaDB MaxScale consist of setting up MariaDB MaxScale fo
These tutorials are for specific use cases and module combinations.
- [Connection Routing Tutorial](Tutorials/Connection-Routing-Tutorial.md)
- [Read Write Splitting Tutorial](Tutorials/Read-Write-Splitting-Tutorial
- [Administration Tutorial](Tutorials/Administration-Tutorial.md)
- [Avro Router Tutorial](Tutorials/Avrorouter-Tutorial.md)
- [Failover with Keepalived and MaxCtrl](Tutorials/MaxScale-Failover-with-Keepalived-and-MaxCtrl.md)
- [Filter Tutorial](Tutorials/Filter-Tutorial.md)
- [Galera Cluster Connection Routing Tutorial](Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md)
- [Galera Gluster Read Write Splitting Tutorial](Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md)
- [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md)
- [MariaDB Replication Connection Routing Tutorial](Tutorials/MariaDB-Replication-Connection-Routing-Tutorial.md)
- [MariaDB Replication Read Write Splitting Tutorial](Tutorials/MariaDB-Replication-Read-Write-Splitting-Tutorial.md)
- [MaxScale Failover with Keepalived and MaxCtrl](Tutorials/MaxScale-Failover-with-Keepalived-and-MaxCtrl.md)
- [MariaDB Monitor Failover Tutorial](Tutorials/MariaDB-Monitor-Failover.md)
- [MariaDB MaxScale Information Schema Tutorial](Tutorials/MaxScale-Information-Schema.md)
- [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md)
- [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md)
- [Replication Proxy with the Binlog Router Tutorial](Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md)
- [Simple Schema Sharding Tutorial](Tutorials/Simple-Sharding-Tutorial.md)
- [Filter Tutorial](Tutorials/Filter-Tutorial.md)
- [MySQL Cluster Setup](Tutorials/MySQL-Cluster-Setup.md)
- [RabbitMQ and Tee Filter Data Archiving Tutorial](Tutorials/RabbitMQ-And-Tee-Archiving.md)
- [RabbitMQ Setup and MariaDB MaxScale Integration Tutorial](Tutorials/RabbitMQ-Setup-And-MaxScale-Integration.md)
Here are tutorials on monitoring and managing MariaDB MaxScale in cluster environments.

36
Documentation/Tutorials/Configuring-Galera-Monitor.md Normal file
View File

@ -0,0 +1,36 @@
# Configuring the Galera Monitor
This document describes how to configure a Galera cluster monitor.
## Configuring the Monitor
Define the monitor that monitors the servers.
```
[Galera-Monitor]
type=monitor
module=galeramon
servers=dbserv1, dbserv2, dbserv3
user=monitor_user
password=my_password
monitor_interval=2000
```
The mandatory parameters are the object type, the monitor module to use, the
list of servers to monitor and the username and password to use when connecting
to the servers. The `monitor_interval` parameter controls how many milliseconds
the monitor waits between each monitoring loop.
This monitor module will assign one node within the Galera Cluster as the
current master and other nodes as slave. Only those nodes that are active
members of the cluster are considered when making the choice of master node. The
master node will be the node with the lowest value of `wsrep_local_index`.
## Monitor User
The monitor user does not require any special grants to monitor a Galera
cluster. To create a user for the monitor, execute the following SQL.
```
CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'my_password';
```

33
Documentation/Tutorials/Configuring-MariaDB-Monitor.md Normal file
View File

@ -0,0 +1,33 @@
# Configuring the MariaDB Monitor
This document describes how to configure a MariaDB master-slave cluster monitor
to be used with MaxScale.
## Configuring the Monitor
Define the monitor that monitors the servers.
```
[Replication-Monitor]
type=monitor
module=mariadbmon
servers=dbserv1, dbserv2, dbserv3
user=monitor_user
password=my_password
monitor_interval=2000
```
The mandatory parameters are the object type, the monitor module to use, the
list of servers to monitor and the username and password to use when connecting
to the servers. The `monitor_interval` parameter controls how many milliseconds
the monitor waits between each monitoring loop.
## Monitor User
The monitor user requires the REPLICATION CLIENT privileges to do basic
monitoring. To create a user with the proper grants, execute the following SQL.
```
CREATE USER 'monitor_user'@'%' IDENTIFIED BY 'my_password';
GRANT REPLICATION CLIENT on *.* to 'monitor_user'@'%';
```

21
Documentation/Tutorials/Configuring-MaxAdmin.md Normal file
View File

@ -0,0 +1,21 @@
# Configuring the MaxAdmin Administrative Interface
To configure the service which is used by the `maxadmin` command to connect to
MariaDB MaxScale, add the following service and listener sections to the
configuration file.
```
[CLI]
type=service
router=cli
[CLI-Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
```
This defines a UNIX domain socket which `maxadmin` will use to connect to
MaxScale. MaxAdmin provides monitoring and administration functionality that can
be used to inspect the state of MaxScale.

27
Documentation/Tutorials/Configuring-Servers.md Normal file
View File

@ -0,0 +1,27 @@
# Configuring Servers
The first step is to define the servers that make up the cluster. These servers
will be used by the services and are monitored by the monitor.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MariaDBBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MariaDBBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MariaDBBackend
```
The `address` and `port` parameters tell where the server is located. The
`protocol` should always be set to `MariaDBBackend`.

206
Documentation/Tutorials/Connection-Routing-Tutorial.md Normal file
View File

@ -0,0 +1,206 @@
# Connection Routing with MariaDB MaxScale
The object of this tutorial is to have a system that has two ports
available, one for write connections and another for read connection that
are load balanced across all servers.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md).
Please read it and follow the instructions for setting up MariaDB MaxScale with
the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can
create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template
configuration is provided with the MaxScale installation.
A global `[maxscale]` section is included in every MariaDB MaxScale
configuration file; this is used to set the values of various global parameters,
perhaps the most important of these is the number of threads that MariaDB
MaxScale will use to handle client requests. To automatically configure the
thread count, use the `threads=auto` parameter.
```
[maxscale]
threads=auto
```
## Configuring Servers
Read the [Configuring Servers](Configuring-Servers.md) mini-tutorial to see how
the servers are configured.
## Configuring the Monitor
The next step is the configuration of the monitor. This depends on the type of
cluster you use with MaxScale.
For master-slave clusters read the
[Configuring MariaDB Monitor](Configuring-MariaDB-Monitor.md)
tutorial. If you are using a Galera cluster, read the
[Configuring Galera Monitor](Configuring-Galera-Monitor.md)
tutorial instead.
## Configuring the Service
We want two different ports to which the client application can connect; one
that will be directed to a server where writes can be sent and another that will
load balance between all servers. To achieve this, we need to define two
services in the configuration file.
Create the following two sections in your configuration file. The section
names are the names of the services themselves and should be meaningful to
the administrator. For this tutorial, we use the `Write-Service` and
`Read-Service` names for our services.
```
[Write-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw
[Read-Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw
```
The router module for these two sections is identical, the `readconnroute`
module.
The services must be provided with the list of servers where queries
will be routed to. The server names given here are the names of server sections
in the configuration file (to be defined later) and not the physical hostnames
or addresses of the servers.
In order to instruct the router to which servers it should route we must add the
`router_options` parameter to the service. This parameter tells what sort of
servers the service will use. For the write service we use the _master_ type and
for the read service we use the _slave_ type.
The final part of the service configuration is the `user` and `password`
parameters that define the credentials that the service will use to populate the
user authentication data. To create this user, execute the following SQL commands.
```
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
```
**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md).
## Configuring the Listener
In order to allow network connections to the service, we must associate a network
port with the service. This is done by creating a separate listener section in
the configuration file. A service may have multiple listeners but for this
tutorial we will only need one per service.
```
[Write-Listener]
type=listener
service=Write-Service
protocol=MariaDBClient
port=3306
[Read-Listener]
type=listener
service=Read-Service
protocol=MariaDBClient
port=3307
```
The `service` parameter tells to which service the listener connects to. For the
`Write-Listener` we set it to `Write-Service` and for the `Read-Listener` we set
it to `Read-Service`.
A listener must also define the protocol module it will use for the incoming
network protocol (must be the `MariaDBClient` protocol for all database
listeners) as well as the the network port to listen on.
Additionally, the `address` parameter may be given if the listener is required
to bind to a particular network interface when the host machine has multiple
network interfaces. The default behavior is to listen on all network interfaces
(the IPv6 address `::`).
## Configuring the Administrative Interface
The MaxAdmin configuration is described in the
[Configuring MaxAdmin](Configuring-MaxAdmin.md) document.
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be
started for the first time. For newer systems that use systemd, use the _systemctl_ command.
```
sudo systemctl start maxscale
```
For older SysV systems, use the _service_ command.
```
sudo service maxscale start
```
If MaxScale fails to start, check the error log in
`/var/log/maxscale/maxscale.log` to see if any errors are detected in the
configuration file. The `maxadmin` command may be used to confirm that MariaDB
MaxScale is running and the services, listeners and servers have been correctly
configured.
```
% sudo maxadmin list services
Services.
--------------------------+-------------------+--------+----------------+-------------------
Service Name | Router Module | #Users | Total Sessions | Backend databases
--------------------------+-------------------+--------+----------------+-------------------
Write-Service | readconnroute | 1 | 1 | dbserv1, dbserv2, dbserv3
Read-Service | readconnroute | 1 | 1 | dbserv1, dbserv2, dbserv3
CLI | cli | 2 | 3 |
--------------------------+-------------------+--------+----------------+-------------------
% sudo maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+--------------------
% sudo maxadmin list listeners
Listeners.
---------------------+---------------------+--------------------+-----------------+-------+--------
Name | Service Name | Protocol Module | Address | Port | State
---------------------+---------------------+--------------------+-----------------+-------+--------
Write-Listener | Write-Service | MariaDBClient | * | 3306 | Running
Read-Listener | Read-Service | MariaDBClient | * | 3307 | Running
CLI-Listener | CLI | maxscaled | default | 0 | Running
---------------------+---------------------+--------------------+-----------------+-------+--------
```
MariaDB MaxScale is now ready to start accepting client connections and routing
them to the cluster. More options may be found in the
[Configuration Guide](../Getting-Started/Configuration-Guide.md)
and in the [readconnroute module documentation](../Routers/ReadConnRoute.md).
More detail on the use of `maxadmin` can be found in the
[MaxAdmin](../Reference/MaxAdmin.md) document.

34
Documentation/Tutorials/Encrypting-Passwords.md Normal file
View File

@ -0,0 +1,34 @@
# Encrypting Passwords
There are two options for representing the password, either plain text or
encrypted passwords may be used. In order to use encrypted passwords a set of
keys must be generated that will be used by the encryption and decryption
process. To generate the keys use the `maxkeys` command and pass the name of the
secrets file in which the keys are stored.
```
maxkeys /var/lib/maxscale/.secrets
```
Once the keys have been created the `maxpasswd` command can be used to generate
the encrypted password.
```
maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
```
The username and password, either encrypted or plain text, are stored in the
service section using the `user` and `password` parameters.
Here is an example configuration that uses an encrypted password.
```
[My-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=96F99AA1315BDC3604B006F427DD9484
```

268
Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md
View File

@ -1,268 +0,0 @@
# Connection Routing with Galera Cluster
# Environment & Solution Space
The object of this tutorial is to have a system that has two ports available, one for
write connections to the database cluster and the other for read connections to the database.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md).
Please read it and follow the instructions for setting up MariaDB MaxScale with the
type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create
the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale configuration is held in an ini file that is located in the file maxscale.cnf
in the directory /etc, if you have installed in the default location then this file
is available in /etc/maxscale.cnf. This is not created as part of the installation process
and must be manually created. A template file does exist within the /usr/share/maxscale directory
that may be use as a basis for your configuration.
A global, maxscale, section is included within every MariaDB MaxScale configuration file;
this is used to set the values of various MariaDB MaxScale wide parameters, perhaps
the most important of these is the number of threads that MariaDB MaxScale will use
to execute the code that forwards requests and handles responses for clients.
```
[maxscale]
threads=4
```
Since we are using Galera Cluster and connection routing we want a single to which
the client application can connect; MariaDB MaxScale will then route connections to
this port onwards to the various nodes within the Galera Cluster. To achieve this
within MariaDB MaxScale we need to define a service in the ini file. Create a section
for each in your MariaDB MaxScale configuration file and set the type to service,
the section name is the names of the service and should be meaningful to
the administrator. Names may contain whitespace.
```
[Galera Service]
type=service
```
The router for this section the readconnroute module, also the service should be
provided with the list of servers that will be part of the cluster. The server names
given here are actually the names of server sections in the configuration file and not
the physical hostnames or addresses of the servers.
```
[Galera Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
```
In order to instruct the router to which servers it should route we must add router
options to the service. The router options are compared to the status that the monitor
collects from the servers and used to restrict the eligible set of servers to which that
service may route. In our case we use the option that restricts us to servers that are
fully functional members of the Galera cluster which are able to support SQL operations
on the cluster. To achieve this we use the router option synced.
```
[Galera Service]
type=service
router=readconnroute
router_options=synced
servers=dbserv1, dbserv2, dbserv3
```
The final step in the service section is to add the username and password that will be
used to populate the user data from the database cluster. There are two options for
representing the password, either plain text or encrypted passwords may be used.
In order to use encrypted passwords a set of keys must be generated that will be used
by the encryption and decryption process. To generate the keys use the maxkeys command
and pass the name of the secrets file in which the keys are stored.
```
% maxkeys /var/lib/maxscale/.secrets
%
```
Once the keys have been created the maxpasswd command can be used to generate
the encrypted password.
```
% maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
%
```
The username and password, either encrypted or plain text, are stored in the service
section using the user and passwd parameters.
```
[Galera Service]
type=service
router=readconnroute
router_options=synced
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the service, however listening ports must
be associated with a service in order to allow network connections. This is done by
creating a series of listener sections. These sections again are named for the convenience
of the administrator and should be of type listener with an entry labeled service which
contains the name of the service to associate the listener with.
Each service may have multiple listeners.
```
[Galera Listener]
type=listener
service=Galera Service
```
A listener must also define the protocol module it will use for the incoming
network protocol, currently this must be the `MariaDBClient` protocol for all
database listeners. The listener must also supply the network port to listen on.
```
[Galera Listener]
type=listener
service=Galera Service
protocol=MariaDBClient
port=4306
```
An address parameter may be given if the listener is required to bind to a particular
network address when using hosts with multiple network addresses.
The default behavior is to listen on all network interfaces.
The next stage is the configuration is to define the server information.
This defines how to connect to each of the servers within the cluster, again a section
is created for each server, with the type set to server, the network address and port to
connect to and the protocol to use to connect to the server. Currently the protocol for
all database connections in MariaDBBackend.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MariaDBBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MariaDBBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MariaDBBackend
```
In order for MariaDB MaxScale to monitor the servers using the correct monitoring
mechanisms a section should be provided that defines the monitor to use and
the servers to monitor. Once again a section is created with a symbolic name for
the monitor, with the type set to monitor. Parameters are added for the module to use,
the list of servers to monitor and the username and password to use when connecting to
the servers with the monitor.
```
[Galera Monitor]
type=monitor
module=galeramon
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
As with the password definition in the server either plain text or encrypted
passwords may be used.
The final stage in the configuration is to add the option service which is used by
the maxadmin command to connect to MariaDB MaxScale for monitoring and
administration purposes. This creates a service section and a listener section.
```
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
```
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be
started for the first time. This may either be done manually by running the
maxscale command or via the service interface.
```
% maxscale
```
or
```
% service maxscale start
```
Check the error log in /var/log/maxscale to see if any errors are detected in
the configuration file and to confirm MariaDB MaxScale has been started.
Also the maxadmin command may be used to confirm that MariaDB MaxScale is running
and the services, listeners etc have been correctly configured.
```
% maxadmin list services
Services.
--------------------------+----------------------+--------+---------------
Service Name | Router Module | #Users | Total Sessions
--------------------------+----------------------+--------+---------------
Galera Service | readconnroute | 1 | 1
CLI | cli | 2 | 2
--------------------------+----------------------+--------+---------------
% maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+-------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Synced, Master
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Synced, Slave
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Slave
-------------------+-----------------+-------+-------------+--------------------
```
A Galera Cluster is a multi-master clustering technology, however the monitor is able
to impose false notions of master and slave roles within a Galera Cluster in order to
facilitate the use of Galera as if it were a standard MariaDB Replication setup.
This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster.
You can control which Galera node is the master server by using the _priority_
mechanism of the Galera Monitor module. For more details,
read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation.
```
% maxadmin list listeners
Listeners.
---------------------+--------------------+-----------------+-------+--------
Service Name | Protocol Module | Address | Port | State
---------------------+--------------------+-----------------+-------+--------
Galera Service | MariaDBClient | * | 4306 | Running
CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
%
```
MariaDB MaxScale is now ready to start accepting client connections and routing
them to the master or slaves within your cluster. Other configuration options are
available that can alter the criteria used for routing, such as using weights to
obtain unequal balancing operations.
These options may be found in the MariaDB MaxScale Configuration Guide.
More detail on the use of maxadmin can be found in the document
["MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application"](../Reference/MaxAdmin.md).

203
Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md
View File

@ -1,203 +0,0 @@
# Read/Write Splitting with Galera Cluster
## Environment & Solution Space
The object of this tutorial is to have a system that appears to the clients of MariaDB MaxScale as if there is a single database behind MariaDB MaxScale. MariaDB MaxScale will split the statements such that write statements will be sent to the current write-master server in the Galera cluster and read statements will be balanced across the rest of the nodes.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale configuration is held in an ini file that is located in the file `maxscale.cnf` in the directory `/etc`, if you have installed in the default location then this file is available in `/etc/maxscale.cnf`. This is not created as part of the installation process and must be manually created. A template file does exist within the `/usr/share/maxscale` directory that may be use as a basis for your configuration.
A global, maxscale, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to execute the code that forwards requests and handles responses for clients.
```
[maxscale]
threads=4
```
The first step is to create a service for our Read/Write Splitter. Create a section in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Names may contain whitespace.
```
[Splitter Service]
type=service
```
The router for we need to use for this configuration is the readwritesplit module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers.
```
[Splitter Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
```
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
```
% maxkeys /var/lib/maxscale/.secrets
%
```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
```
% maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
%
```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
```
[Splitter Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the service, however listening ports must be associated with the service in order to allow network connections. This is done by creating a series of listener sections. This section again is named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. A service may have multiple listeners.
```
[Splitter Listener]
type=listener
service=Splitter Service
```
A listener must also define the protocol module it will use for the incoming
network protocol, currently this must be the `MariaDBClient` protocol for all
database listeners. The listener must also supply the network port to listen on.
```
[Splitter Listener]
type=listener
service=Splitter Service
protocol=MariaDBClient
port=3306
```
An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces.
The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol module for all database connections in `MariaDBBackend`.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MariaDBBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MariaDBBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MariaDBBackend
```
In order for MariaDB MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor.
```
[Galera Monitor]
type=monitor
module=galeramon
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
As with the password definition in the server either plain text or encrypted passwords may be used.
This monitor module will assign one node within the Galera Cluster as the current master and other nodes as slave. Only those nodes that are active members of the cluster are considered when making the choice of master node. Normally the master node will be the node with the lowest value of the status variable, `WSREP_LOCAL_INDEX`. When cluster membership changes a new master may be elected. In order to prevent changes of the node that is currently master, a parameter can be added to the monitor that will result in the current master remaining as master even if a node with a lower value of `WSREP_LOCAL_INDEX` joins the cluster. This parameter is called `disable_master_failback`.
```
[Galera Monitor]
type=monitor
module=galeramon
disable_master_failback=1
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
Using this option the master node will only change if there is a problem with the current master and never because other nodes have joined the cluster.
The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section.
```
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
```
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface.
```
% maxscale
```
or
```
% service maxscale start
```
Check the error log in `/var/log/maxscale` to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured.
```
% maxadmin list services
Services.
--------------------------+----------------------+--------+---------------
Service Name | Router Module | #Users | Total Sessions
--------------------------+----------------------+--------+---------------
Splitter Service | readwritesplit | 1 | 1
CLI | cli | 2 | 2
--------------------------+----------------------+--------+---------------
% maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Synced, Master
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Synced, Slave
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Synced, Slave
-------------------+-----------------+-------+-------------+--------------------
```
A Galera Cluster is a multi-master clustering technology, however the monitor is able to impose false notions of master and slave roles within a Galera Cluster in order to facilitate the use of Galera as if it were a standard MariaDB Replication setup. This is merely an internal MariaDB MaxScale convenience and has no impact on the behavior of the cluster but does allow the monitor to create these pseudo roles which are utilized by the Read/Write Splitter.
You can control which Galera node is the master server by using the _priority_ mechanism of the Galera Monitor module. For more details, read the [Galera Monitor](../Monitors/Galera-Monitor.md) documentation.
```
% maxadmin list listeners
Listeners.
---------------------+--------------------+-----------------+-------+--------
Service Name | Protocol Module | Address | Port | State
---------------------+--------------------+-----------------+-------+--------
Splitter Service | MariaDBClient | * | 3306 | Running
CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
```
MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide. More details on the use of maxadmin can be found in the document _MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application_.

233
Documentation/Tutorials/MariaDB-Replication-Connection-Routing-Tutorial.md
View File

@ -1,233 +0,0 @@
# Connection Routing with MariaDB Replication
# Environment & Solution Space
The object of this tutorial is to have a system that has two ports available, one for write connections to the database cluster and the other for read connections to the database.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the instructions for setting up MariaDB MaxScale with the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template configuration is provided with the MaxScale installation.
A global, `[maxscale]`, section is included within every MariaDB MaxScale configuration file; this is used to set the values of various MariaDB MaxScale wide parameters, perhaps the most important of these is the number of threads that MariaDB MaxScale will use to handle client requests.
```
[maxscale]
threads=4
```
Since we are using MariaDB Replication and connection routing we want two different ports to which the client application can connect; one that will be directed to the current master within the replication cluster and another that will load balance between the slaves. To achieve this within MariaDB MaxScale we need to define two services in the ini file; one for the read/write operations that should be executed on the master server and another for connections to one of the slaves. Create a section for each in your MariaDB MaxScale configuration file and set the type to service, the section names are the names of the services themselves and should be meaningful to the administrator. Avoid using whitespace in the section names.
```
[Write-Service]
type=service
[Read-Service]
type=service
```
The router for these two sections is identical, the readconnroute module, also the services should be provided with the list of servers that will be part of the cluster. The server names given here are actually the names of server sections in the configuration file and not the physical hostnames or addresses of the servers.
```
[Write-Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
[Read-Service]
type=service
router=readconnroute
servers=dbserv1, dbserv2, dbserv3
```
In order to instruct the router to which servers it should route we must add router options to the service. The router options are compared to the status that the monitor collects from the servers and used to restrict the eligible set of servers to which that service may route. In our case we use the two options master and slave for our two services.
```
[Write-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
[Read-Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
```
The final step in the service sections is to add the username and password that will be used to populate the user data from the database cluster. There are two options for representing the password, either plain text or encrypted passwords may be used. In order to use encrypted passwords a set of keys must be generated that will be used by the encryption and decryption process. To generate the keys use the maxkeys command and pass the name of the secrets file in which the keys are stored.
```
maxkeys /var/lib/maxscale/.secrets
```
Once the keys have been created the maxpasswd command can be used to generate the encrypted password.
```
maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
```
The username and password, either encrypted or plain text, are stored in the service section using the user and passwd parameters.
```
[Write-Service]
type=service
router=readconnroute
router_options=master
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
[Read-Service]
type=service
router=readconnroute
router_options=slave
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the definitions required by the services, however listening ports must be associated with the services in order to allow network connections. This is done by creating a series of listener sections. These sections again are named for the convenience of the administrator and should be of type listener with an entry labeled service which contains the name of the service to associate the listener with. Each service may have multiple listeners.
```
[Write-Listener]
type=listener
service=Write-Service
[Read-Listener]
type=listener
service=Read-Service
```
A listener must also define the protocol module it will use for the incoming
network protocol, currently this must be the `MariaDBClient` protocol for all
database listeners. The listener must also supply the network port to listen on.
```
[Write-Listener]
type=listener
service=Write-Service
protocol=MariaDBClient
port=4306
[Read-Listener]
type=listener
service=Read-Service
protocol=MariaDBClient
port=4307
```
An address parameter may be given if the listener is required to bind to a particular network address when using hosts with multiple network addresses. The default behavior is to listen on all network interfaces.
The next stage is the configuration is to define the server information. This defines how to connect to each of the servers within the cluster, again a section is created for each server, with the type set to server, the network address and port to connect to and the protocol to use to connect to the server. Currently the protocol for all database connections in MariaDBBackend.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MariaDBBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MariaDBBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MariaDBBackend
```
In order for MariaDB MaxScale to monitor the servers using the correct monitoring mechanisms a section should be provided that defines the monitor to use and the servers to monitor. Once again a section is created with a symbolic name for the monitor, with the type set to monitor. Parameters are added for the module to use, the list of servers to monitor and the username and password to use when connecting to the the servers with the monitor.
```
[Replication-Monitor]
type=monitor
module=mariadbmon
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
monitor_interval=10000
```
As with the password definition in the server either plain text or encrypted passwords may be used.
The final stage in the configuration is to add the option service which is used by the maxadmin command to connect to MariaDB MaxScale for monitoring and administration purposes. This creates a service section and a listener section.
```
[CLI]
type=service
router=cli
[CLI-Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
```
# Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface.
```
maxscale
```
or
```
service maxscale start
```
Check the error log in /var/log/maxscale/ to see if any errors are detected in the configuration file and to confirm MariaDB MaxScale has been started. Also the maxadmin command may be used to confirm that MariaDB MaxScale is running and the services, listeners etc have been correctly configured.
```
% maxadmin list services
Services.
--------------------------+----------------------+--------+---------------
Service Name | Router Module | #Users | Total Sessions
--------------------------+----------------------+--------+---------------
Read Service | readconnroute | 1 | 1
Write Service | readconnroute | 1 | 1
CLI | cli | 2 | 2
--------------------------+----------------------+--------+---------------
% maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+--------------------
% maxadmin list listeners
Listeners.
---------------------+--------------------+-----------------+-------+--------
Service Name | Protocol Module | Address | Port | State
---------------------+--------------------+-----------------+-------+--------
Read Service | MariaDBClient | * | 4307 | Running
Write Service | MariaDBClient | * | 4306 | Running
CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
```
MariaDB MaxScale is now ready to start accepting client connections and routing them to the master or slaves within your cluster. Other configuration options are available that can alter the criteria used for routing, these include monitoring the replication lag within the cluster and routing only to slaves that are within a predetermined delay from the current master or using weights to obtain unequal balancing operations. These options may be found in the MariaDB MaxScale Configuration Guide.
More detail on the use of maxadmin can be found in the document [MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).

248
Documentation/Tutorials/MariaDB-Replication-Read-Write-Splitting-Tutorial.md
View File

@ -1,248 +0,0 @@
# Read/Write Splitting with MariaDB Replication
## Environment & Solution Space
The object of this tutorial is to have a system that appears to the clients of
MariaDB MaxScale as if there was a single database behind MariaDB MaxScale.
MariaDB MaxScale will split the statements such that write statements will be
sent to the current master server in the replication cluster and read statements
will be balanced across the rest of the slave servers.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in
[MariaDB MaxScale Tutorial](MaxScale-Tutorial.md). Please read it and follow the
instructions for setting up MariaDB MaxScale with the type of cluster you want
to use.
Once you have MariaDB MaxScale installed and the database users created, the
configuration file for MariaDB MaxScale can be written.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale configuration is defined in the file `maxscale.cnf` located in
the directory `/etc`. If you have installed MaxScale in the default location the
file path should be `/etc/maxscale.cnf`. This file is not created as part of the
installation process and must be manually created. A template file, which may be
used as a basis for your configuration, exists within the `/usr/share/maxscale`
directory.
A global section, marked `maxscale`, is included within every MariaDB MaxScale
configuration file. The section is used to set the values of various
process-wide parameters, for example the number of worker threads.
```
[maxscale]
threads=4
```
The first step is to create a Read/Write Splitter service. Create a section in
your configuration file and set the type to service. The section header is the
name of the service and should be meaningful to the administrator. Names may
contain whitespace.
```
[Splitter Service]
type=service
```
The router module needed for this service is named `readwritesplit`. The service
must contain a list of backend server names. The server names are the headers of
server sections in the configuration file and not the physical hostnames or
addresses of the servers.
```
[Splitter Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
```
The final step in the service section is to add the username and password that
will be used to populate the user data from the database cluster. There are two
options for representing the password: either plain text or encrypted passwords.
To use encrypted passwords, a set of keys for encryption/decryption must be
generated. To generate the keys use the `maxkeys` command and pass the name of
the secrets file containing the keys.
```
maxkeys /var/lib/maxscale/.secrets
```
Once the keys have been created, use the `maxpasswd` command to generate the
encrypted password.
```
maxpasswd plainpassword
96F99AA1315BDC3604B006F427DD9484
```
The username and password, either encrypted or in plain text, are stored in the
service section.
```
[Splitter Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
This completes the service definition. To have the service accept network
connections, a listener must be associated with it. The listener is defined in
its own section. The type should be `listener` with an entry `service` defining
the name of the service the listener is listening for. A service may have
multiple listeners.
```
[Splitter Listener]
type=listener
service=Splitter Service
```
A listener must also define the protocol module it will use for the incoming
network protocol, currently this must be the `MariaDBClient` protocol for all
database listeners. The listener must also supply the network port to listen on.
```
[Splitter Listener]
type=listener
service=Splitter Service
protocol=MariaDBClient
port=3306
```
An address parameter may be given if the listener is required to bind to a
particular network address when using hosts with multiple network addresses. The
default behavior is to listen on all network interfaces.
The next stage in the configuration is to define the backend servers. The
definitions include how to connect to the servers. A section is created for each
server and it contains: `type` set to `server`, the network address and port,
and the protocol to use. Currently, the protocol module for all database
connections is `MariaDBBackend`.
```
[dbserv1]
type=server
address=192.168.2.1
port=3306
protocol=MariaDBBackend
[dbserv2]
type=server
address=192.168.2.2
port=3306
protocol=MariaDBBackend
[dbserv3]
type=server
address=192.168.2.3
port=3306
protocol=MariaDBBackend
```
For MariaDB MaxScale to monitor the servers using the correct monitoring
mechanisms a monitor section should be written. This section defines the monitor
module to use and the monitored servers. The section `type` should be set to
`monitor`. Parameters added include: the list of servers to monitor and the
username and password the monitor module should use when connecting.
```
[Replication Monitor]
type=monitor
module=mariadbmon
servers=dbserv1, dbserv2, dbserv3
user=maxscale
passwd=96F99AA1315BDC3604B006F427DD9484
```
Similarly to the password definition in the server either a plain text or an
encrypted password may be used.
The final stage in the configuration is to add the service which used by the
`maxadmin` command to connect to MariaDB MaxScale for monitoring and
administration purposes. The example below shows a service section and a
listener section.
```
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
```
# Starting MariaDB MaxScale
Upon completion of the configuration MariaDB MaxScale is ready to be started.
This may either be done manually by running the `maxscale` command or via the
service interface.
```
% maxscale
```
or
```
% service maxscale start
```
Check the error log in /var/log/maxscale to see if any errors are detected in
the configuration file and to confirm MariaDB MaxScale has been started. Also
the maxadmin command may be used to confirm that MariaDB MaxScale is running and
the services, listeners etc have been correctly configured.
```
% maxadmin list services
Services.
--------------------------+----------------------+--------+---------------
Service Name | Router Module | #Users | Total Sessions
--------------------------+----------------------+--------+---------------
Splitter Service | readwritesplit | 1 | 1
CLI | cli | 2 | 2
--------------------------+----------------------+--------+---------------
% maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+--------------------
% maxadmin list listeners
Listeners.
---------------------+--------------------+-----------------+-------+--------
Service Name | Protocol Module | Address | Port | State
---------------------+--------------------+-----------------+-------+--------
Splitter Service | MariaDBClient | * | 3306 | Running
CLI | maxscaled | localhost | 6603 | Running
---------------------+--------------------+-----------------+-------+--------
```
MariaDB MaxScale is now ready to start accepting client connections and routing
them to the master or slaves within your cluster. Other configuration options,
that can alter the criteria used for routing, are available. These include
monitoring the replication lag within the cluster and routing only to slaves
that are within a predetermined delay from the current master or using weights
to obtain unequal balancing operations. These options may be found in the
MariaDB MaxScale Configuration Guide. More details on the use of maxadmin can be
found in the document
[MaxAdmin - The MariaDB MaxScale Administration & Monitoring Client Application](Administration-Tutorial.md).

172
Documentation/Tutorials/MaxScale-Tutorial.md
View File

@ -1,103 +1,42 @@
# Setting up MariaDB MaxScale
This document is designed as a quick introduction to setting up MariaDB MaxScale
in an environment in which you have either a MariaDB Master-Slave replication cluster
with one master and multiple slave servers or a multi-node Galera cluster.
The process of setting and configuring MariaDB MaxScale will be covered within this document.
This document is designed as a quick introduction to setting up MariaDB MaxScale.
The installation and configuration of the MariaDB Replication or the Galera cluster
will not be covered nor will any discussion of installation management tools
to handle automated or semi-automated failover of the replication cluster.
The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/)
The installation and configuration of the MariaDB Server will not be covered in
this document. The [Setting Up Replication](https://mariadb.com/kb/en/mariadb/setting-up-replication/)
article on the MariaDB knowledgebase can help you get started with replication clusters
and the [Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/) article will help you set up a Galera cluster.
and the
[Getting Started With Mariadb Galera Cluster](https://mariadb.com/kb/en/mariadb/getting-started-with-mariadb-galera-cluster/)
article will help you set up a Galera cluster.
This tutorial will assume the user is running from one of the binary distributions
available and has installed this in the default location.
Building from source code in GitHub is covered in the
[Building from Source](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
## Process
## Installing MaxScale
The steps involved in setting up MariaDB MaxScale are:
* Install the package relevant to your distribution
* Create the required users in your MariaDB or MySQL Replication cluster
* Create a MariaDB MaxScale configuration file
## Installation
The precise installation process will vary from one distribution to another
details of what to do with the RPM and DEB packages can be found on the download
site when you select the distribution you are downloading from.
The process involves setting up your package manager to include the MariaDB repositories
and then running the package manager for your distribution (usually yum or apt-get).
Upon successful completion of the installation command you will have MariaDB MaxScale
installed and ready to be run but without a configuration.
You must create a configuration file before you first run MariaDB MaxScale
which is covered in a later section.
The precise installation process will vary from one distribution to another.
Details of what to do with the RPM and DEB packages
[can be found on the MaxScale download page](https://mariadb.com/downloads/mariadb-tx/maxscale)
when you select the distribution you are downloading from.
## Creating Database Users
MariaDB MaxScale needs to connect to the backend databases and run queries for
two reasons; one to determine the current state of the database and the other to
retrieve the user information for the database cluster. The first pair of
credentials will be used by the monitor modules and the second is used by
MariaDB MaxScale itself. This may be done either using two separate usernames
or with a single user.
The first user required must be able to select data from the table mysql.user,
to create this user follow the steps below.
1. Connect to the current master server in your replication tree as the root user
2. Create the user, substituting the username, password and host on which maxscale
runs within your environment
```
MariaDB [(none)]> create user '*username*'@'*maxscalehost*' identified by '*password*';
**Query OK, 0 rows affected (0.00 sec)**
```
3. Grant select privileges on the mysql.user table.
```
MariaDB [(none)]> grant SELECT on mysql.user to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.03 sec)**
```
Additionally, `SELECT` privileges on the `mysql.db` and `mysql.tables_priv` tables
and `SHOW DATABASES` privileges are required in order to load databases name
and grants suitable for database name authorization.
```
MariaDB [(none)]> GRANT SELECT ON mysql.db TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
MariaDB [(none)]> GRANT SELECT ON mysql.tables_priv TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
MariaDB [(none)]> GRANT SHOW DATABASES ON *.* TO 'username'@'maxscalehost';
**Query OK, 0 rows affected (0.00 sec)**
```
The second user is used to monitored the state of the cluster. This user, which may be
the same username as the first, requires permissions to access the various sources
of monitoring data. In order to monitor a replication cluster this user must be granted
the role REPLICATION CLIENT. This is only required by the MySQL monitor
and Multi-Master monitor modules.
After installation, we need to create a database user. We do this as we need to
connect to the backend databases to retrieve the user authentication
information. To create this user, execute the following SQL commands.
```
MariaDB [(none)]> grant REPLICATION CLIENT on *.* to '*username*'@'*maxscalehost*';
**Query OK, 0 rows affected (0.00 sec)**
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
```
If you wish to use two different usernames for the two different roles of monitoring
and collecting user information then create a different username using the first
two steps from above.
These credentials will be used by the services in MaxScale to populate the user
authentication data. The tutorials that follow will be using these credentials.
## Creating additional grants for users
@ -106,64 +45,49 @@ two steps from above.
Because MariaDB MaxScale sits between the clients and the backend databases, the
backend databases will see all clients as if they were connecting from MariaDB
MaxScale's address. This usually requires users to create additional grants for
MariaDB MaxScale's hostname. The best way to describe this process is with an
example.
MaxScale's address. This usually means that you must create two sets of grants
for each user.
User `'jdoe'@'192.168.0.200` has the following grant on the cluster:
`GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200'`.
When the user connects directly to the server it will see it as
`'jdoe'@'192.168.0.200` connecting to the server and it will match
the grant for `'jdoe'@'192.168.0.200`.
For example, if you have the `'jdoe'@'client-host'` user and MaxScale is located
at `maxscale-host`, the `'jdoe'@'maxscale-host'` user must be created with the
same password as `'jdoe'@'client-host'` and given the same grants that
`'jdoe'@'client-host'` has.
If MariaDB MaxScale is at the address `192.168.0.101` and the user `jdoe`
connects to this MariaDB MaxScale, the backend server will see the connection as
`'jdoe'@'192.168.0.101'`. Since the backend server has no grants for
`'jdoe'@'192.168.0.101'`, the connection from MariaDB MaxScale to the server
will be refused.
The quickest way to do this is to first create the new user:
We can fix this by either creating a matching grant for user `jdoe` from
the MariaDB MaxScale address or by using a wildcard to cover both addresses.
The quickest way to do this is by doing a SHOW GRANTS query:
```
MariaDB [(none)]> SHOW GRANTS FOR 'jdoe'@'192.168.0.200';
CREATE USER 'jdoe'@'maxscale-host' IDENTIFIED BY 'my_secret_password';
```
Then do a `SHOW GRANTS` query:
```
MariaDB [(none)]> SHOW GRANTS FOR 'jdoe'@'client-host';
+-----------------------------------------------------------------------+
| Grants for jdoe@192.168.0.200 |
| Grants for jdoe@client-host |
+-----------------------------------------------------------------------+
| GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.200' |
| GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'client-host' |
+-----------------------------------------------------------------------+
1 row in set (0.01 sec)
```
Then creating the user `'jdoe'@'192.168.0.101'` and giving it the same grants:
```
MariaDB [(none)]> CREATE USER 'jdoe'@'192.168.0.101' IDENTIFIED BY 'secret_password';
Query OK, 0 rows affected (0.00 sec)
MariaDB [(none)]> GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'192.168.0.101';
Query OK, 0 rows affected (0.00 sec)
```
The other option is to use a wildcard grant like the following:
Followed by copying grant the same grants to the `'jdoe'@'maxscale-host'` user.
```
GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'%' IDENTIFIED BY 'secret_password'
GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'jdoe'@'maxscale-host';
```
This is more convenient but less secure than having specific grants for both the
client's address and MariaDB MaxScale's address as it allows access from all
Another other option is to use a wildcard grant that covers both hosts. This is
more convenient but less secure than having specific grants for both the
client's hostname and MariaDB MaxScale's hostname as it allows access from all
hosts.
## Creating the configuration file
The configuration file creation is covered in different tutorials.
The next step is to create the configuration file. This part is covered in two
different tutorials.
### Master-Slave cluster
* [MariaDB Replication Connection Routing Tutorial](MariaDB-Replication-Connection-Routing-Tutorial.md)
* [MariaDB Replication Read-Write Splitting Tutorial](MariaDB-Replication-Read-Write-Splitting-Tutorial.md)
### Galera cluster
* [Galera Cluster Connection Routing Tutorial](Galera-Cluster-Connection-Routing-Tutorial.md)
* [Galera Cluster Read Write Splitting Tutorial](Galera-Cluster-Read-Write-Splitting-Tutorial.md)
For a fully automated read/write splitting setup, read the
[Read Write Splitting Tutorial](Read-Write-Splitting-Tutorial.md).
For a simpler connection based setup, read the
[Connection Routing Tutorial](Connection-Routing-Tutorial.md).

179
Documentation/Tutorials/Read-Write-Splitting-Tutorial.md Normal file
View File

@ -0,0 +1,179 @@
# Read/Write Splitting with MariaDB MaxScale
The object of this tutorial is to have a system that appears to the client as a
single database. MariaDB MaxScale will split the statements such that write
statements will be sent to the current master server in the replication cluster
and read statements will be balanced across the rest of the servers.
## Setting up MariaDB MaxScale
The first part of this tutorial is covered in [MariaDB MaxScale Tutorial](MaxScale-Tutorial.md).
Please read it and follow the instructions for setting up MariaDB MaxScale with
the type of cluster you want to use.
Once you have MariaDB MaxScale installed and the database users created, we can
create the configuration file for MariaDB MaxScale.
## Creating Your MariaDB MaxScale Configuration
MariaDB MaxScale reads its configuration from `/etc/maxscale.cnf`. A template
configuration is provided with the MaxScale installation.
A global `[maxscale]` section is included in every MariaDB MaxScale
configuration file; this is used to set the values of various global parameters,
perhaps the most important of these is the number of threads that MariaDB
MaxScale will use to handle client requests. To automatically configure the
thread count, use the `threads=auto` parameter.
```
[maxscale]
threads=auto
```
## Configuring Servers
Read the [Configuring Servers](Configuring-Servers.md) mini-tutorial to see how
the servers are configured.
## Configuring the Monitor
The next step is the configuration of the monitor. This depends on the type of
cluster you use with MaxScale.
For master-slave clusters read the
[Configuring MariaDB Monitor](Configuring-MariaDB-Monitor.md)
tutorial. If you are using a Galera cluster, read the
[Configuring Galera Monitor](Configuring-Galera-Monitor.md)
tutorial instead.
## Configuring the Service
After configuring the servers and the monitor, we create a Read/Write Splitter
service configuration. Create the following section in your configuration
file. The section name is the names of the service and should be meaningful to
the administrator. For this tutorial, we use the `Splitter-Service` name for our
service.
```
[Splitter-Service]
type=service
router=readwritesplit
servers=dbserv1, dbserv2, dbserv3
user=maxscale
password=maxscale_pw
```
The router module we use for this service is `readwritesplit`.
The services must be provided with the list of servers where queries
will be routed to. The server names given here are the names of server sections
in the configuration file (to be defined later) and not the physical hostnames
or addresses of the servers.
The final part of the service configuration is the `user` and `password`
parameters that define the credentials that the service will use to populate the
user authentication data. To create this user, execute the following SQL commands.
```
CREATE USER 'maxscale'@'%' IDENTIFIED BY 'maxscale_pw';
GRANT SELECT ON mysql.user TO 'maxscale'@'%';
GRANT SELECT ON mysql.db TO 'maxscale'@'%';
GRANT SELECT ON mysql.tables_priv TO 'maxscale'@'%';
GRANT SHOW DATABASES ON *.* TO 'maxscale'@'%';
```
**Note:** For increased security [encrypt your passwords in the configuration file](Encrypting-Passwords.md).
## Configuring the Listener
In order to allow network connections to the services, we must associate network
ports with the services. This is done by creating a separate listener section in
the configuration file. A service may have multiple listeners but for this
tutorial we will only need one.
```
[Splitter-Listener]
type=listener
service=Splitter-Service
protocol=MariaDBClient
port=3306
```
The `service` parameter tells to which service the listener connects to. For the
`Splitter-Listener` we set it to `Splitter-Service`.
A listener must also define the protocol module it will use for the incoming
network protocol (must be the `MariaDBClient` protocol for all database
listeners) as well as the the network port to listen on.
Additionally, the `address` parameter may be given if the listener is required
to bind to a particular network interface when the host machine has multiple
network interfaces. The default behavior is to listen on all network interfaces
(the IPv6 address `::`).
## Configuring the Administrative Interface
The MaxAdmin configuration is described in the
[Configuring MaxAdmin](Configuring-MaxAdmin.md) document.
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be
started for the first time. For newer systems that use systemd, use the _systemctl_ command.
```
sudo systemctl start maxscale
```
For older SysV systems, use the _service_ command.
```
sudo service maxscale start
```
If MaxScale fails to start, check the error log in
`/var/log/maxscale/maxscale.log` to see if any errors are detected in the
configuration file. The `maxadmin` command may be used to confirm that MariaDB
MaxScale is running and the services, listeners and servers have been correctly
configured.
```
% sudo maxadmin list services
Services.
--------------------------+-------------------+--------+----------------+-------------------
Service Name | Router Module | #Users | Total Sessions | Backend databases
--------------------------+-------------------+--------+----------------+-------------------
Splitter-Service | readwritesplit | 1 | 1 | dbserv1, dbserv2, dbserv3
CLI | cli | 2 | 3 |
--------------------------+-------------------+--------+----------------+-------------------
% sudo maxadmin list servers
Servers.
-------------------+-----------------+-------+-------------+--------------------
Server | Address | Port | Connections | Status
-------------------+-----------------+-------+-------------+--------------------
dbserv1 | 192.168.2.1 | 3306 | 0 | Running, Slave
dbserv2 | 192.168.2.2 | 3306 | 0 | Running, Master
dbserv3 | 192.168.2.3 | 3306 | 0 | Running, Slave
-------------------+-----------------+-------+-------------+--------------------
% sudo maxadmin list listeners
Listeners.
---------------------+---------------------+--------------------+-----------------+-------+--------
Name | Service Name | Protocol Module | Address | Port | State
---------------------+---------------------+--------------------+-----------------+-------+--------
Splitter-Listener | Splitter-Service | MariaDBClient | * | 3306 | Running
CLI-Listener | CLI | maxscaled | default | 0 | Running
---------------------+---------------------+--------------------+-----------------+-------+--------
```
MariaDB MaxScale is now ready to start accepting client connections and routing
them to the cluster. More options may be found in the
[Configuration Guide](../Getting-Started/Configuration-Guide.md)
and in the [readwritesplit module documentation](../Routers/ReadWriteSplit.md).
More detail on the use of `maxadmin` can be found in the
[MaxAdmin](../Reference/MaxAdmin.md) document.

4
maxscale-system-test/CMakeLists.txt
View File

@ -616,6 +616,10 @@ add_test_executable(mxs1677_temp_table.cpp mxs1677_temp_table replication LABELS
# https://jira.mariadb.org/browse/MXS-1678
add_test_executable(mxs1678_relay_master.cpp mxs1678_relay_master replication LABELS REPL_BACKEND)
# MXS-1713: SchemaRouter unable to process SHOW DATABASES for a lot of schemas
# https://jira.mariadb.org/browse/MXS-1713
add_test_executable(mxs1713_lots_of_databases.cpp mxs1713_lots_of_databases mxs1713_lots_of_databases LABELS REPL_BACKEND)
# 'namedserverfilter' test
add_test_executable(namedserverfilter.cpp namedserverfilter namedserverfilter LABELS namedserverfilter LIGHT REPL_BACKEND)

312
maxscale-system-test/Documentation/BUILD_TEST_DEBUG.md Normal file
View File

@ -0,0 +1,312 @@
# Maxscale Continuous Integration and Test Automation
## Basics
Jenkins at http://max-tst-01.mariadb.com:8089/
is the main tool for providing build and test services for Maxscale,
but note that it _cannot_ be accessed directly (see further down).
A set of virtual machines (VMs) is in use for all building and testing.
The VMs are controlled by [Vagrant](https://www.vagrantup.com/)
and [MDBCI](https://github.com/OSLL/mdbci/).
3 types of VMs are supported:
* Libvirt/qemu
* AWS
* Docker containers
All Jenkins jobs are in
[Jenkins job Builder](https://docs.openstack.org/infra/jenkins-job-builder/)
YAML format and are available
[here](https://github.com/mariadb-corporation/maxscale-jenkins-jobs).
VMs for every build or test run are created from clean Vagrant box.
To speed up regular builds and tests there are a set of constantly running VMs:
* Build machine _centos\_7\_libvirt\_build_
* Test VMs set _centos\_7\_libvirt-mariadb-10.0-permanent_
Build and test Jenkins jobs generate e-mails with results report.
In addition, test run logs are stored [here](http://max-tst-01.mariadb.com/LOGS/).
## Accessing _max-tst-01_
Jenkins running on _max-tst-01_ can only be accessed from localhost. In order
to be able to access it from your computer, an ssh tunnel needs to be setup.
* Ensure that your public key is available on _max-tst-01_.
* Then setup the ssh tunnel:
```
$ ssh -f -N -L 8089:127.0.0.1:8089 vagrant@max-tst-01.mariadb.com
```
After that, Jenkins on _max-tst-01_ can be accessed by browsing to
http://localhost:8089.
In the following it is assumed that the above has been done.
## Build
* [Build](http://localhost:8089/job/build/) builds Maxscale
and creates a binary repository for one Linux distribution.
* [Build_all](http://localhost:8089/job/build_all/) builds
Maxscale and creates binary repository for _all_ supported Linux
distributions.
The list of supported distributions (Vagrant boxes) is
[here](https://github.com/mariadb-corporation/maxscale-jenkins-jobs/blob/master/maxscale_jobs/include/boxes.yaml).
### Main _Build_ and _Build_all_ jobs parameters
To start a build, click on _Build with Parameters_ to the left in
the Jenkins panel.
#### scm_source
The place in Maxscale source code.
* for branch - put branch name here
* for commit ID - put Git Commit ID here
* for tag - put `refs/tags/<tagName>` here
#### box
The name of Vagrant box to create VM.
Box name consists of the name of distribution, distribution version and the name of VM provider.
Whole list of supported boxes can be found [here](https://github.com/mariadb-corporation/maxscale-jenkins-jobs/blob/master/maxscale_jobs/include/boxes_all.yaml)
#### target
Then name of binary repository. Ensure that the name is reasonably
unique so that there can be no unintended overwrites. If you are
building a personal branch, then using the same value for _target_
as is the value for _scm_source_ should be fine.
Binaries will go to:
`http://max-tst-01.mariadb.com/ci-repository/<target>/mariadb-maxscale/<distribution_name>/<version>`
#### cmake_flags
Debug build:
```
-DBUILD_TESTS=Y -DCMAKE_BUILD_TYPE=Debug -DFAKE_CODE=Y -DBUILD_MMMON=Y -DBUILD_AVRO=Y -DBUILD_CDC=Y
```
Release build:
```
-DBUILD_TESTS=N -DFAKE_CODE=N -DBUILD_MMMON=Y -DBUILD_AVRO=Y -DBUILD_CDC=Y
```
Build scripts automatically add all other necessary flags (e.g. -DPACKAGE=Y)
#### do_not_destroy_vm
If `yes`, then the VM will not be destroyed after the build. Choose that **if** you,
for some specific reason (e.g. debugging), intend to log into the VM later.
#### repo_path
The location for binary repositories on _max-tst-01_. Usually no need to change.
#### try_alrady_running
If `yes` constantly running VM will be used for build instead of bringing clean
machines from scratch. The name of VM is `<box_name>_build`.
If this VM is not running it will be created from clean box. If new build
dependency is introduced and new package have to be installed (and build
script is modified to do it) before the build it is necessary to destroy
constantly running VM - in this case a new VM will be created and all stuff
will be installed.
#### run_upgrade_test
If `yes` upgrade test will be executed after build.
Upgrade test is executed on a separate VM.
* First, old version of Maxsale is installed (parameter **old_target**),
* then upgrade to recently built version is executed,
* then Maxscale is started with minimum configuration (only CLI service is
configured, no backend at all), and
* finally, _maxadmin_ is executed to check that Maxscale is running and available.
### Regular automatic builds
File `~/jobs_branches/build_all_branches.list` on _max-tst-02.mariadb.com contains
a list of regexes. If branch name matches one of the regex from this file
_build_all_ job will be executed for this branch every night.
Regular builds are executed with _run\_upgrade\_test=yes_
## Test execution
* [run_test](http://localhost:8089/view/test/job/run_test/) creates a set of
VMs: 1 VM for Maxscale, 4 VMs for Master/Slave setup and VMs for Galera cluster.
### Main _Run_test_ parameters
Before this job can be run, a
[build](#build)
job must have been executed first.
#### target
The name of Maxscale binary repository.
The value used here, should be the same as the value used in [target](#target).
#### box
The name of Vagrant box to create VM.
The value used here, must be the same as the value used in
[box](#box)
when the used **target** was built.
#### product
MariaDB or MySQL to be installed to all backend machines.
#### version
Version of MariaDB or MySQL to be installed on all MariaDB machines.
The list of versions contains all MariaDB and MySQL major version.
Selecting wrong version (e.g. 5.7 for MariaDB or 10.0 for MySQL) causes
VM creation error and job failure.
#### do_not_destroy_vm
If `yes` all VMs will run until manually destoroy by **Destroy** job.
It can be used for debugging. **Do not forget to destroy** VMs after debugging
is finished.
#### name
The name of test run. The names of the VMs will be:
* `<name>_maxscale`,
* `<name>_node_000`, ..., `<name>_node_003` and
* `<name>_galera_000`, ..., `<name>_galera_003`-
The **name** can be used to access VMs:
```bash
. ~/build-scripts/test/set_env_vagrant.sh <name>
ssh -i $<vm_name>_keyfile $<vm_name>_whoami@$<vm_name>_network
```
where `<vm_name>` can be 'maxscale', 'node_XXX' or 'galera_XXX'.
#### test_branch
The name of _MaxScale_ repository branch to be used in the test run.
It is usually the same as the one used in [scm_source](#scm_source).
#### slave_name
Host server to for VMs and _maxscale-system-test_ execution
|Name|Server|
|-------|:---------------------|
|master |localhost|
|maxtst2|max-tst-02.mariadb.com|
|maxtst3|max-tst-03.mariadb.com|
#### test_set
Defines tests to be run. See ctest documentation
https://cmake.org/cmake/help/v3.7/manual/ctest.1.html
for details.
Most common cases:
|Arguments|Description|
|-------------|:--------------------------------------------------|
|-I 1,5,,45,77| Execute tests from 1 to 5 and tests 45 and 77|
|-L HEAVY|Execute all tests with 'HEAVY' label|
|-LE UNSTABLE|Execute all tests except tests with 'UNSTABLE' label|
### Run_test_snapshot
This job uses already running VMs. The set of VMs have to have snapshot
(by default snapshot name is 'clean').
Instead of bringing up all VMs from scratch this job only reverts VMs to
the 'clean' state.
The name of running VMs set should be:
`<box>-<product>-<version>-permanent`
If there is no VMs set with such name it will be created automatically.
If case of broken VMs it can be destroyd with help of **Destroy** job
and **Run_test_snapshot** should be restarted after it to create a new
VMs set.
Only one VMs set on every server can be started for particular **box**,
**product** and **version** combination.
If two **Run_test_snapshot** jobs are runnig for the same
**box**, **product** and **version**
the second one will be waiting until the first job run ios finished.
(job sets 'snapshot_lock').
If case if locak is not removed automatically (for example
due to Jenkins crash) it can be removed manually:
```bash
rm ~/mdbci/centos_7_libvirt-mariadb-10.0-permanent_snapshot_lock
```
### Run_test_labels and Run_test_snapshot_labels
The only difference from **Run_test** and
**Run_test_snapshot** is the way to define set of tests to execute.
**\*_labels** jobs use checkboxes list of test labels.
Labels list have to be maintained manually.
It can be created by
https://github.com/mariadb-corporation/maxscale-jenkins-jobs/blob/master/create_labels_jobs.sh
script.
### Regular test runs
#### Test runs by timer
File
```
~/jobs_branches/run_test_branches.list
```
on max-tst-02.mariadb.com
contains a list of regexes. If branch name matches one of regexes
tests are executed for this branch every day.
The test set is defined also in this file.
Job **print_branches_which_matches_regex_in_file**
http://localhost:8089/view/All/job/print\_branches\_which\_matches\_regex\_in\_file/build
can be used to check the list of branches that match
regexes.
Job **weekly_smoke_run_test_matrix** triggers **build_regular**
and **run_test_matrix**
http://localhost:8089/view/test/job/run_test_matrix/
every week for 'develop' branch
with test set '-L LIGHT' (all tests with label 'LIGHT')
#### Test runs by GIT push
File
```
~/jobs_branches/on_push_maxscale_branches.list
```
on max-tst-02.mariadb.com
contains a list of regexes. If branch name matches one of regexes
tests are executed for this branch after every push.
Job **print_branches_which_matches_regex_in_file**
http://localhost:8089/view/All/job/print\_branches\_which\_matches\_regex\_in\_file/build
can be used to check the list of branches that match
regexes (select _on\_push\_maxscale\_branches.list_
file for _branches\_list_ parameter)
## Debugging
For regular debugging contsntly running set of VMs is recommended.
See [documentation here](DEBUG_ENVIRONMENT.md).
Another way is to use **do_not_destroy=yes** parameter of **run_test** job.
After **run_test** job executing VMs stay running and
can be accessed from the host server. See [here](LOCAL_DEPLOYMENT.md#accessing-vms)
for details.

113
maxscale-system-test/Documentation/DEBUG_ENVIRONMENT.md Normal file
View File

@ -0,0 +1,113 @@
# Debug environment
## Create ssh tunnel to Jenkins server
```bash
ssh -f -N -L 8089:127.0.0.1:8089 vagrant@max-tst-01.mariadb.com
```
## Create environment for debugging
To create virtual machines for debugging please
use Jenkins job 'create_env'
http://127.0.0.1:8089/view/env/job/create_env/build
This Jenkins job creates backend VMs
(4 Master/Slave and 4 Galera) and
Maxscale development machine.
Maxscale development machine will contain all
build tools and build dependencies as well as
Maxscale source Git.
Source is located in:
```
~/MaxScale/
```
## Environmental variables setup
```bash
. ~/build-scripts/test/set_env_vagrant.sh <name>
```
Example:
```bash
. ~/build-scripts/test/set_env_vagrant.sh debug_env
```
## Access to Maxscale VM
```bash
ssh -i $maxscale_sshkey $maxscale_whoami@maxscale_network
```
```bash
scp -i $maxscale_sshkey <stuff_to_copy> $maxscale_whoami@maxscale_network:/home/$maxscale_whoami/
```
```bash
scp -i $maxscale_sshkey $maxscale_whoami@maxscale_network:/home/$maxscale_whoami/<stuff_to_copy> .
```
## Executing tests
Clone https://github.com/mariadb-corporation/maxscale
and build tests
```bash
cd MaxScale/maxscale-system/test
cmake .
make
```
and then run
```bash
ctest -VV
```
or manually any test executable from _maxscale-system-test_
It is recommended to run
```bash
./check_backend
```
before manual testing to be sure Master/Slave and Galera setups are
in order (_check_backend_ also fixes broken replication or Galera)
## Restoring broken setup
Just use http://127.0.0.1:8089/view/snapshot/job/restore_snapshot/build
Manual snapshot reverting:
```bash
~/mdbci/mdbci snapshot revert --path-to-nodes debug_env --snapshot-name clean
```
## Destroying
Use http://127.0.0.1:8089/view/axilary/job/destroy/build
with _name=debug_env_
or _clean_vms.sh_ script
```bash
cd ~/mdbci/scripts
./clean_vms.sh debug_env
```
## Notes
Please check _slave_name_ parameter when executing any Jenkins job.
All jobs are executed only for defined slave (or for master).
i.e. VM set with the same name can be running on different slaves at the same time.

173
maxscale-system-test/Documentation/LOCAL_DEPLOYMENT.md Normal file
View File

@ -0,0 +1,173 @@
# Local deployment
## Prepare MDBCI environment
_Libvirt_, _Docker_ and _Vagrant_, with a set of plugins, are needed for MDBCI.
Please follow the instructions [here](https://github.com/mariadb-corporation/mdbci/blob/integration/PREPARATION_FOR_MDBCI.md).
## Creating VMs for local tests
[test/create_local_config.sh](test/create_local_config.sh) script creates a set of virtual machines
(1 maxscale VM, 4 Master/Slave and 4 Galera).
Direct execution of create_local_config.sh requires manuall paramters setting.
It is easiler to ese create_local_config_libvirt.sh and create_local_config_docker.sh
Script usage:
```bash
. ~/build-scripts/test/create_local_config.sh <target> <name>
```
where
target - Maxscale binary repository name
name - name of virtual machines set
Note: '.' before command allows script to load all environmental variables (needed for 'maxscale-system-test').
All other parameters have to be defined as environmental variables before executing the script.
Examples of parameters definition can be found in the following scripts:
[test/create_local_config_libvirt.sh](test/create_local_config_libvirt.sh)
[test/create_local_config_docker.sh](test/create_local_config_docker.sh)
```bash
. ~/build-scripts/test/create_local_config_libvirt.sh <target> <name>
```
```bash
. ~/build-scripts/test/create_local_config_docker.sh <target> <name>
```
## Execute test
Clone and compile https://github.com/mariadb-corporation/MaxScale
Build tests:
```bash
cd Maxscale/maxscale-system-test
cmake .
make
```
if environmental variables are not set:
```bash
. ~/build-scripts/test/set_env_vagrant.sh <name>
```
Execute single test by starting test binary or use ctest to run all or selected tests (see https://cmake.org/cmake/help/v3.8/manual/ctest.1.html)
To see test output:
```bash
ctest -VV
```
## Destroying VMs
```bash
cd ~/mdbci/scripts
./clean_vms.sh <name>
```
## Reverting default snapshot
create_local_config.sh script takes one snapshot of recently created set of VMs. Snapshot name is 'clean'
If VMs are damaged during testing process it is easy to restore them:
```bash
~/mdbci/mdbci snapshot revert --path-to-nodes <name> --snapshot-name clean
```
If needed, more snapshots can be created:
```bash
cd ~/mdbci
./mdbci snapshot take --path-to-nodes <name> --snapshot-name <snapshot_name>
```
## Accessing VMs
```bash
cd ~/mdbci/<name>
vagrant ssh <vm_name>
```
where <vm_name> can be 'maxscale', 'node_XXX' or 'galera_XXX'.
```bash
. ~/build-scripts/test/set_env_vagrant.sh <name>
ssh -i $<vm_name>_keyfile $<vm_name>_whoami@$<vm_name>_network
```
examples:
```bash
ssh -i $node_002_keyfile $node_002_whoami@$node_002_network
ssh -i $maxscale_keyfile $maxscale_whoami@$maxscale_network
```
### Own VM configuration template
By default scripts use
~/build-scripts/test/template.libvirt.json
and
~/build-scripts/test/template.docker.json
These templates can be used as examples to create your own templates.
To use own template:
put your template file to ~/build-scripts/test/templates/
and define 'template_name' variable
```bash
export template_name=<your_template_filename>
. ~/build-scripts/test/create_local_config_libvirt.sh <target> <name>
```
## Troubleshooting
### More info about libvirt and vagrant-libvirt plugin
https://help.ubuntu.com/lts/serverguide/libvirt.html
https://github.com/vagrant-libvirt/vagrant-libvirt#installation
### vagrant is locked, waiting ...
```bash
rm ~/vagrant_lock
```
### Random VM creation failures
Plese check the amount of free memory and amount of running VMs
```bash
virsh list
docker ps
```
and remove all VMs and containers you do not need
### Wrong time on host server
If server time is wrong it can cause random problems. Please do time sync: use ntp or
```bash
sudo date -s "$(curl -s --head http://google.com | grep ^Date: | sed 's/Date: //g')"
```
### Info from OSLL wiki
#### Libvirt DNS resolving problem quick fix
https://dev.osll.ru/projects/mdbci/wiki/Libvirt_DNS_resolving_problem_quick_fix

91
maxscale-system-test/Documentation/README.md Normal file
View File

@ -0,0 +1,91 @@
# build-scripts-vagrant
Build and test scripts to work with Vagrant-controlled VMs do follwoing:
* create VM for Maxscale build
* create a set of VMs (test environment) for running Maxscale tests
Test environment consists of:
* 'maxscale' machine
* 'nodeN' machines for Master/Slave setup (node0, node1, node2, node3)
* 'galeraN' machines for Galera cluster (galera0, galera1, galera2, galera3)
## Main files
File|Description
----|-----------
[prepare_and_build.sh](prepare_and_build.sh)|Create VM for build and execute build, publish resulting repository
build.\<provider\>.template.json|templates of MDBCI configuration description (build environment description) of build machines|
[test-setup-scripts/setup_repl.sh](test-setup-scripts/setup_repl.sh)|Prepares repl_XXX machines to be configured into Master/Slave
[test-setup-scripts/galera/setup_galera.sh](test-setup-scripts/galera/setup_galera.sh)|Prepares galera_XXX machines to be configured into Galera cluster
[test-setup-scripts/cnf/](test-setup-scripts/cnf/)|my.cnf files for all backend machines
test/template.\<provider\>.json|Templates of MDBCI configuration description (test environment description) of test machines|
[test/run_test.sh](test/run_test.sh)|Creates test environment, build maxscale-system-tests from source and execute tests using ctest
[test/set_env_vagrant.sh](test/set_env_vagrant.sh)|set all environment variables for existing test machines using MDBCI to get all values
[test/create_env.sh](test/create_env.sh)|Creates test environment, copy Maxscale source code to 'maxscale' machine in this environment, build Maxscale
## [prepare_and_build.sh](prepare_and_build.sh)
Following variables have to be defined before executing prepare_and_build.sh
|Variable|Meaning|
|--------|--------|
|$MDBCI_VM_PATH|Path to duirectory to store VM info and Vagrant files (by default $HOME/vms)|
|$box|name of MDBCI box (see [MDBCI docs](https://github.com/OSLL/mdbci#terminology))|
|$target|name of repository to put result of build|
|$scm_source|reference to the place in Maxscale source GIT repo|
|$cmake_flags|additional cmake flags|
|$do_not_destroy_vm|if 'yes' build VM won't be destroyed after the build. NOTE: do not forget destroy it manually|
|$no_repo|if 'yes' repository won't be built|
Scripts creates MDBCI configuration build_$box-<current data and time>.json, bringing it up (the directory build_$box-<current data and time> is created)
Resulting DEB or RPM first go to ~/pre-repo/$target/$box
NOTE: if ~/pre-repo/$target/$box contains older version they will also go to repostory
Resulting repository goes to ~/repository/$target/mariadb-maxscale/
It is recommeneded to publish ~/repository/ directory on a web server
## [test/run_test.sh](test/run_test.sh)
Following variables have to be defined before executing run_test.sh
|Variable|Meaning|
|--------|--------|
|$box|name of MDBCI box for Maxscale machine (see [MDBCI docs](https://github.com/OSLL/mdbci#terminology))|
|$name|unique name of test setup|
|$product|'mariadb' or 'mysql'|
|$version|version of backend DB|
|$target|name of Maxscale repository|
|$ci_url|URL of repostory web site, Maxscale will be installed from $ci_url/$target/mariadb-maxscale/
|$do_not_destroy_vm|if 'yes' build VM won't be destroyed after the build. NOTE: do not forget to destroy it manually|
|$smoke|if 'yes' all tests are executed in 'quick' mode (less iterations, skip heavy operations)|
|$test_set|definition of set of tests to run in ctest notation|
|test_set_labels|list of ctest labels. If it is not define 'test_set' will be used as a plain string|
## Test environment operations
### Accessing nodes
<pre>
cd $MDBCI_VM_PATH/$name/
vagrant ssh $node_name
</pre>
where $node_name - 'maxscale', 'node0', ..., 'node3', ..., 'nodeN', 'galera0', ..., 'galera3', ..., 'galeraN'
### Getting IP address and access keys
<pre>
~/mdbci/mdbci show network $name
~/mdbci/mdbci show network $name/$node_name
~/mdbci/mdbci show keyfile $name/$node_name
</pre>
### Destroying environemnt
<pre>
cd $MDBCI_VM_PATH/$name/
vagrant destroy -f
</pre>
### Set variables by [test/set_env_vagrant.sh](test/set_env_vagrant.sh)
<pre>
. ../build-scripts/test/set_env_vagrant.sh $name
</pre>

268
maxscale-system-test/Documentation/RELEASE.md Normal file
View File

@ -0,0 +1,268 @@
# Release process
## Pre-release Checklist
* Create new release notes and add all fixed bugs, use a previous one as a template
* Update the link to the latest release notes in Documentation-Contents.md
* Add link to release notes and document major changes in Changelog.md
* Add link to release notes in the Upgrading guide
## 1. Tag
Release builds are always made using a tag. However, the used
tag is a _tentative_ tag, to ensure that there never is a need
to _move_ any tag, should the release have to be modified after
it has been tagged. All that is needed is to create a new
tentative tag.
The source for release `x.y.z` is tagged with `maxscale-x.y.z-ttN`
where `N` is 1 for the first attempt and incremented in case the
`x.y.z` source still needs to be modified and the release rebuilt.
The final tag `maxscale-x.y.z` is created _after_ the packages have
been published and we are certain they will not be rebuilt, without
also the version number being changed.
So, ensure that the `maxscale-x.y.z-ttN` has been created and pushed
to the repository.
**NOTE** The tentative suffix - `-ttN` - is **only** used when
specifying the tag for the build, it must **not** be present in
any other names or paths.
## 2. Build and upgrade test
The Jenkins
[Build_all](http://localhost:8089/job/build_all/)
job should be used for building the packages.
Note that the above will not work unless you have set up an
ssh tunnel to Jenkins:
```
$ ssh -f -N -L 8089:127.0.0.1:8089 vagrant@max-tst-01.mariadb.com
```
Usually two runs are done: one for _release_ and one for _debug_ packages.
### Parameters to define
Use defaults for all other parameters.
#### source
```
refs/tags/maxscale-x.y.z-ttN
```
#### target
Debug build:
```
maxscale-x.y.z-debug
```
Release build:
```
maxscale-x.y.z-release
```
#### cmake_flags
Debug build:
```
-DBUILD_TESTS=Y -DCMAKE_BUILD_TYPE=Debug -DBUILD_MMMON=Y -DBUILD_CDC=Y
```
Release build:
```
-DBUILD_TESTS=N -DBUILD_MMMON=Y -DBUILD_CDC=Y
```
#### run_upgrade_test
```
yes
```
#### old_target
Name of some existing Maxscale repository
(please check http://max-tst-01.mariadb.com/ci-repository/
before build).
```
maxscale-x'.y'.z'-release
```
### Options for 1.4.x build
For `1.4` builds the default values of the following parameters
should be changed:
#### use_mariadbd
```
yes
```
#### cnf_file
```
maxscale.cnf.minimum.1.4.4
```
#### maxadmin_command
```
maxadmin -pmariadb show services
```
## 3. Copying to code.mariadb.com
ssh to `code.mariadb.com` with your LDAP credentials.
Create directories and copy repositories files:
```bash
cd /home/mariadb-repos/mariadb-maxscale/
mkdir x.y.z
mkdir x.y.z-debug
cd x.y.z
rsync -avz --progress --delete -e ssh vagrant@max-tst-01.mariadb.com:/home/vagrant/repository/maxscale-x.y.z-release/mariadb-maxscale/ .
cd ../x.y.z-debug
rsync -avz --progress --delete -e ssh vagrant@max-tst-01.mariadb.com:/home/vagrant/repository/maxscale-x.y.z-debug/mariadb-maxscale/ .
```
## 4. Email webops-requests@mariadb.com
Email example:
Subject: `MaxScale x.y.z release`
```
Hello,
Please publish Maxscale x.y.z binaries on web page.
Repos are on code.mariadb.com /home/mariadb-repos/mariadb-maxscale/x.y.z
symlink 'x.y' should be set to 'x.y.z'
symlink 'latest' [should|should NOT] be set to 'x.y.z'
Also please make sure that debug binaries are not visible from
https://mariadb.com/my_portal/download/maxscale
```
Replace `x.y.z` with the correct version.
**NOTE** Sometimes - especially at _big_ releases when the exact release
date is fixed in advance - the following steps 5, 6 and 7 are done right
after the packages have been uploaded, to ensure that the steps 4 and 8
can be done at the same time.
## 5. Create the final tag
Once the packages have been made available for download, create
the final tag
```
$ git checkout maxscale-x.y.z-ttN
$ git tag -a -m "Tag for MaxScale x.y.z" maxscale-x.y.z
$ git push --tags origin
```
and remove the tentative tag(s)
```
$ git tag -d maxscale-x.y.z-ttN
$ git push origin :refs/tags/maxscale-x.y.z-ttN
```
## 6. Create the branch
Release `x.y.z` is typically developed in the branch `x.y`.
Once `x.y.z` has been released, the branch `x.y.z` also needs
to be created.
```
$ git checkout maxscale-x.y.z
$ git checkout -b x.y.z
$ git push origin x.y.z
```
## 7. Update the release date
Once the branch `x.y.z` has been created and the actual release
date of the release is known, update the release date in the
release notes.
```
$ git checkout x.y.z
$ # Update release date in .../MaxScale-x.y.z-Release-Notes.md
$ git add .../MaxScale-x.y.z-Release-Notes.md
$ git commit -m "Update release date"
$ git push origin x.y.z
```
**NOTE** The `maxscale-x.y.z` tag is **not** moved. That is, the
release date is _not_ available in the documentation marked with
the tag `maxscale-x.y.z` but _is_ available in the branch marked
with `x.y.z`.
Merge `x.y.z` to `x.y`.
```
$ git checkout x.y
$ git merge x.y.z
```
At this point, the last commits on branches `x.y` and `x.y.z`
should be the same and the commit should be the one containing the
update of the release date. Further, that commit should be the only
difference between the branches and the tag `maxscale-x.y.z`.
**Check that indeed is the case**.
## 8. Update documentation
Email webops-requests@mariadb.com with a mail containing the
following.
```
subject: Please update MaxScale x.y knowledge base
body:
---
Hi,
Please update https://mariadb.com/kb/en/mariadb-enterprise/mariadb-maxscale-XY/
from https://github.com/mariadb-corporation/MaxScale/tree/x.y.z/Documentation
using the "new" algorithm that does not honor single line-breaks.
Br,
Your Name
```
## 9. Send release email to mailing list
Email maxscale@googlegroups.com with a mail containing the following.
```
subject: MariaDB MaxScale x.y.z available for download
body:
---
Hi,
We are happy to announce that MariaDB MaxScale x.y.z GA is now available for download. This is a bugfix release.
The Jira list of fixed issues can be found here(ADD LINK HERE).
* [MXS-XYZ] BUG FIX DESCRIPTION HERE
Binaries:
https://mariadb.com/downloads/maxscale
https://mariadb.com/my_portal/download
Documentation:
LINK TO KB DOCUMENTATION HERE
Release notes:
LINK TO RELEASE NOTES HERE
Source code:
LINK TO maxscale-x.y.z TAG HERE
Please report any issues on Jira:
https://jira.mariadb.org/projects/MXS/issues
On behalf of the entire MaxScale team,
YOUR NAME HERE
```

105
maxscale-system-test/Documentation/RUN_TEST.md Normal file
View File

@ -0,0 +1,105 @@
# How to run test
## Prerequirements
Installed [MDBCI](https://github.com/mariadb-corporation/mdbci) (with dependencies, see
[MDBCI doc](https://github.com/mariadb-corporation/mdbci#mariadb-continuous-integration-infrastructure-mdbci)),
[build-scripts](https://github.com/mariadb-corporation/build-scripts-vagrant)
Componets should be in the following directories:
[build-scripts](https://github.com/mariadb-corporation/build-scripts-vagrant) - in ~/build-scripts/
[mdbci](https://github.com/mariadb-corporation/mdbci) - in ~/mdbci/
## Creating test environment and running tests
[run_test.sh](test/run_test.sh) generates MDBCI description of configuration, bring all VMs up, setup DB on all backends,
prapare DB for creating Master/Slave and Galera setups, build [maxscale-system-test](https://github.com/mariadb-corporation/MaxScale/tree/develop#maxscale-system-test)
package, execute ctest. Source code of
[maxscale-system-test](https://github.com/mariadb-corporation/MaxScale/tree/develop/maxscale-system-test#maxscale-system-test)
have to be in current directory before execution [run_test.sh](test/run_test.sh)
Environmental variables have to be defined before executing [run_test.sh](test/run_test.sh)
For details see [description](README.md#run_testsh)
Example:
<pre>
export export MDBCI_VM_PATH=$HOME/vms
export name="my-centos7-release-1.3.0-test"
export box="centos7"
export product="mariadb"
export version="5.5"
export target="develop"
export ci_url="http://max-tst-01.mariadb.com/ci-repository/"
export do_not_destroy_vm="yes"
export test_set="1,10,,20,30,95"
~/build-scripts/test/run_test.sh
</pre>
After the test, all machines can be accessed:
<pre>
cd $MDBCI_VM_PATH/$name
vagrant ssh \<machine_name\>
</pre>
where \<machine_name\> is 'maxscale', 'node0', ..., 'node3', ..., 'nodeN', 'galera0', ..., 'galera3', ..., 'galeraN'
http://max-tst-01.mariadb.com/ci-repository/develop/mariadb-maxscale/ have to contain Maxscale repository
## Running tests with existing test environment
[set_env_vagrant.sh](test/set_env_vagrant.sh) script sets all needed environmental variables for
[maxscale-system-test](https://github.com/mariadb-corporation/MaxScale/tree/develop/maxscale-system-test)
See [maxscale-system-test documentation](https://github.com/mariadb-corporation/MaxScale/tree/develop/maxscale-system-test#environmental-variables) for details regarding variables.
Example:
<pre>
export name="running_conf_name"
. ../build-scripts/test/set_env_vagrant.sh $name
set +x
git clone https://github.com/mariadb-corporation/maxscale.git
cd MaxScale/maxscale-system-test
cmake .
make
./test_executable_name
</pre>
or use ctest to run several tests
## Creating environment for Maxscale debugging
[create_env.sh](test/create_env.sh) script generates MDBCI description of configuration, bring all VMs up,
setup DB on all backends, prapare DB for creating Master/Slave and Galera setups, copy source code of
[Maxscale](https://github.com/mariadb-corporation/MaxScale) to 'maxscale' VM and build it.
Note: script does not install Maxscale, it have to be done manually.
Following variables have to be defined:
'name', 'box', 'product', 'version'
(see [run_test.sh documentation](https://github.com/mariadb-corporation/build-scripts-vagrant/blob/master/README.md#run_testsh))
'source', 'value'
(see
[prepare_and_build.sh documentation](https://github.com/mariadb-corporation/build-scripts-vagrant/blob/master/README.md#prepare_and_buildsh))
Example:
<pre>
export MDBCI_VM_PATH=$HOME/vms
export name="my-centos7-release-1.3.0-test"
export box="centos7"
export product="mariadb"
export version="5.5"
export source="BRANCH"
export value="develop"
~/build-scripts/test/create_env.sh
</pre>
**Note**: do not forget to destroy test environment by vagrant destroy:
<pre>
cd $MDBCI_VM_PATH/$name/
vagrant destroy -f
</pre>

39
maxscale-system-test/cnf/maxscale.cnf.template.mxs1713_lots_of_databases Normal file
View File

@ -0,0 +1,39 @@
[maxscale]
threads=###threads###
[MySQL Monitor]
type=monitor
module=mysqlmon
###repl51###
servers=server1
user=maxskysql
passwd=skysql
[Sharding router]
type=service
router=schemarouter
servers=server1
user=maxskysql
passwd=skysql
[Sharding Listener]
type=listener
service=Sharding router
protocol=MySQLClient
port=4006
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
[server1]
type=server
address=###node_server_IP_1###
port=###node_server_port_1###
protocol=MySQLBackend

78
maxscale-system-test/failover_mysqlmon.cpp Normal file
View File

@ -0,0 +1,78 @@
/**
* @file failover_mysqlmon.cpp MySQL Monitor Failover Test
* - block all nodes, but one
* - wait for minitor (monitor_interval)
* - check maxadmin output
* - check that queries work
* - unblock backend nodes
* - wait for monitor
* - check that we are still using the last node to which we failed over to and that the old nodes are in maintenance mode
*/
#include <iostream>
#include "testconnections.h"
int main(int argc, char *argv[])
{
TestConnections * test = new TestConnections(argc, argv);
test->tprintf(" Create the test table and insert some data ");
test->connect_maxscale();
test->try_query(test->conn_rwsplit, "CREATE OR REPLACE TABLE test.t1 (id int)");
test->try_query(test->conn_rwsplit, "INSERT INTO test.t1 VALUES (1)");
test->close_maxscale_connections();
test->repl->connect();
test->repl->sync_slaves();
test->tprintf(" Block all but one node ");
test->repl->block_node(0);
test->repl->block_node(1);
test->repl->block_node(2);
execute_query(test->repl->nodes[3], "STOP SLAVE;RESET SLAVE ALL;");
test->tprintf(" Wait for the monitor to detect it ");
sleep(15);
test->tprintf(" Connect and insert should work ");
char *output = test->ssh_maxscale_output(true, "maxadmin list servers");
test->tprintf("%s", output);
free(output);
test->connect_maxscale();
test->try_query(test->conn_rwsplit, "INSERT INTO test.t1 VALUES (1)");
test->close_maxscale_connections();
test->tprintf(" Unblock nodes ");
test->repl->unblock_node(0);
test->repl->unblock_node(1);
test->repl->unblock_node(2);
test->tprintf(" Wait for the monitor to detect it ");
sleep(15);
test->tprintf("Check that we are still using the last node to which we failed over "
"to and that the old nodes are in maintenance mode");
test->connect_maxscale();
test->try_query(test->conn_rwsplit, "INSERT INTO test.t1 VALUES (1)");
char maxscale_id[256], real_id[256];
find_field(test->conn_rwsplit, "SELECT @@server_id", "@@server_id", maxscale_id);
test->repl->connect();
find_field(test->repl->nodes[3], "SELECT @@server_id", "@@server_id", real_id);
test->add_result(strcmp(maxscale_id, real_id) != 0,
"@@server_id is different: %s != %s", maxscale_id, real_id);
test->close_maxscale_connections();
test->ssh_maxscale(true, "maxadmin clear server server1 maintenance");
test->ssh_maxscale(true, "maxadmin clear server server2 maintenance");
test->ssh_maxscale(true, "maxadmin clear server server3 maintenance");
test->repl->fix_replication();
test->tprintf(" Check that MaxScale is running ");
test->check_maxscale_alive();
int rval = test->global_result;
delete test;
return rval;
}

6
maxscale-system-test/mariadb_func.h
View File

@ -71,7 +71,7 @@ MYSQL* open_conn_db_timeout(int port, std::string ip, std::string db, std::strin
* @return MYSQL struct
*/
static MYSQL* open_conn_db(int port, std::string ip, std::string db, std::string user, std::string password,
bool ssl)
bool ssl = false)
{
return open_conn_db_flags(port, ip, db, user, password, CLIENT_MULTI_STATEMENTS, ssl);
}
@ -87,7 +87,7 @@ static MYSQL* open_conn_db(int port, std::string ip, std::string db, std::string
*
* @return MYSQL struct
*/
static MYSQL* open_conn(int port, std::string ip, std::string user, std::string password, bool ssl)
static MYSQL* open_conn(int port, std::string ip, std::string user, std::string password, bool ssl = false)
{
return open_conn_db(port, ip.c_str(), "test", user.c_str(), password.c_str(), ssl);
}
@ -103,7 +103,7 @@ static MYSQL* open_conn(int port, std::string ip, std::string user, std::string
*
* @return MYSQL struct
*/
static MYSQL* open_conn_no_db(int port, std::string ip, std::string user, std::string password, bool ssl)
static MYSQL* open_conn_no_db(int port, std::string ip, std::string user, std::string password, bool ssl = false)
{
return open_conn_db_flags(port, ip, "", user, password, CLIENT_MULTI_STATEMENTS, ssl);
}

6
maxscale-system-test/mariadb_nodes.h
View File

@ -160,6 +160,12 @@ public:
*/
void close_connections();
// Alias for close_connections()
void disconnect()
{
close_connections();
}
/**
* @brief reads IP, Ports, sshkeys for every node from enviromental variables as well as number of nodes (N) and User/Password
* @return 0

14
maxscale-system-test/maxscales.cpp
View File

@ -417,3 +417,17 @@ StringSet Maxscales::get_server_status(const char* name, int m)
return rval;
}
int Maxscales::port(enum service type, int m) const
{
switch (type)
{
case RWSPLIT:
return rwsplit_port[m];
case READCONN_MASTER:
return readconn_master_port[m];
case READCONN_SLAVE:
return readconn_slave_port[m];
}
return -1;
}

17
maxscale-system-test/maxscales.h
View File

@ -8,6 +8,13 @@
class Maxscales: public Nodes
{
public:
enum service
{
RWSPLIT,
READCONN_MASTER,
READCONN_SLAVE
};
Maxscales(const char *pref, const char *test_cwd, bool verbose);
int read_env();
@ -26,6 +33,16 @@ public:
*/
int readconn_slave_port[256];
/**
* @brief Get port number of a MaxScale service
*
* @param type Type of service
* @param m MaxScale instance to use
*
* @return Port number of the service
*/
int port(enum service type = RWSPLIT, int m = 0) const;
/**
* @brief binlog_port binlog router service port
*/

58
maxscale-system-test/mxs1713_lots_of_databases.cpp Normal file
View File

@ -0,0 +1,58 @@
/**
* MXS-1713: SchemaRouter unable to process SHOW DATABASES for a lot of schemas
*
* https://jira.mariadb.org/browse/MXS-1713
*/
#include "testconnections.h"
#include <vector>
#include <set>
#include <numeric>
int main(int argc, char** argv)
{
TestConnections test(argc, argv);
const int n_db = 2000;
std::vector<std::string> db_list;
for (int i = 0; i < n_db; i++)
{
db_list.push_back("db" + std::to_string(i));
}
test.tprintf("Create %lu databases...", db_list.size());
test.repl->connect();
for (auto db : db_list)
{
execute_query(test.repl->nodes[0], "CREATE DATABASE %s", db.c_str());
}
test.tprintf("Done!");
test.tprintf("Opening a connection with each database as the default database...", db_list.size());
std::set<std::string> errors;
for (auto db : db_list)
{
MYSQL* conn = open_conn_db(test.maxscales->port(), test.maxscales->ip(), db,
test.maxscales->user_name, test.maxscales->password);
if (execute_query_silent(conn, "SELECT 1") ||
execute_query_silent(conn, "SHOW DATABASES"))
{
errors.insert(mysql_error(conn));
}
mysql_close(conn);
}
test.tprintf("Done!");
test.assert(errors.empty(), "None of the queries should fail: %s",
std::accumulate(errors.begin(), errors.end(), std::string(),
[](const std::string &a, const std::string &b){return a + b + " ";}));
test.tprintf("Dropping databases...");
for (auto db : db_list)
{
execute_query(test.repl->nodes[0], "DROP DATABASE %s", db.c_str());
}
test.tprintf("Done!");
return test.global_result;
}

5
maxscale-system-test/mysqlmon_detect_standalone_master.cpp
View File

@ -88,13 +88,14 @@ int main(int argc, char *argv[])
test.tprintf(" Create the test table and insert some data ");
test.try_query(test.maxscales->conn_rwsplit[0], "CREATE OR REPLACE TABLE test.t1 (id int)");
test.try_query(test.maxscales->conn_rwsplit[0], "INSERT INTO test.t1 VALUES (1)");
sleep(2);
test.repl->sync_slaves();
print_gtids(test);
test.maxscales->close_maxscale_connections(0);
if (test.global_result != 0)
{
return test.global_result;
return test.global_result;
}
test.tprintf(" Block all but one node, stop slave on server 4 ");

4
maxscale-system-test/nodes.cpp
View File

@ -467,7 +467,7 @@ int Nodes::read_basic_env()
return 0;
}
char* Nodes::ip(int i) const
const char* Nodes::ip(int i) const
{
return use_ipv6 ? (char*)IP6[i] : (char*)IP[i];
return use_ipv6 ? IP6[i] : IP[i];
}

2
maxscale-system-test/nodes.h
View File

@ -93,7 +93,7 @@ public:
*
* @return The current IP address
*/
char* ip(int i) const;
const char* ip(int i = 0) const;
/**
* @brief Generate command line to execute command on the node via ssh

5
server/modules/protocol/MySQL/mariadbbackend/mysql_backend.c
View File

@ -371,7 +371,6 @@ mxs_auth_state_t handle_server_response(DCB *dcb, GWBUF *buffer)
}
}
gwbuf_free(buffer);
return rval;
}
@ -518,7 +517,6 @@ gw_read_backend_event(DCB *dcb)
}
proto->protocol_auth_state = state;
gwbuf_free(readbuf);
}
else if (proto->protocol_auth_state == MXS_AUTH_STATE_RESPONSE_SENT)
{
@ -548,6 +546,8 @@ gw_read_backend_event(DCB *dcb)
/** Authentication failed */
gw_reply_on_error(dcb, proto->protocol_auth_state);
}
gwbuf_free(readbuf);
}
else if (proto->protocol_auth_state == MXS_AUTH_STATE_CONNECTED &&
dcb->ssl_state == SSL_ESTABLISHED)
@ -752,6 +752,7 @@ gw_read_and_write(DCB *dcb)
if (rcap_type_required(capabilities, RCAP_TYPE_PACKET_OUTPUT) ||
rcap_type_required(capabilities, RCAP_TYPE_CONTIGUOUS_OUTPUT) ||
proto->collect_result ||
proto->ignore_replies != 0)
{
GWBUF *tmp = modutil_get_complete_packets(&read_buffer);