<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Failover</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.transient_errors.html">Transient errors</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.loadbalancing.html">Load balancing</a></div>
<div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.failover" class="section">
<h2 class="title">Failover</h2>
<p class="para">
By default, connection failover handling is left to the user.
The application is responsible
for checking return values of the database functions it calls and reacting
to possible errors. If, for example, the plugin recognizes a query as a read-only
query to be sent to the slave servers, and the slave server selected by the
plugin is not available, the plugin will raise an error after not executing
the statement.
</p>
<p class="para">
<em class="emphasis">Default: manual failover</em>
</p>
<p class="para">
It is up to
the application to handle the error and, if required, re-issue the query to
trigger the selection of another slave server for statement execution.
The plugin will make no attempts to failover automatically, because the plugin
cannot ensure that an automatic failover will not change the state of
the connection. For example, the application may have issued a query
which depends on SQL user variables which are bound to a specific connection.
Such a query might return incorrect results if the plugin would switch the
connection implicitly as part of automatic failover. To ensure correct
results, the application must take care of the failover, and rebuild
the required connection state. Therefore, by default, no automatic failover
is performed by the plugin.
</p>
<p class="para">
A user that does not change the connection state after opening a connection
may activate automatic failover. Please note, that automatic failover logic
is limited to connection attempts. Automatic failover is not used for already
established connections. There is no way to instruct the plugin to attempt
failover on a connection that has been connected to MySQL already in the past.
</p>
<p class="para">
<em class="emphasis">Automatic failover</em>
</p>
<p class="para">
The failover policy is configured in the plugins configuration file, by
using the <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.failover" class="link">failover</a>
configuration directive.
</p>
<p class="para">
Automatic and silent failover can be enabled through the
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.failover" class="link">failover</a>
configuration directive. Automatic failover can either be configured to
try exactly one master after a slave failure or, alternatively, loop
over slaves and masters before returning an error to the user. The number
of connection attempts can be limited and failed hosts can be excluded
from future load balancing attempts. Limiting the number of retries and
remembering failed hosts are considered experimental features, albeit being
reasonable stable. Syntax and semantics may change in future versions.
</p>
<p class="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
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.trx-stickiness" class="link"><em>trx_stickiness</em></a>
documentation how to do this.
</p>
<p class="para">
A basic manual failover example is provided within the
<a href="mysqlnd-ms.errorhandling.html" class="link">error handling</a> section.
</p>
<p class="para">
<em class="emphasis">Standby servers</em>
</p>
<p class="para">
Using <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filter-random" class="link">weighted load balancing</a>,
introduced in PECL/mysqlnd 1.4.0, it is possible
to configure standby servers that are sparsely used during normal operations.
A standby server that is primarily used as a worst-case standby failover target
can be assigned a very low weight/priority in relation to all other
servers. As long as all servers are up and running the majority of the workload
is assigned to the servers which have hight weight values. Few requests
will be directed to the standby system which has a very low weight value.
</p>
<p class="para">
Upon failure of the servers with a high priority, you can still failover to
the standby, which has been given a low load balancing priority by assigning a low
weight to it. Failover can be some manually or automatically. If done
automatically, you may want to combine it with the
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.failover" class="link"><em>remember_failed</em></a>
option.
</p>
<p class="para">
At this point, it is not possible to instruct the load balancer to direct no
requests at all to a standby. This may not be much of a limitation given that
the highest weight you can assign to a server is 65535. Given two slaves,
of which one shall act as a standby and has been assigned a weight of 1,
the standby will have to handle far less than one percent of the overall workload.
</p>
<p class="para">
<em class="emphasis">Failover and primary copy</em>
</p>
<p class="para">
Please note, if using a primary copy cluster, such as MySQL Replication, it is
difficult to do connection failover in case of a master failure.
At any time there is only one master in the cluster for a given dataset.
The master is a single point of failure. If the master fails, clients have no
target to fail over write requests. In case of a master outage the database
administrator must take care of the situation and update the client
configurations, if need be.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.transient_errors.html">Transient errors</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.loadbalancing.html">Load balancing</a></div>
<div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
