Developing a client library

This chapter is relevant for developers who are creating their own client library that communicates with the Couchbase Server. For instance, developers creating a library for language or framework that is not yet supported by Couchbase would be interested in this content.

Couchbase SDKs provide an abstraction layer your web application will use to communicate with a cluster. Your application logic does not need to contain logic about navigating information in a cluster, nor does it need much additional code for handling data requests.

Once your client makes calls into your client library the following should be handled automatically at the SDK level:

  • Maintain direct communications with the cluster,

  • Determining cluster topology,

  • Distribute requests to the cluster; automatically make reads and writes to the correct node in a cluster,

  • Direct and redirect requests based on topology changes,

  • Handle and direct requests appropriately during a failover.

In general, your Couchbase client library implementation will be similar to a memcached (binary protocol) client library implementation.

For instance, it may even be an extension of some existing memcached binary-protocol client library), but just supports a different key hashing approach. Instead of using modulus or ketama/consistent hashing, the new hashing approach in Couchbase is instead based around “vbuckets”, which you can read about here

In the vBucket approach, to find a server to talk to for a given key, your client library should hash the key string into a vBucket-Id (a 16-bit integer). The default hash algorithm for this step is plain CRC, masked by the required number of bits. The vBucket-Id is then used as an array index into a server lookup table, which is also called a vBucket-to-server map. Those two steps will allow your client library to find the right couchbase server given a key and a vBucket-to-server map. This extra level of indirection (where we have an explicit vBucket-to-server map) allows couchbase to easily control item data rebalancing, migration and replication.