sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

v1.5 - discussion of automatic and silent failover in the middle of a transaction

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329494 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2013-02-18 13:27:12 +00:00
parent cd4beb9181
commit af871c29a5
3 changed files with 92 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
reference/mysqlnd_ms/changes.xml
View file

@ -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>

10
reference/mysqlnd_ms/concepts.xml
View file

@ -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.
</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.

81
reference/mysqlnd_ms/setup.xml
View file

@ -1993,10 +1993,9 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio
</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 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio
</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 @@ $mysqli->set_charset("latin1");
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 @@ $mysqli->set_charset("latin1");
<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 @@ $mysqli->set_charset("latin1");
</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>