The marking of of the Node.js MongoDB 2.0 driver as stable is a major leap forward. We’ve made improvements to the codebase that will serve as the foundation going forward. The end result is a better path forward for developers of tools and frameworks who want simple integration with MongoDB. The fundamentals of the driver are now located in the mongodb-core npm package and are meant for people building things like Mongoose, Mongojs and other libraries or frameworks that do not require all the additional abstractions and helpers available in the existing driver.

In this release, we implemented our new CRUD API specification, which is now consistent across all the officially supported drivers. We also addressed some long-standing requests, including exposing the entire write results in insert/update and delete methods. Here’s what you can expect in the Node.js MongoDB driver.

The Node.js MongoDB 2.0 driver

There are some key changes in the driver going from 1.X to 2.X that you need to be aware of before changing your application to using the new 2.X versions. There has been some cleanup of API's and some deprecations of 1.X features.

Architectural Differences in 2.X

One of the main changes is that the driver has been split into two pieces. There is a new mongodb-core module that contains the low level MongoDB API's while mongodb contains the high level driver. mongodb-core is targeted to creators of libraries like Mongoose and other ODM's who do not need all the abstractions available in the mongodb module. The driver is also as of the time of writing compatible with the node 0.11.x as well as io.js.

The 2.0 driver implements the new Server Discovery and Monitoring specification that specifies the official driver behaviors when connected to a replicaset. The specification can be found here.

Furthermore 2.0 implements the new CRUD names for all official drivers allowing for easing of cross platform API development.

Possible Breaking Changes

Let’s outline the changes that could break your existing application.

Node.JS versions and Streams

The 2.0 driver drops support for 0.8.x style streams and moves to 0.10.x or higher style pull based streams making for more reliable and faster streams. Backwards compatibility is provided by using the readable-stream npm package that might cause some slight behavior changes for the cursor streams.

All dependencies have now been updated to use the nan package meaning they will compile and work on 0.12.x or higher as well as io.js.

Grid Object

The grid object has been removed as it's not widely used and offers very limited GridStore capabilities.

Db Object

The db instance object has been simplified. We've removed the following methods:

db.dereference due to db references being deprecated in the server.

due to db references being deprecated in the server. db.cursorInfo removed as it never worked reliably.

removed as it never worked reliably. db.stats removed as inconsistent.

removed as inconsistent. db.collectionNames removed as it's just a specialized version of the new listCollections helper.

removed as it's just a specialized version of the new helper. db.collectionInfo removed as it's not compatible with the new MongoDB 2.8 or higher alternative storage engines.

The following new method was added to the db object.

db.listCollections to replace all other collection inquiry methods, as it will behave correctly for MongoDB 3.0 and higher as well as provide backwards compatibility for MongoDB 2.6 or lower.

Collection Object

A collection instance been enhanced. Most importantly, we now return the mongodb-core result objects directly with all the associated information returned from the server instead of the current selective information returned in the 1.4.x version.

In 1.4.x the second result of the callback in an update or delete only returned the number of documents affected by the operation, while insert returned the documents inserted decorated with the generated _id fields.

Insert 2.0 return value