Merge branch '2.3' into develop
This commit is contained in:
Markus Mäkelä
commit
12c22f0ba8
@ -86,6 +86,7 @@ Here are detailed documents about the filters MariaDB MaxScale offers. They cont
|
||||
- [Maxrows Filter](Filters/Maxrows.md)
|
||||
- [Named Server Filter](Filters/Named-Server-Filter.md)
|
||||
- [Query Log All](Filters/Query-Log-All-Filter.md)
|
||||
- [Hint Filter](Filters/Hintfilter.md)
|
||||
- [RabbitMQ Filter](Filters/RabbitMQ-Filter.md)
|
||||
- [Regex Filter](Filters/Regex-Filter.md)
|
||||
- [Tee Filter](Filters/Tee-Filter.md)
|
||||
|
||||
132
Documentation/Filters/Hintfilter.md
Normal file
132
Documentation/Filters/Hintfilter.md
Normal file
@ -0,0 +1,132 @@
|
||||
# Hintfilter
|
||||
|
||||
This filter adds routing hints to a service. The filter has no parameters.
|
||||
|
||||
# Hint Syntax
|
||||
|
||||
**Note:** If a query has more than one comment only the first comment is
|
||||
processed. Always place any MaxScale related comments first before any other
|
||||
comments that might appear in the query.
|
||||
|
||||
## Comments and comment types
|
||||
|
||||
The client connection will need to have comments enabled. For example the
|
||||
`mysql` command line client has comments disabled by default and they need to be
|
||||
enabled by passing the `-c` option. Most, if not all, connectors keep all
|
||||
comments intact in executed queries.
|
||||
|
||||
For comment types, use either `-- ` (notice the whitespace after the double
|
||||
hyphen) or `#` after the semicolon or `/* ... */` before the semicolon.
|
||||
|
||||
Inline comment blocks, i.e. `/* .. */`, do not require a whitespace character
|
||||
after the start tag or before the end tag but adding the whitespace is advised.
|
||||
|
||||
## Hint body
|
||||
|
||||
All hints must start with the `maxscale` tag.
|
||||
|
||||
```
|
||||
-- maxscale <hint body>
|
||||
```
|
||||
|
||||
The hints have two types, ones that define a server type and others that contain
|
||||
name-value pairs.
|
||||
|
||||
### Routing destination hints
|
||||
|
||||
These hints will instruct the router to route a query to a certain type of a
|
||||
server.
|
||||
|
||||
```
|
||||
-- maxscale route to [master | slave | server <server name>]
|
||||
```
|
||||
|
||||
A `master` value in a routing hint will route the query to a master server. This
|
||||
can be used to direct read queries to a master server for a up-to-date result
|
||||
with no replication lag. A `slave` value will route the query to a slave
|
||||
server. A `server` value will route the query to a named server. The value of
|
||||
_<server name>_ needs to be the same as the server section name in maxscale.cnf.
|
||||
|
||||
### Name-value hints
|
||||
|
||||
These control the behavior and affect the routing decisions made by the router.
|
||||
|
||||
```
|
||||
-- maxscale <param>=<value>
|
||||
```
|
||||
|
||||
Currently the only accepted parameter is `max_slave_replication_lag`. This will
|
||||
route the query to a server with lower replication lag then what is defined in
|
||||
the hint value.
|
||||
|
||||
## Hint stack
|
||||
|
||||
Hints can be either single-use hints, which makes them affect only one query, or
|
||||
named hints, which can be pushed on and off a stack of active hints.
|
||||
|
||||
Defining named hints:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> prepare <hint content>
|
||||
```
|
||||
|
||||
Pushing a hint onto the stack:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> begin
|
||||
```
|
||||
|
||||
Popping the topmost hint off the stack:
|
||||
|
||||
```
|
||||
-- maxscale end
|
||||
```
|
||||
|
||||
You can define and activate a hint in a single command using the following:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> begin <hint content>
|
||||
```
|
||||
|
||||
You can also push anonymous hints onto the stack which are only used as long as
|
||||
they are on the stack:
|
||||
|
||||
```
|
||||
-- maxscale begin <hint content>
|
||||
```
|
||||
|
||||
# Examples
|
||||
|
||||
## Routing `SELECT` queries to master
|
||||
|
||||
In this example, MariaDB MaxScale is configured with the readwritesplit router
|
||||
and the hint filter.
|
||||
|
||||
```
|
||||
[ReadWriteService]
|
||||
type=service
|
||||
router=readwritesplit
|
||||
servers=server1,server2
|
||||
user=maxuser
|
||||
passwd=maxpwd
|
||||
filters=Hint
|
||||
|
||||
[Hint]
|
||||
type=filter
|
||||
module=hintfilter
|
||||
```
|
||||
|
||||
Behind MariaDB MaxScale is a master server and a slave server. If there is
|
||||
replication lag between the master and the slave, read queries sent to the slave
|
||||
might return old data. To guarantee up-to-date data, we can add a routing hint
|
||||
to the query.
|
||||
|
||||
```
|
||||
INSERT INTO table1 VALUES ("John","Doe",1);
|
||||
SELECT * from table1; -- maxscale route to master
|
||||
```
|
||||
|
||||
The first INSERT query will be routed to the master. The following SELECT query
|
||||
would normally be routed to the slave but with the added routing hint it will be
|
||||
routed to the master. This way we can do an INSERT and a SELECT right after it
|
||||
and still get up-to-date data.
|
||||
@ -1,148 +1,4 @@
|
||||
# Hint Syntax
|
||||
|
||||
## Enabling routing hints
|
||||
|
||||
To enable user specified routing hints for a service, the hintfilter module
|
||||
needs to be configured and the filter needs to be applied to the service.
|
||||
|
||||
Here is an example service which has the hint filter configured and applied.
|
||||
|
||||
```
|
||||
[Read-Service]
|
||||
type=service
|
||||
router=readconnroute
|
||||
router_options=master
|
||||
servers=server1
|
||||
user=maxuser
|
||||
passwd=maxpwd
|
||||
filters=Hint
|
||||
|
||||
[Hint]
|
||||
type=filter
|
||||
module=hintfilter
|
||||
|
||||
```
|
||||
|
||||
## Comments and comment types
|
||||
|
||||
The client connection will need to have comments enabled. For example the
|
||||
`mysql` command line client has comments disabled by default and they need
|
||||
to be enabled by passing the `-c` option.
|
||||
|
||||
For comment types, use either `-- ` (notice the whitespace after the double
|
||||
hyphen) or `#` after the semicolon or `/* .. */` before the semicolon.
|
||||
|
||||
The MySQL manual doesn't specify if comment blocks, i.e. `/* .. */`, should
|
||||
contain a whitespace character before or after the tags, so adding
|
||||
whitespace at both the start and the end is advised.
|
||||
|
||||
## Hint body
|
||||
|
||||
All hints must start with the `maxscale` tag.
|
||||
|
||||
```
|
||||
-- maxscale <hint body>
|
||||
```
|
||||
|
||||
The hints have two types, ones that define a server type and others that contain
|
||||
name-value pairs.
|
||||
|
||||
### Routing destination hints
|
||||
|
||||
These hints will instruct the router to route a query to a certain type of a server.
|
||||
```
|
||||
-- maxscale route to [master | slave | server <server name> | last]
|
||||
```
|
||||
|
||||
A `master` value in a routing hint will route the query to a master
|
||||
server. This can be used to direct read queries to a master server for a
|
||||
up-to-date result with no replication lag. A `slave` value will route the
|
||||
query to a slave server. A `server` value will route the query to a named
|
||||
server. The value of <server name> needs to be the same as the server
|
||||
section name in maxscale.cnf. A `last` value will route the query to the
|
||||
same server the previous query was routed to.
|
||||
|
||||
### Name-value hints
|
||||
|
||||
These control the behavior and affect the routing decisions made by the router.
|
||||
|
||||
```
|
||||
-- maxscale <param>=<value>
|
||||
```
|
||||
|
||||
Currently the only accepted parameter is `max_slave_replication_lag`. This
|
||||
will route the query to a server with lower replication lag then what is
|
||||
defined in the hint value.
|
||||
|
||||
## Hint stack
|
||||
|
||||
Hints can be either single-use hints, which makes them affect only one
|
||||
query, or named hints, which can be pushed on and off a stack of active
|
||||
hints.
|
||||
|
||||
Defining named hints:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> prepare <hint content>
|
||||
```
|
||||
|
||||
Pushing a hint onto the stack:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> begin
|
||||
```
|
||||
|
||||
Popping the topmost hint off the stack:
|
||||
|
||||
```
|
||||
-- maxscale end
|
||||
```
|
||||
|
||||
You can define and activate a hint in a single command using the following:
|
||||
|
||||
```
|
||||
-- maxscale <hint name> begin <hint content>
|
||||
```
|
||||
|
||||
You can also push anonymous hints onto the stack which are only used as long
|
||||
as they are on the stack:
|
||||
|
||||
```
|
||||
-- maxscale begin <hint content>
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1 - Routing SELECT queries to master
|
||||
|
||||
In this example, MariaDB MaxScale is configured with the readwritesplit
|
||||
router and the hint filter.
|
||||
|
||||
```
|
||||
[ReadWriteService]
|
||||
type=service
|
||||
router=readwritesplit
|
||||
servers=server1,server2
|
||||
user=maxuser
|
||||
passwd=maxpwd
|
||||
filters=Hint
|
||||
|
||||
[Hint]
|
||||
type=filter
|
||||
module=hintfilter
|
||||
```
|
||||
|
||||
Behind MariaDB MaxScale is a master server and a slave server. If there is
|
||||
replication lag between the master and the slave, read queries sent to the
|
||||
slave might return old data. To guarantee up-to-date data, we can add a
|
||||
routing hint to the query.
|
||||
|
||||
```
|
||||
INSERT INTO table1 VALUES ("John","Doe",1);
|
||||
SELECT * from table1; -- maxscale route to master
|
||||
```
|
||||
|
||||
The first INSERT query will be routed to the master. The following SELECT
|
||||
query would normally be routed to the slave but with the added routing hint
|
||||
it will be routed to the master. This way we can do an INSERT and a SELECT
|
||||
right after it and still get up-to-date data.
|
||||
Refer to the [Hintfilter](../Filters/Hintfilter.md) documentation for the
|
||||
MaxScale hint syntax.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user