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.
The grid object has been removed as it's not widely used and offers very limited GridStore capabilities.
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
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.
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.
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.
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
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.
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 now only has the class method
connect. Constructing a new MongoClient using
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.
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
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
MongoDB also offers an online node.js course through
MongoDB University that runs every quarter. To register, click below:
About the Author - Christian
Christian Amor Kvalheim is an Engineering Lead on the DX team at MongoDB and the author of the