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

Merge remote-tracking branch 'origin/develop' into MXS-122

Browse Source 
Conflicts:
	server/core/dcb.c
This commit is contained in:
counterpoint
2015-07-08 14:54:22 +01:00
parent de80e75796 6185397572
commit 9c1df7301d
6 changed files with 193 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
Documentation-Contents.md
View File

@ -5,7 +5,7 @@
## About MaxScale
- [About MaxScale](About/About-MaxScale.md)
- [Release Notes 1.1](Release-Notes/MaxScale-1.1-Release-Notes.md)
- [MaxScale 1.2.0 Release Notes](Release-Notes/MaxScale-1.2.0-Release-Notes.md)
- [Changelog](Changelog.md)
- [Limitations](About/Limitations.md)
- [COPYRIGHT](About/COPYRIGHT.md)
@ -19,7 +19,8 @@
## Upgrading MaxScale
- [Upgrading MaxScale to 1.1.0](Upgrading-To-MaxScale-1.1.0.md)
- [Upgrading MaxScale from 1.1.1 to 1.2.0](Upgrading-To-MaxScale-1.2.0.md)
- [Upgrading MaxScale from 1.0.5 to 1.1.0](Upgrading-To-MaxScale-1.1.0.md)
## Reference
@ -28,6 +29,7 @@
- [MaxScale HA with Lsyncd](Reference/MaxScale-HA-with-lsyncd.md)
- [How Errors are Handled in MaxScale](Reference/How-errors-are-handled-in-MaxScale.md)
- [Debug and Diagnostic Support](Reference/Debug-And-Diagnostic-Support.md)
- [Routing Hints](Reference/Hint-Syntax.md)
## Tutorials
@ -70,10 +72,6 @@ Here are detailed documents about the filters MaxScale offers. They contain conf
- [RabbitMQ Consumer Client](filters/RabbitMQ-Consumer-Client.md)
## Routers
- [Simple Schema Sharding Router](routers/schemarouter/SchemaRouter.md)
## Design Documents
- [Core Objects Design (in development)](http://mariadb-corporation.github.io/MaxScale/Design-Documents/core-objects-html-docs)
@ -89,4 +87,7 @@ Here are detailed documents about the filters MaxScale offers. They contain conf
- [MaxScale 1.0 Release Notes](Release-Notes/MaxScale-1.0-Release-Notes.md)
- [MaxScale 1.0.1 Release Notes](Release-Notes/MaxScale-1.0.1-Release-Notes.md)
- [MaxScale 1.0.3 Release Notes](Release-Notes/MaxScale-1.0.3-Release-Notes.md)
- [MaxScale 1.1.0 Release Notes](Release-Notes/MaxScale-1.1-Release-Notes.md)
- [MaxScale 1.1.1 Release Notes](Release-Notes/MaxScale-1.1.1-Release-Notes.md)
- [MaxScale 1.2.0 Release Notes](Release-Notes/MaxScale-1.2.0-Release-Notes.md)

46
Getting-Started/Building-MaxScale-from-Source-Code.md
View File

@ -22,9 +22,9 @@ After following the instructions on that site you should have a working MariaDB
The full list of dependencies for the most common distributions is provided in this section. If your system is not listed here, MaxScale building isn't guaranteed to be compatible but might still be successful.
## RHEL, CentOS and Fedora
## RHEL and CentOS
You will need to install all of the following packages for all versions of RHEL, CentOS and Fedora.
You will need to install all of the following packages for all versions of RHEL and CentOS.
```
gcc gcc-c++ ncurses-devel bison glibc-devel cmake libgcc perl make libtool
@ -39,7 +39,7 @@ rpm-build
There are also some version specific packages you need to install.
#### RHEL 6, 7, CentOS 6, 7, Fedora:
#### RHEL 6, 7, CentOS 6, 7:
```
libedit-devel
@ -51,17 +51,11 @@ libedit-devel
mariadb-devel mariadb-embedded-devel
```
#### RHEL 5, 6, CentOS 5, 6, Fedora 19, 20
#### RHEL 5, 6, CentOS 5, 6
```
MariaDB-devel MariaDB-server
```
#### Fedora 19, 20
```
systemtap-sdt-devel
```
## Ubuntu and Debian
These packages are required on all versions of Ubuntu and Debian.
@ -87,16 +81,13 @@ You will also need some version specific packages.
#### Earlier versions of Ubuntu or Debian
For these, you will need to obtain the MariaDB embedded library. It has to be manually extracted from the tarball. But first ascertain what version of glibc is installed. Run the command:
For these, you will need to obtain the MariaDB embedded library. It has to be manually extracted from the tarballs at the MariaDB site. But first ascertain what version of glibc is installed. Run the command:
```
dpkg -l | grep libc6
```
which will show the version number. If the version is less than 2.14 you should obtain the library from:
[https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-x86_64/mariadb-5.5.41-linux-x86_64.tar.gz](https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-x86_64/mariadb-5.5.41-linux-x86_64.tar.gz).
Otherwise, from:
[https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-glibc_214-x86_64/mariadb-5.5.41-linux-glibc_214-x86_64.tar.gz](https://downloads.mariadb.org/interstitial/mariadb-5.5.41/bintar-linux-glibc_214-x86_64/mariadb-5.5.41-linux-glibc_214-x86_64.tar.gz)
which will show the version number. For versions older than 2.14 you should obtain the library which supports GLIBC versions older than 2.14 and for newer versions, the library which supports newer GLIBC versions should be used.
The suggested location for extracting the tarball is `/usr` so the operation can be done by the following commands:
@ -107,22 +98,6 @@ The suggested location for extracting the tarball is `/usr` so the operation can
where /path/to/mariadb.library.tar.gz is replaced by the actual path and name of the downloaded tarball.
## OpenSUSE
At the time this guide was written, the MariaDB development packages for OpenSUSE were broken and the build failed.
The packages required are:
```
gcc gcc-c++ ncurses-devel bison glibc-devel cmake libgcc_s1 perl
make libtool libopenssl-devel libaio libaio-devel
libedit-devel librabbitmq-devel
MariaDB-devel MariaDB-client MariaDB-server
```
If zypper ask which MariaDB client should be installed `MariaDB-client` or `mariadb-client`
please select `MariaDB-client`. This is the package provided by the MariaDB repository.
# Obtaining the MaxScale Source Code
Now clone the GitHub project to your machine either via the web interface, your favorite graphical interface or the git command line
@ -152,16 +127,15 @@ wipe the build directory clean without the danger of deleting important files wh
something goes wrong. Building 'out-of-source' also allows you to have multiple
configurations of MaxScale at the same time.
The default values that CMake uses can be found in the 'macros.cmake' file.
If you wish to change these, edit the 'macros.cmake' file or define the
variables manually at configuration time.
The default values that MaxScale uses for CMake can be found in the 'macros.cmake' file under the `cmake` folder.
If you wish to change these, edit the 'macros.cmake' file or define the variables manually at configuration time.
To display all CMake variables with their descriptions:
```
cmake .. -LH
```
This is a useful command if you have your libraries installed in non-standard locations.
This is a useful command if you have your libraries installed in non-standard locations and need to provide them manually.
When you are ready to run cmake, provide the following command:
@ -241,7 +215,7 @@ $ make install
This will result in an installation being created which is identical to that which would be achieved by installing the binary package.
By default, MaxScale installs to `/usr/local/mariadb-maxscale` and places init.d scripts and ldconfig files into their folders. Change the `CMAKE_INSTALL_PREFIX` variable to your desired installation directory and set `WITH_SCRIPTS=N` to prevent the init.d script and ldconfig file installation.
When building from source, MaxScale installs to `/usr/local/` and places init.d scripts and ldconfig files into their folders. Change the `CMAKE_INSTALL_PREFIX` variable to your desired installation directory and set `WITH_SCRIPTS=N` to prevent the init.d script and ldconfig file installation.
Other useful targets for Make are `documentation`, which generates the Doxygen documentation, and `uninstall` which uninstall MaxScale binaries after an install.

83
Reference/Hint-Syntax.md
View File

@ -1,42 +1,97 @@
# Hint Syntax
Use either ’-- ’ (notice the whitespace) or ’#’ after the semicolon or ’/* .. */’ before
the semicolon.
## Enabling routing hints
The MySQL manual doesn’t specify if comment blocks, i.e. ’/* .. */’, should contain a w
hitespace character before or after the tags.
To enable routing hints for a service, the hintfilter module needs to be configured and the filter needs to be applied to the service.
All hints must start with the ’maxscale tag’:
-- maxscale <hint>
The hints right now have two types, ones that route to a server and others that contain
Here is an example service which has the hint filter configured and applied.
```
[Read Service]
type=service
router=readconnroute
router_options=master
servers=server1
user=maxuser
passwd=maxpwd
filter=Hint
[Hint]
type=filter
module=hintfilter
```
## Comments and comment types
The client connection will need to have comments enabled. For example the `mysql` command line client has comments disabled by default.
For comment types, use either `-- ` (notice the whitespace) or `#` after the semicolon or `/* .. */` before the semicolon. All comment types work with routing hints.
The MySQL manual doesn`t specify if comment blocks, i.e. `/* .. */`, should contain a w
hitespace character before or after the tags, so adding whitespace at both the start and the end is advised.
## Hint body
All hints must start with the `maxscale` tag.
```
-- maxscale <hint body>
```
The hints have two types, ones that route to a server and others that contain
name-value pairs.
Routing queries to a server:
###Routing destination hints
These hints will instruct the router to route a query to a certain type of a server.
```
-- maxscale route to [master | slave | server <server name>]
```
The name of the server is the same as in maxscale.cnf
A `master` value in a routing hint will route the query to a master server. This can be used to direct read queries to a master server for a up-to-date result with no replication lag. A `slave` value will route the query to a slave server. A `server` value will route the query to a named server. The value of <server name> needs to be the same as the server section name in maxscale.cnf.
Creating a name-value pair:
### Name-value hints
These control the behavior and affect the routing decisions made by the router.
```
-- maxscale <param>=<value>
```
Currently the only accepted parameter is
’max_slave_replication_lag’
Currently the only accepted parameter is `max_slave_replication_lag`. This will route the query to a server with lower replication lag then what is defined in the hint value.
## Hint stack
Hints can be either single-use hints, which makes them affect only one query, or named
hints, which can be pushed on and off a stack of active hints.
Defining named hints:
```
-- maxscale <hint name> prepare <hint content>
```
Pushing a hint onto the stack:
```
-- maxscale <hint name> begin
```
Popping the topmost hint off the stack:
```
-- maxscale end
```
You can define and activate a hint in a single command using the following:
```
-- maxscale <hint name> begin <hint content>
```
You can also push anonymous hints onto the stack which are only used as long as they are on the stack:
-- maxscale begin <hint content>
```
-- maxscale begin <hint content>
```

73
Release-Notes/MaxScale-1.2.0-Release-Notes.md
View File

@ -24,3 +24,76 @@ A quick list of changes in installation directories and file names:
* Data directory is `/var/lib/maxscale`. This is the default location for MaxScale-specific data.
* PID file can be found at `/var/run/maxscale`
### Client side SSL encryption
MaxScale now supports SSL/TLS encrypted connections to MaxScale.
### Launchable scripts
Now you can configure MaxScale monitor module to automatically launch a script when it detects change in the state of a backend server. The script can be any customer script defined by you to take diagnostic or reporting action. With this you can easily customize MaxScale's behavior.
### Lsyncd configuration guide
A new tutorial has beed added which helps you keep MaxScale's configuration files in sync across multiple hosts. This allows for easier HA setups with MaxScale and guarantees up-to-date configuration files on all nodes. The tutorial can be found [here](../Reference/MaxScale-HA-with-lsyncd.md).
## Bug fixes
Here is a list of bugs fixed since the release of MaxScale 1.1.1.
* [MXS-24](https://mariadb.atlassian.net/browse/MXS-24): bugzillaId-604: Module load path documentation issues ...
* [MXS-40](https://mariadb.atlassian.net/browse/MXS-40): Display logged in users
* [MXS-113](https://mariadb.atlassian.net/browse/MXS-113): MaxScale seems to fail if built against MariaDB 10.0 libraries
* [MXS-116](https://mariadb.atlassian.net/browse/MXS-116): Do not run maxscale as root.
* [MXS-117](https://mariadb.atlassian.net/browse/MXS-117): Allow configuration of the log file directory
* [MXS-125](https://mariadb.atlassian.net/browse/MXS-125): inconsistency in maxkeys/maxpassword output and parameters
* [MXS-128](https://mariadb.atlassian.net/browse/MXS-128): cyclic dependency utils -> log_manager -> utils
* [MXS-136](https://mariadb.atlassian.net/browse/MXS-136): Check for MaxScale replication heartbeat table existence before creating
* [MXS-137](https://mariadb.atlassian.net/browse/MXS-137): cannot get sql for queries with length >= 0x80
* [MXS-139](https://mariadb.atlassian.net/browse/MXS-139): Schemarouter authentication for wildcard grants fails without optimize_wildcard
* [MXS-140](https://mariadb.atlassian.net/browse/MXS-140): strip_db_esc does not work without auth_all_servers
* [MXS-162](https://mariadb.atlassian.net/browse/MXS-162): Fix Incorrect info in Configuration Guide
* [MXS-165](https://mariadb.atlassian.net/browse/MXS-165): Concurrency issue while incrementing sessions in qlafilter
* [MXS-166](https://mariadb.atlassian.net/browse/MXS-166): Memory leak when creating a new event
* [MXS-171](https://mariadb.atlassian.net/browse/MXS-171): Allow reads on master for readwritesplit
* [MXS-176](https://mariadb.atlassian.net/browse/MXS-176): Missing dependencies in documentation
* [MXS-179](https://mariadb.atlassian.net/browse/MXS-179): Keep configuration changes in synch across MaxScale Mate Nodes
* [MXS-180](https://mariadb.atlassian.net/browse/MXS-180): MariaDB10 binlog router compatibilty
* [MXS-181](https://mariadb.atlassian.net/browse/MXS-181): Poor performance on TCP connection due to Nagle's algoritm
* [MXS-182](https://mariadb.atlassian.net/browse/MXS-182): SHOW SLAVE STATUS and maxadmin "show services" for binlog router needs updated when used with MariaDB 10 Master
* [MXS-212](https://mariadb.atlassian.net/browse/MXS-212): Stopped services accept connections
* [MXS-225](https://mariadb.atlassian.net/browse/MXS-225): RPM Debug build packages have no debugging symbols
* [MXS-227](https://mariadb.atlassian.net/browse/MXS-227): Memory leak in Galera Monitor
* [MXS-244](https://mariadb.atlassian.net/browse/MXS-244): Memory leak when using prepared statements without arguments
## Known Issues and Limitations
There are a number bugs and known limitations within this version of MaxScale, the most serious of this are listed below.
* MaxScale can not manage authentication that uses wildcard matching in hostnames in the mysql.user table of the backend database. The only wildcards that can be used are in IP address entries.
* When users have different passwords based on the host from which they connect MaxScale is unable to determine which password it should use to connect to the backend database. This results in failed connections and unusable usernames in MaxScale.
* LONGBLOB are currently not supported.
* Galera Cluster variables, such as @@wsrep_node_name, are not resolved by the embedded MariaDB parser.
* The Database Firewall filter does not support multi-statements. Using them will result in an error being sent to the client.
## Packaging
Both RPM and Debian packages are available for MaxScale in addition to the tar based releases previously distributed we now provide
* CentOS/RedHat 5
* CentOS/RedHat 6
* CentOS/RedHat 7
* Debian 6
* Debian 7
* Ubuntu 12.04 LTS
* Ubuntu 14.04 LTS
* SuSE Linux Enterprise 11
* SuSE Linux Enterprise 12

24
Upgrading-To-MaxScale-1.2.0.md Normal file
View File

@ -0,0 +1,24 @@
# Upgrading MaxScale from 1.1 to 1.2
This document describes upgrading MaxScale from version 1.1.1 to 1.2 and the major differences in the new version compared to the old version. The major changes can be found in the `Changelog.txt` file in the installation directory and the official release notes in the `ReleaseNotes.txt` file.
## Installation
Before starting the upgrade, we recommend you back up your configuration, log and binary log files in `/usr/local/mariadb-maxscale/`.
Upgrading MaxScale will copy the `MaxScale.cnf` file in `/usr/local/mariadb-maxscale/etc/` to `/etc/` and renamed to `maxscale.cnf`. Binary log files are not automatically copied and should be manually moved from `/usr/local/mariadb-maxscale` to `/var/lib/maxscale/`.
## File location changes
MaxScale 1.2 follows the [FHS-standard](http://www.pathname.com/fhs/) and installs to `/usr/` and `/var/` subfolders. Here are the major changes and file locations.
* Configuration files are located in `/etc/` and use lowercase letters: `/etc/maxscale.cnf`
* Binary files are in `/usr/bin/`
* Libraries and modules are in `/usr/lib64/maxscale/`. If you are using custom modules, please make sure they are in this directory before starting MaxScale.
* Log files are in the `var/log/maxscale/` folder
* MaxScale's PID file is located in `/var/run/maxscale/maxscale.pid`
* Data files and other persistent files are in `/var/lib/maxscale/`
## Running MaxScale without root permissions
MaxScale can run as a non-root user with the 1.2 version. RPM and DEB packages install the `maxscale` user and `maxscale` group which are used by the init scripts and systemd configuration files. If you are installing from a binary tarball, you can run the `postinst` script included in it to manually create these groups.

11
routers/ReadWriteSplit.md
View File

@ -4,7 +4,9 @@ This document provides a short overview of the **readwritesplit** router module
## Overview
The **readwritesplit** router is designed to be used with a Master-Slave replication cluster. It automatically detects changes in the master server and will use the current master server of the cluster. With a Galera cluster, one can achieve a resilient setup and easy master failover by using one of the Galera nodes as a Write-Master node, where are write queries are routed, and spreading the read load over all the nodes.
The **readwritesplit** router is designed to increase the read-only processing capability of a cluster while maintaining consistency. This is achieved by splitting the query load into read and write queries. Read queries, which do not modify data, are spread across multiple nodes while all write queries will be sent to a single node.
The router is designed to be used with a traditional Master-Slave replication cluster. It automatically detects changes in the master server and will use the current master server of the cluster. With a Galera cluster, one can achieve a resilient setup and easy master failover by using one of the Galera nodes as a Write-Master node, where all write queries are routed, and spreading the read load over all the nodes.
## Configuration
@ -91,6 +93,13 @@ disable_sescmd_history=true
disable_slave_recovery=true
```
**`master_accept_reads`** allows the master server to be used for reads. This is a useful option to enable if you are using a small number of servers and wish to use the master for reads as well.
```
# Use the master for reads
master_accept_reads=true
```
## Limitations
In Master-Slave replication cluster also read-only queries are routed to master too in the following situations: