Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
132 lines (89 sloc) 4.4 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 string that represents the relative file path of that config, e.g. cfg/tests.js. Do refer to cfg/couch.example.js for a example. There you can use it to specify where couchdb lives, if you want to use https, or even to use a proxy.

  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.