Docs Menu

Docs HomeNode.js

What's New

On this page

  • What's New in 5.1
  • What's New in 5.0
  • What's New in 4.14
  • What's New in 4.13
  • What's New in 4.12
  • What's New in 4.11
  • What's New in 4.10
  • What's New in 4.9
  • What's New in 4.8
  • What's New in 4.7
  • What's New in 4.6
  • What's New in 4.5
  • What's New in 4.4
  • What's New in 4.3
  • What's New in 4.2
  • What's New in 4.1
  • What's New in 4.0
  • What's New in 3.7
  • What's New in 3.6

Learn what's new in:

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

  • The driver now supports automatic serialization of JavaScript bigint to BSON.Long. It also supports the deserialization of BSON.Long values returned from the server to bigint values when the useBigInt64 flag is passed as true.

To learn more, see the v5.1.0 Release Highlights.


Breaking Changes in v5.0

  • Version 5.0 of the Node.js driver is not compatible with Node.js v12 or earlier. If you want to use this version of the driver, You must use Node.js v14.20.1 or greater.

  • This release removes support for callbacks in favor of a promise-based API. The following list provides some strategies for callback users to adopt this version:

    • Migrate to the promise-based API (recommended)

    • Use the promise-based API and util.callbackify

    • Add mongodb-legacy to continue using callbacks

    For more information about these strategies, see Changes in the MongoDB Node.js Driver v5.

  • This release removes support for the Collection.insert(), Collection.update(), and Collection.remove() helper methods. The following list provides instructions on how to replace the functionality of the removed methods:

    • Migrate from Collection.insert() to insertOne() or insertMany()

    • Migrate from Collection.update() to updateOne() or updateMany()

    • Migrate from Collection.remove() to deleteOne() or deleteMany()

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

  • By default, the driver no longer checks types referenced in dot notation unless the StrictFilter type annotation is explicitly used. To learn more about this change, see the Typescript fundamentals page.


    This change is for Typescript only, and does not affect queries or operations at runtime.

  • Optional installation of @aws-sdk/credential-providers as a dependency.

    • The driver no longer includes AWS SDK modules by default. Use the following npm command to install the SDK:

      npm install --save "@aws-sdk/credential-providers@^3.201.0"

      If you install the SDK, npm notifies you if the version of the SDK you installed is incompatible with the driver. Once you install the dependency successfully, the driver uses the AWS SDK itself to manage credentials from the environment.


Upgrade from v4.13 to v4.14

This version includes a fix to a memory leak introduced in v4.13. We recommend upgrading to v4.14.

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

  • Fixed a memory leak introduced in v4.13.

  • Deprecated methods and options that reference the legacy Logger.

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

  • Automatic cancellation of in-flight operations in the connection pool when the driver encounters network timeout errors.

  • Disabled causal consistency in implicit sessions to prevent conflicting with the linearizable and available read concern settings.

  • Fixed a potential memory leak by ensuring that the driver destroys MessageStream instances whenever their connections are destroyed.


Upgrade Driver to Version 4.12.1

The 4.12.1 Node.js driver includes a fix to a regression in monitoring logic that could cause processes to crash.

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

  • Redefinition of the ChangeStream class as an async iterable. You can use ChangeStream instances in any context that expects an AsyncIterator.

    • Notably, change streams can now be used in Javascript for-await loops:

      const changeStream =;
      for await (const change of changeStream) {
      console.log("Received change: ", change);
  • Fix to server monitoring when the driver skips monitoring events. In this release, the driver always updates its view of the topology when processing monitoring events.

  • Performance improvements with buffering as a result of modification to data structures used internally in the driver.

To learn more, see the v4.12.0 Release Highlights.

When connecting to MongoDB Server version 6.0 or later, the driver prioritizes electionId settings before setVersion settings during Server Discovery and Monitoring events. In previous versions, the prioritization order was reversed.

This release also includes added support for mutually recursive collection schema types. The driver also provides type safety for dot-notation queries up to a depth of eight in this release. At a depth greater than or equal to eight, Typescript successfully compiles your code but does not provide type safety. This depth limit on recursive types is a current limitation of TypeScript.

Suppose we have a collection of type Collection<Author> that contains the following mutually recursive types:

interface Author {
name: string;
bestBook: Book;
interface Book {
title: string;
author: Author;

TypeScript enforces type checking up to a depth of eight. The following code causes a TypeScript compilation error because the name property value must be a string type:

myColl.findOne({ '': 25 });

At a depth greater than or equal to eight, TypeScript compiles your code but no longer type checks it. For example, the following code assigns a number to a string property but does not cause a compilation error because the referenced property is at a depth of 10:

'': 25

To learn more, see the v4.11.0 Release Highlights.

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

  • Callback Deprecation

    • Callbacks are now deprecated in favor of Promises. Callbacks will be removed in the next major release. The Node driver team recommends migrating to promises where possible:

      • Use async/await syntax.

      • Use the Node.js callbackify utility:

        require('util').callbackify(() => myColl.findOne())(callback)
      • Use then syntax:

        myColl.findOne().then(res => callback(null, res), err => callback(err))
    • If you are unable to migrate to Promises in a large codebase, you can use the MongoDB Node.js driver with optional callback support package.

To learn more, see v4.10.0 Release Highlights.

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

  • Fixed an inconsistency with writeConcern options in the type definitions.

  • Included the latest BSON release, which adds automatic UUID support. See the BSON release notes here.

To learn more, see v4.9.0 Release Highlights.

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

  • Added auto-completion and type safety for nested keys in an update filter

  • client.startSession() can now be called before connecting to MongoDB

  • estimatedDocumentCount() method can now accept a comment

To learn more, see v4.8.0 Release Highlights.

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

  • The MongoClient.connect() method is now optional when connecting to your MongoDB instance

  • Ability to compress messages with the Zstandard compression algorithm

  • Added support for the maxConnecting connection option

  • Ability for change stream documents to show your documents before and after an update

  • Added support for new change stream fields related to Cluster to Cluster Replication

  • The estimatedDocumentCount() method now uses the $count database command

  • Improved connecting to MongoDB in the AWS Lambda Init phase


Deprecation Notice

The ResumeOptions interface is deprecated. Use the ChangeStreamCursorOptions interface instead.

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

  • Improved the ChangeStreamDocument in TypeScript.

  • Even distribution of server selection based on load across servers.

To learn more, see v4.6.0 Release Highlights.

See v4.5.0 Release Highlights on GitHub.

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

  • KMIP provider support when using CSFLE.

  • TLS support when using CSFLE.

  • Hostname canonicalization now accepts "none", "forward", and "forwardAndReverse" as authMechanismProperties when using GSSAPI.

  • In the 4.0.0 release of the driver, the deprecated collection.count() method was inadvertently changed to behave like collection.countDocuments(). In this release, the collection.count() method is updated to match legacy behavior:

    • If a query is provided, collection.count() behaves the same as collection.countDocuments() and performs a collection scan.

    • If no query is provided, collection.count() behaves the same as collection.estimatedDocumentCount() and relies on collection metadata.


    Deprecation Notice

    The cursor.count() method is deprecated and will be removed in the next major version, along with collection.count(). Use the collection.estimatedDocumentCount() or collection.countDocuments() methods instead.

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

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

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.


In this release of the driver, the deprecated collection.count() method was inadvertently changed to behave like collection.countDocuments(). This behavior is corrected in version 4.4.

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 consistently 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 implementation is now updated to make it clear what is possible before and after execution of an operation.


const fc = myColl.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 = myColl.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 no 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 no longer required to specify useUnifiedTopology or useNewUrlParser.

  • You must use the new directConnection option to connect to uninitialized 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.7 Node.js driver release include:

  • Added support for load balancer mode while enabling the useUnifiedTopology option

  • Added support for Stable API while enabling the useUnifiedTopology option

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

  • 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

←  Compatibility
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.