v6.20.0

6.20.0 (2025-09-17)

The MongoDB Node.js team is pleased to announce version 6.20.0 of the mongodb package!

Release Notes

Collection and Db objects now provide references to their Db and MongoClient

import { 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 object

Hint is supported with unacknowledged writes for delete, update and findAndModify commands on servers that support hint

The driver no longer throws errors when hint is provided to unacknowledged writes for delete, update and findAndModify commands in the following circumstances:

• No error is thrown for update commands.
• No errors are thrown for delete and findAndModify commands on servers >=4.4.

ServerCapabilities and ReadPreference.minWireVersion are deprecated

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.

Driver info and metadata MongoClient options have been deprecated.

These will be made internal in a future major release:

• driverInfo
• additionalDriverInfo
• metadata
• extendedMetadata

CommandOperationOptions.retryWrites is deprecated

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

ChangeStream .tryNext() now updates resumeToken to prevent duplicates after resume

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

Change Streams now resume on MongoServerSelectionError

When 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 metadata

MongoClient.appendMetadata() will no longer append metadata if it duplicates the metadata already appended to the MongoClient.

Features

• NODE-7125: add db and client properties to collection and database objects (#4640) (3469f86)
• NODE-7134: allow hint with unacknowledged writes for delete, update and findAndModify commands (#4647) (82d6ce6)
• NODE-7139: remove pre-4.2 logic and deprecate dead code (#4657) (14303bc)
• NODE-7140: deprecate driver info options (#4654) (b813c85)
• NODE-7157: deprecate retryWrites in CommandOperationOptions (#4661) (620972d)

Bug Fixes

• NODE-4763: cache resumeToken in ChangeStream.tryNext() (#4636) (8331a93)
• NODE-6858: treat MongoServerSelectionError as a resumable error for Change Streams (#4653) (c6d64e7)
• NODE-7138: prevent duplicate metadata from being appended to handshake metadata (#4651) (05c230c)

Documentation

• Reference
• API
• Changelog

We invite you to try the mongodb library immediately, and report any issues to the NODE project.