Docs Menu
Docs Home
/
Languages
/
Javascript
/
Node.js

Upgrade Driver Versions

On this page

  • Overview
  • How to Upgrade
  • Breaking Changes
  • Version 5.x Breaking Changes
  • Version 4.x Breaking Changes
  • Server Release Compatibility Changes
  • Version 4.2 Server Release Support Changes

Overview

On this page, you can learn how to upgrade your driver to a new version. This page also includes the changes you must make to your application to upgrade your driver without losing functionality, if applicable.

How to Upgrade

Before you upgrade, perform the following actions:

  • Ensure the new driver version is compatible with the MongoDB Server version your application connects to and the version of Node.js that your application runs on. See the Compatibility page for this information.

  • Address any breaking changes between the version of the driver your application currently uses and your planned upgrade version in the Breaking Changes section of this guide. To learn more about the MongoDB Server release compatibility changes, see the Server Release Compatibility Changes section.

Tip

You can minimize the amount of changes that you must make to your application when upgrading driver versions by using the Stable API.

To upgrade your driver version, run the following command in your application's directory:

npm install mongodb@5.6

To upgrade to a different version of the driver, replace the information after the @ symbol with your preferred version number. For more information about the npm install command, see the npm-install npm documentation.

Breaking Changes

A breaking change is a modification in a convention or behavior in a specific version of the driver that may prevent your application from working as expected.

The breaking changes in this section are categorized by the major version releases that introduced them. When upgrading driver versions, address all the breaking changes between your current version and the planned upgrade version. For example, if you are upgrading the driver from v3.x to v5.x, address all breaking changes listed under v4.x and v5.x.

Version 5.x Breaking Changes

  • Driver versions 5.x are 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.

  • The driver 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 the v5.0 changelog.

  • The driver 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()

  • The driver no longer includes AWS SDK modules by default.

  • The driver no longer automatically imports the bson-ext package.

  • The driver removes support for custom Promise libraries. The driver no longer supports the promiseLibrary option of MongoClient and the Promise.set export that allows specifying a custom Promise library.

  • The driver removes support for the Collection.mapReduce() helper.

  • The BulkWriteResult type no longer has the publicly enumerable result property.

  • The following types, options, and methods have been removed:

    • BulkResult.lastOp() method

    • opTime property of BulkResult

    • BulkWriteOptions.keepGoing option

    • WriteConcernError.err() method

    • AddUserOptions.digestPassword option

    • Kerberos gssapiCanonicalizeHostName option

    • slaveOk options and method removed in favor of secondaryOk

    • ObjectID type removed in favor of ObjectId

    • AsyncIterator interface removed in favor of AsyncGenerator

Version 4.x Breaking Changes

  • Driver versions 4.x are not compatible with Node.js v12.8 or earlier. If you want to use this version of the driver, You must use Node.js v12.9 or greater.

  • Cursor types no longer extend Readable directly.

  • You cannot use a ChangeStream instance as an iterator after using it as an EventEmitter. You also cannot do the reverse—using an EventEmitter instance as an iterator after using it as a ChangeStream.

  • The following methods no longer accept a callback parameter:

    • Collection.find()

    • Collection.aggregate()

    • Db.aggregate()

  • The default value of the maxPoolSize connection option is now 100.

  • The driver no longer supports the gssapiServiceName Kerberos option. Users should use authMechanismProperties.SERVICE_NAME instead.

  • The driver no longer accepts non-boolean types, such as 0 or 1, for boolean options.

  • The db.collection type no longer accepts a callback.

  • The Db type is no longer an EventEmitter. You can listen to any events directly from the MongoClient instance.

  • The driver removes support for the Collection.group() helper.

  • The driver no longer includes the deprecated GridStore API.

For more information about these changes, see the v4.0 changelog.

Server Release Compatibility Changes

A server release compatibility change is a modification to the driver that discontinues support for a set of MongoDB Server versions.

The driver discontinues support for a MongoDB Server version after it reaches end-of-life (EOL).

To learn more about the MongoDB support for EOL products, see the Legacy Support Policy.

Version 4.2 Server Release Support Changes

  • The v4.2 driver drops support for MongoDB Server v3.4 and earlier. To use the v4.2 driver, your MongoDB Server must be v3.6 or later. To learn how to upgrade your MongoDB Server deployment, see Release Notes in the MongoDB Server manual.

Back

Compatibility