the high-level, caching, CouchDB library
A high-level, caching, CouchDB client for Node.js
Cradle's API, although closely knit with CouchDB's, isn't overly so. Whenever the API can be abstracted in a friendlier, simpler way, that's the route it takes. So even though a large part of the
Cradle <--> CouchDB mappings are one to one, some Cradle functions, such as
save(), can perform more than one operation, depending on how they are used.
var cradle = ;var db = newcradleConnection;db;db;
$ npm install cradle
Cradle's API builds right on top of Node's asynch API. Every asynch method takes a callback as its last argument. The return value is an
event.EventEmitter, so listeners can also be optionally added.
newcradleConnection'' 5984cache: trueraw: false;
Note that you can also use
cradle.setup to set a global configuration:
cradle;var c = newcradleConnectioncc = newcradleConnection'188.8.131.52';
var db = c;db;
You can check if a database exists with the
If you want to get a specific revision for that document, you can pass it as the 2nd parameter to
Cradle is also able to fetch multiple documents if you have a list of ids, just pass an array to
Lets suppose that you have a design document that you've created:
In CouchDB you could query this view directly by making an HTTP request to:
cradle you can make this same query by using the
.view() database function:
In general, document creation is done with the
save() method, while updating is done with
Note that when saving a document this way, CouchDB overwrites the existing document with the new one. If you want to update only certain fields of the document, you have to fetch it first (with
get), make your changes, then resave the modified document with the above method.
If you only want to update one or more attributes, and leave the others untouched, you can use the
Note that we didn't pass a
_rev, this only works because we previously saved a full version of 'luke', and the
cache option is enabled.
If you want to insert more than one document at a time, for performance reasons, you can pass an array to
Here we create a design document named 'characters', with two views: 'all' and 'darkside'.
These views can later be queried with
db.view('characters/all'), for example.
Here we create a temporary view. WARNING: do not use this in production as it is extremely slow (use it to test views).
when saving a design document, cradle guesses you want to create a view, mention views explicitly to work around this.
To remove a document, you call the
remove() method, passing the latest document revision.
remove is called without a revision, and the document was recently fetched from the database, it will attempt to use the cached document's revision, providing caching is enabled.
var connection = newcradleConnection'' 443auth: username: 'john' password: 'fha82l';
var connection = newcradleConnection'couch.io' 443secure: trueauth: username: 'john' password: 'fha82l';
For a one-time
_changes query, simply call
db.changes with a callback:
Or if you want to see changes since a specific sequence number:
The callback will receive the list of changes as an Array. If you want to include
the affected documents, simply pass
include_docs: true in the options.
var feed = db;feed;
In this case, it returns an instance of
follow.Feed, which behaves very similarly to node's
EventEmitter API. For full documentation on the options available to you when monitoring CouchDB with
.changes() see the follow documentation.
databases(): Get list of databases
config(): Get server config
info(): Get server information
stats(): Statistics overview
activeTasks(): Get list of currently active tasks
uuids(count): Get count list of UUIDs
replicate(options): Replicate a database.
info(): Database information
all(): Get all documents
compact(): Compact database
viewCleanup(): Cleanup old view data
replicate(target, options): Replicate this database to