minimalistic couchdb driver for node.js

nano features:

• minimalistic - there is only a minimum of abstraction between you and couchdb
• pipes - proxy requests from couchdb directly to your end user
• errors - errors are proxied directly from couchdb: if you know couchdb you already know nano.

1. install npm
2. npm install nano

• getting started
• tutorials & screencasts
• configuration
• database functions
  • nano.db.create(name, [callback])
  • nano.db.get(name, [callback])
  • nano.db.destroy(name, [callback])
  • nano.db.list([callback])
  • nano.db.compact(name, [designname], [callback])
  • nano.db.replicate(source, target, [opts], [callback])
  • nano.db.changes(name, [params], [callback])
  • nano.db.follow(name, [params], [callback])
  • nano.db.info([callback])
  • nano.use(name)
  • nano.request(opts, [callback])
  • nano.config
  • nano.updates([params], [callback])
  • nano.followUpdates([params], [callback])
• document functions
  • db.insert(doc, [params], [callback])
  • db.destroy(docname, rev, [callback])
  • db.get(docname, [params], [callback])
  • db.head(docname, [callback])
  • db.copy(src_doc, dest_doc, opts, [callback])
  • db.bulk(docs, [params], [callback])
  • db.list([params], [callback])
  • db.fetch(docnames, [params], [callback])
  • db.fetchRevs(docnames, [params], [callback])
• multipart functions
  • db.multipart.insert(doc, attachments, [params], [callback])
  • db.multipart.get(docname, [params], [callback])
• attachments functions
  • db.attachment.insert(docname, attname, att, contenttype, [params], [callback])
  • db.attachment.get(docname, attname, [params], [callback])
  • db.attachment.destroy(docname, attname, [params], [callback])
• views and design functions
  • db.view(designname, viewname, [params], [callback])
  • db.show(designname, showname, doc_id, [params], [callback])
  • db.atomic(designname, updatename, docname, [body], [callback])
  • db.search(designname, viewname, [params], [callback])
• using cookie authentication
• advanced features
  • extending nano
  • pipes
• tests

to use nano you need to connect it to your couchdb install, to do that:

varnano=require('nano')('http://localhost:5984');

to create a new database:

nano.db.create('alice');

and to use it:

varalice=nano.db.use('alice');

in this examples we didn't specify a callback function, the absence of a callback means "do this, ignore what happens". in nano the callback function receives always three arguments:

• err - the error, if any
• body - the http response body from couchdb, if no error. json parsed body, binary for non json responses
• header - the http response header from couchdb, if no error

a simple but complete example using callbacks is:

varnano=require('nano')('http://localhost:5984');// clean up the database we created previouslynano.db.destroy('alice',function(){// create a new databasenano.db.create('alice',function(){// specify the database we are going to usevaralice=nano.use('alice');// and insert a document in italice.insert({crazy: true},'rabbit',function(err,body,header){if(err){console.log('[alice.insert] ',err.message);return;}console.log('you have inserted the rabbit.')console.log(body);});});});

if you run this example(after starting couchdb) you will see:

you have inserted the rabbit.{ok: true, id: 'rabbit', rev: '1-6e4cb465d49c0368ac3946506d26335d' } 

you can also see your document in futon.

configuring nano to use your database server is as simple as:

varnano=require('nano')('http://localhost:5984'),db=nano.use('foo');

however if you don't need to instrument database objects you can simply:

// nano parses the url and knows this is a databasevardb=require('nano')('http://localhost:5984/foo');

you can also pass options to the require:

// nano parses the url and knows this is a databasevardb=require('nano')('http://localhost:5984/foo');

to specify further configuration options you can pass an object literal instead:

// nano parses the url and knows this is a databasevardb=require('nano')({"url" : "http://localhost:5984/foo","requestDefaults" : {"proxy" : "http://someproxy"},"log" : function(id,args){console.log(id,args);}});

Please check request for more information on the defaults. They support features like cookie jar, proxies, ssl, etc.

You can tell nano to not parse the url (maybe the server is behind a proxy, is accessed through a rewrite rule or other):

// nano does not parse the url and return the server api// "http://localhost:5984/prefix" is the CouchDB server rootvarcouch=require('nano')({"url" : "http://localhost:5984/prefix""parseUrl" : false});vardb=couch.use('foo');

a very important configuration parameter if you have a high traffic website and are using nano is setting up the pool.size. by default, the node.js http global agent (client) has a certain size of active connections that can run simultaneously, while others are kept in a queue. pooling can be disabled by setting the agent property in requestDefaults to false, or adjust the global pool size using:

http.globalAgent.maxSockets=20;

you can also increase the size in your calling context using requestDefaults if this is problematic. refer to the request documentation and examples for further clarification.

here's an example explicitly using the keep alive agent (installed using npm install agentkeepalive), especially useful to limit your open sockets when doing high-volume access to couchdb on localhost:

varagentkeepalive=require('agentkeepalive');varmyagent=newagentkeepalive({maxSockets: 50,maxKeepAliveRequests: 0,maxKeepAliveTime: 30000});vardb=require('nano')({"url" : "http://localhost:5984/foo","requestDefaults" : {"agent" : myagent}});

creates a couchdb database with the given name.

nano.db.create('alice',function(err,body){if(!err){console.log('database alice created!');}});

get informations about name.

nano.db.get('alice',function(err,body){if(!err){console.log(body);}});

destroys name.

nano.db.destroy('alice');

even though this examples looks sync it is an async function.

lists all the databases in couchdb

nano.db.list(function(err,body){// body is an arraybody.forEach(function(db){console.log(db);});});

compacts name, if designname is specified also compacts its views.

replicates source on target with options opts. target has to exist, add create_target:true to opts to create it prior to replication.

nano.db.replicate('alice','http://admin:[email protected]:5984/alice',{create_target:true},function(err,body){if(!err)console.log(body);});

asks for the changes feed of name, params contains additions to the query string.

nano.db.changes('alice',function(err,body){if(!err){console.log(body);}});

Uses Follow to create a solid changes feed. please consult follow documentation for more information as this is a very complete API on it's own.

varfeed=db.follow({since: "now"});feed.on('change',function(change){console.log("change: ",change);});feed.follow();process.nextTick(function(){db.insert({"bar": "baz"},"bar");});

gets database information.

nano.db.info(function(err, body){if (!err){console.log('got database info'', body)} });

creates a scope where you operate inside name.

varalice=nano.use('alice');alice.insert({crazy: true},'rabbit',function(err,body){// do something});

alias for nano.use

alias for nano.use

alias for nano.use

makes a request to couchdb, the available opts are:

• opts.db – the database name
• opts.method – the http method, defaults to get
• opts.path – the full path of the request, overrides opts.doc and opts.att
• opts.doc – the document name
• opts.att – the attachment name
• opts.qs – query string parameters, appended after any existing opts.path, opts.doc, or opts.att
• opts.content_type – the content type of the request, default to json
• opts.headers – additional http headers, overrides existing ones
• opts.body – the document or attachment body
• opts.encoding – the encoding for attachments
• opts.multipart – array of objects for multipart request

alias for nano.request

alias for nano.request

 _ / '_) WAT U SAY! _.----._/ / / / _/ ( | ( | /__.-|_|--|_l 

an object containing the nano configurations, possible keys are:

• url - the couchdb url
• db - the database name

listen to db updates, the available params are:

• params.feed – Type of feed. Can be one of
• longpoll: Closes the connection after the first event.
• continuous: Send a line of JSON per event. Keeps the socket open until timeout.
• eventsource: Like, continuous, but sends the events in EventSource format.
• params.timeout – Number of seconds until CouchDB closes the connection. Default is 60.
• params.heartbeat – Whether CouchDB will send a newline character (\n) on timeout. Default is true.

** changed in version 6 **

Use Follow to create a solid _db_updates feed. Please consult follow documentation for more information as this is a very complete api on it's own

varfeed=nano.followUpdates({since: "now"});feed.on('change',function(change){console.log("change: ",change);});feed.follow();process.nextTick(function(){nano.db.create('alice');});

inserts doc in the database with optional params. if params is a string, its assumed as the intended document name. if params is an object, its passed as query string parameters and docName is checked for defining the document name.

varalice=nano.use('alice');alice.insert({crazy: true},'rabbit',function(err,body){if(!err)console.log(body);});

The insert function can also be used with the method signature db.insert(doc,[callback]), where the doc contains the _id field e.g.

varalice=nano.use('alice')alice.insert({_id: 'myid',crazy: true},function(err,body){if(!err)console.log(body)})

and also used to update an existing document, by including the _rev token in the document being saved:

varalice=nano.use('alice')alice.insert({_id: 'myid',_rev: '1-23202479633c2b380f79507a776743d5',crazy: false},function(err,body){if(!err)console.log(body)})

removes revision rev of docname from couchdb.

alice.destroy('rabbit','3-66c01cdf99e84c83a9b3fe65b88db8c0',function(err,body){if(!err)console.log(body);});

gets docname from the database with optional query string additions params.

alice.get('rabbit',{revs_info: true},function(err,body){if(!err)console.log(body);});

same as get but lightweight version that returns headers only.

alice.head('rabbit',function(err,_,headers){if(!err)console.log(headers);});

copy the contents (and attachments) of a document to a new document, or overwrite an existing target document

alice.copy('rabbit','rabbit2',{overwrite: true},function(err,_,headers){if(!err)console.log(headers);});

bulk operations(update/delete/insert) on the database, refer to the couchdb doc.

list all the docs in the database with optional query string additions params. This is useful for searching.

alice.list({startkey:'cat',limit:3},function(err,body){if(!err){body.rows.forEach(function(doc){console.log(doc);});}});

For a full list of params, see couchdb doc.

bulk fetch of the database documents, docnames are specified as per couchdb doc. additional query string params can be specified, include_docs is always set to true.

** changed in version 6 **

bulk fetch of the revisions of the database documents, docnames are specified as per couchdb doc. additional query string params can be specified, this is the same method as fetch but include_docs is not automatically set to true.

inserts a doc together with attachments and params. if params is a string, its assumed as the intended document name. if params is an object, its passed as query string parameters and docName is checked for defining the document name. refer to the doc for more details. attachments must be an array of objects with name, data and content_type properties.

varfs=require('fs');fs.readFile('rabbit.png',function(err,data){if(!err){alice.multipart.insert({foo: 'bar'},[{name: 'rabbit.png',data: data,content_type: 'image/png'}],'mydoc',function(err,body){if(!err)console.log(body);});}});

get docname together with its attachments via multipart/related request with optional query string additions params. refer to the doc for more details. the multipart response body is a Buffer.

alice.multipart.get('rabbit',function(err,buffer){if(!err)console.log(buffer.toString());});

inserts an attachment attname to docname, in most cases params.rev is required. refer to the doc for more details.

varfs=require('fs');fs.readFile('rabbit.png',function(err,data){if(!err){alice.attachment.insert('rabbit','rabbit.png',data,'image/png',{rev: '12-150985a725ec88be471921a54ce91452'},function(err,body){if(!err)console.log(body);});}});

or using pipe:

varfs=require('fs');fs.createReadStream('rabbit.png').pipe(alice.attachment.insert('new','rab.png',null,'image/png'));

get docname's attachment attname with optional query string additions params.

varfs=require('fs');alice.attachment.get('rabbit','rabbit.png',function(err,body){if(!err){fs.writeFile('rabbit.png',body);}});

or using pipe:

varfs=require('fs');alice.attachment.get('rabbit','rabbit.png').pipe(fs.createWriteStream('rabbit.png'));

changed in version 6

destroy attachment attname of docname's revision rev.

alice.attachment.destroy('rabbit','rabbit.png',{rev: '1-4701d73a08ce5c2f2983bf7c9ffd3320'},function(err,body){if(!err)console.log(body);});

calls a view of the specified design with optional query string additions params. if you're looking to filter the view results by key(s) pass an array of keys, e.g {keys: ['key1', 'key2', 'key_n'] }, as params.

alice.view('characters','crazy_ones',function(err,body){if(!err){body.rows.forEach(function(doc){console.log(doc.value);});}});

calls a list function feeded by the given view of the specified design document.

alice.viewWithList('characters','crazy_ones','my_list',function(err,body){if(!err){console.log(body);}});

calls a show function of the specified design for the document specified by doc_id with optional query string additions params.

alice.show('characters','format_doc','3621898430',function(err,doc){if(!err){console.log(doc);}});

take a look at the couchdb wiki for possible query paramaters and more information on show functions.

calls the design's update function with the specified doc in input.

db.atomic("update","inplace","foobar",{field: "foo",value: "bar"},function(error,response){assert.equal(error,undefined,"failed to update");assert.equal(response.foo,"bar","update worked");});

Note that the data is sent in the body of the request. An example update handler follows:

"updates": {"in-place" : "function(doc, req){varfield=req.body.field;varvalue=req.body.value;varmessage='set '+field+' to '+value;doc[field]=value;return[doc,message];}"

calls a view of the specified design with optional query string additions params.

alice.search('characters','crazy_ones',{q: 'cat'},function(err,doc){if(!err){console.log(doc);}});

check out the tests for a fully functioning example.

nano supports making requests using couchdb's cookie authentication functionality. there's a example in coffeescript, but essentially you just:

varnano=require('nano')('http://localhost:5984'),username='user',userpass='pass',callback=console.log// this would normally be some callback,cookies={}// store cookies, normally redis or something;nano.auth(username,userpass,function(err,body,headers){if(err){returncallback(err);}if(headers&&headers['set-cookie']){cookies[user]=headers['set-cookie'];}callback(null,"it worked");});

reusing a cookie:

varauth="some stored cookie",callback=console.log// this would normally be some callback,alice=require('nano')({url : 'http://localhost:5984/alice',cookie: 'AuthSession='+auth});;alice.insert(doc,function(err,body,headers){if(err){returncallback(err);}// change the cookie if couchdb tells us toif(headers&&headers['set-cookie']){auth=headers['set-cookie'];}callback(null,"it worked");});

getting current session:

varnano=require('nano')({url: 'http://localhost:5984',cookie: 'AuthSession='+auth});nano.session(function(err,session){if(err){returnconsole.log('oh noes!')}console.log('user is %s and has these roles: %j',session.userCtx.name,session.userCtx.roles);});

nano is minimalistic but you can add your own features with nano.request(opts, callback)

for example, to create a function to retrieve a specific revision of the rabbit document:

functiongetrabbitrev(rev,callback){nano.request({db: 'alice',doc: 'rabbit',method: 'get',params: {rev: rev}},callback);}getrabbitrev('4-2e6cdc4c7e26b745c2881a24e0eeece2',function(err,body){if(!err){console.log(body);}});

you can pipe in nano like in any other stream. for example if our rabbit document has an attachment with name picture.png (with a picture of our white rabbit, of course!) you can pipe it to a writable stream

varfs=require('fs'),nano=require('nano')('http://127.0.0.1:5984/');varalice=nano.use('alice');alice.attachment.get('rabbit','picture.png').pipe(fs.createWriteStream('/tmp/rabbit.png'));

then open /tmp/rabbit.png and you will see the rabbit picture.

• article: nano - a minimalistic couchdb client for nodejs
• article: getting started with node.js and couchdb
• article: document update handler support
• article: nano 3
• article: securing a site with couchdb cookie authentication using node.js and nano
• article: adding copy to nano
• article: how to update a document with nano
• article: thoughts on development using couchdb with node.js
• example in the wild: nanoblog

check issues

to run (and configure) the test suite simply:

cd nano npm install npm test

after adding a new test you can run it individually (with verbose output) using:

nano_env=testing node tests/doc/list.js list_doc_params

where list_doc_params is the test name.

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

• code: git clone git://github.com/dscape/nano.git
• home: http://github.com/dscape/nano
• bugs: http://github.com/dscape/nano/issues
• build:
• deps:
• chat: https://gitter.im/dscape/nano

(oo)--',- in caos

copyright 2011 nuno job <nunojob.com> (oo)--',--

licensed under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at

http://www.apache.org/licenses/LICENSE-2.0.html 

unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.