Upgrade Driver Versions

Version 6.x Breaking Changes

• Version 6.0 of the Node.js driver requires Node.js v16.20.1 or later.

• The driver removes support for the addUser() helper command. Use the createUser MongoDB Shell command instead.

• The driver removes support for the collStats operation. Use the $collStats aggregation operator instead.

• The driver deprecates all the ssl-prefixed options and the tlsCertificateFile option in the MongoClientOptions type. Create a SecureContext object or set the tls-prefixed options in your MongoClientOptions instance instead.

• The driver reads files set in the tlsCAFile and tlsCertificateKeyFile connection options when you call the MongoClient.connect() method, not when you create the MongoClient instance.

• The driver removes the keepAlive and keepAliveInitialDelay connection options. The value of keepAlive is permanently set to true and the value of keepAliveInitialDelay is set to 300000 milliseconds (300 seconds).

• The Db.command() method accepts only options that are not related to a specific command. To learn more about these options, see the Command Options section of the Run a Command guide.

• If you add mongodb-client-encryption as a dependency, the major version number must match that of the Node.js driver. For example, Node.js driver v6.x.x requires mongodb-client-encryption v6.x.x.

• Automatic Encryption methods are now in the Node.js driver. You must import these methods from the driver instead of from mongodb-client-encryption.

• Removed the ObjectId constructor that accepted a 12-character string.

• Modified abortTransaction() and commitTransaction() methods to return null instead of the raw command results.

• Removed connection option helpers that accepted values other than true or false as booleans. You must provide either true or false values in the connection string or to the MongoClient constructor.

• Removed the Binary BSON type constructor that accepted a string.

• The Binary.write() method no longer accepts a string to write to the binary BSON object.

• The ClientEncryption API returns promises instead of callbacks.

• The socks package, which enables SOCKS5 proxy support, is a peer-optional dependency. You must install the package to enable SOCKS5 in your application. To learn more, see Enable SOCKS5 Proxy Support.

• If you start a session on a client, then pass that session to a different client, the driver throws an error when you perform any operations in the session.

• The includeResultMetadata option for compound operation methods is false by default. See the Built-in Methods section of the Compound Operations guide for more information.

• The withSession() method returns the value that the provided function returns. In previous driver versions, this method returns undefined. The withTransaction() method returns the value that the callback returns. In previous driver versions, this method returns the server command response, which varies depending on the MongoDB Server version or type that the driver connects to. To learn more about transactions, see the Perform a Transaction usage examples and the Transactions guide.

• Raised the optional kerberos dependency minimum version to 2.0.1 and removed support for version 1.x.

• Raised the optional zstd dependency minimum version to 1.1.0.

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. 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.

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 to v3.6, follow the link that corresponds to your MongoDB deployment configuration:

  • Upgrade a Replica Set to 3.6

  • Upgrade a Standalone to 3.6

  • Upgrade a Sharded Cluster to 3.6