Release Notes

What's New in 6.20

The Node.js driver v6.20 release includes the following features:

• No longer generates an error when the hint option is provided to unacknowledged update commands. When connected to MongoDB Server 4.4 or later, the driver also supports the hint option for unacknowledged delete and findAndModify commands.

• Allows you to access the parent Db object from a Collection and the parent MongoClient object from a Db.

• Deprecates the ServerCapabilities class.

• Deprecates the ReadPreference.minWireVersion property.

• Deprecates the following MongoClient options:

  • driverInfo

  • additionalDriverInfo

  • metadata

  • extendedMetadata

• Deprecates the CommandOperationOptions.retryWrites option. The Node.js driver supports the retryWrites option only at the MongoClient level and already ignored the option when it was set at the operation level. However, this option will be removed in a future major release and might generate type or build errors in your code.

• Updates the resumeToken when you use the tryNext() method to iterate change stream events. Previous driver versions did not update the resumeToken, resulting in inconsistent behavior during change stream iteration.

• Allows change streams to resume after the driver encounters a MongoServerSelectionError.

• Ignores duplicate metadata when calling MongoClient.appendMetadata().

To learn more about this release, see the v6.20.0 Release Notes on GitHub.

What's New in 6.19

The Node.js driver v6.19 release includes the following features:

• Adds experimental support for Queryable Encryption text field prefix, suffix, and substring queries. You must upgrade your mongodb-client-encryption package to v6.5.0 or later to use this feature.

  Important

  Substring, prefix and suffix search are in preview and should be used for experimental workloads only.

• Deprecates the following options for findOne() operations:

  • limit

  • noCursorResponse

  • batchSize

• Ensures that findOne() can only receive a single batch of documents from the server to avoid unnecessary killCursor commands.

• Adds support to specify a secureContext to tlsOptions:<provider> in the autoEncryption options on the MongoClient or as an option to the``ClientEncryption`` object. This allows you to pass tlsCAFile and tlsCertificateKeyFile as in memory options to both MongoClientOptions.autoEncryption.tlsOptions and ClientEncryption.

• When authentication is enabled, the MongoClient now checks a connection out of the connection pool to force the initial handshake and checks it back in when connecting. This prevents unnecessary ping commands when connecting.

To learn more about this release, see the v6.19.0 Release Notes on GitHub.

What's New in 6.18

The Node.js driver v6.18 release includes the following features:

• Deprecates the following members and types:

  • Transaction.options()

  • Transaction.recoveryToken()

  • Transaction.isPinned()

  • Transaction.isStarting()

  • Transaction.isActive()

  • Transaction.isCommitted()

  • ClientMetadata

  • ClientMetadataOptions

  • CancellationToken

  • CommandOperationOptions.noResponse

  These members and types will be removed in an upcoming major version of the driver.

• Adds an appendMetadata() method that you can use to add handshake metadata after constructing the MongoClient object. The following example shows how to use this method to add the library name, version, and platform to a MongoClient object:

  import { MongoClient } from 'mongodb';
  const client = new MongoClient(process.env.MONGODB_URI);
  client.appendMetadata({ name: 'my library', version: '1.0', platform: 'NodeJS' });

• Adds a wallTime property to all ChangeStream event interfaces except ChangeStreamRefineCollectionShardKeyEvent and ChangeStreamReshardCollectionDocument. This property contains the server date and time of the database operation.

• Adds a databaseName property to the CommandSucceededEvent and CommandFailedEvent events. This property contains the name of the database against which the application executed the command.

• Closes idle connections during periods of no activity, even when the minPoolSize setting is set to 0. This fixes a bug where the ConnectionPool did not clean up idle or perished connections unless minPoolSize was greater than 0.

• The driver allocates sessions lazily when a cursor is iterated. In previous versions, the driver allocated sessions whenever a cursor was created, regardless of whether the application iterated on the cursor.

To learn more about this release, see the v6.18.0 Release Notes on GitHub.

What's New in 6.17

The Node.js driver v6.17 release includes the following features:

• Removes support for MongoDB Server 4.0.

• Upgrades the bson package to v6.10.4. For more information about this release, see the v6.10.4 Release Notes for the bson package on GitHub.

• Adds the keepAliveInitialDelay option when constructing a MongoClient. This option defaults to 120000 milliseconds.

• Retries OIDC authentication when the initial authentication fails due to an expired token error.

• Adds the sort option for updateOne() and replaceOne() operations. This option requires MongoDB Server 8.0 or later.

• Instructs the MongoClient.close() method to close outstanding in-use connections.

• Adds a keyTimeoutMS encryption option for configuring DEK cache expiration time. This option defaults to 6000 milliseconds and requires mongodb-client-encryption version 6.4 or later.

• Instructs update operations to generate an error if the ignoreUndefined is set to true and all updates are undefined.

• Treats socket errors as network errors.

To learn more about this release, see the v6.17.0 Release Notes on GitHub.

What's New in 6.16

The Node.js driver v6.16 release includes the following features:

• The Collection.distinct() method now supports an optional hint parameter which you can use to specify the index to use for the command. This functionality requires MongoDB Server 7.1 or later.

• Fixes a bug with processing of multiple messages within one network data chunk which could cause processing times to slow down.

• Fixes a bug where FindCursor.rewind() threw errors in certain cases.

• Deprecates support for MongoDB Server 4.0. Support will be completely removed in a future minor release.

To learn more about this release, see the v6.16.0 Release Notes on GitHub.

What's New in 6.15

The Node.js driver v6.15 release includes the following features:

• Adds support for supplying custom AWS credentials when configuring authentication or In-Use Encryption. You must supply the custom function signature in the following form:

  () => Promise<AWS.Credentials>

  You can also specify provider chains from the AWS SDK, allowing you to customize your options. To view examples of how to provide custom credentials, see the v6.15.0 Release Notes on GitHub.

• Fixes a bug that caused a MongoClient configured for OIDC with an AbortSignal to abort on the cursor when the client reauthenticates.

• Fixes a bug that caused an unhandled rejection to throw when a timeoutms expires before an operation reaches the server selection process.

• Fixes a bug caused by closing a change stream while processing a change event. This bug caused a potential error to reject an internal promise representing the "next" change.

To learn more about this release, see the v6.15.0 Release Notes on GitHub.

What's New in 6.14

The Node.js driver v6.14 release includes the following features:

• Adds support for the $lookup aggregation stage on encrypted collections. You must upgrade your mongodb-client-encryption package to v6.3.0 or later to use this feature.

• Uses the driver's implementation of the isUint8Array() method to prevent importing the util/types package.

• Reverts the version compatibility of @aws-sdk/credential-providers to v3.188.0.

To learn more about this release, see the v6.14.0 Release Notes on GitHub.

What's New in 6.13

The Node.js driver v6.13 release includes the following features:

• Adds a new standardized logger to enable insight into database operations without code changes. You can enable and configure the logger through environment variables, as shown in the following example:

  env MONGODB_LOG_ALL=debug node server.mjs

  To learn more about logging, see the Logging guide.

• Improves command monitoring performance by removing deep copies of command and reply objects. Modifying the command and response values might lead to undefined behavior.

• Adds an experimental abort signal feature. You can pass the signal command to the following methods to interrupt the execution of the method when the signal is triggered:

  • collection.find()

  • collection.findOne()

  • collection.aggregate()

  • collection.countDocuments()

  • db.listCollections()

  • db.command()

  Aborting a signal closes a connection, which might cause unnecessary connection reestablishment.

• To avoid potential DNS timeout errors, the driver catches and retries DNS lookups when resolving mongodb+srv:// connection strings.

• MongoClient.close() also closes any associated cursors.

• You can safely invoke MongoClient.close() concurrently, but we do not recommend doing so if avoidable.

• Fixes an issue that caused MONGODB-OIDC authentication to not properly reauthenticate if the handshake includes speculative authentication.

To learn more about this release, see the v6.13.0 Release Notes on GitHub.

What's New in 6.12

The Node.js driver v6.12 release includes the following features:

• Adds support for v2.0 of the zstd compression algorithm. For more information about zstd v2.0, see the zstd Release Notes on GitHub.

• Upgrades the bson package to v6.10.1. For more information about this release, see the v6.10.1 Release Notes for the bson package on GitHub.

• The driver populates the ServerDescription.error field with a more specific error type and message when marking a primary replica-set member stale.

• The driver reads socket data with a stream in object mode instead of buffer mode. This prevents message parsing errors in rare cases caused by inaccurate data chunking.

• If the driver encounters an error while connecting to a socks5 proxy, it no longer wraps the socks5 error in a MongoNetworkError. This prevents the driver from wrapping a MongoNetworkError in another MongoNetworkError.

To learn more about this release, see the v6.12.0 Release Notes on GitHub.

What's New in 6.11

The Node.js driver v6.11 release includes the following features:

• Adds support for Node.js v22.

• Adds the Client-Side Operations Timeout (CSOT) feature. You can use CSOT to apply a single timeout to all steps needed to complete a server-side operation, including server selection, connection checkout, serialization, and server-side execution. To learn more, see the Limit Server Execution Time guide.

  Note

  Experimental Feature

  The CSOT feature is experimental and might change in future driver releases.

• Adds OIDC authentication support for Kubernetes environments. To learn more about this feature, see the OIDC Authentication Mechanism guide.

  To use OIDC to authenticate from a Kubernetes environment, set the authMechanismProperties connection option to ENVIRONMENT:k8s in your connection string. You can use this feature when connecting to an environment running in Amazon's Elastic Kubernetes Service, Google Kubernetes Engine, or Azure Kubernetes Service.

• The bson package adds support for binary vector data. To learn more about this feature, see the v6.10.0 Release Notes for the bson package on GitHub.

• The driver emits ConnectionClosedEvents after PoolClearedEvents.

To learn more about this release, see the v6.11.0 Release Notes on GitHub.

What's New in 6.10

The Node.js driver v6.10 release is the first official release to support all MongoDB Server 8.0 features, and includes the following improvements and fixes:

• Removes support for MongoDB Server 3.6.

• Adds support for the MongoDB Server 8.0 bulk write API, which supports bulk write operations across multiple databases and collections in a single call.

• Allows SRV hostnames with fewer than three parts separated by . characters. For example, the driver now supports hostnames such as mongodb+srv://mongodb.local.

• Supports the explain option to retrieve an accurate maxTimeMS value for CRUD commands to describe the operation time. The explain options for find and aggregate operations are deprecated.

To learn more about this release, see the v6.10.0 Release Notes on GitHub.

What's New in 6.9

• Support for MongoDB Server 3.6 is deprecated and will be removed in a future driver release.

• The driver natively supports explicit resource management for cursors and the MongoClient, ClientSession, and ChangeStream objects. When using a compatible Node.js version, you can implement explicit resource management by using the cursor.stream() method and GridFSDownloadStream class.

  To learn how to use explicit resource management, see the v6.9.0 Release Notes on GitHub. For more information about explicit resource management, see the ECMAScript Explicit Resource Management Proposal on GitHub.

• If you're using Node.js 18.13 or later, you can pass the autoSelectFamily and autoSelectFamilyTimeout options to the MongoClient constructor. When the autoSelectFamily option is true, the driver automatically selects between an IPv4 or IPv6 connection. The autoSelectFamilyTimeout option specifies the timeout, in milliseconds, for the driver to select the connection family.

  The following code example shows how to use these options:

  const client = new MongoClient(uri,
    { autoSelectFamily: true, autoSelectFamilyTimeout: 100 });

• The MongoClient constructor accepts the allowPartialTrustChain option. This option controls the X509_V_FLAG_PARTIAL_CHAIN OpenSSL flag.

• The ConnectionCheckedOutEvent and ConnectionCheckFailedEvent now include a durationMS property. This property indicates the time elapsed between the start and end of a connection checkout operation.

• If you're using Node.js 18 or later, the driver ignores the cryptoCallbacks option and uses callbacks defined in C++ instead, significantly improving encryption performance. This change is available in the v6.1.0 version of the mongodb-client-encryption package.

• To enhance security, the options specifying the spawn path and arguments for mongocryptd must be own properties of autoEncryption.extraOptions. This change helps prevent global prototype pollution bugs related to these options. For more information about own properties, see Object.hasOwn() on MDN.

• Adds official support for Queryable Encryption (QE) range queries. To use this feature, your app must use mongodb-client-encryption v6.1.0 or later and must connect to MongoDB Server 8.0 or later. For more information about QE range queries, see Queryable Encryption in the MongoDB Server manual.

• The insertMany() and bulkWrite() methods accept ReadonlyArray inputs.

• The driver retries writes based on the top-level code, found in error.code, rather than the nested code in error.result.writeConcernError.code. This fixes an issue in sharded clusters running versions MongoDB Server earlier than 4.4.

• The LocalKMSProviderConfiguration.key property accepts a BSON Binary instance for AutoEncryptionOptions.

• In TypeScript, the BulkOperationBase class reports the length getter property.

• The MongoWriteConcernError type now preserves the original top-level code in MongoWriteConcernError.code.

• The cursor.toArray() method empties the current batch of documents into the array before calling the async iterator again. This change avoids the delays associated with async/await execution and improves performance by up to 5% on average. This optimization doesn't apply if you provide a transform to the cursor.map() method before calling the toArray() method.

• Fixes mixed use of the cursor.next() method with for await syntax.

• Adds the enableUtf8Validation option when deserializing BSON, which was inadvertently removed in Node.js driver v6.8.

• Adds the durationMS property to the ConnectionReadyEvent class. This property represents the time between the connection creation event and when the ConnectionReadyEvent fires.

To learn more about this release, see the v6.9.0 Release Notes on GitHub.

What's New in 6.8

The Node.js driver v6.8 release includes the following features:

• Fixes a bug where a local KMS provider accepted a BSON Binary instance at runtime, but the TypeScript compiler allowed only values of type Buffer and string.

• The ReadConcernMajorityNotAvailableYet error is now a retryable read error.

• You can now associate a name with, and provide multiple keys for, KMS providers. This feature requires mongodb-client-encryption v6.0.1 or later. You can't use named KMS providers if your application uses the automatic KMS provider refresh capability.

  The following code example shows how to configure a ClientEncryption object with multiple AWS keys:

  const clientEncryption = new ClientEncryption(keyVaultClient, {
    'aws:key1': {
      accessKeyId: ...,
      secretAccessKey: ...
    },
    'aws:key2': {
      accessKeyId: ...,
      secretAccessKey: ...
   },
  clientEncryption.createDataKey('aws:key-1', { ... });

• When you create a KMIP data key, you can now specify the delegated option. If this option is set to true, the KMIP provider performs encryption and decryption of the data key locally, ensuring that the encryption key never leaves the KMIP server. This feature requires mongodb-client-encryption v6.0.1 or later.

  The following code example shows how to specify this option:

  clientEncryption.createDataKey('kmip', { masterKey: { delegated: true } } );

• The driver now decodes BSON responses as the cursor iterates over them, rather than decoding the entire BSON response when it is received.

• The Github release for the mongodb package now contains a detached signature file, mongodb-X.Y.Z.tgz.sig, for the NPM package. This change applies to every major and patch release for versions 5.x and 6.x of the driver. To verify the package signature, follow the instructions in the Release Integrity section of the README.md file in the driver's GitHub repository.

To learn more about this release, see the v6.8.0 Release Notes on GitHub.

What's New in 6.7

The Node.js driver v6.7 release includes the following features:

• Adds support for the MONGODB-OIDC authentication mechanism when connected to MongoDB Server v7.0 and later. The driver supports authentication with Azure machine authentication, GCP machine authentication, callback authentication, and human interaction callback authentication facets.

• Fixes an issue where setting the useBigInt64 flag to true caused the internal compareTopologyVersion function to generate an error.

To learn more about this release, see the v6.7.0 Release Notes on GitHub.

What's New in 6.6

The Node.js driver v6.6 release includes the following features:

• Upgrades to using BSON 6.7.0. For details about the new BSON features, see the release notes for BSON 6.5.0, BSON 6.6.0, and BSON 6.7.0.

• Adds the addStage() method to the fluid aggregation API. You can use this method to add aggregation pipeline stages individually, as shown in the following example:

  const documents = await users.aggregate().addStage({ $project: { name: true } }).toArray();

• Adds the cause and dependencyName fields to the MongoMissingDependencyError class. You can use these fields to programmatically determine if a package is missing or why a package didn't load.

• Adds the minRoundTripTime property to the ServerDescription class. This property contains the minimum round-trip time over the last 10 heartbeats.

• Adds the toJSON() method to the TopologyDescription class. Although you can use this method to stringify TopologyDescription objects to JSON, we recommend using Node's util.inspect() method instead, because it properly handles all types used in JavaScript and the driver.

• Adds cursor options support for the Collection.indexExists(), Collection.indexes(), and Collection.indexInformation() methods in Typescript.

• Removes support for the readConcern and writeConcern options from the Collection.listSearchIndexes() method. listSearchIndexes() is an Atlas-specific method, and Atlas search indexes don't support these options.

• Redefines the ServerDescription.roundTripTime property as a moving average. Previously, it was a weighted average of the most recently observed heartbeat duration and the previous duration.

• You can specify the type of a search index when creating the index, as shown in the following example:

  const indexName = await collection.createSearchIndex({
      name: 'my-vector-search-index',
      type: 'vectorSearch',
      definition: {
          mappings: { dynamic: false }
      }
  });

• The UpdateFilter.$currentDate property no longer throws an error when you pass it to a compound method, such as findOneAndUpdate(), on a collection with a limited schema.

• The driver throws a MongoTransactionError only if you provide a ReadPreferenceMode other than primary and then try to perform a command that involves a read operation.

• The data type of the TopologyDescription.error property is MongoError.

• The Collection.indexExists() method no longer supports the full option.

• The Collection.indexInformation(), Collection.indexes(), and Db.indexInformation() methods have a return type of IndexDescriptionCompact | IndexDescriptionInfo[] in TypeScript.

• When retrieving AWS KMS (Key Management System) credentials, the driver no longer throws an error when it receives an access key that includes an expiration timestamp.

• The ClusterTime interface no longer defines the signature field as required in TypeScript.

To learn more about this release, see the v6.6.0 Release Highlights on GitHub.

What's New in 6.5

The Node.js driver v6.5 release includes the following features:

• Updates bulk write operations to use the pkFactory class for document ID generation.

• Fixes the read preference that is sent with read operations to primaryPreferred when the driver is connected to a secondary node in the replica set.

• Fixes a memory leak in promise creation for socket operations.

• Reduces first-time connection latency when connecting to a DNS seedlist by querying the SRV and TXT records in parallel.

• Adds tracking to container metadata when running a client in Kubernetes or a container environment in the client.env.container field of the handshake document.

• Adds the original error document returned by the server to the errorResponse field of the MongoServerError document.

• Deprecates the CloseOptions interface which is unused by the driver.

To learn more about this release, see the v6.5.0 Release Highlights on GitHub.

What's New in 6.4

The Node.js driver v6.4 release includes the following features:

• When multiple mongos instances are available, different servers are used for read and write retry attempts.

• Caches AWS credentials at the client level, rather than for each authentication.

• Upgrades to using BSON 6.4.0. For details about the new BSON features, see the release notes for BSON 6.3.0 and BSON 6.4.0.

• Read operations that result in an ExceededTimeLimit error are retried.

• Fixes a request issue related to TLS sockets and KMS Providers.

• Fixes the base64 padding on the saslContinue command to allow for mongosh authentication.

• Types countDocuments using Filter<Schema> rather than Document, which enables autocompletion and helps prevent downstream typing issues.

• Fixes a type error in the $addToSet option of the bulkWrite command. The driver skips $addToSet validation you extend your types from Document or any, or use properties of any type.

• Fixes the ServerHeartbeatSucceeded and ServerHeartbeatFailed event heartbeat duration so that it does not include the time to create the socket.

• Appropriately emits errors from cursor transform streams, rather than absorbing them.

• Makes AWS session tokens optional when a username and password are provided, and allows AWS SDK to handle the authentication requests.

To learn more about this release, see the v6.4.0 Release Highlights on GitHub.

What's New in 6.3

The Node.js driver v6.3 release includes the following features:

• Adds the serverMonitoringMode client option to control the behavior of the monitoring connection among the nodes in a topology. This option takes a value of auto (default), poll, or stream. To learn more, see the entry for this option in the Specify Connection Options guide.

  You can set the serverMonitoringMode option in a MongoClientOptions instance or as a connection string option. The following example shows how to create a client with the option set to stream:

  new MongoClient('<connection string>', { serverMonitoringMode: 'stream' });

• Fixes a connection leak when the serverApi client option is set.

• Deprecates the contentType and aliases GridFS options. To store the content type and aliases of a file, add contentType and aliases fields to the metadata document.

To learn more about this release, see the v6.3.0 Release Highlights.

What's New in 6.2

The Node.js driver v6.2 release includes the following features:

• Updates the bson package version to 6.2.0 to include color visualization of types, as shown in the following image:

  

  To learn more, see the bson v6.2.0 release notes.

• Ensures that the result.insertedIds property of a bulk write error type contains the _id values of successfully inserted documents. In previous versions, when a bulk write operation rejected an insert operation, the result.insertedIds property contained the _id values for all attempted inserts.

• Closes the implicit session created when running the findOne() method on a time series collection regardless of the outcome of the operation.

• Allows the creation of collections that have names that start or end with the . character. This change aligns the driver's database and collection name-checking behavior with the server's.

To learn more about this release, see the v6.2.0 Release Highlights.

What's New in 6.1

The Node.js driver v6.1 release includes the following features:

• Updates the bson package version to 6.1.0 to expose the Decimal128.fromStringWithRounding() method. To learn more, see the v6.1.0 bson release notes.

• Detects environment variables for region settings when you authenticate by using the IAM AssumeRoleWithWebIdentity action with MONGODB-AWS authentication. To instruct the driver to use your region options, you must set both of the following environment variables:

  • AWS_STS_REGIONAL_ENDPOINTS

  • AWS_REGION

  To learn how to set region settings when using the MONGODB-AWS authentication mechanism, see the Web Identity Token tab in the AWS IAM Authentication Mechanism guide.

• Fixes a memory leak issue caused by recursive calls to the next() method of the ChangeStream type.

To learn more about this release, see the v6.1.0 Release Highlights.

What's New in 6.0

The Node.js driver v6.0 release includes the following features:

• Removal of support for the addUser() helper command. Use the createUser MongoDB Shell command instead.

• Removal of support for the collStats operation. Use the $collStats aggregation operator instead.

• The options field of the ConnectionPoolCreatedEvent type contains only the following fields, which are the non-default pool options:

  • maxConnecting

  • maxPoolSize

  • minPoolSize

  • maxIdleTimeMS

  • waitQueueTimeoutMS

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

• Removal of 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).

  To learn how to set keepalive settings at a system level, see the Does TCP keepalive time affect MongoDB Deployments? FAQ entry in the Server manual.

• Removes the following options for the Db.command() method:

  • willRetryWrite

  • omitReadPreference

  • writeConcern

  • explain

  • readConcern

  • collation

  • maxTimeMS

  • comment

  • retryWrites

  • dbName

  • authdb

  • noResponse

  Although you cannot pass these options to the Db.command() method, you can still set them in the command document. To learn more, see the Command Options section of the Run a Database Command guide.

To learn more about this release, see the v6.0.0 Release Highlights.