node-mongodb-wrapper

A wrapper for node-mongodb-native as close as possible to the native javascript driver. Why learn two interfaces?

History

v1.0.0 - A complete rewrite of the driver that now uses mongoclient. The interface is generally the same, but all the messiness of reconnecting has been removed, as thats transparently handeled by the mongo client. If you see any breakage, please open an issue!

Features

1. Minimal interface closely matching the command-line driver: http://www.mongodb.org/display/DOCS/Manual
2. Lazy open/close of connections (now handeled by the low level node-mongodb-native)
3. Most features of node-mongodb-native

Installation

  npm install mongodb-wrapper

Usage

1. You have to tell the db object which collections you're about to use (Harmony Proxies, I need you!)
2. You have to provide callbacks on "actionable" calls (toArray, count, but not find)
3. Otherwise, just like the native javascript driver

    var mongo = require('mongodb-wrapper')
    var db = mongo.db('localhost', 27017, 'test')
    db.collection('posts')
    
    db.posts.save({title: "A new post", body: "Here is some text"}, function(err, post) {
        db.posts.findOne({_id: doc._id}, function(err, post) {
            db.posts.find().limit(1).toArray(function(err, posts) {
                // posts[0].title == "A new post"
            })
        })
    })      

For more examples, please look at the test suite

Documentation

Remember the guiding principle: the syntax exactly matches the command-line driver, except you pass a call back to any function that hits the database.

Connecting

There are lots of ways to open up a database connection mongo.db(mongodbConnectionString) - returns a database object, for details on the connection string see mongodb docs

• NOTE: this mode does not support a prefix! mongo.db(host, port, dbname, [prefix], [username], [password]) - returns a database project

• If prefix is specified all collections will use the prefix in mongo, but you refer to them without the prefix in node.

• If username and password are specified, it will attempt to authenticate.

db.collection(name) - Returns a Collection object. Also creates db[name] so you can do this:

db.collection('users')
db.users.count(cb)

Replica Sets

Replica sets are also supported with an alternate function signature:

var hostsArray = [
  // opts is a hash of mongodb-native server opts: http://mongodb.github.com/node-mongodb-native/api-generated/server.html
  // also optional
  {host: "host1", port: 27017, opts: {}},
  {host: "host1", port: 27018, opts: {}},
  ...
]
// other replica set opts, such as read_secondary, are passed in here
// these opts are also passed to each mongodb-native server object, so you can have defaults for your servers
var opts = {rs_name: "myReplicaSet"}
 
mongo.db(hostsArray, opts, dbname, [prefix], [username], [password])

Authentication

db.auth(username, password, cb) - You can pass username and password into mongo.db instead of calling this manually

db.addUser(username, password, cb)

db.removeUser(username, password, cb)

Database

db.dropDatabase(cb)

db.lastError(cb) - cb(err, lastError)

db.eval(code, [parameters], cb)

db.createCollection(name, options, cb) - allows you to create a collection by hand if you want to specify the options

Collection

collection.ensureIndex(index, options, cb)

collection.dropIndexes(cb)

collection.renameCollection(newName, dropTarget, cb)

collection.insert(doc(s), cb)

collection.remove(selector, cb)

collection.drop(cb)

collection.save(doc, cb)

collection.update(selector, updates, [upsert], [multi], cb)

collection.count(cb)

collection.findAndModify(options, cb)

collection.find(selector, fields) - Returns a Cursor

collection.findOne(selector, fields, cb)

collection.group(options, cb)

collection.mapReduce(map, reduce, options, cb) - map and reduce can be functions, it will toString them for you.

collection.distinct(key, [query], cb)

Cursor

cursor.limit(num)

cursor.skip(num)

cursor.sort({field:1})

cursor.next(cb)

cursor.explain(cb)

cursor.toArray(cb)

cursor.count(cb)

cursor.getRawCursor - retrieves a raw mongodb-native cursor, so you can do things like cursor streams, and other fancy things not supported

Useful Exports

mongo.ObjectID - you need to wrap any string ids in this class to match on _id