Things to look out for when switching from Couchbase SDK 2 to 3

Recently I have been working on converting a rather large project from couchbase SDK 2 to couchbase SDK 3. I would like to share a major change I had to make and a gotcha I ran into when converting the SDK version.

Major change: Introducing Collection

One of the biggest differences is that the Collection Class is introduced and that the individual methods like bucket immediately return, and do not throw an exception. Compare that to SDK 2 where the openBucket method would not work if it could not open the bucket.

A connection that looked like this before.

Cluster cluster = Cluster.connect(connectionString, username, password);
Bucket bucket = cluster.bucket(bucketName);
GetResult getResult = bucket.defaultCollection().get("airline_10");
cluster.disconnect();

Would now look like this.

Cluster cluster = Cluster.connect("127.0.0.1", "Administrator", "password");
Bucket bucket = cluster.bucket("travel-sample");
Collection collection = bucket.defaultCollection();
GetResult getResult = collection.get("airline_10");
cluster.disconnect();

One thing I found useful (now that the bucket immediately returns without throwing an exception) was the this.cluster.ping() function. This can be used to check your connection before you start running operations on your cluster. This was useful to me because I was retrofitting this to an existing system.

The Gotcha: Error Handling Changes

The huge gotcha I ran into was that Errors are returned differently. A pretty big change in version 3 is that now the errors are in a different structure. Whereas the error code used to return like this. 

error { code: 12 }

It is now

error { cause: LibcouchbaseError { code: 301 } }

Knowing this, I was able to make a mapping function that added code back to be a base level attribute. This is equally important because not only is the structure different from before, but also the error number. What was code 12 is now code 301 by adding this function you can now use either version of error handling.

/**
  * Translates new error code to former code
  * @function mapErrorCodes
  * @param {object} error
  */
 mapErrorCodes(error) {
     if(error instanceof couchbase.DocumentNotFoundError) {
         error.code = 13;
     } else if (error instanceof couchbase.DocumentExistsError) {
         error.code = 12;
     } else if (error instanceof couchbase.TemporaryFailureError || error instanceof couchbase.DocumentLockedError) {
         error.code = 11;
     } else if (error instanceof couchbase.TimeoutError) {
         error.code = 23;
     }
     return error;
 }

This function I created allowed me to keep our existing error handling the same and simply added error.code to the error object. If you are updating your couchbase sdk hopefully these two insights will help the process go smoothly. 

This error mapping function as well as many other functions and helpful process handling are in a package our company created and maintain called couchbase-service. If you are planning on updating your project to couchbase 3 I would highly recommend using this package.

https://github.com/Computer-Know-how/couchbase-service