Merge branch '2.1' into develop
This commit is contained in:
Johan Wikman
@ -271,8 +271,7 @@ For more information on how to use these scripts, see the output of `cdc.py -h`
|
||||
|
||||
To build the avrorouter from source, you will need the [Avro C](https://avro.apache.org/docs/current/api/c/)
|
||||
library, liblzma, [the Jansson library](http://www.digip.org/jansson/) and sqlite3 development headers. When
|
||||
configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y
|
||||
-DBUILD_CDC=Y` to build the avrorouter and the CDC protocol module.
|
||||
configuring MaxScale with CMake, you will need to add `-DBUILD_CDC=Y` to build the CDC module set.
|
||||
|
||||
For more details about building MaxScale from source, please refer to the
|
||||
[Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document.
|
||||
|
||||
@ -13,7 +13,7 @@ replication setup where replication is high-priority.
|
||||
|
||||
## Mandatory Router Parameters
|
||||
|
||||
The binlogrouter requires the `server`, `user` and `passwd` parameters. These
|
||||
The binlogrouter requires the `server`, `user` and `password` parameters. These
|
||||
should be configured according to the
|
||||
[Configuration Guide](../Getting-Started/Configuration-Guide.md#service).
|
||||
|
||||
@ -32,18 +32,20 @@ following options should be given as a value to the `router_options` parameter.
|
||||
|
||||
### `binlogdir`
|
||||
|
||||
This parameter allows the location that MariaDB MaxScale uses to store binlog
|
||||
files to be set. If this parameter is not set to a directory name then MariaDB
|
||||
This parameter controls the location where MariaDB MaxScale stores the binary log
|
||||
files. If this parameter is not set to a directory name then MariaDB
|
||||
MaxScale will store the binlog files in the directory
|
||||
/var/cache/maxscale/<Service Name>. In the binlog dir there is also the 'cache'
|
||||
directory that contains data retrieved from the master during registration phase
|
||||
and the master.ini file which contains the configuration of current configured
|
||||
master.
|
||||
`/var/cache/maxscale/<Service Name>` where `<Service Name>` is the name of the
|
||||
service in the configuration file. The _binlogdir_ also contains the
|
||||
_cache_ subdirectory which stores data retrieved from the master during the slave
|
||||
registration phase. The master.ini file also resides in the _binlogdir_. This
|
||||
file keeps track of the current master configuration and it is updated when a
|
||||
`CHANGE MASTER TO` query is executed.
|
||||
|
||||
From 2.1 onwards, the 'cache' directory is stored in the same location as other
|
||||
user credential caches. This means that with the default options, the user
|
||||
credential cache is stored in
|
||||
/var/cache/maxscale/<Service Name>/<Listener Name>/cache/.
|
||||
`/var/cache/maxscale/<Service Name>/<Listener Name>/cache/`.
|
||||
|
||||
Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md)
|
||||
documentation for instructions on how to define a custom location for the user
|
||||
@ -51,45 +53,45 @@ cache.
|
||||
|
||||
### `uuid`
|
||||
|
||||
This is used to set the unique uuid that the binlog router uses when it connects
|
||||
to the master server. If no explicit value is given for the uuid in the
|
||||
configuration file then a uuid will be generated.
|
||||
This is used to set the unique UUID that the binlog router uses when it connects
|
||||
to the master server. If no explicit value is given for the UUID in the
|
||||
configuration file then a UUID will be generated.
|
||||
|
||||
### `server_id`
|
||||
|
||||
As with uuid, MariaDB MaxScale must have a unique _server id_ for the connection
|
||||
it makes to the master. This parameter provides the value of the server id that
|
||||
As with UUID, MariaDB MaxScale must have a unique _server_id_. This parameter
|
||||
configures the value of the _server_id_ that
|
||||
MariaDB MaxScale will use when connecting to the master.
|
||||
|
||||
The id can also be specified using `server-id` but that is deprecated
|
||||
and will be removed in a future release of MariaDB MaxScale.
|
||||
Older versions of MaxScale allowed the ID to be specified using `server-id`.
|
||||
This has been deprecated and will be removed in a future release of MariaDB MaxScale.
|
||||
|
||||
### `master_id`
|
||||
|
||||
The _server id_ value that MariaDB MaxScale should use to report to the slaves
|
||||
The _server_id_ value that MariaDB MaxScale should use to report to the slaves
|
||||
that connect to MariaDB MaxScale. This may either be the same as the server id
|
||||
of the real master or can be chosen to be different if the slaves need to be
|
||||
aware of the proxy layer. The real master server id will be used if the option
|
||||
aware of the proxy layer. The real master server ID will be used if the option
|
||||
is not set.
|
||||
|
||||
The id can also be specified using `master-id` but that is deprecated
|
||||
and will be removed in a future release of MariaDB MaxScale.
|
||||
Older versions of MaxScale allowed the ID to be specified using `master-id`.
|
||||
This has been deprecated and will be removed in a future release of MariaDB MaxScale.
|
||||
|
||||
### `master_uuid`
|
||||
|
||||
It is a requirement of replication that each slave have a unique UUID value. The
|
||||
MariaDB MaxScale router will identify itself to the slaves using the uuid of the
|
||||
It is a requirement of replication that each slave has a unique UUID value. The
|
||||
MariaDB MaxScale router will identify itself to the slaves using the UUID of the
|
||||
real master if this option is not set.
|
||||
|
||||
### `master_version`
|
||||
|
||||
The MariaDB MaxScale router will identify itself to the slaves using the server
|
||||
version of the real master if this option is not set.
|
||||
By default, the router will identify itself to the slaves using the server
|
||||
version of the real master. This option allows the router to use a custom version string.
|
||||
|
||||
### `master_hostname`
|
||||
|
||||
The MariaDB MaxScale router will identify itself to the slaves using the server
|
||||
hostname of the real master if this option is not set.
|
||||
By default, the router will identify itself to the slaves using the
|
||||
hostname of the real master. This option allows the router to use a custom hostname.
|
||||
|
||||
### `user`
|
||||
|
||||
@ -113,13 +115,13 @@ the router options or using the username and password defined of the service
|
||||
must be granted replication privileges on the database server.
|
||||
|
||||
```
|
||||
MariaDB> CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password';
|
||||
MariaDB> GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost';
|
||||
CREATE USER 'repl'@'maxscalehost' IDENTIFIED by 'password';
|
||||
GRANT REPLICATION SLAVE ON *.* TO 'repl'@'maxscalehost';
|
||||
```
|
||||
|
||||
### `password`
|
||||
|
||||
The password of the above user. If the password is not explicitly given then the
|
||||
The password for the user. If the password is not explicitly given then the
|
||||
password in the service entry will be used. For compatibility with other
|
||||
username and password definitions within the MariaDB MaxScale configuration file
|
||||
it is also possible to use the parameter passwd=.
|
||||
@ -167,9 +169,9 @@ incomplete transactions detection.
|
||||
|
||||
### `send_slave_heartbeat`
|
||||
|
||||
This defines whether (on | off) MariaDB MaxScale sends to the slave the
|
||||
heartbeat packet when there are no real binlog events to send. The default value
|
||||
if 'off', no heartbeat event is sent to slave server. If value is 'on' the
|
||||
This defines whether MariaDB MaxScale sends the heartbeat packet to the slave
|
||||
when there are no real binlog events to send. The default value
|
||||
is 'off' and no heartbeat events are sent to slave servers. If value is 'on' the
|
||||
interval value (requested by the slave during registration) is reported in the
|
||||
diagnostic output and the packet is send after the time interval without any
|
||||
event to send.
|
||||
@ -205,6 +207,7 @@ master.ini or later via CHANGE MASTER TO. This parameter cannot be modified at
|
||||
runtime, default is 9.
|
||||
|
||||
### `encrypt_binlog`
|
||||
|
||||
Whether to encrypt binlog files: the default is Off.
|
||||
|
||||
When set to On the binlog files will be encrypted using specified AES algorithm
|
||||
@ -226,11 +229,11 @@ the binlog events positions in binlog file are the same as in the master binlog
|
||||
file and there is no position mismatch.
|
||||
|
||||
### `encryption_algorithm`
|
||||
'aes_ctr' or 'aes_cbc'
|
||||
|
||||
The default is 'aes_cbc'
|
||||
The encryption algorithm, either 'aes_ctr' or 'aes_cbc'. The default is 'aes_cbc'
|
||||
|
||||
### `encryption_key_file`
|
||||
|
||||
The specified key file must contains lines with following format:
|
||||
|
||||
`id;HEX(KEY)`
|
||||
@ -277,10 +280,8 @@ values may be used for all other options.
|
||||
|
||||
## Examples
|
||||
|
||||
The [Replication
|
||||
Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will
|
||||
The [Replication Proxy](../Tutorials/Replication-Proxy-Binlog-Router-Tutorial.md) tutorial will
|
||||
show you how to configure and administrate a binlogrouter installation.
|
||||
|
||||
|
||||
Tutorial also includes SSL communication setup to the master server and SSL
|
||||
client connections setup to MaxScale Binlog Server.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
# CLI
|
||||
|
||||
The command line interface as used by `maxadmin`. The _CLI_ router requires the use
|
||||
of the `maxscaled` protocol.
|
||||
The command line interface as used by `maxadmin`. The _CLI_ router requires the
|
||||
use of the `maxscaled` protocol.
|
||||
|
||||
## Configuration
|
||||
|
||||
Two components are required in order to run the command line interface for use with
|
||||
_maxadmin_; a service and a listener. The listener may either use a Unix domain socket
|
||||
or an internet socket.
|
||||
Two components are required to run the command line interface for _maxadmin_; a
|
||||
service and a listener. The listener may either use a Unix domain socket or an
|
||||
internet socket.
|
||||
|
||||
The default entries required are shown below.
|
||||
|
||||
@ -31,19 +31,20 @@ protocol=maxscaled
|
||||
address=localhost
|
||||
port=6603
|
||||
```
|
||||
|
||||
In the example above, two listeners have been specified; one that listens on the
|
||||
default Unix domain socket and one that listens on the default port. In the latter
|
||||
case, if the `address=` entry is removed, connections are allowed from any machine
|
||||
on your network.
|
||||
default Unix domain socket and one that listens on the default port. In the
|
||||
latter case, if the `address=` entry is removed, connections are allowed from
|
||||
any machine on your network.
|
||||
|
||||
In the former case, if the value of `socket` is changed and in the latter case,
|
||||
if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and
|
||||
`-P` options respectively.
|
||||
`-P` options, respectively.
|
||||
|
||||
Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_
|
||||
can only be used on the same host where MariaDB MaxScale runs. If internet sockets
|
||||
are used, the connection is _inherently insecure_ but _maxadmin_ can be used from
|
||||
another host than the one where MariaDB MaxScale runs.
|
||||
If Unix domain sockets are used, the connection is secure, but _maxadmin_ can
|
||||
only be used on the same host where MariaDB MaxScale runs. If internet sockets
|
||||
are used, the connection is _inherently insecure_ but _maxadmin_ can be used
|
||||
from another host than the one where MariaDB MaxScale runs.
|
||||
|
||||
Note that the latter approach is **deprecated** and will be removed in a future
|
||||
version of MariaDB MaxScale.
|
||||
|
||||
@ -18,38 +18,4 @@ protocol=telnetd
|
||||
port=4442
|
||||
```
|
||||
|
||||
Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the add user command. As soon as any users are explicitly created the default username will no longer continue to work. The default username is admin with a password of mariadb.
|
||||
|
||||
The debugcli supports two modes of operation, `developer` and `user`. The mode is set via the `router_options` parameter. The user mode is more suited to end-users and administrators, whilst the develop mode is explicitly targeted to software developing adding or maintaining the MariaDB MaxScale code base. Details of the differences between the modes can be found in the debugging guide for MariaDB MaxScale. The default is `user` mode. The following service definition would enable a developer version of the debugcli.
|
||||
|
||||
```
|
||||
[Debug Service]
|
||||
type=service
|
||||
router=debugcli
|
||||
router_options=developer
|
||||
```
|
||||
|
||||
It should be noted that both `user` and `developer` instances of debugcli may be defined within the same instance of MariaDB MaxScale, however they must be defined as two distinct services, each with a distinct listener.
|
||||
|
||||
```
|
||||
[Debug Service]
|
||||
type=service
|
||||
router=debugcli
|
||||
router_options=developer
|
||||
|
||||
[Debug Listener]
|
||||
type=listener
|
||||
service=Debug Service
|
||||
protocol=telnetd
|
||||
port=4442
|
||||
|
||||
[Admin Service]
|
||||
type=service
|
||||
router=debugcli
|
||||
|
||||
[Admin Listener]
|
||||
type=listener
|
||||
service=Debug Service
|
||||
protocol=telnetd
|
||||
port=4242
|
||||
```
|
||||
Connections using the telnet protocol to port 4442 of the MariaDB MaxScale host will result in a new debug CLI session. A default username and password are used for this module, new users may be created using the administrative interface. As soon as any users are explicitly created the default username will no longer continue to work. The default username is `admin` with a password of `mariadb`.
|
||||
|
||||
@ -8,11 +8,9 @@ The readconnroute router provides simple and lightweight load balancing across a
|
||||
|
||||
## Configuration
|
||||
|
||||
Readconnroute router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section.
|
||||
|
||||
For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md).
|
||||
|
||||
## Router Options
|
||||
### Router Options
|
||||
|
||||
**`router_options`** can contain a list of valid server roles. These roles are used as the valid types of servers the router will form connections to when new sessions are created.
|
||||
```
|
||||
|
||||
@ -1,54 +1,78 @@
|
||||
# Readwritesplit
|
||||
|
||||
This document provides a short overview of the **readwritesplit** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. A list of current limitations of the module is included and examples of the router's use are provided.
|
||||
This document provides a short overview of the **readwritesplit** router module
|
||||
and its intended use case scenarios. It also displays all router configuration
|
||||
parameters with their descriptions. A list of current limitations of the module
|
||||
is included and use examples are provided.
|
||||
|
||||
## Overview
|
||||
|
||||
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 **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.
|
||||
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
|
||||
|
||||
Readwritesplit router-specific settings are specified in the configuration file of MariaDB MaxScale in its specific section. The section can be freely named but the name is used later as a reference from listener section.
|
||||
Readwritesplit router-specific settings are specified in the configuration file
|
||||
of MariaDB MaxScale in its specific section. The section can be freely named but
|
||||
the name is used later as a reference in a listener section.
|
||||
|
||||
For more details about the standard service parameters, refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md).
|
||||
For more details about the standard service parameters, refer to the
|
||||
[Configuration Guide](../Getting-Started/Configuration-Guide.md).
|
||||
|
||||
## Optional parameters
|
||||
|
||||
### `max_slave_connections`
|
||||
|
||||
**`max_slave_connections`** sets the maximum number of slaves a router session uses at any moment. The default is to use all available slaves.
|
||||
**`max_slave_connections`** sets the maximum number of slaves a router session
|
||||
uses at any moment. The default is to use all available slaves.
|
||||
|
||||
max_slave_connections=<max. number, or % of available slaves>
|
||||
|
||||
### `max_slave_replication_lag`
|
||||
**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to be behind the master. If the lag is bigger than configured value a slave can't be used for routing.
|
||||
|
||||
**`max_slave_replication_lag`** specifies how many seconds a slave is allowed to
|
||||
be behind the master. If the lag is bigger than the configured value a slave
|
||||
can't be used for routing.
|
||||
|
||||
This feature is disabled by default.
|
||||
|
||||
max_slave_replication_lag=<allowed lag in seconds>
|
||||
|
||||
This applies to Master/Slave replication with MySQL monitor and `detect_replication_lag=1` options set.
|
||||
Please note max_slave_replication_lag must be greater than monitor interval.
|
||||
This applies to Master/Slave replication with MySQL monitor and
|
||||
`detect_replication_lag=1` options set. max_slave_replication_lag must be
|
||||
greater than the monitor interval.
|
||||
|
||||
This option only affects Master-Slave clusters. Galera clusters do not have a
|
||||
concept of slave lag even if the application of write sets might have lag.
|
||||
|
||||
|
||||
### `use_sql_variables_in`
|
||||
|
||||
**`use_sql_variables_in`** specifies where should queries, which read session variable, be routed. The syntax for `use_sql_variable_in` is:
|
||||
**`use_sql_variables_in`** specifies where should queries, which read session
|
||||
variable, be routed. The syntax for `use_sql_variable_in` is:
|
||||
|
||||
use_sql_variables_in=[master|all]
|
||||
|
||||
The default is to use SQL variables in all servers.
|
||||
|
||||
When value all is used, queries reading session variables can be routed to any available slave (depending on selection criteria). Note, that queries modifying session variables are routed to all backend servers by default, excluding write queries with embedded session variable modifications, such as:
|
||||
When value `all` is used, queries reading session variables can be routed to any
|
||||
available slave (depending on selection criteria). Queries modifying session
|
||||
variables are routed to all backend servers by default, excluding write queries
|
||||
with embedded session variable modifications, such as:
|
||||
|
||||
INSERT INTO test.t1 VALUES (@myid:=@myid+1)
|
||||
|
||||
In above-mentioned case the user-defined variable would only be updated in the master where query would be routed due to `INSERT` statement.
|
||||
In above-mentioned case the user-defined variable would only be updated in the
|
||||
master where the query would be routed to due to the `INSERT` statement.
|
||||
|
||||
**Note:** As of version 2.1 of MaxScale, all of the router options can also be
|
||||
defined as parameters. The values defined in _router_options_ will have priority
|
||||
@ -83,21 +107,30 @@ for a long time.
|
||||
|
||||
## Router options
|
||||
|
||||
**`router_options`** may include multiple **readwritesplit**-specific options. All the options are parameter-value pairs. All parameters listed in this section must be configured as a value in `router_options`.
|
||||
**`router_options`** may include multiple **readwritesplit**-specific options.
|
||||
All the options are parameter-value pairs. All parameters listed in this section
|
||||
must be configured as a value in `router_options`.
|
||||
|
||||
Multiple options can be defined as a comma-separated list of parameter-value pairs.
|
||||
Multiple options can be defined as a comma-separated list of parameter-value
|
||||
pairs.
|
||||
|
||||
```
|
||||
router_options=<option>,<option>
|
||||
```
|
||||
For example, to set **`slave_selection_criteria** and **`disable_sescmd_history`**, write
|
||||
|
||||
For example, to set **`slave_selection_criteria`** and
|
||||
**`disable_sescmd_history`**, write
|
||||
|
||||
```
|
||||
router_options=slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS,disable_sescmd_history=true
|
||||
```
|
||||
|
||||
### `slave_selection_criteria`
|
||||
|
||||
This option controls how the readwritesplit router chooses the slaves it connects to and how the load balancing is done. The default behavior is to route read queries to the slave server with the lowest amount of ongoing queries i.e. `LEAST_CURRENT_OPERATIONS`.
|
||||
This option controls how the readwritesplit router chooses the slaves it
|
||||
connects to and how the load balancing is done. The default behavior is to route
|
||||
read queries to the slave server with the lowest amount of ongoing queries i.e.
|
||||
`LEAST_CURRENT_OPERATIONS`.
|
||||
|
||||
The option syntax:
|
||||
|
||||
@ -112,9 +145,12 @@ Where `<criteria>` is one of the following values.
|
||||
* `LEAST_BEHIND_MASTER`, the slave with smallest replication lag
|
||||
* `LEAST_CURRENT_OPERATIONS` (default), the slave with least active operations
|
||||
|
||||
The `LEAST_GLOBAL_CONNECTIONS` and `LEAST_ROUTER_CONNECTIONS` use the connections from MariaDB MaxScale to the server, not the amount of connections reported by the server itself.
|
||||
The `LEAST_GLOBAL_CONNECTIONS` and `LEAST_ROUTER_CONNECTIONS` use the
|
||||
connections from MariaDB MaxScale to the server, not the amount of connections
|
||||
reported by the server itself.
|
||||
|
||||
`LEAST_BEHIND_MASTER` does not take server weights into account when choosing a server.
|
||||
`LEAST_BEHIND_MASTER` does not take server weights into account when choosing a
|
||||
server.
|
||||
|
||||
#### Interaction Between `slave_selection_criteria` and `max_slave_connections`
|
||||
|
||||
@ -122,29 +158,33 @@ Depending on the value of `max_slave_connections`, the slave selection criteria
|
||||
behave in different ways. Here are a few example cases of how the different
|
||||
criteria work with different amounts of slave connections.
|
||||
|
||||
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` and `max_slave_connections=1`, each session picks
|
||||
one slave and one master
|
||||
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` and
|
||||
`max_slave_connections=1`, each session picks one slave and one master
|
||||
|
||||
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` and `max_slave_connections=100%`, each session
|
||||
picks one master and as many slaves as possible
|
||||
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` and
|
||||
`max_slave_connections=100%`, each session picks one master and as many slaves
|
||||
as possible
|
||||
|
||||
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` each read is load balanced based on how many
|
||||
queries are active on a particular slave
|
||||
|
||||
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` each read is sent to the slave with the least
|
||||
amount of connections
|
||||
* With `slave_selection_criteria=LEAST_CURRENT_OPERATIONS` each read is load
|
||||
balanced based on how many queries are active on a particular slave
|
||||
|
||||
* With `slave_selection_criteria=LEAST_GLOBAL_CONNECTIONS` each read is sent to
|
||||
the slave with the least amount of connections
|
||||
|
||||
### `max_sescmd_history`
|
||||
|
||||
**`max_sescmd_history`** sets a limit on how many session commands each session can execute before the session command history is disabled. The default is an unlimited number of session commands.
|
||||
**`max_sescmd_history`** sets a limit on how many session commands each session
|
||||
can execute before the session command history is disabled. The default is an
|
||||
unlimited number of session commands.
|
||||
|
||||
```
|
||||
# Set a limit on the session command history
|
||||
router_options=max_sescmd_history=1500
|
||||
```
|
||||
|
||||
When a limitation is set, it effectively creates a cap on the session's memory consumption. This might be useful if connection pooling is used and the sessions use large amounts of session commands.
|
||||
When a limitation is set, it effectively creates a cap on the session's memory
|
||||
consumption. This might be useful if connection pooling is used and the sessions
|
||||
use large amounts of session commands.
|
||||
|
||||
### `disable_sescmd_history`
|
||||
|
||||
@ -157,9 +197,8 @@ This option is only intended to be enabled if the value of
|
||||
`max_slave_connections` is lowered below the default value. This will allow a
|
||||
failed slave to be replaced with a standby slave server.
|
||||
|
||||
In versions 2.0 and older, the session command history is enabled by
|
||||
default. Starting with version 2.1, the session command history is disabled by
|
||||
default.
|
||||
In versions 2.0 and older, the session command history is enabled by default.
|
||||
Starting with version 2.1, the session command history is disabled by default.
|
||||
|
||||
```
|
||||
# Disable the session command history
|
||||
@ -168,7 +207,9 @@ router_options=disable_sescmd_history=true
|
||||
|
||||
### `master_accept_reads`
|
||||
|
||||
**`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.
|
||||
**`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.
|
||||
|
||||
By default, no reads are sent to the master.
|
||||
|
||||
@ -179,15 +220,17 @@ router_options=master_accept_reads=true
|
||||
|
||||
### `strict_multi_stmt`
|
||||
|
||||
When a client executes a multi-statement query, all queries after that will be routed to
|
||||
the master to guarantee a consistent session state. This behavior can be controlled with
|
||||
the **`strict_multi_stmt`** router option. This option is enabled by default.
|
||||
When a client executes a multi-statement query, all queries after that will be
|
||||
routed to the master to guarantee a consistent session state. This behavior can
|
||||
be controlled with the **`strict_multi_stmt`** router option. This option is
|
||||
enabled by default.
|
||||
|
||||
If set to false, queries are routed normally after a multi-statement query.
|
||||
|
||||
**Warning:** this can cause false data to be read from the slaves if the multi-statement query modifies
|
||||
the session state. Only disable the strict mode if you know that no changes to the session
|
||||
state will be made inside the multi-statement queries.
|
||||
**Warning:** this can cause false data to be read from the slaves if the
|
||||
multi-statement query modifies the session state. Only disable the strict mode
|
||||
if you know that no changes to the session state will be made inside the
|
||||
multi-statement queries.
|
||||
|
||||
```
|
||||
# Disable strict multi-statement mode
|
||||
@ -199,18 +242,18 @@ router_options=strict_multi_stmt=false
|
||||
This option controls how the failure of a master server is handled. By default,
|
||||
the router will close the client connection as soon as the master is lost.
|
||||
|
||||
The following table describes the values for this option and how they treat
|
||||
the loss of a master server.
|
||||
The following table describes the values for this option and how they treat the
|
||||
loss of a master server.
|
||||
|
||||
|Value |Description|
|
||||
| Value | Description|
|
||||
|--------------|-----------|
|
||||
|fail_instantly|When the failure of the master server is detected, the connection will be closed immediately.|
|
||||
|fail_on_write |The client connection is closed if a write query is received when no master is available.|
|
||||
|error_on_write|If no master is available and a write query is received, an error is returned stating that the connection is in read-only mode.|
|
||||
|fail_instantly | When the failure of the master server is detected, the connection will be closed immediately.|
|
||||
|fail_on_write | The client connection is closed if a write query is received when no master is available.|
|
||||
|error_on_write | If no master is available and a write query is received, an error is returned stating that the connection is in read-only mode.|
|
||||
|
||||
These also apply to new sessions created after the master has failed. This means
|
||||
that in _fail_on_write_ or _error_on_write_ mode, connections are accepted as long
|
||||
as slave servers are available.
|
||||
that in _fail_on_write_ or _error_on_write_ mode, connections are accepted as
|
||||
long as slave servers are available.
|
||||
|
||||
**Note:** If _master_failure_mode_ is set to _error_on_write_ and the connection
|
||||
to the master is lost, clients will not be able to execute write queries without
|
||||
@ -218,18 +261,19 @@ reconnecting to MariaDB MaxScale once a new master is available.
|
||||
|
||||
### `retry_failed_reads`
|
||||
|
||||
This option controls whether autocommit selects are retried in case of
|
||||
failure. This option is enabled by default.
|
||||
This option controls whether autocommit selects are retried in case of failure.
|
||||
This option is enabled by default.
|
||||
|
||||
When a simple autocommit select is being executed outside of a transaction
|
||||
and the slave server where the query is being executed fails,
|
||||
readwritesplit can retry the read on a replacement server. This makes the
|
||||
failure of a slave transparent to the client.
|
||||
When a simple autocommit select is being executed outside of a transaction and
|
||||
the slave server where the query is being executed fails, readwritesplit can
|
||||
retry the read on a replacement server. This makes the failure of a slave
|
||||
transparent to the client.
|
||||
|
||||
## Routing hints
|
||||
|
||||
The readwritesplit router supports routing hints. For a detailed guide on hint
|
||||
syntax and functionality, please read [this](../Reference/Hint-Syntax.md) document.
|
||||
syntax and functionality, please read [this](../Reference/Hint-Syntax.md)
|
||||
document.
|
||||
|
||||
**Note**: Routing hints will always have the highest priority when a routing
|
||||
decision is made. This means that it is possible to cause inconsistencies in
|
||||
@ -239,55 +283,79 @@ hints when you are sure that they can cause no harm.
|
||||
|
||||
## Limitations
|
||||
|
||||
For a list of readwritesplit limitations, please read the [Limitations](../About/Limitations.md) document.
|
||||
For a list of readwritesplit limitations, please read the
|
||||
[Limitations](../About/Limitations.md) document.
|
||||
|
||||
## Examples
|
||||
|
||||
Examples of the readwritesplit router in use can be found in the [Tutorials](../Tutorials) folder.
|
||||
Examples of the readwritesplit router in use can be found in the
|
||||
[Tutorials](../Tutorials) folder.
|
||||
|
||||
## Readwritesplit routing decisions
|
||||
|
||||
Here is a small explanation which shows what kinds of queries are routed to which type of server.
|
||||
Here is a small explanation which shows what kinds of queries are routed to
|
||||
which type of server.
|
||||
|
||||
### Routing to Master
|
||||
|
||||
Routing to master is important for data consistency and because majority of writes are written to binlog and thus become replicated to slaves.
|
||||
Routing to master is important for data consistency and because majority of
|
||||
writes are written to binlog and thus become replicated to slaves.
|
||||
|
||||
The following operations are routed to master:
|
||||
|
||||
* write statements,
|
||||
* all statements within an open transaction,
|
||||
* stored procedure calls, and
|
||||
* user-defined function calls.
|
||||
* stored procedure calls
|
||||
* user-defined function calls
|
||||
* DDL statements (`DROP`|`CREATE`|`ALTER TABLE` … etc.)
|
||||
* `EXECUTE` (prepared) statements
|
||||
* all statements using temporary tables
|
||||
|
||||
In addition to these, if the **readwritesplit** service is configured with the `max_slave_replication_lag` parameter, and if all slaves suffer from too much replication lag, then statements will be routed to the _Master_. (There might be other similar configuration parameters in the future which limit the number of statements that will be routed to slaves.)
|
||||
In addition to these, if the **readwritesplit** service is configured with the
|
||||
`max_slave_replication_lag` parameter, and if all slaves suffer from too much
|
||||
replication lag, then statements will be routed to the _Master_. (There might be
|
||||
other similar configuration parameters in the future which limit the number of
|
||||
statements that will be routed to slaves.)
|
||||
|
||||
### Routing to Slaves
|
||||
|
||||
The ability to route some statements to *Slave*s is important because it also decreases the load targeted to master. Moreover, it is possible to have multiple slaves to share the load in contrast to single master.
|
||||
The ability to route some statements to slaves is important because it also
|
||||
decreases the load targeted to master. Moreover, it is possible to have multiple
|
||||
slaves to share the load in contrast to single master.
|
||||
|
||||
Queries which can be routed to slaves must be auto committed and belong to one of the following group:
|
||||
Queries which can be routed to slaves must be auto committed and belong to one
|
||||
of the following group:
|
||||
|
||||
* read-only database queries,
|
||||
* read-only queries to system, or user-defined variables,
|
||||
* `SHOW` statements, and
|
||||
* `SHOW` statements
|
||||
* system function calls.
|
||||
|
||||
### Routing to every session backend
|
||||
|
||||
A third class of statements includes those which modify session data, such as session system variables, user-defined variables, the default database, etc. We call them session commands, and they must be replicated as they affect the future results of read and write operations, so they must be executed on all servers that could execute statements on behalf of this client.
|
||||
A third class of statements includes those which modify session data, such as
|
||||
session system variables, user-defined variables, the default database, etc. We
|
||||
call them session commands, and they must be replicated as they affect the
|
||||
future results of read and write operations. They must be executed on all
|
||||
servers that could execute statements on behalf of this client.
|
||||
|
||||
Session commands include for example:
|
||||
|
||||
* `SET` statements
|
||||
* `USE `*`<dbname>`*
|
||||
* system/user-defined variable assignments embedded in read-only statements, such as `SELECT (@myvar := 5)`
|
||||
* system/user-defined variable assignments embedded in read-only statements, such
|
||||
as `SELECT (@myvar := 5)`
|
||||
* `PREPARE` statements
|
||||
* `QUIT`, `PING`, `STMT RESET`, `CHANGE USER`, etc. commands
|
||||
|
||||
**NOTE: if variable assignment is embedded in a write statement it is routed to _Master_ only. For example, `INSERT INTO t1 values(@myvar:=5, 7)` would be routed to _Master_ only.**
|
||||
**NOTE**: if variable assignment is embedded in a write statement it is routed
|
||||
to _Master_ only. For example, `INSERT INTO t1 values(@myvar:=5, 7)` would be
|
||||
routed to _Master_ only.
|
||||
|
||||
The router stores all of the executed session commands so that in case of a slave failure, a replacement slave can be chosen and the session command history can be repeated on that new slave. This means that the router stores each executed session command for the duration of the session. Applications that use long-running sessions might cause MariaDB MaxScale to consume a growing amount of memory unless the sessions are closed. This can be solved by setting a connection timeout on the application side.
|
||||
The router stores all of the executed session commands so that in case of a
|
||||
slave failure, a replacement slave can be chosen and the session command history
|
||||
can be repeated on that new slave. This means that the router stores each
|
||||
executed session command for the duration of the session. Applications that use
|
||||
long-running sessions might cause MariaDB MaxScale to consume a growing amount
|
||||
of memory unless the sessions are closed. This can be solved by setting a
|
||||
connection timeout on the application side.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
#SchemaRouter Router
|
||||
# SchemaRouter Router
|
||||
|
||||
The SchemaRouter router provides an easy and manageable sharding solution by building a single logical database server from multiple separate ones. Each database is shown to the client and queries targeting unique databases are routed to their respective servers. In addition to providing simple database-based sharding, the schemarouter router also enables cross-node session variable usage by routing all queries that modify the session to all nodes.
|
||||
|
||||
@ -29,7 +29,7 @@ The list of databases is built by sending a SHOW DATABASES query to all the serv
|
||||
|
||||
If you are connecting directly to a database or have different users on some of the servers, you need to get the authentication data from all the servers. You can control this with the `auth_all_servers` parameter. With this parameter, MariaDB MaxScale forms a union of all the users and their grants from all the servers. By default, the schemarouter will fetch the authentication data from all servers.
|
||||
|
||||
For example, if two servers have the database 'shard' and the following rights are granted only on one server, all queries targeting the database 'shard' would be routed to the server where the grants were given.
|
||||
For example, if two servers have the database `shard` and the following rights are granted only on one server, all queries targeting the database `shard` would be routed to the server where the grants were given.
|
||||
|
||||
```
|
||||
# Execute this on both servers
|
||||
@ -68,6 +68,8 @@ refresh_interval=60
|
||||
|
||||
## Router Options
|
||||
|
||||
**Note:** Router options for the Schemarouter were deprecated in MaxScale 2.1.
|
||||
|
||||
The following options are options for the `router_options` parameter of the
|
||||
service. Multiple router options are given as a comma separated list of key
|
||||
value pairs.
|
||||
@ -87,7 +89,7 @@ will not be consistent anymore.
|
||||
### `refresh_databases`
|
||||
|
||||
Enable database map refreshing mid-session. These are triggered by a failure to
|
||||
change the database i.e. `USE ...``queries.
|
||||
change the database i.e. `USE ...` queries.
|
||||
|
||||
### `refresh_interval`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user