From 943c9f5f650688d9caab55c1fb7f204c17a16a0c Mon Sep 17 00:00:00 2001 From: Markus Makela Date: Tue, 12 May 2015 04:57:18 +0300 Subject: [PATCH] Updated readwritesplit documentation. --- About/Limitations.md | 34 ++++++++++++++-------------------- routers/ReadWriteSplit.md | 7 +++---- 2 files changed, 17 insertions(+), 24 deletions(-) diff --git a/About/Limitations.md b/About/Limitations.md index 4bfac725b..01d63008c 100644 --- a/About/Limitations.md +++ b/About/Limitations.md @@ -37,9 +37,8 @@ In master-slave replication cluster also read-only queries are routed to master * statement includes a stored procedure, or an UDF call ### Limitations in client session handling - -Some of the queries that client sends are routed to all backends instead of sending them just to one of server. These queries include "USE " and “SET autocommit=0” among many others. Read/Write Splitter sends a copy of these queries to each backend server and forwards the first reply it receives to the client. Below is a list of MySQL commands which we call session commands : - +Some of the queries that client sends are routed to all backends instead of sending them just to one of server. 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 @@ -52,9 +51,7 @@ COM_STMT_RESET COM_STMT_PREPARE -Also these are session commands: - -COM_QUIT (no response) +COM_QUIT (no response, session is closed) COM_REFRESH @@ -62,9 +59,7 @@ COM_DEBUG COM_PING -In addition there are query types which belong to the same group: - -SQLCOM_CHANGE_DB +SQLCOM_CHANGE_DB (USE ... statements) SQLCOM_DEALLOCATE_PREPARE @@ -74,25 +69,24 @@ SQLCOM_SET_OPTION SELECT ..INTO variable|OUTFILE|DUMPFILE -Then there are queries which modify session characteristics, listed as derived, internal RWSplit types: +SET autocommit=1|0 +``` - QUERY_TYPE_ENABLE_AUTOCOMMIT +There is a possibility for misbehavior; if `USE mytable` was executed in one of the slaves and it failed, it may be due to replication lag rather than the fact it didn’t exist. Thus the same command may end up with different result among 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 that are in use by the session. - QUERY_TYPE_DISABLE_AUTOCOMMIT +The above-mentioned behavior can be partially controller with the `use_sql_variables_in` configuration parameter. -There is a possibility for misbehavior; if "USE mytable" was executed in one of the slaves and it failed, it may be due to replication lag rather than the fact it didn’t exist. Thus the same command may end up with different result among backend servers. This disparity is missed. - -The above-mentioned behavior can be partially controller with RWSplit configuration parameter called - - use_sql_variables_in=[master|all] (master) +``` +use_sql_variables_in=[master|all] (master) +``` Server-side session variables are called as SQL variables. If "master" or no value is set, SQL variables are read and written in master only. Autocommit values and prepared statements are routed to all nodes always. -NOTE: If variable is written as a part of write query, it is treated like write query and not routed to all servers. For example, INSERT INTO test.t1 VALUES (@myvar:= 7) . +**NOTE**: If variable is written as a part of write query, it is treated like write query and not routed to all servers. For example, `INSERT INTO test.t1 VALUES (@myvar:= 7)` will be routed to the master and an error in the error log will be written. -Examples: +#### Examples of session command limitations -If new database "db" was created and client executes “USE db” and it is routed to slave before the CREATE DATABASE clause is replicated to all slaves there is a risk of executing query in wrong database. Similarly, if any response that RWSplit sends back to the client differ from that of the master, there is a risk for misbehavior. +If new database "db" was created and client executes “USE db” and it is routed to slave before the CREATE DATABASE clause is replicated to all slaves there is a risk of executing query in wrong database. Similarly, if any response that RWSplit sends back to the client differ from that of the master, there is a risk for misbehavior. To prevent this, any failures in session command execution are treated as fatal errors and all connections by the session to that particular slave server will be closed. In addition, the server will not used again for routing for the duration of the session. Most imaginable reasons are related to replication lag but it could be possible that a slave fails to execute something because of some non-fatal, temporary failure while execution of same command succeeds in other backends. diff --git a/routers/ReadWriteSplit.md b/routers/ReadWriteSplit.md index 2727a4fdf..52b1c11b2 100644 --- a/routers/ReadWriteSplit.md +++ b/routers/ReadWriteSplit.md @@ -103,7 +103,7 @@ In Master-Slave replication cluster also read-only queries are routed to master ### Limitations in client session handling -Some of the queries that client sends are routed to all backends instead of sending them just to one of server. 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 : +Some of the queries that client sends are routed to all backends instead of sending them just to one of server. 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) @@ -138,7 +138,7 @@ SELECT ..INTO variable|OUTFILE|DUMPFILE SET autocommit=1|0 ``` -There is a possibility for misbehavior; if `USE mytable` was executed in one of the slaves and it failed, it may be due to replication lag rather than the fact it didn’t exist. Thus the same command may end up with different result among backend servers. This disparity is missed. +There is a possibility for misbehavior; if `USE mytable` was executed in one of the slaves and it failed, it may be due to replication lag rather than the fact it didn’t exist. Thus the same command may end up with different result among 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 that are in use by the session. The above-mentioned behavior can be partially controller with the `use_sql_variables_in` configuration parameter. @@ -152,11 +152,10 @@ Server-side session variables are called as SQL variables. If "master" or no val ### Examples of limitations -If new database "db" was created and client executes “USE db” and it is routed to slave before the CREATE DATABASE clause is replicated to all slaves there is a risk of executing query in wrong database. Similarly, if any response that RWSplit sends back to the client differ from that of the master, there is a risk for misbehavior. +If new database "db" was created and client executes “USE db” and it is routed to slave before the CREATE DATABASE clause is replicated to all slaves there is a risk of executing query in wrong database. Similarly, if any response that RWSplit sends back to the client differ from that of the master, there is a risk for misbehavior. To prevent this, any failures in session command execution are treated as fatal errors and all connections by the session to that particular slave server will be closed. In addition, the server will not used again for routing for the duration of the session. Most imaginable reasons are related to replication lag but it could be possible that a slave fails to execute something because of some non-fatal, temporary failure while execution of same command succeeds in other backends. - ## Examples Examples of the readwritesplit router in use can be found in the [Tutorials](../Tutorials) folder.