From 9ddd1865501a196b7da067e0f732b5e6926b3545 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 13 Mar 2019 12:57:39 +0200 Subject: [PATCH] MXS-2313: Update rank documentation Updated the value types, added a simpler example and created a separate section in readwritesplit documentation on the behavior of ranked servers. --- .../Getting-Started/Configuration-Guide.md | 107 ++++++------------ Documentation/Routers/ReadWriteSplit.md | 25 ++++ 2 files changed, 58 insertions(+), 74 deletions(-) diff --git a/Documentation/Getting-Started/Configuration-Guide.md b/Documentation/Getting-Started/Configuration-Guide.md index 7d2daa0fe..6124796cb 100644 --- a/Documentation/Getting-Started/Configuration-Guide.md +++ b/Documentation/Getting-Started/Configuration-Guide.md @@ -1558,95 +1558,54 @@ if the disk space situation should be monitored. #### `rank` -The ranking of this server. Servers with a lower value of `rank` are prioritized -over servers with a higher value. This parameter is intended to allow the user -to control in which order the servers of a cluster are used. +This parameter controls the order in which servers are used. Valid values for +this parameter are `primary` and `secondary`. The default value is +`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 -lowest accepted value is 1. This parameter replaces the use of the `weightby` -parameter as the primary means of controlling server usage. +This behavior depends on the router implementation but the general rule of thumb +is that primary servers will be used before secondary servers. -Each server that shares the same `rank` is placed into a set and only one set of -servers is used at any one time. This behavior depends on the router -implementation which is why there are a few exceptions to this rule. +Readconnroute will always use primary servers before secondary servers as long +as they match the configured server type. -One exception to the rule is when a readwritesplit session must find a master -server but the rank of the master is not the lowest among all available -servers. In this case readwritesplit will pick the master with the lowest value -of rank among all master servers. +Readwritesplit will pick servers that have the same rank as the current +master. Read the +[readwritesplit documentation on server ranks](../Routers/ReadWriteSplit.md#server-ranks) +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 address=192.168.0.11 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 address=192.168.0.22 protocol=MariaDBBackend -rank=2 - -[C] -type=server -address=192.168.0.33 -protocol=MariaDBBackend -rank=2 - -[D] -type=server -address=192.168.0.44 -protocol=MariaDBBackend +rank=secondary ``` -The three servers, A, B and C, each have a `rank` value. Server D has no rank so -the default value is used. Three distinct sets of servers are created: - -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. +The `main-site-master` and `main-site-slave` servers will be used as long as +they are available. When they are no longer available, the `DR-site-master` and +`DR-site-slave` will be used. ### Listener diff --git a/Documentation/Routers/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 6d3847c9c..e8e893510 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -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, 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 The readwritesplit router supports routing hints. For a detailed guide on hint