From a395db174eb81d16ba3297be1f94e066c7df60b1 Mon Sep 17 00:00:00 2001 From: Esa Korhonen Date: Tue, 28 Mar 2017 14:42:53 +0300 Subject: [PATCH] Add HintRouter documentation --- Documentation/Documentation-Contents.md | 1 + Documentation/Routers/HintRouter.md | 86 +++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 Documentation/Routers/HintRouter.md diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index 9a2a8e26d..6b8057d68 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -64,6 +64,7 @@ of their use. - [Schemarouter](Routers/SchemaRouter.md) - [Binlogrouter](Routers/Binlogrouter.md) - [Avrorouter](Routers/Avrorouter.md) + - [HintRouter](Routers/HintRouter.md) There are also two diagnostic routing modules. The CLI is for MaxAdmin and the Debug CLI client for Telnet. diff --git a/Documentation/Routers/HintRouter.md b/Documentation/Routers/HintRouter.md new file mode 100644 index 000000000..dbb7c9ef5 --- /dev/null +++ b/Documentation/Routers/HintRouter.md @@ -0,0 +1,86 @@ +# HintRouter + +## Overview + +The **HintRouter** module is a simple router intended to operate in conjunction +with the NamedServerFilter. The router looks at the hints embedded in a packet +buffer and attempts to route the packet according to the hint. The user can also +set a default action to be taken when a query has no hints or when the hints +could not be applied. + +If a packet has multiple hints attached, the router will read them in order and +attempt routing. Any successful routing ends the process and any further hints +are ignored for the packet. + +## Configuration + +The HintRouter is a rather simple router and only accepts a few configuration +settings. + +``` +default_action= +``` + +This setting defines what happens when a query has no routing hint or applying +the routing hint(s) fails. If also the default action fails, the routing will +end in error and the session closes. The different values are: + +Value | Description +------ |----------- +master | Route to the master server. +slave | Route to any single slave server. +named | Route to a named server. The name is given in the `default_server`-setting. +all | Default value. Route to all connected servers. + +Note that setting default action to anything other than `all` means that session +variable write commands are by default not routed to all backends. + +``` +default_server= +``` + +Defines the default backend name if `default_action=named`. `` must +be a valid backend name. + +``` +max_slaves= +``` + +`` should be an integer, -1 by default. Defines how many backend slave +servers a session should attempt to connect to. Having less slaves defined in +the services and/or less successful connections during session creation is not +an error. The router will attempt to distribute slaves evenly between sessions +by assigning them in a round robin fashion. The session will always try to +connect to a master regardless of this setting, although not finding one is not +an error. + +Negative values activate default mode, in which case this value is set to the +number of backends in the service - 1, so that the sessions are connected to all +slaves. + +If the hints or the `default_action` point to a named server, this setting is +probably best left to default to ensure that the specific server is connected to +at session creation. The router will not attempt to connect to additional +servers after session creation. + +## Examples + +A minimal configuration doesn't require any parameters as all settings have +reasonable defaults. +``` +[Routing Service] +type=service +router=hintrouter +servers=slave1,slave2,slave3 +``` + +If packets should be routed to the master server by default and only a few +connections are required, the configuration might be as follows. +``` +[Routing Service] +type=service +router=hintrouter +servers=MyMaster, slave1,slave2,slave3,slave4,slave5,slave6,slave7 +default_action=master +max_slaves=2 +```