Introducing the Node.js MongoDB 2.0 Driver

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 at 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.
• db.cursorInfo removed as it never worked reliably.
• db.stats removed as inconsistent.
• db.collectionNames removed as it's just a specialized version of the new listCollections 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 behvave 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

Delete 2.0 return value

We've added the following new methods

• collection.insertOne Insert a single document.
• collection.insertMany Insert an array of documents.
• collection.replaceOne Replace an existing document fully.
• collection.updateOne Update a single document.
• collection.updateMany Update multiple documents in one go.
• collection.deleteOne Delete a single document.
• collection.deleteMany Delete multiple documents in one go.
• collection.findOneAndUpdate Use findAndModify to update a document.
• collection.findOneAndRemove Use findAndModify to remove a specific document.
• collection.findOneAndReplace Use findAndModify to replace a specific document.

The current insert, update and remove methods are marked for deprecation and will be removed in a future 3.0 driver. These 3 methods now also return the full mongodb-core results and have had their third return value removed to ensure less compatibility problems with orchestration libraries like async.

The insert methods are now capping at the maxWriteBatchSize passed back from MongoDB on the results from the ismaster command. For MongoDB 2.4 or lower this means a max of 1000 documents in each insert batch. Legacy insert mode has been deprecated in favor of proper emulation of current 2.6 or higher write commands.

Another important change is in how collection.find works. The idea is to chain commands instead of passing them into the find method. It still supports existing behavior from 1.4 so no code should break but the API documentation reflects the new preferred way to use the find to execute queries. An example is shown below.

db.collection(‘docs’).find({a:1}).limit(1).skip(100).toArray(function(err, docs) { console.dir(err); console.dir(docs); });

GridStore
The GridStore object has had some major changes due to issues discovered by users related to parallel writing using the previous available w+ append mode. Thus w+ in 2.0 only allows for changes to the file metadata and does not allow for appending to a file avoiding the possible data corruption. The hope is to create a new GridStore spec in the future that allows for proper handling of parallel writes to an existing file but, this requires changes for all drivers as well as the server.

MongoClient
MongoClient now only has the class method connect. Constructing a new MongoClient using Server, ReplSet or Mongos has been removed due to the confusion it caused in duplicating the way one can build a topology connection using Db in 1.4. MongoClient.connect is the recommended way to connect to a MongoDB topology.

Get Started

There is a getting started guide available in the driver documentation site that will help you get up and running quickly with examples. The driver API documentation also has extensive examples integrated into the documentation for all the available functions. The following shows the collection documentation.

To set up a simple new npm project with the driver you can perform the following steps.

This will create a basic npm module and install the mongodb driver as well as add it to the package.json file.

MongoDB also offers an online node.js course through MongoDB University that runs every quarter. To register, click below:

REGISTER NOW

About the Author - Christian

Christian Amor Kvalheim is an Engineering Lead on the DX team at MongoDB and the author of the node.js driver.