This article is about setting up active failover for ArangoDB-PHP, the PHP client driver for ArangoDB. It requires ArangoDB-PHP 3.3.2 or higher, and an ArangoDB server version of 3.3.4 or higher.

Active failover: basic setup

Historically, ArangoDB-PHP has been able to connect to a single ArangoDB endpoint, i.e. one combination of IP address and port number.

To connect to an ArangoDB server that is running on localhost or on a remote server, simply set the OPTION_ENDPOINT item in the ConnectionOptions and connect:

To make use of the new active failover option in ArangoDB 3.3, the PHP driver now allows setting up multiple endpoints. For example, if the active failover ArangoDB instances run on 127.0.0.1 on ports 8529, 8539 and 8549, the example configuration would be:

(Please note that in reality the ArangoDB instances should be set up on different physical machines. We only use the same machine here for demonstration purposes.)

The driver will by default try to connect to the first endpoint in the endpoints array, and only try the following servers if no connection can be established. If no connection can be made to any of the configured endpoints, the driver will bail out by throwing an exception.

If the driver connects to a follower (non-leader), it would not be able to perform any write operations on it, so the follower will reject the connection and redirect to the current leader. The driver will then automatically reconnect to the current leader.

In case the leader has just failed and the failover is currently ongoing, there will be a “leadership challenge” period in which the remaining followers will try to compete for leadership. In this period the driver will try to find the new leader for a configurable amount of time, which can be adjusted using the OPTION_FAILOVER_TIMEOUT options entry. The maximum number of servers to contact in case of a failover can be configured by setting the OPTION_FAILOVER_TRIES entry.

It is also possible to register a user-defined callback function that will be invoked if the failover procedure cannot find any server to contact to (e.g. because all servers are unreachable). This can be set via the OPTION_NOTIFY_CALLBACK entry.

With the options all set, we can now try the active failover by starting a few local ArangoDB servers in active failover mode.

By default, this will start three local ArangoDB instances on ports 8529, 8539 and 8549.

We can now use the following PHP code to test connecting to the correct server and automatic failover:

The above code will automatically connect to the configured servers, starting with the first one in the endpoints array, until it finds the leader.

The script will run endlessly and print to which server it is connected to. One can now viciously kill the current leader by sending it a kill signal from another shell. The script will then show that the driver has automatically connected to one of the remaining servers that, in its turn, became a new leader.

Using Memcached for storing the last known leader

As it is unknown to the driver on startup which server from the endpoints array is the current leader, the driver will connect to the specified servers in array order by default. To spare a few unnecessary connection attempts to non-leaders (or failed servers), it is possible to set up caching (using Memcached) for the server list. The cached server list will contain the last working server first, so that as few connection attempts as possible will need to be made for future invocations.

In order to use caching, it is required to install the Memcached module for PHP, and to set up the following relevant options in the ConnectionOptions:

Full setup example

Putting all the above together, we end up with the following PHP code for setting up the active failover:

You can give it a try by downloading the latest maintenance release – ArangoDB 3.3.4, and the ArangoDB-PHP driver. Read more on active failover architecture in our docs.

Enjoy!