We'll explore the Couchbase SDK and relevant APIs in detail over the next few chapters. But to complete our discussion on balancing and rebalancing, it's useful to understand the process from client to cluster. When an SDK is initialized in a client application, it makes a persistent connection to the cluster over a RESTful API. This API broadcasts a JSON message containing the cluster's topology. As nodes are added or removed, the cluster sends a new message with an updated topology.

This behavior sets Couchbase apart from other databases, whether relational or nonrelational. Most database systems have a central point of communication that is responsible for client communications. Couchbase owes some of its massive throughput to its smart clients. Eliminating the bottleneck of a man-in-the-middle allows performance levels to reach a massive scale. On a cluster with only four nodes, Couchbase is capable of achieving nearly 1 million operations per second.

Returning to the idea of balancing data across nodes, there's an additional detail that I didn't mention. The cluster maintains an abstraction known as vBuckets, which are used to direct a key to the correct server. Rather than mapping a key directly to a node, Couchbase SDKs map the key to one of the vBuckets. The endpoint for a vBucket is provided to the client as part of its topology message from the cluster. Regardless of the number of nodes, the number of vBuckets remains the same. The keys always hash to the same vBucket, even if the cluster changes the endpoint of the vBucket.

While you'll generally not need to worry about the existence of vBuckets, it is important to understand what happens on the client as the cluster changes its topology. The client maintains a map of vBuckets to the nodes. If that map changes due to a node failure, brief client failures may appear while the map is updated.