NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #3169 most downloaded on npm
The official MongoDB driver for Node.js
Last release today
04 Oct 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
195 versions withdrawn
withdrawn after publishing
15 years old
922 releases · first in 2011
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
📜 Removal of deprecated functionality
The MongoDB Node.js team is pleased to announce version 7.0.0 of the mongodb package!
The following is a detailed collection of the changes in the major v7 release of the mongodb package for Node.js.
The main focus of this release was usability improvements and a streamlined API. Read on for details!
Important
This is a list of changes relative to v6.21.0 of the driver. ALL changes listed below are BREAKING unless indicated otherwise.
Users migrating from an older version of the driver are advised to upgrade to at least v6.21.0 before adopting v7.
The minimum supported Node.js version is now v20.19.0 and our TypeScript target has been updated to ES2023. We strive to keep our minimum supported Node.js version in sync with the runtime's release cadence to keep up with the latest security updates and modern language features.
Notably, the driver now offers native support for explicit resource management. Symbol.asyncDispose implementations are available on the MongoClient, ClientSession, ChangeStream and on cursors.
Note
Explicit resource management is considered experimental in the driver and will be until the TC39 explicit resource management proposal is completed.
bson and mongodb-connection-string-url versions 7.0.0This driver version has been updated to use bson@7.0.0 and mongodb-connection-string-url@7.0.0, which match the driver's Node.js runtime version support. BSON functionality re-exported from the driver is furthermore subject to the changes outlined in the BSON V7 release notes.
@mongodb-js/zstd optional peer dependency minimum version raised to 7.0.0, dropped support for 1.x and 2.x (note that @mongodb-js/zstd does not have 3.x-6.x version releases)kerberos optional peer dependency minimum version raised to 7.0.0, dropped support for 2.x (note that kerberos does not have 3.x-6.x version releases)mongodb-client-encryption optional peer dependency minimum version raised to 7.0.0, dropped support for 6.xAdditionally, the driver is now compatible with the following packages:
| Dependency | Previous Range | New Allowed Range |
|---|---|---|
| @aws-sdk/credential-providers | ^3.188.0 | ^3.806.0 |
| gcp-metadata | ^5.2.0 | ^7.0.1 |
| socks | ^2.7.1 | ^2.8.6 |
To improve long-term maintainability and ensure compatibility with AWS updates, we’ve standardized AWS auth to use the official SDK in all cases and made a number of supporting changes outlined below.
@aws-sdk/credential-providers is now required for MONGODB-AWS authenticationPrevious versions of the driver contained two implementations for AWS authentication and could run the risk of the custom driver implementation not supporting all AWS authentication features as well as not being correct when AWS makes changes. Using the official AWS SDK in all cases alleviates these issues.
npm install @aws-sdk/credential-providersWhen providing a custom AWS credential provider via the auth mechanism property AWS_CREDENTIAL_PROVIDER, it will now take the highest precedence over any other AWS auth method.
AWS environments (such as AWS Lambda) do not have credentials that are permanent and expire within a set amount of time. Providing credentials in the URI or options would mandate that those credentials would be valid for the life of the MongoClient, which is problematic. With this change, the fetching of credentials is fully handled by the installed required AWS SDK.
This means that for AWS authentication, all client URIs MUST now be specified as:
import { MongoClient } from 'mongodb';
const client = new MongoClient('mongodb<+srv>://<host>:<port>/?authMechanism=MONGODB-AWS');The previous method of providing URI encoded credentials based on the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY directly in the connection string will no longer work.
This change has been made for consistency with the common drivers specifications.
This will now throw a MongoServerError instead.
The driver aims to ensure that all errors it throws are subclasses of MongoError. However, when using CSFLE or QE, the driver's encryption implementation could sometimes throw errors that were not instances of MongoError.
Now, all errors thrown during encryption are subclasses of MongoError.
The PoolClearedError thrown in cases where the connection pool was cleared now fixes the typo in the error label.
$changeStream stage optionsUsers can now pass any option to collection.watch(). If an option is invalid for the $changeStream stage of the pipeline, the server will return an error. This change makes it possible to use newly introduced server options without waiting for them to become available in our public type definitions and eliminates the risk of valid but unrecognized options being silently ignored.
batchSize of 1000 for getMoresIn driver versions <7.0, the driver provides a default batchSize of 1000 for each getMore when iterating a cursor. This behavior is not ideal because the default is set regardless of the documents being fetched. For example, if a cursor fetches many small documents, the driver's default of 1000 can result in many round-trips to fetch all documents, when the server could fit all documents inside a single getMore if no batchSize were set.
Now, cursors no longer provide a default batchSize when executing a getMore. A batchSize will only be set on getMore commands if a batchSize has been explicitly configured for the cursor.
A common source of confusion for people configuring auto encryption is where to specify the path to mongocryptd and where to specify the path to crypt_shared. We've now made this clearer in our Typescript users. Typescript now reports errors if the specified filename doesn't match the default name of the file. Some examples:
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'some path'; // ERROR
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'mongocryptd'; // OK
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] =
'/usr/local/bin/mongocryptd'; // OK
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'mongocryptd.exe'; // OK
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'some path'; // ERROR
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.so'; // OK
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.dll'; // OK
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.dylib'; // OKMongoClient.connect() consistency across environmentsThe MongoClient connect function will now run a handshake regardless of credentials being defined. The upshot of this change is that connect is more consistent at verifying some fail-fast preconditions regardless of environment. For example, previously, if connecting to a loadBalanced=true cluster without authentication there would not have been an error until a command was attempted.
MongoClient.close() no longer sends endSessions if the topology does not have session supportMongoClient.close() attempts to free up any server resources that the client has instantiated, including sessions. Previously, MongoClient.close() unconditionally attempted to kill all sessions, regardless of whether or not the topology actually supports sessions.
Now, MongoClient.close() only attempts to clean up sessions if the topology supports sessions.
One socket.write call was not correctly wrapped in a try/catch block and network errors could bubble up to the driver. This call is now properly wrapped and will result in a retry.
ClientEncryption.rewrapManyDataKey() options now correctly marked as optionalThe options parameter for the ClientEncryption.rewrapManyDataKey() method is now correctly marked as optional in its TypeScript definition. This change aligns the type signature with the method's implementation and documentation, resolving a type mismatch for TypeScript users.
stream() method no longer accepts a transformCursors and ChangeStreams no longer accept a transform function. ReadableStream.map() can be used instead:
// before
const stream = cursor.stream({ transform: JSON.stringify });
// after
const stream = cursor.stream().map(JSON.stringify);This mechanism has been unsupported as of MongoDB 4.0 and attempting to use it will still raise an error.
ClientMetadata properties have been removed from the public APIPrevious versions of the driver unintentionally exposed the following properties that have now been made internal:
MongoClient.options.additionalDriverInfo
MongoClient.options.metadata
MongoClient.options.extendedMetadata
MongoOptions.additionalDriverInfo
MongoOptions.metadata
MongoOptions.extendedMetadata
ConnectionOptions.metadata
ConnectionOptions.extendedMetadata
CommandOptions.noResponse option removedThis option was never intended to be public, and never worked properly for user-facing APIs. It has now been removed.
GridFSFile.contentType;
GridFSFile.aliases;
GridFSBucketWriteStreamOptions.contentType;
GridFSBucketWriteStreamOptions.aliases;
CloseOptions;
ResumeOptions;
MongoClientOptions.useNewUrlParser;
MongoClientOptions.useUnifiedTopology;
CreateCollectionOptions.autoIndexId;
FindOptions<TSchema>; // now no generic type
ClientMetadataOptions;
FindOneOptions.batchSize;
FindOneOptions.limit;
FindOneOptions.noCursorTimeout;
ReadPreference.minWireVersion;
ServerCapabilities;
CommandOperationOptions.retryWrites; // is a global option on the MongoClient
ClientSession.transaction;
Transaction;
CancellationToken;beta namespace and move resource management into driver (#4719)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Deprecated items to be removed in 7.0.0
The MongoDB Node.js team is pleased to announce version 6.21.0 of the mongodb package!
The following items have been deprecated and will be removed in 7.0.0:
MongoCredentials.authMechanismProperties.AWS_SESSION_TOKEN // URI & client options for AWS variables will no longer be respected
CommandOptions.noResponse // Unused
ConnectionOptions.cancellationToken // Unused
CursorStreamOptions // Only option, transform, removed in favor of Stream#mapWe invite you to try the mongodb library immediately, and report any issues to the NODE project.
ServerCapabilities and ReadPreference.minWireVersion are deprecated
The MongoDB Node.js team is pleased to announce version 6.20.0 of the mongodb package!
Collection and Db objects now provide references to their Db and MongoClientimport { MongoClient } from 'mongodb';
const client = new MongoClient(process.env.MONGODB_URI);
const db = client.db('test');
assert(db.client === client); // returns the MongoClient associated with the Db object
const collection = db.collection('test');
assert(collection.db === db); // returns the Db associated with the Collection objectThe driver no longer throws errors when hint is provided to unacknowledged writes for delete, update and findAndModify commands in the following circumstances:
update commands.delete and findAndModify commands on servers >=4.4.Neither the ServerCapabilities class nor the ReadPreference.minWireVersion property were ever intended for public use and, internally, are effectively dead code with the driver's minimum supported server version being 4.2.
These will be made internal in a future major release:
driverInfoadditionalDriverInfometadataextendedMetadataCommandOperationOptions.retryWrites is deprecatedCommandOperationOptions.retryWrites is deprecated. This per‑command option has no effect; the Node.js driver only honors retryWrites when configured at the client level (MongoClient options) or via the connection string. Do not use this option on individual commands. There is no runtime behavior change because it was already ignored, but it will be removed in an upcoming major release and may cause type or build errors in code that references it. To control retryable writes, set retryWrites in MongoClient options or include retryWrites=true|false in the connection string.
.tryNext() now updates resumeToken to prevent duplicates after resumeWhen .tryNext() returns a change document, the driver now caches its resumeToken, aligning its behavior with .next() and the 'change' event. If .tryNext() returns null (no new changes), nothing is cached, which is unchanged from previous behavior.
Previously, .tryNext() did not update the resumeToken, so a resumable error could cause a resume from an older token and re-deliver already processed changes. With this release, resumes continue from the latest token observed via .tryNext(), preventing duplicates.
const changeStream = collection.watch([]);
while (true) {
const change = await changeStream.tryNext(); // prior versions could return duplicates
await scheduler.wait(1000); // delay since tryNext() does not wait for changes
}Applications that poll change streams with .tryNext() in non-blocking loops benefit directly. There are no API changes; if you previously tracked and passed resumeAfter or startAfter manually, you can now rely on the driver’s built-in token caching.
Huge thanks to @rkistner for bringing this bug to our attention and for sharing code to reproduce it. Huge thanks as well to @Omnicpie for investigating and implementing a fix.
MongoServerSelectionErrorWhen the driver encounters a MongoServerSelectionError while processing a Change Stream (e.g., due to a transient network issue or during an election), it now treats the error as resumable and attempts to resume using the latest cached resume token.
This applies to both iterator and event-emitter usage:
// Iterator form
const changeStream = collection.watch([]);
for await (const change of changeStream) {
// process change
}// Event-emitter form
const changeStream = collection.watch([]);
changeStream.on('change', (change) => {
// process change
});There are no API changes. If you previously caught MongoServerSelectionError and implemented manual resume logic, you can now rely on the driver’s built-in resume mechanism, which uses the cached resume token from the change event’s _id to continue without losing events.
Huge thanks to @grossbart for bringing this bug to our attention, investigating it and for sharing code to reproduce it!
MongoClient.appendMetadata() ignores duplicate metadataMongoClient.appendMetadata() will no longer append metadata if it duplicates the metadata already appended to the MongoClient.
retryWrites in CommandOperationOptions (#4661) (620972d)resumeToken in ChangeStream.tryNext() (#4636) (8331a93)We invite you to try the mongodb library immediately, and report any issues to the NODE project.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →