What's New

On this page

Learn what's new in:

New features of the 4.1 Node.js driver release include:

  • Added load balanced connection support for all cluster types including the beta Serverless platform.
  • Added support for the advanceClusterTime() method to determine if the ClientSession should update its cluster time.

New features of the 4.0 Node.js driver release include:

  • We've migrated the driver to TypeScript. You can now harness the type hinting and intellisense features in editors that support it to develop your MongoDB applications. Enjoy the benefits of this work in pure JavaScript projects as well.
  • The underlying BSON library used by this version is now migrated to TypeScript.
  • Inline documentation is now consistenly formatted to improve display in editors.
  • If you are a user of the community types @types/mongodb, there will likely be issues adopting the types from our codebase. We could not achieve a one to one match in types due to the details of writing the codebase in TypeScript.

We'd love to hear your TypeScript related feature requests. Please submit ideas on our JIRA project here.

The minimum supported version of Node.js is now v12.9 or greater for version 4 of the driver. Support for our 3.x branches will continue until summer 2022 to allow time to upgrade.


3.x supports back to Node.js v4.

Our Cursor implentation is now updated to make it clear what is possible before and after execution of an operation.

const fc = collection.find({a: 2.3}).skip(1)
for await (const doc of fc) {
fc.limit(1) // incorrect usage, cursor already executing

There was inconsistency surrounding how the cursor would error if a setting was applied after cursor execution began. Now, the cursor will throw an error when attempting to apply operations in an invalid state, similar to the following:

MongoError: Cursor is already initialized

  • Affected classes:

    • AbstractCursor
    • FindCursor
    • AggregationCursor
    • ChangeStreamCursor (This is the underlying cursor for ChangeStream)
    • ListCollectionsCursor

Our Cursor types no longer extend Readable directly. They must be transformed into a stream by calling

const cursor = collection.find({})
const stream =
stream.on("data", data => console.log)
stream.on("error", () => client.close())

Use hasNext() and next() for manual iteration. Use for await of syntax or any Promise helpers for asynchronous iteration.

With type hinting, you should find that options passed to a MongoClient are enumerated and discoverable. We've made a large effort to process all options in the driver to give early warnings about incompatible settings to get your app up and running in a correct state quickly.

  • checkServerIdentity is no longer checked before being passed to the underlying Node API. Previously, accepted values were false, or a function. Now, the argument must be a function. Specifying a boolean will result in an error being thrown.
  • It is longer required to specify useUnifiedTopology or useNewUrlParser.

This method no longer supports a strict option, which returned an error if the collection did not exist. To assert the existence of a collection, use the listCollections() method instead.

const collections = (await db.listCollections({}, { nameOnly: true })
({name}) => name
if (!collections.includes(myNewCollectionName)) {
throw new Error(`${myNewCollectionName} doesn't exist`);

BulkWriteError is now renamed to MongoBulkWriteError.

When running bulk operations that make writes you can encounter errors depending on your settings. Import the new class name MongoBulkWriteError when testing for errors in bulk operations.

DB is no longer an EventEmitter. Listen for events directly from your MongoClient instance.

The helper, deprecated since MongoDB 3.4, is now removed. Use the aggregation pipeline $group operator instead.

  • gssapiServiceName is now removed. Use authMechanismProperties.SERVICE_NAME in the URI or as an option on MongoClientOptions.

    // or
    new MongoClient(url, { SERVICE_NAME: "alternateServiceName" })
  • Specifying username and password as options is only supported in the URI or as an option on MongoClientOptions.

    new MongoClient("mongodb://username:password@<host><port>")
    // or
    new MongoClient(url, { auth: { username: "<>", password: "<>" } })

The GridStore API (already deprecated in 3.x) is now replaced with GridFSBucket. For more information on GridFS, see the mongodb manual.

Below are some snippets that represent equivalent operations.

// old way
const gs = new GridStore(db, filename, mode[, options])
// new way
const bucket = new GridFSBucket(client.db('test')[,options])

GridFSBucket uses the Node.js Stream API. You can replicate file seeking by using the start and end options, creating a download stream from your GridFSBucket.

bucket.openDownloadStreamByName(filename, { start: 0, end: 100 })
await client.connect();
const filename = 'test.txt'; // whatever local file name you want
const db = client.db();
const bucket = new GridFSBucket(db);
.on('error', console.error)
.on('finish', () => {
console.log('done writing to db!');
.then(files => {
.pipe(fs.createWriteStream('downloaded_' + filename))
.on('error', console.error)
.on('finish', () => {
console.log('done downloading!');

GridFSBucket does not need to be closed like GridStore.

// old way
GridStore.unlink(db, name, callback);
// new way

File metadata that used to be accessible on the GridStore instance can be found by querying the bucket.

const fileMetaDataList: GridFSFile[] = bucket.find({}).toArray();
  • We internally now only manage a unifiedTopology when you connect to a mongod. The differences between this and previous versions is detailed here.
  • It is longer required to specify useUnifiedTopology or useNewUrlParser.
  • You must use the new directConnection option to connect to unitiliazed replica set members.

Support is now added for fine-grained verbosity modes. You can learn more about each mode here.

The instrument() method is now removed. Use command monitoring instead. See our guide on command monitoring for more information.

For a detailed list of breaking changes, removals, and associated JIRA tickets, see the detailed list here.

New features of the 3.6 Node.js driver release include:

  • Added support for the MONGODB-AWS authentication mechanism using Amazon Web Services (AWS) Identity and Access Management (IAM) credentials
  • Added support for Online Certificate Status Protocol (OCSP)
  • The find() method supports allowDiskUse() for sorts that require too much memory to execute in RAM
  • The update() and replaceOne() methods support index hints
  • A reduction in recovery time for topology changes and failover events
  • Improvements in validation testing for the default writeConcern
  • Authentication requires fewer round trips to the server, resulting in faster connection setup
  • Shorter Salted Challenge Response Authentication Mechanism (SCRAM) conversations
  • Ability to create collections and indexes for multiple document transactions
  • Running validation for a collection in the background
Give Feedback

On this page