Documentation Home
Connectors and APIs Manual
Download this Manual Failover

Copyright 1997-2018 the PHP Documentation Group.

By default, the plugin does not attempt to fail over if connecting to a host fails. This prevents pitfalls related to connection state. It is recommended to manually handle connection errors in a way similar to a failed transaction. You should catch the error, rebuild the connection state and rerun your query as shown below.

If connection state is no issue to you, you can alternatively enable automatic and silent failover. Depending on the configuration, the automatic and silent failover will either attempt to fail over to the master before issuing and error or, try to connect to other slaves, given the query allowes for it, before attempting to connect to a master. Because automatic failover is not fool-proof, it is not discussed in the quickstart. Instead, details are given in the concepts section below.

Example 7.239 Manual failover, automatic optional

    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
        "slave": {
            "slave_0": {
                "host": "simulate_slave_failure",
                "port": "0"
            "slave_1": {
                "host": "",
                "port": 3311
       "filters": { "roundrobin": [] }

Example 7.240 Manual failover

$mysqli = new mysqli("myapp", "username", "password", "database");
if (!$mysqli) {
    /* Of course, your error handling is nicer... */
    die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
$sql = "SELECT 1 FROM DUAL";
/* error handling as it should be done regardless of the plugin */
if (!($res = $link->query($sql))) {
    /* plugin specific: check for connection error */
    switch ($link->errno) {
    case 2002:
    case 2003:
    case 2005:
        printf("Connection error - trying next slave!\n");
        /* load balancer will pick next slave */
        $res = $link->query($sql);
        /* no connection error, failover is unlikely to help */
        die(sprintf("SQL error: [%d] %s", $link->errno, $link->error));
if ($res) {