diff --git a/Documentation/About/Limitations.md b/Documentation/About/Limitations.md index f56c5a156..43854ad38 100644 --- a/Documentation/About/Limitations.md +++ b/Documentation/About/Limitations.md @@ -157,122 +157,4 @@ can be influenced with the server priority mechanic described in the ## Router limitations -### Avrorouter limitations (avrorouter) - -The avrorouter does not support the following data types, conversions or SQL statements: - -* BIT -* Fields CAST from integer types to string types -* [CREATE TABLE ... AS SELECT statements](https://mariadb.com/kb/en/library/create-table/#create-select) - -The avrorouter does not do any crash recovery. This means that the avro files -need to be truncated to valid block lengths before starting the avrorouter. - -#### Binlog Checksums - -The avrorouter does not support binlog checksums. They must must not be used in -any of the binlogs that the avrorouter will process. - -Follow [MXS-1341](https://jira.mariadb.org/browse/MXS-1341) for progress -on this issue. - -### Limitations in the connection router (readconnroute) - -Sending of binary data with `LOAD DATA LOCAL INFILE` is not supported. - -### Limitations in the Read/Write Splitter (readwritesplit) - -Read queries are routed to the master server in the following situations: - -* query is executed inside an open transaction -* statement includes a stored procedure or an UDF call -* if there are multiple statements inside one query e.g. `INSERT INTO ... ; SELECT -LAST_INSERT_ID();` - -#### JDBC Batched Statements - -Readwritesplit does not support pipelining of JDBC batched statements. This is -caused by the fact that readwritesplit executes the statements one at a time to -track the state of the response. - -#### Limitations in multi-statement handling - -When a multi-statement query is executed through the readwritesplit router, it -will always be routed to the master. See -[`strict_multi_stmt`](../Routers/ReadWriteSplit.md#strict_multi_stmt) for more -details. - -Execution of LOAD DATA LOCAL INFILE statements inside a multi-statement query is -not supported. If one is executed MaxScale will most likely hang (see -[MXS-1828](https://jira.mariadb.org/browse/MXS-1828)). - -#### Limitations in client session handling - -Some of the queries that a client sends are routed to all backends instead of -just to one. These queries include `USE ` and `SET autocommit=0`, among -many others. Readwritesplit sends a copy of these queries to each backend server -and forwards the master's reply to the client. Below is a list of MySQL commands -which are classified as session commands. - -``` -COM_INIT_DB (USE creates this) -COM_CHANGE_USER -COM_STMT_CLOSE -COM_STMT_SEND_LONG_DATA -COM_STMT_RESET -COM_STMT_PREPARE -COM_QUIT (no response, session is closed) -COM_REFRESH -COM_DEBUG -COM_PING -SQLCOM_CHANGE_DB (USE ... statements) -SQLCOM_DEALLOCATE_PREPARE -SQLCOM_PREPARE -SQLCOM_SET_OPTION -SELECT ..INTO variable|OUTFILE|DUMPFILE -SET autocommit=1|0 -``` - -Prior to MaxScale 2.3.0, session commands that were 2²⁴ - 1 bytes or longer were -not supported and caused the session to be closed. - -There is a possibility for misbehavior. If `USE mytable` is executed in one of -the slaves and fails, it may be due to replication lag rather than the database -not existing. Thus, the same command may produce different result in different -backend servers. The slaves which fail to execute a session command will be -dropped from the active list of slaves for this session to guarantee a -consistent session state across all the servers used by the session. In -addition, the server will not used again for routing for the duration of the -session. - -The above-mentioned behavior for user variables can be partially controlled with -the configuration parameter `use_sql_variables_in`: - -``` -use_sql_variables_in=[master|all] (default: all) -``` - -**WARNING** - -If a SELECT query modifies a user variable when the `use_sql_variables_in` -parameter is set to `all`, it will not be routed and the client will receive an -error. A log message is written into the log further explaining the reason for -the error. Here is an example use of a SELECT query which modifies a user -variable and how MariaDB MaxScale responds to it. - -``` -MySQL [(none)]> set @id=1; -Query OK, 0 rows affected (0.00 sec) - -MySQL [(none)]> SELECT @id := @id + 1 FROM test.t1; -ERROR 1064 (42000): Routing query to backend failed. See the error log for further details. -``` - -Allow user variable modification in SELECT queries by setting -`use_sql_variables_in=master`. This will route all queries that use user -variables to the master. - -### Schemarouter limitations (schemarouter) - -Please see [SchemaRouter documentation](../Routers/SchemaRouter.md). - +Refer to individual router documentation for a list of their limitations. diff --git a/Documentation/Routers/Avrorouter.md b/Documentation/Routers/Avrorouter.md index 02589bab6..1bd12cd89 100644 --- a/Documentation/Routers/Avrorouter.md +++ b/Documentation/Routers/Avrorouter.md @@ -22,37 +22,7 @@ should be used to communicate with the avrorouter and currently it is the only supported protocol. The clients can request either Avro or JSON format data streams from a database table. -Table of Contents -================= - -* [Configuration](#configuration) - * [Router Parameters](#router-parameters) - * [source](#source) - * [codec](#codec) - * [match](#match) - * [exclude](#exclude) - * [Router Options](#router-options) - * [General Options](#general-options) - * [binlogdir](#binlogdir) - * [avrodir](#avrodir) - * [filestem](#filestem) - * [start_index](#start_index) - * [Avro file options](#avro-file-options) - * [group_trx](#group_trx) - * [group_rows](#group_rows) - * [block_size](#block_size) -* [Module commands](#module-commands) - * [avrorouter::convert SERVICE {start | stop}](#avrorouterconvert-service-start--stop) - * [avrorouter::purge SERVICE](#avrorouterpurge-service) -* [Files Created by the Avrorouter](#files-created-by-the-avrorouter) -* [Resetting the Conversion Process](#resetting-the-conversion-process) -* [Stopping the Avrorouter](#stopping-the-avrorouter) -* [Example Client](#example-client) -* [Avro Schema Generator](#avro-schema-generator) - * [Python Schema Generator](#python-schema-generator) - * [Go Schema Generator](#go-schema-generator) -* [Examples](#examples) -* [Building Avrorouter](#building-avrorouter) +[TOC] ## Configuration @@ -444,3 +414,15 @@ configuring the Avro C library. For more details about building MaxScale from source, please refer to the [Building MaxScale from Source Code](../Getting-Started/Building-MaxScale-from-Source-Code.md) document. + +## Limitations + +The avrorouter does not support the following data types, conversions or SQL statements: + +* BIT +* Fields CAST from integer types to string types +* [CREATE TABLE ... AS SELECT statements](https://mariadb.com/kb/en/library/create-table/#create-select) + +The avrorouter does not do any crash recovery. This means that the avro files +need to be removed or truncated to valid block lengths before starting the +avrorouter. diff --git a/Documentation/Routers/Binlogrouter.md b/Documentation/Routers/Binlogrouter.md index a329caddb..9dfce4788 100644 --- a/Documentation/Routers/Binlogrouter.md +++ b/Documentation/Routers/Binlogrouter.md @@ -9,37 +9,7 @@ logs. You can switch to a new master server without the slaves noticing that the actual master server has changed. This allows for a more highly available replication setup where replication is high-priority. -Table of Contents -================= - -* [Configuration](#configuration) - * [Mandatory Router Parameters](#mandatory-router-parameters) - * [Router Parameters](#router-parameters) - * [binlogdir](#binlogdir) - * [server_id](#server_id) - * [master_id](#master_id) - * [uuid](#uuid) - * [master_uuid](#master_uuid) - * [master_version](#master_version) - * [master_hostname](#master_hostname) - * [slave_hostname](#slave_hostname) - * [user](#user) - * [password](#password) - * [heartbeat](#heartbeat) - * [burstsize](#burstsize) - * [mariadb10-compatibility](#mariadb10-compatibility) - * [transaction_safety](#transaction_safety) - * [send_slave_heartbeat](#send_slave_heartbeat) - * [semisync](#semisync) - * [ssl_cert_verification_depth](#ssl_cert_verification_depth) - * [encrypt_binlog](#encrypt_binlog) - * [encryption_algorithm](#encryption_algorithm) - * [encryption_key_file](#encryption_key_file) - * [mariadb10_master_gtid](#mariadb10_master_gtid) - * [master_retry_count](#master_retry_count) - * [connect_retry](#connect_retry) - * [Using secondary masters](#using-secondary-masters) -* [Examples](#examples) +[TOC] ## Configuration diff --git a/Documentation/Routers/ReadConnRoute.md b/Documentation/Routers/ReadConnRoute.md index 03e29bd04..50456e1c6 100644 --- a/Documentation/Routers/ReadConnRoute.md +++ b/Documentation/Routers/ReadConnRoute.md @@ -4,6 +4,8 @@ This document provides an overview of the **readconnroute** router module and its intended use case scenarios. It also displays all router configuration parameters with their descriptions. +[TOC] + ## Overview The readconnroute router provides simple and lightweight load balancing @@ -45,11 +47,6 @@ the list of servers is processed in from first entry to last. This means that if two servers with equal weight and status are found, the one that's listed first in the _servers_ parameter for the service is chosen. -## Limitations - -For a list of readconnroute limitations, please read the -[Limitations](../About/Limitations.md) document. - ## Examples The most common use for the readconnroute is to provide either a read or @@ -74,3 +71,9 @@ slave servers. For more complex examples of the readconnroute router, take a look at the examples in the [Tutorials](../Tutorials) folder. + +## Limitations + +* Sending of binary data with `LOAD DATA LOCAL INFILE` is not supported. + +* The router will never reconnect to the server it initially connected to. diff --git a/Documentation/Routers/ReadWriteSplit.md b/Documentation/Routers/ReadWriteSplit.md index 3ce87aee6..d7a4a6fdf 100644 --- a/Documentation/Routers/ReadWriteSplit.md +++ b/Documentation/Routers/ReadWriteSplit.md @@ -723,3 +723,91 @@ executed session command for the duration of the session. Applications that use long-running sessions might cause MariaDB MaxScale to consume a growing amount of memory unless the sessions are closed. This can be solved by adjusting the value of `max_sescmd_history`. + +## Limitations + +Read queries are routed to the master server in the following situations: + +* query is executed inside an open transaction +* statement includes a stored procedure or an UDF call +* if there are multiple statements inside one query e.g. + `INSERT INTO ... ; SELECT LAST_INSERT_ID();` + +### JDBC Batched Statements + +Readwritesplit does not support pipelining of JDBC batched statements. This is +caused by the fact that readwritesplit executes the statements one at a time to +track the state of the response. + +#### Limitations in multi-statement handling + +When a multi-statement query is executed through the readwritesplit router, it +will always be routed to the master. See +[`strict_multi_stmt`](../Routers/ReadWriteSplit.md#strict_multi_stmt) for more +details. + +#### Limitations in client session handling + +Some of the queries that a client sends are routed to all backends instead of +just to one. These queries include `USE ` and `SET autocommit=0`, among +many others. Readwritesplit sends a copy of these queries to each backend server +and forwards the master's reply to the client. Below is a list of MySQL commands +which are classified as session commands. + +``` +COM_INIT_DB (USE creates this) +COM_CHANGE_USER +COM_STMT_CLOSE +COM_STMT_SEND_LONG_DATA +COM_STMT_RESET +COM_STMT_PREPARE +COM_QUIT (no response, session is closed) +COM_REFRESH +COM_DEBUG +COM_PING +SQLCOM_CHANGE_DB (USE ... statements) +SQLCOM_DEALLOCATE_PREPARE +SQLCOM_PREPARE +SQLCOM_SET_OPTION +SELECT ..INTO variable|OUTFILE|DUMPFILE +SET autocommit=1|0 +``` + +Prior to MaxScale 2.3.0, session commands that were 2²⁴ - 1 bytes or longer were +not supported and caused the session to be closed. + +There is a possibility for misbehavior. If `USE mytable` is executed in one of +the slaves and fails, it may be due to replication lag rather than the database +not existing. Thus, the same command may produce different result in different +backend servers. The slaves which fail to execute a session command will be +dropped from the active list of slaves for this session to guarantee a +consistent session state across all the servers used by the session. In +addition, the server will not be used again for routing for the duration of the +session. + +The above-mentioned behavior for user variables can be partially controlled with +the configuration parameter `use_sql_variables_in`: + +``` +use_sql_variables_in=[master|all] (default: all) +``` + +**WARNING** + +If a SELECT query modifies a user variable when the `use_sql_variables_in` +parameter is set to `all`, it will not be routed and the client will receive an +error. A log message is written into the log further explaining the reason for +the error. Here is an example use of a SELECT query which modifies a user +variable and how MariaDB MaxScale responds to it. + +``` +MySQL [(none)]> set @id=1; +Query OK, 0 rows affected (0.00 sec) + +MySQL [(none)]> SELECT @id := @id + 1 FROM test.t1; +ERROR 1064 (42000): Routing query to backend failed. See the error log for further details. +``` + +Allow user variable modification in SELECT queries by setting +`use_sql_variables_in=master`. This will route all queries that use user +variables to the master.