Couchdev

I released couchdev on github and npm today. It is a simple utility that aides in writing applications, which use CouchDB as a data store.

About couchdev

The main purpose of couchdev is to push data from a directory to an instance of CouchDB. couchdev is in a sense similar to couchapp or armrest but differs largely in how and to what end it is used for.

• couchdev is not focused on a particular design document. It handles whole databases.

• couchdev is a "close to the metal" utility. There is a direct one-to-one correspondence between the content in your directory and your couch database.

• Unlike couchapp or armrest, couchdev doesn't give guidance when writing applications for CouchDB.

• couchdev does not necessarily distinguish between design- and data-documents. By default, it will only push design-documents. However, you can tell it to push data-documents, too.

Installing couchdev

Issue npm install -g couchdev. You need to have Node.js and NPM installed.

Using couchdev

Commands and help

We start by simply calling couchdev, and we learn that there are two commands available:

• push, and
• pull.

Both will give some details of usage when given the --help option.

Pull

The pull command will retrieve documents from your database and map them to a directory.

Say, we have a database test with a design document named demo which does have a view simpleview containing a map-function. If we issue

$ couchdev pull --database test --targetdir db_design

we will get a directory structure like:

`~db_design/
              `~_design/
                `~demo/
                  |~views/
                  | `~simpleview/
                  |   `-map.js
                  `-_doc.json

Push

We can now change our documents in the directory structure as we wish. Afterwards, we can perform

$ couchdev push  --database test --sourcedir db_design/

and Couchdev should respond with

couchdev pushed 1 design, and 0 data document(s)

Going further

Couchdev doesn't really make a difference between design and regular data documents. You can use the option --include-data-docs with both push and pull.

Consider the following two use-cases:

• You can push a set of data-documents to test your map and reduce functions conveniently.

This is the reason why I wrote couchdev, and maybe it is the sweet-spot of the application.

• You can pull all data-documents to your disk to create an accessible backup.

Note, that couchdev doesn't care about revisions even in the case of non-design documents. The push command used with --include-data-docs will silently overwrite newer revisions in your database! In general, you should not use couchdev for two-way synchronization between a directory structure and a CouchDB database.

Last but not least

couchdev is written in CoffeeScript for the Node.js runtime. Almost everything is done in parallel and asynchronously. couchdev is quite fast. It takes less than 3 seconds to push or pull 275 documents on my MacBook.

Tests run very fast even with database access. For medium sized projects, all tests are done before the first would even start in a ruby or java project. In many cases, you will not need a continuous integration machinery when developing for Node.js and CouchDB.

Update 2011-11-05

I don't use CouchDB anymore at this time. Consequently, I won't work on couchdev in the foreseeable future. However, the code will remain on Github.