From af871c29a56de390dbc98f2d3844482296a75a2d Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Mon, 18 Feb 2013 13:27:12 +0000 Subject: [PATCH] v1.5 - discussion of automatic and silent failover in the middle of a transaction git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329494 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/changes.xml | 9 ++++ reference/mysqlnd_ms/concepts.xml | 10 ++++ reference/mysqlnd_ms/setup.xml | 81 ++++++++++++++++++++++++++++--- 3 files changed, 92 insertions(+), 8 deletions(-) diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index a8552d8ed7..523ff56aba 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -47,6 +47,15 @@ Fixed #60605 PHP segmentation fault when mysqlnd_ms is enabled + + + Setting transaction stickiness disables all load balancing, including + automatic failover, for the duration of a transaction. So far + connection switches could have happened in the middle of a transaction + in multi-master configurations and during automatic failover although + transaction monitoring had detected transaction boundaries properly. + + diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 794a556bad..8dfd0116ed 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -706,6 +706,16 @@ version = 5.6.2-m5-log remembering failed hosts are considered experimental features, albeit being reasonable stable. Syntax and semantics may change in future versions. + + Please note, since version 1.5.0 automatic failover is disabled for the + duration of a transaction if transaction stickiness is enabled and + transaction boundaries have been detected. The plugin will not switch + connections for the duration of a transaction. It will also not perform + automatic and silent failover. Instead an error will be thrown. It is then left + to the user to handle the failure of the transaction. Please check, the + trx_stickiness + documentation how to do this. + A basic manual failover example is provided within the error handling section. diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index 01105c407d..8713cc1339 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -1993,10 +1993,9 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio - Since 1.4.0. Experimental feature. The feature is only available together + Since 1.4.0. The feature is only available together with the random and roundrobin - load balancing filter. The behavior and syntax is likely to change - in the future. + load balancing filter. Use of the setting is recommended. @@ -2019,10 +2018,9 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio - Since 1.4.0. Experimental feature. The feature is only available together + Since 1.4.0. The feature is only available together with the random and roundrobin - load balancing filter. The behavior and syntax is likely to change - in the future. + load balancing filter. @@ -2250,6 +2248,10 @@ $mysqli->set_charset("latin1"); and, it offers additional functionality introducing service levels. + + All transaction stickiness settings, + including trx_stickiness=on, are overruled by master_on_write=1. + @@ -2293,9 +2295,9 @@ $mysqli->set_charset("latin1"); mysqli_autocommit. - Although setting ser_stickiness=master, the plugin + Although setting trx_stickiness=master, the plugin cannot be made aware of autocommit mode changes caused - by SQL statements such as SET AUTOCOMMIT=0. + by SQL statements such as SET AUTOCOMMIT=0 or BEGIN. @@ -2322,6 +2324,69 @@ $mysqli->set_charset("latin1"); + + Since version 1.5.0 automatic and silent failover is disabled for the + duration of a transaction. If the boundaries of a transaction have been + properly detected, transaction stickiness is enabled and a server fails, + the plugin will not attempt to fail over to the next server, if any, regardless + of the failover policy configured. The user must handle the error + manually. Depending on the configuration, the plugin may emit + an error of type E_WARNING reading like + (mysqlnd_ms) Automatic failover is not permitted in the middle of a transaction. + This error may then be overwritten by follow up errors such as + (mysqlnd_ms) No connection selected by the last filter. + Those errors will be generated by the failing query function. + + + + No automatic failover, error handling pitfall + +autocommit(false); + +/* assumption: server fails */ +if (!($res = $mysqli->query("SELECT 'Assume this query fails' AS _msg FROM DUAL"))) { + /* handle failure of transaction, plugin internal state is still in_trx = 1 */ + printf("[%d] %s", $mysqli->errno, $mysqli->error); + /* + If using autocommit() based transaction detection it is a + MUST to call autocommit(true). Otherwise the plugin assumes + the current transaction continues and connection + changes remain forbidden. + */ + $mysqli->autocommit(true); + /* Likewise, you'll want to start a new transaction */ + $mysqli->autocommit(false); +} +/* latin1 used from now on */ +$mysqli->set_charset("latin1"); +?> +]]> + + + + + If a server fails in the middle of a transaction the + plugin continues to refuse to switch connections until the + current transaction has been finished. Recall + that the plugin monitors API calls to detect transaction + boundaries. Thus, you have to, for example, enable + auto commit mode to end the current transaction before + the plugin continues load balancing and switches the server. + Likewise, you will want to start a new transaction + immediately thereafter and disable auto commit mode again. + + + Not handling failed queries and not ending a failed transaction + using API calls may cause all following commands emit errors + such as Commands out of sync; you can't run this command now. + Thus, it is important to handle all errors. +