npm install mongojs
mongojs is easy to use:
var mongojs =var db =
The connection string should follow the format described in the mongo connection string docs. Some examples of this could be:
// simple usage for a local dbvar db =// the db is on a remote server (the port default to mongo)var db =// we can also provide some credentialsvar db =// connect using SCRAM-SHA-1 mechanismvar db =// connect using a different auth sourcevar db =// connect with optionsvar db =// connect now, and worry about collections latervar db =var mycollection = db
After we connected we can query or update the database just how we would using the mongo API with the exception that we use a callback.
The format for callbacks is always
callback(error, value) where error is null if no exception has occured. The update methods
findAndModify also pass the
lastErrorObject as the last argument to the callback function.
// find everythingdbmycollection// find everything, but sort by namedbmycollection// iterate over all whose level is greater than 90.dbmycollection// find a document using a native ObjectIddbmycollection// find all named 'mathias' and increment their leveldbmycollection// find one named 'mathias', tag him as a contributor and return the modified docdbmycollection// use the save function to just save a document (callback is optional for all writes)dbmycollection
If you provide a callback to
find or any cursor config operation mongojs will call
toArray for you
is the same as
For more detailed information about the different usages of update and querying see the mongo docs
var db =dbdb
0.7.0 all cursors are a readable stream of objects.
var JSONStream =// pipe all documents in mycollection to stdoutdbmycollection
Notice that you should pipe the cursor through a stringifier (like JSONStream) if you want to pipe it to a serial stream like a http response.
If you are using a capped collection you can create a tailable cursor to that collection by adding
tailable:true to the find options
var cursor = dbmycollection// since all cursors are streams we can just listen for datacursor
Note that you need to explicitly set the selection parameter in the
With mongojs you can run database commands just like with the mongo shell using
As of 0.15 mongojs supports the Bulk updates introduced in mongodb 2.6. Here's an example of the usage
var bulk = dbabulkbulkbulkbulkbulkbulkbulkbulkbulk
Mongojs can also connect to a mongo replication set by providing a connection string with multiple hosts
var db =
For more detailed information about replica sets see the mongo replication docs
Using harmony features
If you run node.js with the
--harmony option, then you can ommit the collection names array, and you can do stuff like.
var mongojs =var db =dbhackers
In the above example the
hackers collection is enabled automagically (similar to the shell) using the
Proxy feature in harmony
Passing a DB to the constructor
If you have an instance of mongojs, you can pass this to the constructor and mongojs will use the existing connection of that instance instead of creating a new one.
var mongodb =var mongojs =mongodbDb
Features not supported for MongoDB 2.4 or older (on mongojs version 1.0+).
- Index creation and deletion
- Aggregation cursors.
This features are relatively easy to add, but would make the code unnecessarily more complex. If you are using mongodb 2.4 or older and would like to use mongojs 1.0 with the above mentioned feautres, feel free to make a pull request or open and issue..
Upgrading from 0.x.x to 1.2.x
Version > 1.0.x is a major rewrite of mongojs. So expect some things not to work the same as in mongojs 0.x.x versions. Breaking changes include:
This API documentation is a work in progress.
db.collection.aggregate([pipeline], [options], [callback])
db.collection.aggregate([pipelineStep], [pipelineStep], [pipelineStep], ..., [callback])
db.collection.createIndex(keys, options, [callback])
db.collection.distinct(field, query, callback)
db.collection.ensureIndex(keys, options, [callback])
db.collection.find([criteria], [projection], [callback])
This function applies a query to a collection. You can get the return value, which is a cursor, or pass a callback
as the last parameter. Said callback receives
db.collection.findOne([criteria], [projection], callback)
Apply a query and get one single document passed as a callback. The callback receives
db.collection.mapReduce(map, reduce, options, [callback])
db.collection.remove(query, [justOne], [callback])
db.collection.remove(query, [options], [callback])
db.collection.save(doc, [options], [callback])
db.collection.update(query, update, [options], [callback])
Get the name of the collection.