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
.
- install npm
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.use(name)
- nano.request(opts, [callback])
- nano.config
- document functions
- multipart functions
- attachments functions
- views and design functions
- using cookie authentication
- advanced features
- tests
to use nano
you need to connect it to your couchdb install, to do that:
var nano = require('nano')('http://localhost:5984');
to create a new database:
nano.db.create('alice');
and to use it:
var alice = 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 anybody
- the http response body from couchdb, if no error. json parsed body, binary for non json responsesheader
- the http response header from couchdb, if no error
a simple but complete example using callbacks is:
var nano = require('nano')('http://localhost:5984');
// clean up the database we created previously
nano.db.destroy('alice', function() {
// create a new database
nano.db.create('alice', function() {
// specify the database we are going to use
var alice = nano.use('alice');
// and insert a document in it
alice.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:
var server = require('nano')('http://localhost:5984')
, db = server.use('foo')
;
however if you don't need to instrument database objects you can simply:
// nano parses the url and knows this is a database
var db = require('nano')('http://localhost:5984/foo');
you can also pass options to the require:
// nano parses the url and knows this is a database
var db = 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 database
var db = require('nano')(
{ "url" : "http://localhost:5984/foo"
, "request_defaults" : { "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.
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 request_defaults
to false, or adjust the global pool size using:
http.globalAgent.maxSockets = 20;
you can also increase the size in your calling context using request_defaults
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:
var agentkeepalive = require('agentkeepalive');
var myagent = new agentkeepalive({
maxSockets: 50
, maxKeepAliveRequests: 0
, maxKeepAliveTime: 30000
});
var db = require('nano')(
{ "url" : "http://localhost:5984/foo"
, "request_defaults" : { "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 array
body.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
var feed = db.follow({since: "now"});
feed.on('change', function (change) {
console.log("change: ", change);
});
feed.follow();
process.nextTick(function () {
db.insert({"bar": "baz"}, "bar");
});
creates a scope where you operate inside name
.
var alice = 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 nameopts.method
– the http method, defaults toget
opts.path
– the full path of the request, overridesopts.doc
andopts.att
opts.doc
– the document nameopts.att
– the attachment nameopts.params
– query string parameters, appended after any existingopts.path
,opts.doc
, oropts.att
opts.content_type
– the content type of the request, default tojson
opts.headers
– additional http headers, overrides existing onesopts.body
– the document or attachment bodyopts.encoding
– the encoding for attachmentsopts.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 urldb
- the database name
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 doc_name
is checked for defining the document name.
var alice = nano.use('alice');
alice.insert({ crazy: true }, 'rabbit', 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
.
alice.list(function(err, body) {
if (!err) {
body.rows.forEach(function(doc) {
console.log(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
.
inserts a doc
together with attachments
and 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 doc_name
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.
var fs = 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.
var fs = 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
:
var fs = 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
.
var fs = require('fs');
alice.attachment.get('rabbit', 'rabbit.png', function(err, body) {
if (!err) {
fs.writeFile('rabbit.png', body);
}
});
or using pipe
:
var fs = require('fs');
alice.attachment.get('rabbit', 'rabbit.png').pipe(fs.createWriteStream('rabbit.png'));
destroy attachment attname
of docname
's revision rev
.
alice.attachment.destroy('rabbit', 'rabbit.png',
'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.view_with_list('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");
});
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 step-by-step guide here, but essentially you just:
var nano = 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) {
return callback(err);
}
if (headers && headers['set-cookie']) {
cookies[user] = headers['set-cookie'];
}
callback(null, "it worked");
});
reusing a cookie:
var auth = "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) {
return callback(err);
}
// change the cookie if couchdb tells us to
if (headers && headers['set-cookie']) {
auth = headers['set-cookie'];
}
callback(null, "it worked");
});
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:
function getrabbitrev(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
var fs = require('fs'),
nano = require('nano')('http://127.0.0.1:5984/');
var alice = 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
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:
(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.