hcq/MaxScale
hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-2359 Update schemarouter documentation

Browse Source 
Moved limitations to the router documentation. Documented which queries get
exceptional handling.
This commit is contained in:
Esa Korhonen 2019-03-25 16:40:58 +02:00
parent c6272594d6
commit c6ce4c2234
2 changed files with 52 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Documentation/About/Limitations.md
View File

@ -262,32 +262,5 @@ variables to the master.
### Schemarouter limitations (schemarouter)
The schemarouter currently has some limitations due to the nature of the
sharding implementation and the way the session variables are detected and
routed. Here is a list of the current limitations:
Please see [SchemaRouter documentation](../Routers/SchemaRouter.md).
* Cross-database queries (e.g. `SELECT column FROM database1.table UNION select
column FROM database2.table`) are not supported and are routed either to the
first explicit database in the query, the current database in use or to the
first available database, depending on which succeeds.
* Without a default database, queries without explicit databases that do not
modify the session state will be routed to the first available server. This
means that, for example when creating a new database, queries should be done
directly on the node or the router should be equipped with the hint filter and a
routing hint should be used. Queries that modify the session state (e.g. `SET
autocommit=1`) will be routed to all servers regardless of the default database.
* SELECT queries that modify session variables are not currently supported because
uniform results can not be guaranteed. If such a query is executed, the behavior
of the router is undefined. To work around this limitation, the query must be
executed in separate parts.
* If a query targets a database the schemarouter hasn't mapped to a server, the
query will be routed to the first available server. This possibly returns an
error about database rights instead of a missing database.
* The preparation of a prepared statement is routed to all servers. The
execution of a prepared statement is routed to the first available server or to
the server pointed by a routing hint attached to the query. In practice this
means that prepared statements aren't supported by the schemarouter.

55
Documentation/Routers/SchemaRouter.md
View File

@ -8,8 +8,12 @@ database-based sharding, the schemarouter also enables cross-node
session variable usage by routing all queries that modify the session to all
nodes.
From 2.3.0 onwards, the SchemaRouter is capable of table family sharding,
in addition to being capable of sharding databases.
The main limitation of SchemaRouter is that aside from session variable writes
and some specific queries, a query can only target one server. This means that
queries which depend on results from multiple servers give incorrect results.
See [Limitations](#limitations) for more information.
From 2.3.0 onwards, SchemaRouter is capable of limited table family sharding.
Table of Contents
=================
@ -50,6 +54,19 @@ In almost all the cases these can be avoided by proper server configuration
and the databases are always mapped to the same servers. More on
configuration in the next chapter.
To check how databases and tables map to servers, execute the special query
`SHOW SHARDS`. The query does not support any modifiers such as `LIKE`.
```
show shards;
Database |Server |
---------|-------------|
db1.t1 |MyServer1 |
db1.t2 |MyServer1 |
db2.t1 |MyServer2 |
```
## Configuration
Here is an example configuration of the schemarouter:
@ -185,8 +202,38 @@ The minimum interval between database map refreshes in seconds.
## Limitations
For a list of schemarouter limitations, please read the
[Limitations](../About/Limitations.md) document.
1. Cross-database queries (e.g. `SELECT column FROM database1.table UNION select column
FROM database2.table`) are not properly supported. Such queries are routed either to the
first explicit database in the query, the current database in use or to the first
available database, depending on which succeeds.
* Without a default database, queries without explicit databases that do not modify the
session state will be routed to the first available server. This includes queries such as
`CREATE DATABASE db1`. Such queries should be done directly on the node or the router
should be equipped with the hint filter and a routing hint should be used. Queries that
modify the session state (e.g. `SET autocommit=1`) will be routed to all servers
regardless of the default database.
* SELECT queries that modify session variables are not supported because uniform results
can not be guaranteed. If such a query is executed, the behavior of the router is
undefined. To work around this limitation, the query must be executed in separate parts.
* If a query targets a database the SchemaRouter has not mapped to a server, the
query will be routed to the first available server. This possibly returns an
error about database rights instead of a missing database.
* The preparation of a prepared statement is routed to all servers. The
execution of a prepared statement is routed to the first available server or to
the server pointed by a routing hint attached to the query. In practice this
means that prepared statements aren't supported by the SchemaRouter.
* `SHOW DATABASES` is handled by the router instead of routed to a server. The router only
answers correctly to the basic version of the query. Any modifiers such as `LIKE` are
ignored.
* `SHOW TABLES` is routed to the server with the current database. If using table-level
sharding, the results will be incomplete. Use `SHOW SHARDS` to get results from the router
itself.
## Examples