svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ changes.xml concepts.xml setup.xml

uw Mon, 18 Feb 2013 13:27:12 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=329494 Log: v1.5 - discussion of automatic and silent failover in the middle of a transaction Changed paths: U phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml U phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml U phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml Modified: phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2013-02-18 13:21:05 UTC (rev 329493) +++ phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2013-02-18 13:27:12 UTC (rev 329494) @@ -47,6 +47,15 @@ Fixed #60605 PHP segmentation fault when mysqlnd_ms is enabled </para> </listitem> + <listitem> + <para> + 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. + </para> + </listitem> </itemizedlist> </para> <para> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml 2013-02-18 13:21:05 UTC (rev 329493) +++ phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml 2013-02-18 13:27:12 UTC (rev 329494) @@ -707,6 +707,16 @@ reasonable stable. Syntax and semantics may change in future versions. </para> <para> + 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 + <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness"><literal>trx_stickiness</literal></link> + documentation how to do this. + </para> + <para> A basic manual failover example is provided within the <link linkend="mysqlnd-ms.errorhandling">error handling</link> section. </para> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2013-02-18 13:21:05 UTC (rev 329493) +++ phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2013-02-18 13:27:12 UTC (rev 329494) @@ -1993,10 +1993,9 @@ </para> </entry> <entry> - Since 1.4.0. Experimental feature. The feature is only available together + Since 1.4.0. The feature is only available together with the <literal>random</literal> and <literal>roundrobin</literal> - load balancing filter. The behavior and syntax is likely to change - in the future. + load balancing filter. Use of the setting is recommended. </entry> </row> <row> @@ -2019,10 +2018,9 @@ </para> </entry> <entry> - Since 1.4.0. Experimental feature. The feature is only available together + Since 1.4.0. The feature is only available together with the <literal>random</literal> and <literal>roundrobin</literal> - load balancing filter. The behavior and syntax is likely to change - in the future. + load balancing filter. </entry> </row> </tbody> @@ -2250,6 +2248,10 @@ and, it offers additional functionality introducing <link linkend="mysqlnd-ms.qos-consistency">service levels</link>. </para> + <para> + All <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">transaction stickiness</link> settings, + including <literal>trx_stickiness=on</literal>, are overruled by <literal>master_on_write=1</literal>. + </para> </listitem> </varlistentry> <varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness"> @@ -2293,9 +2295,9 @@ <function>mysqli_autocommit</function>. </para> <para> - Although setting <literal>ser_stickiness=master</literal>, the plugin + Although setting <literal>trx_stickiness=master</literal>, the plugin cannot be made aware of <literal>autocommit</literal> mode changes caused - by SQL statements such as <literal>SET AUTOCOMMIT=0</literal>. + by SQL statements such as <literal>SET AUTOCOMMIT=0</literal> or <literal>BEGIN</literal>. </para> <para> <example> @@ -2322,6 +2324,69 @@ </programlisting> </example> </para> + <para> + 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 <literal>E_WARNING</literal> reading like + <literal>(mysqlnd_ms) Automatic failover is not permitted in the middle of a transaction</literal>. + This error may then be overwritten by follow up errors such as + <literal>(mysqlnd_ms) No connection selected by the last filter</literal>. + Those errors will be generated by the failing query function. + </para> + <para> + <example> + <title>No automatic failover, error handling pitfall</title> + <programlisting role="php"> +<![CDATA[ +<?php +/* assumption: automatic failover configured */ +$mysqli = new mysqli("myapp", "username", "password", "database"); + +/* sets plugin internal state in_trx = 1 */ +$mysqli->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"); +?> +]]> + </programlisting> + </example> + </para> + <para> + 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. + </para> + <para> + Not handling failed queries and not ending a failed transaction + using API calls may cause all following commands emit errors + such as <literal>Commands out of sync; you can't run this command now</literal>. + Thus, it is important to handle all errors. + </para> </listitem> </varlistentry> </variablelist>