Update NamedServerFilter documentation
The document is now up to date with the rewrite. Also added an assert to enforce a minimum number of allowed match-target pairs.
This commit is contained in:
Esa Korhonen
parent
c2857b976a
commit
657d79470c
@ -2,18 +2,42 @@
|
||||
|
||||
## Overview
|
||||
|
||||
The **namedserverfilter** is a filter module for MariaDB MaxScale which is able to route queries to servers based on regular expression matches.
|
||||
The **namedserverfilter** is a MariaDB MaxScale filter module able to route
|
||||
queries to servers based on regular expression (regex) matches. Since it is a
|
||||
filter instead of a router, the NamedServerFilter only sets routing suggestions.
|
||||
It requires a compatible router to be effective. Currently, both
|
||||
**readwritesplit** and **hintrouter** take advantage of routing hints in the
|
||||
data packets. This filter uses the *PCRE2* library for regular expression
|
||||
matching.
|
||||
|
||||
## Configuration
|
||||
|
||||
The configuration block for the Named Server filter requires the minimal filter options in it’s section within the maxscale.cnf file, stored in /etc/maxscale.cnf.
|
||||
The filter accepts settings in two modes: *legacy* and *indexed*. Only one of
|
||||
the modes may be used for a given filter instance. The legacy mode is meant for
|
||||
backwards compatibility and allows only one regular expression and one server
|
||||
name in the configuration. In indexed mode, up to 25 regex-server pairs are
|
||||
allowed in the form *match01* - *target01*, *match02* - *target02* and so on.
|
||||
Also, in indexed mode, the server names (targets) may contain a list of names or
|
||||
special tags `->master` or `->slave`.
|
||||
|
||||
Below is a configuration example for the filter in indexed-mode. The legacy mode
|
||||
is not recommeded and may be removed in a future release. In the example, a
|
||||
SELECT on TableOne (*match01*) results in routing hints to two named servers,
|
||||
while a SELECT on TableTwo is suggested to be routed to the master server of the
|
||||
service. Whether a list of server names is interpreted as a route-to-any or
|
||||
route-to-all is up to the attached router. The HintRouter sees a list as a
|
||||
suggestion to route-to-any. For additional information on hints and how they can
|
||||
also be embedded into SQL-queries, see
|
||||
[Hint-Syntax](../Reference/Hint-Syntax.md).
|
||||
|
||||
```
|
||||
[NamedServerFilter]
|
||||
type=filter
|
||||
module=namedserverfilter
|
||||
match=some string
|
||||
server=server2
|
||||
match01=^Select.*TableOne$
|
||||
target01=SlaveServer1, SlaveServer2
|
||||
match22=^SELECT.*TableTwo$
|
||||
target22=->master
|
||||
|
||||
[MyService]
|
||||
type=service
|
||||
@ -24,50 +48,39 @@ passwd=mypasswd
|
||||
filters=NamedServerFilter
|
||||
```
|
||||
|
||||
## Filter Options
|
||||
|
||||
The named server filter accepts the following options.
|
||||
|
||||
|Option |Description |
|
||||
|----------|--------------------------------------------|
|
||||
|ignorecase|Use case-insensitive matching |
|
||||
|case |Use case-sensitive matching |
|
||||
|extended |Use extended regular expression syntax (ERE)|
|
||||
|
||||
To use multiple filter options, list them in a comma-separated list.
|
||||
|
||||
```
|
||||
options=case,extended
|
||||
```
|
||||
|
||||
**Note:** The _ignorecase_ and _case_ options are mutually exclusive and only
|
||||
one of them should be used.
|
||||
|
||||
## Filter Parameters
|
||||
|
||||
The named server filter requires two mandatory parameters to be defined.
|
||||
The NamedServerFilter requires two mandatory parameters.
|
||||
|
||||
### `match`
|
||||
### `matchXY`
|
||||
|
||||
A parameter that can be used to match text in the SQL statement which should be replaced.
|
||||
Regular expression the SQL-query is matched against. XY must be a number in the
|
||||
range 01 - 25. Each *match* setting must have a similarly indexed *target*
|
||||
setting.
|
||||
|
||||
```
|
||||
match=TYPE[ ]*=
|
||||
match01=^SELECT
|
||||
```
|
||||
|
||||
If the filter option ignorecase is used all regular expressions are evaluated with the option to ignore the case of the text, therefore a match option of select will match both type, TYPE and any form of the word with upper or lowercase characters.
|
||||
### `targetXY`
|
||||
|
||||
### `server`
|
||||
|
||||
This is the server where matching queries will be router. The server should be in use by the service which uses this filter.
|
||||
This is the hint which will be attached to the queries matching the regex. If a
|
||||
compatible router is used in the service the query will be routed accordingly.
|
||||
The target can be a server name, a list of server names (comma-separated),
|
||||
`->master` or `->slave`. The server names add the names as hints (one name per
|
||||
hint). `->master` adds a *route-to-master*- hint and `->slave` adds a
|
||||
*route-to-slave*-hint.
|
||||
|
||||
```
|
||||
server=server2
|
||||
target01=MyServer2
|
||||
```
|
||||
|
||||
### `source`
|
||||
|
||||
The optional source parameter defines an IP address that is used to match against the address from which the client connection to MariaDB MaxScale originates. Only sessions that originate from this IP address will have the match and replacement applied to them.
|
||||
This optional parameter defines an IP address or mask which a connecting
|
||||
client's IP address is matched against. Only sessions whose address matches this
|
||||
setting will have this filter active and performing the regex matching. Traffic
|
||||
from unmatching client IPs is simply left as is and routed straight through.
|
||||
|
||||
```
|
||||
source=127.0.0.1
|
||||
@ -79,31 +92,70 @@ source=192.%.%.%
|
||||
source=192.168.%.%
|
||||
source=192.168.10.%
|
||||
```
|
||||
Please note that using source=% to match any IP it's not allowed.
|
||||
Note that using source=% to match any IP is not allowed.
|
||||
|
||||
### `user`
|
||||
|
||||
The optional user parameter defines a user name that is used to match against the user from which the client connection to MariaDB MaxScale originates. Only sessions that are connected using this username will have the match and replacement applied to them.
|
||||
This optional parameter defines a user name the connecting client username is
|
||||
matched against. Only sessions that are connected using this username will have
|
||||
the match and routing hints applied to them. Traffic from unmatching client user
|
||||
names is simply left as is and routed straight through.
|
||||
|
||||
```
|
||||
user=john
|
||||
```
|
||||
|
||||
## Filter Options
|
||||
|
||||
The named server filter accepts the following options.
|
||||
|
||||
|Option |Description |
|
||||
|----------|--------------------------------------------|
|
||||
|ignorecase|Use case-insensitive matching (default) |
|
||||
|case |Use case-sensitive matching |
|
||||
|extended |Ignore white space and # comments |
|
||||
|
||||
To use multiple filter options, list them in a comma-separated list.
|
||||
|
||||
```
|
||||
options=case,extended
|
||||
```
|
||||
|
||||
**Note:** The *ignorecase* and *case* options are mutually exclusive and only
|
||||
one of them should be used.
|
||||
|
||||
## Notes
|
||||
|
||||
The maximum number of accepted *match* - *target* pairs may be higher and can
|
||||
change if other features are added to the filter. A minimum of 25 is guaranteed
|
||||
for now.
|
||||
|
||||
In the configuration, the indexed match and target settings may be in any order
|
||||
and may skip numbers. During SQL-query matching, however, the regexes are tested
|
||||
in ascending order: match01, match02, match03 and so on. As soon as a match is
|
||||
found for a qiven query, the routing hints are written and the packet is
|
||||
forwarded to the next filter or router. Any possibly remaining match regexes are
|
||||
ignored. This means the *match* - *target* pairs should be indexed in priority
|
||||
order, or, if priority is not a factor, in order of decreasing match
|
||||
probability.
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1 - Route queries targeting a specific table to a server
|
||||
|
||||
This will route all queries matching the regular expression ` *from *users` to the server named *server2*. The filter will ignore character case in queries.
|
||||
This will route all queries matching the regular expression ` *from *users` to
|
||||
the server named *server2*. The filter will ignore character case in queries.
|
||||
|
||||
A query like `SELECT * FROM users` would be routed to server2 where as a query like `SELECT * FROM accounts` would be routed according to the normal rules of the router.
|
||||
A query like `SELECT * FROM users` would be routed to server2 where as a query
|
||||
like `SELECT * FROM accounts` would be routed according to the normal rules of
|
||||
the router.
|
||||
|
||||
```
|
||||
[NamedServerFilter]
|
||||
type=filter
|
||||
module=namedserverfilter
|
||||
match= *from *users
|
||||
options=ignorecase
|
||||
server=server2
|
||||
match02= *from *users
|
||||
target02=server2
|
||||
|
||||
[MyService]
|
||||
type=service
|
||||
|
||||
@ -820,6 +820,7 @@ extern "C" MXS_MODULE* MXS_CREATE_MODULE()
|
||||
{
|
||||
match_server_pairs = max_pairs;
|
||||
}
|
||||
ss_dassert(match_server_pairs >= 25); // If this limit is modified, update documentation.
|
||||
/* Create parameter pair names */
|
||||
generate_param_names(match_server_pairs);
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user