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 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 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
{
result: { ok: 1, n: 1 },
connection: … Connection executed against …,
ops: [... Array of documents inserted ...]
}
```
Update 2.0 return value
{
result: { ok: 1, nModified: 0, n: 1, upserted: [.. Upsert Id’s returned .. ] },
connection: … Connection executed against …,
}
</code></pre>
<p><i> Delete 2.0 return value</i></p>
<pre><code>{
result: { ok: 1, n: 1 },
connection: … Connection executed against …,
}</code></pre>
<p>We've added the following new methods</p>
<ul>
<li><code>collection.insertOne</code> Insert a single document.</li>
<li><code>collection.insertMany</code> Insert an array of documents.</li>
<li><code>collection.replaceOne</code> Replace an existing document fully.</li>
<li><code>collection.updateOne</code> Update a single document.</li>
<li><code>collection.updateMany</code> Update multiple documents in one go.</li>
<li><code>collection.deleteOne</code> Delete a single document.</li>
<li><code>collection.deleteMany</code> Delete multiple documents in one go.</li>
<li><code>collection.findOneAndUpdate</code> Use findAndModify to update a document.</li>
<li><code>collection.findOneAndRemove</code> Use findAndModify to remove a specific document.</li>
<li><code>collection.findOneAndReplace</code> Use findAndModify to replace a specific document.</li>
</ul>
<p>The current <code>insert</code>, <code>update</code> and <code>remove</code> methods are marked for deprecation and will be removed in a future 3.0 driver. These 3 methods now also return the full <code>mongodb-core</code> results and have had their third return value removed to ensure less compatibility problems with orchestration libraries like <code>async</code>.</p>
<p>The insert methods are now capping at the <code>maxWriteBatchSize</code> passed back from MongoDB on the results from the <code>ismaster</code> 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.</p>
<p>Another important change is in how <code>collection.find</code> works. The idea is to chain commands instead of passing them into the <code>find</code> 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.</p>
<pre><code>db.collection(‘docs’).find({a:1}).limit(1).skip(100).toArray(function(err, docs) {
console.dir(err);
console.dir(docs);
});</code></pre>
<h5 id="gridstore">GridStore</h5>
<p>The GridStore object has had some major changes due to issues discovered by users related to parallel writing using the previous available <code>w+</code> append mode. Thus <code>w+</code> 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.</p>
<h5 id="mongoclient">MongoClient</h5>
<p>MongoClient now only has the class method <code>connect</code>. Constructing a new MongoClient using <code>Server</code>, <code>ReplSet</code> or <code>Mongos</code> has been removed due to the confusion it caused in duplicating the way one can build a topology connection using <code>Db</code> in 1.4. <code>MongoClient.connect</code> is the recommended way to connect to a MongoDB topology.</p>
<h4 id="get-started">Get Started</h4>
<p>There is a <a href="http://mongodb.github.io/node-mongodb-native/2.0/">getting started guide</a> 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 <a href="http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html."><code>collection</code> documentation</a>.</p>
<p>To set up a simple new npm project with the driver you can perform the following steps.</p>
<pre><code>mkdir myprojects
cd myprojects
npm init
npm install mongodb --save
</code></pre>
<p>This will create a basic <code>npm module</code> and install the mongodb driver as well as add it to the <code>package.json</code> file.</p>
<p>MongoDB also offers an online node.js course through <code>MongoDB University</code> that runs every quarter. To register, click below:</p>
<center><a class="btn btn-primary" href="https://university.mongodb.com/courses/M101JS/about?jmp=blog" target="_BLANK">Register Now</a></center>
<p><i>About the Author - Christian</i></p>
<p>Christian Amor Kvalheim is an Engineering Lead on the DX team at MongoDB and the author of the <code>node.js</code> driver.</p>
March 20, 2015