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

MXS-2313: Update rank documentation

Browse Source 
Updated the value types, added a simpler example and created a separate
section in readwritesplit documentation on the behavior of ranked servers.
This commit is contained in:
Markus Mäkelä
2019-03-13 12:57:39 +02:00
parent 4bf9fa872c
commit 9ddd186550
2 changed files with 58 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
Documentation/Getting-Started/Configuration-Guide.md
View File

@ -1558,95 +1558,54 @@ if the disk space situation should be monitored.
#### `rank` #### `rank`
The ranking of this server. Servers with a lower value of `rank` are prioritized This parameter controls the order in which servers are used. Valid values for
over servers with a higher value. This parameter is intended to allow the user this parameter are `primary` and `secondary`. The default value is
to control in which order the servers of a cluster are used. `primary`. This parameter replaces the use of the `weightby` parameter as the
primary means of controlling server usage.
The default value is 2147483647 which is also the upper limit for the value. The This behavior depends on the router implementation but the general rule of thumb
lowest accepted value is 1. This parameter replaces the use of the `weightby` is that primary servers will be used before secondary servers.
parameter as the primary means of controlling server usage.
Each server that shares the same `rank` is placed into a set and only one set of Readconnroute will always use primary servers before secondary servers as long
servers is used at any one time. This behavior depends on the router as they match the configured server type.
implementation which is why there are a few exceptions to this rule.
One exception to the rule is when a readwritesplit session must find a master Readwritesplit will pick servers that have the same rank as the current
server but the rank of the master is not the lowest among all available master. Read the
servers. In this case readwritesplit will pick the master with the lowest value [readwritesplit documentation on server ranks](../Routers/ReadWriteSplit.md#server-ranks)
of rank among all master servers. for a detailed description of the behavior.
The following example configuration demonstrates how the parameter is used. The following example server configuration demonstrates how `rank` can be used
to exclude `DR-site` servers from routing.
``` ```
[A] [main-site-master]
type=server type=server
address=192.168.0.11 address=192.168.0.11
protocol=MariaDBBackend protocol=MariaDBBackend
rank=1 rank=primary
[B] [main-site-slave]
type=server
address=192.168.0.12
protocol=MariaDBBackend
rank=primary
[DR-site-master]
type=server
address=192.168.0.21
protocol=MariaDBBackend
rank=secondary
[DR-site-slave]
type=server type=server
address=192.168.0.22 address=192.168.0.22
protocol=MariaDBBackend protocol=MariaDBBackend
rank=2 rank=secondary
[C]
type=server
address=192.168.0.33
protocol=MariaDBBackend
rank=2
[D]
type=server
address=192.168.0.44
protocol=MariaDBBackend
``` ```
The three servers, A, B and C, each have a `rank` value. Server D has no rank so The `main-site-master` and `main-site-slave` servers will be used as long as
the default value is used. Three distinct sets of servers are created: they are available. When they are no longer available, the `DR-site-master` and
`DR-site-slave` will be used.
1. A
2. B and C
3. D
If A is available, it will always be used. When A is not available, both B and C
are used. Only when D is the last available server will it be used.
Another example use-case for this is a remote server (D) replicating from a
cluster (A, B, C) that is primarily used for backups but in case of a total
cluster failure is also used as a read-only standbyu server. To configure this
in MaxScale using `rank` the following could be used.
```
[A]
type=server
address=192.168.0.11
protocol=MariaDBBackend
rank=1
[B]
type=server
address=192.168.0.22
protocol=MariaDBBackend
rank=1
[C]
type=server
address=192.168.0.33
protocol=MariaDBBackend
rank=1
[D]
type=server
address=192.168.0.44
protocol=MariaDBBackend
rank=2
```
With this configuration the three servers in the primary cluster (A, B, C) would
be used. Only when the whole primary cluster is down would server D be used and
as soon as any of the primary servers became available, D would stop receiving
traffic.
### Listener ### Listener

25
Documentation/Routers/ReadWriteSplit.md
View File

@ -559,6 +559,31 @@ initial connection creation is skipped. If the client executes only read
queries, no connection to the master is made. If only write queries are made, queries, no connection to the master is made. If only write queries are made,
only the master connection is used. only the master connection is used.
## Server Ranks
The general rule with server ranks is that primary servers will be used before
secondary servers. Readwritesplit is an exception to this rule. The following
rules govern how readwritesplit behaves with servers that have different ranks.
* Sessions will use the current master server as long as possible. This means
that sessions with a secondary master will not use the primary master as long
as the secondary master is available.
* All slave connections will use the same rank as the master connection. Any
stale connections with a different rank than the master will be discarded.
* If no master connection is available and `master_reconnection` is enabled, a
connection to the best master is created. If the new master has a different
priority than existing connections have, the connections with a different rank
will be discarded.
* If open connections exist, these will be used for routing. This means that if
the master is lost but the session still has slave servers with the same rank,
they will remain in use.
* If no open connections exist, the servers with the best rank will used.
## Routing hints ## Routing hints
The readwritesplit router supports routing hints. For a detailed guide on hint The readwritesplit router supports routing hints. For a detailed guide on hint