Fail over connection to cluster


Hi all.

I’m trying to understand how connecting to cluster work. So say I have 3 machines with CB and all are clustered together.

Machine A
Machine B
Machine C

From my understanding after reading the manual, my apps can call query any one of the 3 machines and the work load will be automatically balanced among all three of them. So say I setup my app to connect only to Machine A and god forbid, Machine A goes down. I understand that I Machine B and Machine C will take over with the work (assuming I setup the automatic fail over in CB). Since I only have Machine A IP in my application, that will still translate to Machine A is down and not reachable even though the cluster is still up and running and Machine B and Machine C is still accessible. Is that a correct statement?

So if that’s the case, is there a way to configure my PHP-SDK client to include all the IPs from the 3 machines so that if Machine A is down, the apps will automatically go to Machine B or Machine C.

With my lack of understanding of how CB clustering work, I was thinking of adding HA Proxy into the mix but I read it somewhere that it’s a bad idea to add a HA in the between Client connection and CB cluster.

So may I request someone to please enlightened me on my confusion? Many thanks in advance for all your help.



There are two stages to keep in mind:

  1. The initial connection your SDK makes to the cluster.
  2. The ongoing connections between the SDK and the cluster for data operations.

When you make the initial connection, you should give the PHP SDK the address for as many of the Couchbase servers as you can. That way, if Machine A is down when the SDK tries to open the connection then it’ll cycle through to the next machine.

Once that connection is made, the SDK will download the full map of the cluster. The PHP SDK will then automatically direct its queries to the correct machine in the cluster, with no need for intervention from you. The SDK will also receive updates should the shape of the cluster change, such as losing or adding a node.

So, the SDK will do all the load balancing you need. HA Proxy would only confuse things.

As a suggestion, you might want to watch this video:





Thanks for the fast reply. It makes perfect sense what you said. Now the question that I have is, is there some sort of configuration file in the sdk where I can put all the available server information in it or is it a programming issue where I add it in my own application file the information of the servers and first time connection, my application will connect to all of the available servers and the sdk will manage which server to use? Please advise? Many thanks again for all of your help.


The PHP SDK “Managing connections” page covers some of this:

In your application, when you connect to the Couchbase cluster you can provide a comma-separated list of server addresses, like this:

$myCluster = new CouchbaseCluster('couchbase://,,');


Exactly what I’m looking for. Many thanks Matthew… :slight_smile: Have a wonderful day…


Please report back on your success or failure.
It’s been my experience (python) that if the first node in the list is down, you will get either a long timeout before it tries the next node, or a plain connection failure and it will ignore the rest of the nodes in the list.
The way I handle it now is HA proxy with an authenticated http status (200) check on the url: $member:8091/pools/default/buckets/$expected_bucket.
This allows me to put a single ip in the config and not worry about it, it just works.


I will Robert as soon as I got my PHP-SDK working.


Hey ledude, is there something we can help with regarding getting the PHP-SDK working?


Hi matthew,

as we are just migrating our php application from memcached to to couchbase, it would be interesting for me to know, if the php memcached extension has the same behaviour like the your php-sdk ?
Meant, do i get the same behaviour, when connecting to a couchbase cluster with multiple memcached->addServer() for each cluster node ?

thanks mattias