How do I utilize Couchbase from my node.js app?

In yesterdays post I told you that I had created an npm for our Couchbase driver, but I didn't give any examples on how you could utilize it so I figured I should create a short blog post about that. I'm the kind of guy who like real world examples instead of a lot of text, so I went ahead and created a small application for this purpose.

I didn't have any good ideas about what I could create, so I decided I should create a version of the vacuum example I did for libcouchbase a while back. The application is a small daemon that will move all JSON documents you store in a given directory into a Couchbase server by using the _id field in the JSON document as the key, and the entire file as the value. Its a pretty simple example, but should show us some of the concepts. You'll find the entire program (including installation notes) at https://github.com/trondn/vacuum.js.

I won't be going through the entire program, but only mention the specifics needed to talk to Couchbase.

The first thing we need to do is to create an instance of the Couchbase driver:

var couchnode = require('couchbase');
var cb = new couchnode.Couchbase(config.hostname,
    config.username,
    config.password,
    config.bucket);

Here we pass the address of the couchbase cluster (normally: hostname:8091), the username to log in with (normally the name of the bucket) with the corresponding password and the bucket we want to connect to. Unlike the C version we may start to use the instance immediately from JavaScript, and it will buffer all of our operations until it's connected.

If you look in the function process_file you'll find the first usage of the Couchbase instance:

cb.set(obj._id, String(data), 0, undefined, set_handler, fullname);

So what happens here? We try to store an object in Couchbase with the key being the content of the "_id" field in the JSON document. The current version of the driver only allows you to store Strings, so we need to create a String of the data. The next field is the expiration time of the object (0 means that the object will never expire). The undefined parameter is for the CAS field, which would allow us to say that we would only set this parameter if the object already exist in Couchbase with that identifier. The set_handler is the callback function when the operation is finished, and fullname is the absolute name of the file we just stored. But wait, why would the Couchbase driver need the absolute name of the file we just stored? The answer to that is that it doesn't. It is just a data field get back in the callback.

So let's look at the callback:

function set_handler(data, error, key, cas) {
    if (error) {
        console.log('Failed to store object: %s', key);
    } else {
        fs.unlink(data);
        process_next();
    }
}

It looks pretty simple? The first parameter is the "fullname" field we passed to the set parameter. It contains the absolute name of the file we wanted to store. The error parameter tells you if the operation succeeded or not. The key is the key we wanted to store, and the last field is the CAS identifier the server assigned to the object (which you may use in successive calls to set if you want to replace this exact version of the object.


Happy hacking!!!!