Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
172 lines (118 sloc) 4.95 KB


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


  1. install npm
  2. npm install nano


a quick example using nano

to use nano you have to either provide a) a json configuration object or b) a configuration file path like cfg/tests.js. refer to cfg/couch.example.js for a example

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

within the nano variable you have various methods you can call. these include tasks like create, delete or list databases:


in this function there is not callback. in nano the absence of callback means "do this, ignore what happens"

you normally don't want to do that though:

  // 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 alice = nano.use("alice");
      alice.insert("rabbit", {crazy: true}, function(e,h,r){
        if(e) { throw e; }
        console.log("you have inserted the rabbit.")

the nano.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

  // 5: var alice = nano.use("alice");

in nano a callback has always three arguments

  // 6: alice.insert("rabbit", {crazy: true}, function(e,h,r){
  // 7:   if(e) { throw e; }
  // 8:   console.log("you have inserted the rabbit.")
  // 9: });


  e: the `error`, if any. check error.js for more info.
  h: the http response `headers` from couchdb, if no error.
  r: the http `response body` from couchdb, if no error.

that's it. don't forget to delete the database you created:



* marks optional params are additional querystring parameters

databases, et al


nano.db.create(db_name,callback*) nano.db.get(db_name,callback*) nano.db.destroy(db_name,callback*) nano.db.list(callback*) nano.db.compact(db_name,callback*) nano.db.replicate(source,target,continuous*,callback*) nano.use(db_name) nano.request(opts,callback*) nano.config(callback)


nano.use: [nano.db.use, nano.db.scope, nano.scope] nano.request: [nano.relax, nano.dinosaur]

documents, attachments, et al


doc.insert(doc,doc_name*,callback*) doc.update(doc_name,rev,doc,callback*) doc.destroy(doc_name,rev,callback*) doc.get(doc_name,params*,callback*) doc.bulk(docs,callback*) doc.list(params*,callback*) doc.attachment.insert(doc_name,att_name,att,content_type,params*,callback*) doc.attachment.get(doc_name,att_name,params*,callback*) doc.attachment.destroy(doc_name,att_name,rev,callback*)


nano.use sets db_name in scope so you don't have to specify it every time

nano.db.get: [*)] nano.db.replicate: [doc.replicate(target,continuous*,callback*)] nano.db.compact: [doc.compact(callback*)]


nano is minimalistic so it provides advanced users with a way to code their own extension functions:


to get a document in a specific rev an advanced user might do:

  nano.request( { db: "alice"
                , doc: "rabbit"
                , method: "GET"
                , params: { rev: "1-967a00dff5e02add41819138abb3284d"} 
    function (_,_,b) { console.log(b) }

this is the same as (assuming alice = nano.use("alice");):

  alice.get("rabbit", {rev: "1-967a00dff5e02add41819138abb3284d"},
    function (_,_,b) { console.log(b) }


  1. add pipe support as provided by request
  2. explore adding _changes feed


everyone is welcome to contribute. patches, bugfixes, new features

  1. create an issue on github so the community can comment on your idea
  2. fork nano in github
  3. create a new branch git checkout -b my_branch
  4. create tests for the changes you made
  5. make sure you pass both existing and newly inserted tests
  6. commit your changes
  7. push to your branch git push origin my_branch
  8. create an pull request


  1. install the packages referred as dev dependencies in package.json
  2. browse to test/ and ./run.

always make sure all the tests pass before sending in your pull request!

we will tell santa


              / _) ROAR! i'm a vegan!
       .-^^^-/ /
    __/       /
   /__.|_|-|_|     cannes est superb

(oO)--',- in caos

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