From 6f2475b5fa6cc9ebda73e629183ae91e3148910a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Mon, 11 Feb 2019 03:18:38 +0200 Subject: [PATCH 1/2] MXS-2302: Document hintfilter behavior Moved hintfilter documentation to the correct place and cleaned it up. Added a note at the start of the syntax documentation about the behavior of the hint parsing to warn users of possible unexpected behavior. The hint parsing could really use some refactoring to make it more manageable which is why the preliminary fix version of the bug will be 2.4. --- Documentation/Filters/Hintfilter.md | 132 +++++++++++++++++++++++++ Documentation/Reference/Hint-Syntax.md | 126 +---------------------- 2 files changed, 134 insertions(+), 124 deletions(-) create mode 100644 Documentation/Filters/Hintfilter.md diff --git a/Documentation/Filters/Hintfilter.md b/Documentation/Filters/Hintfilter.md new file mode 100644 index 000000000..0a44aec68 --- /dev/null +++ b/Documentation/Filters/Hintfilter.md @@ -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 +``` + +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 ] +``` + +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 +__ 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 = +``` + +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 prepare +``` + +Pushing a hint onto the stack: + +``` +-- maxscale 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 begin +``` + +You can also push anonymous hints onto the stack which are only used as long as +they are on the stack: + +``` +-- maxscale begin +``` + +# 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. diff --git a/Documentation/Reference/Hint-Syntax.md b/Documentation/Reference/Hint-Syntax.md index 69ea8446f..e198a0401 100644 --- a/Documentation/Reference/Hint-Syntax.md +++ b/Documentation/Reference/Hint-Syntax.md @@ -1,126 +1,4 @@ # Hint Syntax -## Enabling routing hints - -To enable 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 -``` - -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 ] -``` - -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 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 = -``` - -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 prepare -``` - -Pushing a hint onto the stack: - -``` --- maxscale 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 begin -``` - -You can also push anonymous hints onto the stack which are only used as long as they are on the stack: - -``` --- maxscale begin -``` - -## 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. From 79fd01d4dd7e36a06855c2e2040c99ef73a772a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 13 Feb 2019 13:37:02 +0200 Subject: [PATCH 2/2] Add hintfilter to documentation contents --- Documentation/Documentation-Contents.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/Documentation-Contents.md b/Documentation/Documentation-Contents.md index a787eaf05..fca982512 100644 --- a/Documentation/Documentation-Contents.md +++ b/Documentation/Documentation-Contents.md @@ -85,6 +85,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)