Couchtato – A CouchDB Document Utility Tool Written In Node.js

30 Jun 2011 Couchtato – A CouchDB Document Utility Tool Written In Node.js

We have been using Apache CouchDB at one of our clients project, and despite how well CouchDB worked, we learnt that there was still no easy way to find certain documents without resorting to writing map reduce functions either via a temporary view or a design document. This was an issue in particular for our testers and others who were not exactly familiar with CouchDB. We needed an easier to use alternative, and that was the main reason why I wrote Couchtato.

Couchtato is a command line tool that remotely iterates all documents in a CouchDB database and applies a set of JavaScript functions against each document, this can roughly be seen as applying ‘offline views’ to a remote database. These functions are defined in a couchtato.js file that lives in file system.

Here’s an example of a simple function that logs the ID of all documents with category ‘Cafe’ and city ‘Melbourne’. Notice that you only need to deal with the documents directly (via doc variable) and you don’t have to worry about implementing map reduce functions.

exports.conf = {
    "tasks": {
        "find-documents-by-criteria": function (c, doc) {
            if (doc.category === 'Cafe' && doc.city === 'Melbourne') {
                console.log(doc._id);
            }
        }
    }
}

But wait, that’s not all! Couchtato also exposes a utility ‘c’ variable which provides convenient functions to save and remove a document, and also to count and log any string which is usually built up with values from the document itself.

exports.conf = {
    "tasks": {
        "rename-city": function (c, doc) {
            if (doc.city === 'Melbourne') {
                doc.city = 'Adelaide';
                c.save(doc);
            }
        },
        "delete-no-city": function (c, doc) {
            if (!doc.city) {
                c.remove(doc);
            }
        },
        "count-by-city": function (c, doc) {
            if (doc.city) {
                c.count('Documents with city ' + doc.city);
            }
        },
        "log-city": function (c, doc) {
            if (doc.city === 'unknown') {
                c.log('Found unexpected ' + doc.city + ' city!');
            }
        }
    }
}

How does it work? Couchtato uses Cradle as the default database driver. It retrieves all documents using linked list pagination technique where each page is then processed asynchronously, and each document within each page is exposed to each couchtato.js function one by one.

So that was the easy part. Now, for the power users… couchtato.js is basically a Node.js module file, which means you can use Node.js API and require various Node.js modules, making couchtato.js pretty powerful. For example, you can post the documents to Twitter or Facebook if you want to, or check the documents against Akismet spam detection service using the relevant Node.js modules for those services, both of which are not something you can easily implement in CouchDB temporary view.

Going back to our client’s project. What have we used Couchtato for thus far?

• Our testers use Couchtato to look for documents with certain criteria.
• One of the developers uses Couchtato to export the data in XML/CSV format.
• The support team uses Couchtato to delete duplicated data and to fix incorrect data.
• Hooked up to a continuous integration tool, we also use Couchtato to automatically generate statistics report.

We’ve been quite happy with Couchtato and it has been a nice addition to the developer’s tool belt.

Couchtato source code, installation, and usage instructions are available on GitHub at https://github.com/cliffano/couchtato. Feedback and contribution are welcome!