Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

132 lines (89 sloc) 4.472 kb


nano (short for nanocouch) is a minimalistic couchdb driver for node.js.


  1. Install npm
  2. npm install nano


A quick example on using nano.

In nano callback always return three arguments:

  err: The error, if any. Check error.js for more info.
  headers: The HTTP response headers from CouchDB, if no error.
  response: The HTTP response body from CouchDB, if no error.

Because in nano you can do database operations you are not bound to one and only one database. The first thing you do is load the module pointing either providing a json configuration object or a configuration file path like cfg/tests.js. Do refer to cfg/couch.example.js for a example. There you will also specify where couchdb lives, if you want to use https, or even to use a proxy server.

  var nano = require('nano')('./cfg/tests.js');

Now you can do your database operations using nano. These include things like create, delete or list databases. Let's create a database to store some documents:


Where is my callback? Well in nano you have the option of not having a callback and say "I don't care".

Of course now you want to insert some documents and you wish you had the callback, so let's add it:

  // Clean up the database we created previously
  nano.db.destroy("alice", function(err,headers,response) {
    nano.db.create("alice", function(){
      // Specify the database we are going to use
      var alicedb = nano.use("alice");
      alicedb.insert("rabbit", {crazy: true}, function(e,h,r){
        if(e) { throw e; }
        console.log("You have inserted the rabbit.")

The alicedb.use method creates a scope where you operate inside a single database. This is just a convenience so you don't have to specify the database name every single time you do an update or delete.

Don't forget to delete the database you created:




Assuming var db = nano.use("somedb");:

  db.insert(doc_name,doc,callback) // doc_name is optional


  nano.db.replicate(source,target,continuous,callback) // continuous is optional

Other / Advanced



You can use nano.scope instead of nano.use. They are both also available inside db, e.g. nano.db.scope.

When using a database with nano.use you can still replicate, compact, and list the database you are using. e.g. to list you can use (because db.list is for listing documents). Other methods remain the same, e.g. db.replicate.

Future plans

Some future plans are mostly:

  1. Add pipe, support as provided by request
  2. Explore adding _changes feed
  3. Convenience functions for attachments
  4. Support views
  5. Support bulk load
  6. _uuids, _stats, _config, _active_tasks, _all_docs_by_seq
  7. Support batch in updates and inserts.

Great segway to contribute.


Everyone is welcome to contribute.

  1. Fork nano in github
  2. Create a new branch - git checkout -b my_branch
  3. Create tests for the changes you made
  4. Make sure you pass both existing and newly inserted tests
  5. Commit your changes
  6. Push to your branch - git push origin my_branch
  7. Create an pull request

Running the tests

To run the tests simply browse to test/ and ./run. Don't forget to install the packages referred as dev dependencies in package.json.

Always make sure all the tests pass before sending in your pull request! OR I'll tell Santa!


              / _) ROAR! I'm a vegan!
       .-^^^-/ /
    __/       /

(oO)--',- in caos

Jump to Line
Something went wrong with that request. Please try again.