From 960921496315df3d16de728f106fb48b59cb8c7a Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 17:21:59 -0400 Subject: [PATCH 01/11] docs: create v7 migration guide --- etc/notes/CHANGES_7.0.0.md | 249 +++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 etc/notes/CHANGES_7.0.0.md diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md new file mode 100644 index 0000000000..0661c1eedf --- /dev/null +++ b/etc/notes/CHANGES_7.0.0.md @@ -0,0 +1,249 @@ +# Changes in the MongoDB Node.js Driver v7 + +## About + +The following is a detailed collection of the changes in the major v6 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. + +## Contents + +- [🛠️ Runtime and dependency updates](#️%EF%B8%8F-runtime-and-dependency-updates) + - [Minimum Node.js version is now v20.19.0](#minimum-nodejs-version-is-now-v20190) + - [`bson` and `mongodb-connection-string-url` versions 7.0.0](#bson-and-mongodb-connection-string-url-versions-700) + - [Optional peer dependency releases and version bumps](#optional-peer-dependency-releases-and-version-bumps) +- [🔐 AWS authentication](#%EF%B8%8F-aws-authentication) + - [@aws-sdk/credential-providers is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication) + - [Custom AWS Credential Provider Takes Highest Precedence](#custom-aws-credential-provider-takes-highest-precedence) + - [Explicitly Provided Credentials No Longer Accepted With MONGODB-AWS Authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication) +- [⚙️ Error handling improvements](#️%EF%B8%8F-error-handling-improvements) + - [Dropping a Collection No Longer Throws When NS not Found](#dropping-a-collection-no-longer-throws-when-ns-not-found) + - [Aggregate with write concern + explain no longer throws client-side](#aggregate-with-write-concern--explain-no-longer-throws-client-side) + - [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror) + - ['PoolRequstedRetry' Error Label Renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) +- [💥 Misc breaking improvements](#%EF%B8%8F-misc-breaking-improvements) + - [Change Streams No Longer Whitelist $changeStream Stage Options](#change-streams-no-longer-whitelist-changestream-stage-options) + - [Cursors no longer provide a default batchSize of 1000 for getMores](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) + - [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts) +- [☀️ Misc non-breaking improvements](#️%EF%B8%8F-misc-non-breaking-improvements) + - [Improve `MongoClient.connect()` consistency across environments](#improve-mongoclientconnect-consistency-across-environments) + - [MongoClient.close() no longer sends endSessions if the topology does not have session support](#mongoclientclose-no-longer-sends-endsessions-if-the-topology-does-not-have-session-support) +- [📜 Removal of deprecated functionality](#%EF%B8%8F-removal-of-deprecated-functionality) + - [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform) + - [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed) + - [Internal ClientMetadata properties have been removed](#internal-clientmetadata-properties-have-been-removed) + - [`CommandOptions.noResponse` option removed](#commandoptionsnoresponse-option-removed) + - [Assorted deprecated type, class, and option removals](#assorted-deprecated-type-class-and-option-removals) + +## 🛠️ Runtime and dependency updates + +### Minimum Node.js version is now v20.19.0 + +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](https://nodejs.dev/en/about/releases/) 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](https://github.com/tc39/proposal-explicit-resource-management) is completed. + +### `bson` and `mongodb-connection-string-url` versions 7.0.0 + +This 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](https://github.com/mongodb/js-bson/releases/tag/v7.0.0). + +### Optional peer dependency releases and version bumps + +- `@mongodb-js/zstd` optional peer depedency 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.x` + +Additionally, the driver is now compatible with the following packages: + +| Dependency | Allowed Range | Previous Range | +| ----------------------------- | ------------- | -------------- | +| @aws-sdk/credential-providers | ^3.806.0 | ^3.188.0 | +| gcp-metadata | ^7.0.1 | ^5.2.0 | +| socks | ^2.8.6 | ^2.7.1 | + +## 🔐 AWS authentication + +### @aws-sdk/credential-providers is now required for MONGODB-AWS authentication + +Previous 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. + +```bash +npm install @aws-sdk/credential-providers +``` + +### Custom AWS credential provider takes highest precedence + +When 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, with the exception of URI parameters or credentials passed directly to the `MongoClient`. + +### Explicitly provided credentials no longer accepted with MONGODB-AWS authentication + +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 installed required AWS SDK will now fetch credentials using the environment, endpoints, or a custom credential provider. + +This means that for AWS authentication, all client URIs MUST now be specified as: + +```ts +import { MongoClient } from 'mongodb'; + +const client = new MongoClient('mongodb<+srv>://:/?authMechanism=MONGODB-AWS'); +``` + +## ⚙️ Error handling improvements + +### Dropping a collection no longer throws when NS not found + +This will now return `false` instead. + +### Aggregate with write concern + explain no longer throws client-side + +This will now throw a `MongoServerError` instead. + +### All encryption-related errors now subclass MongoError + +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`. + +### 'PoolRequstedRetry' error label renamed to 'PoolRequestedRetry' + +The `PoolClearedError` thrown in cases where the connection pool was cleared now fixes the typo in the error label. + +## 💥 Misc breaking improvements + +### Change streams no longer whitelist $changeStream stage options + +Uses are now able to pass any option to `collection.watch()` and if it is invalid in the $changeStream stage of the pipeline the server will error. This is to allow users to provide newly added options quickly that are not in our public types. + +### Cursors no longer provide a default batchSize of 1000 for getMores + +In 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 bet set on `getMore` commands if a batchSize has been explicitly configured for the cursor. + +### Auto encryption options now include default filenames in TS + +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: + +```typescript +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.dlyib'; // OK +``` + +## ☀️ Misc non-breaking improvements + +### Improve `MongoClient.connect()` consistency across environments + +The 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 support + +`MongoClient.close()` attempts to free up any server resources that the client has instantiated, including sessions. Previously, `MongoClient.close()` unconditionally attempted to killall 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. + +## 📜 Removal of deprecated functionality + +### Cursor and ChangeStream `stream()` method no longer accepts a transform + +Cursors and ChangeStreams no longer accept a `transform` function. `ReadableStream.map()` can be used instead: + +```typescript +// before +const stream = cursor.stream({ transform: JSON.stringify }); + +// after +const stream = cursor.stream().map(JSON.stringify); +``` + +### MONGODB-CR AuthMechanism has been removed + +This mechanism has been unsupported as of MongoDB 4.0 and attempting to use it will still raise an error. + +### Internal ClientMetadata properties have been removed + +Previous versions of the driver unintentionally made properties used when constructing client metadata public. These properties have now been made internal. The full list of properties is: + +``` +MongoClient.options.additionalDriverInfo +MongoClient.options.metadata +MongoClient.options.extendedMetadata +MongoOptions.additionalDriverInfo +MongoOptions.metadata +MongoOptions.extendedMetadata +ConnectionOptions.metadata +ConnectionOptions.extendedMetadata +``` + +### `CommandOptions.noResponse` option removed + +This option was never intended to be public, and never worked properly for user-facing APIs. It has now been removed. + +### Assorted deprecated type, class, and option removals + +```ts +GridFSFile.contentType; +GridFSFile.aliases; +GridFSBucketWriteStreamOptions.contentType; +GridFSBucketWriteStreamOptions.aliases; +CloseOptions; +ResumeOptions; +MongoClientOptions.useNewUrlParser; +MongoClientOptions.useUnifiedTopology; +CreateCollectionOptions.autoIndexId; +FindOptions; // 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; +``` + +## ⚠️ ALL BREAKING CHANGES + +- **NODE-7259:** use alphas of all supporting packages ([#4746](https://github.com/mongodb/node-mongodb-native/issues/4746)) +- **NODE-5510:** dont filter change stream options ([#4723](https://github.com/mongodb/node-mongodb-native/issues/4723)) +- **NODE-6296:** remove cursor default batch size of 1000 ([#4729](https://github.com/mongodb/node-mongodb-native/issues/4729)) +- **NODE-7150:** update peer dependency matrix for 3rd party peer deps ([#4720](https://github.com/mongodb/node-mongodb-native/issues/4720)) +- **NODE-7046:** remove AWS uri/options support ([#4689](https://github.com/mongodb/node-mongodb-native/issues/4689)) +- **NODE-4808:** remove support for stream() transform on cursors and change streams ([#4728](https://github.com/mongodb/node-mongodb-native/issues/4728)) +- **NODE-6377:** remove noResponse option ([#4724](https://github.com/mongodb/node-mongodb-native/issues/4724)) +- **NODE-6473:** remove MONGODB-CR auth ([#4717](https://github.com/mongodb/node-mongodb-native/issues/4717)) +- **NODE-5994:** Remove metadata-related properties from public driver API ([#4716](https://github.com/mongodb/node-mongodb-native/issues/4716)) +- **NODE-7016:** remove `beta` namespace and move resource management into driver ([#4719](https://github.com/mongodb/node-mongodb-native/issues/4719)) +- **NODE-4184:** don't throw on aggregate with write concern and explain ([#4718](https://github.com/mongodb/node-mongodb-native/issues/4718)) +- **NODE-7043, NODE-7217:** adopt mongodb-client-encryption v7 ([#4705](https://github.com/mongodb/node-mongodb-native/issues/4705)) +- **NODE-6065:** throw MongoRuntimeError instead of MissingDependencyError in crypto connection ([#4711](https://github.com/mongodb/node-mongodb-native/issues/4711)) +- **NODE-6584:** improve typing for filepaths in AutoEncryptionOptions ([#4341](https://github.com/mongodb/node-mongodb-native/issues/4341)) +- **NODE-6334:** rename PoolRequstedRetry to PoolRequestedRetry ([#4696](https://github.com/mongodb/node-mongodb-native/issues/4696)) +- **NODE-7174:** drop support for Node16 and Node18 ([#4668](https://github.com/mongodb/node-mongodb-native/issues/4668)) +- **NODE-7047:** use custom credential provider first after URI ([#4656](https://github.com/mongodb/node-mongodb-native/issues/4656)) +- **NODE-6988:** require aws sdk for aws auth ([#4659](https://github.com/mongodb/node-mongodb-native/issues/4659)) +- **NODE-5545:** remove deprecated objects ([#4704](https://github.com/mongodb/node-mongodb-native/issues/4704)) ([cfbada6](https://github.com/mongodb/node-mongodb-native/commit/cfbada66ceb017bdb8fa1ff39257e1ab49ee9e25)) + +### Features + +- **NODE-4243:** drop collection checks ns not found ([#4742](https://github.com/mongodb/node-mongodb-native/issues/4742)) ([a8d7c5f](https://github.com/mongodb/node-mongodb-native/commit/a8d7c5ff6c68ad57291641b2eb14cc27d91508ae)) +- **NODE-7223:** run checkout on connect regardless of credentials ([#4715](https://github.com/mongodb/node-mongodb-native/issues/4715)) ([c5f74ab](https://github.com/mongodb/node-mongodb-native/commit/c5f74abe27acd8661f17046b1740ac74de1be082)) +- **NODE-7260:** update bson alpha to latest ([#4748](https://github.com/mongodb/node-mongodb-native/issues/4748)) ([4e88559](https://github.com/mongodb/node-mongodb-native/commit/4e88559e8785973dc2124a54d5e850a00616bb16)) + +### Bug Fixes + +- **NODE-7232:** only send endSessions during client close if the topology supports sessions ([#4722](https://github.com/mongodb/node-mongodb-native/issues/4722)) ([cc85ebf](https://github.com/mongodb/node-mongodb-native/commit/cc85ebf246b20e0bae59e1bdcdf0f9c74ea01979)) From 932afe41a18eefc8b31519d8aa9bda89914eb430 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 17:35:56 -0400 Subject: [PATCH 02/11] docs: update v6 references to v7 in readme --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b4793b9c74..0f0ec5566e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js. -**Upgrading to version 6? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_6.0.0.md)!** +**Upgrading to version 7? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_7.0.0.md)!** ## Quick Links @@ -16,12 +16,10 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js. | MongoDB Developer Center | [www.mongodb.com/developer](https://www.mongodb.com/developer/languages/javascript/) | | Stack Overflow | [stackoverflow.com](https://stackoverflow.com/search?q=%28%5Btypescript%5D+or+%5Bjavascript%5D+or+%5Bnode.js%5D%29+and+%5Bmongodb%5D) | | Source Code | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) | -| Upgrade to v6 | [etc/notes/CHANGES_6.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_6.0.0.md) | +| Upgrade to v7 | [etc/notes/CHANGES_7.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_7.0.0.md) | | Contributing | [CONTRIBUTING.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTING.md) | | Changelog | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md) | - - ### Release Integrity Releases are created automatically and signed using the [Node team's GPG key](https://pgp.mongodb.com/node-driver.asc). This applies to the git tag as well as all release packages provided as part of a GitHub release. To verify the provided packages, download the key and import it using gpg: @@ -34,6 +32,7 @@ The GitHub release contains a detached signature file for the NPM package (named `mongodb-X.Y.Z.tgz.sig`). The following command returns the link npm package. + ```shell npm view mongodb@vX.Y.Z dist.tarball ``` @@ -41,12 +40,13 @@ npm view mongodb@vX.Y.Z dist.tarball Using the result of the above command, a `curl` command can return the official npm package for the release. To verify the integrity of the downloaded package, run the following command: + ```shell gpg --verify mongodb-X.Y.Z.tgz.sig mongodb-X.Y.Z.tgz ``` ->[!Note] -No verification is done when using npm to install the package. The contents of the Github tarball and npm's tarball are identical. +> [!Note] +> No verification is done when using npm to install the package. The contents of the Github tarball and npm's tarball are identical. The MongoDB Node.js driver follows [semantic versioning](https://semver.org/) for its releases. @@ -100,7 +100,7 @@ This is the lowest typescript version guaranteed to work with our driver: older Since typescript [does not restrict breaking changes to major versions](https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes), we consider this support best effort. If you run into any unexpected compiler failures against our supported TypeScript versions, please let us know by filing an issue on our [JIRA](https://jira.mongodb.org/browse/NODE). -Additionally, our Typescript types are compatible with the ECMAScript standard for our minimum supported Node version. Currently, our Typescript targets es2023. +Additionally, our Typescript types are compatible with the ECMAScript standard for our minimum supported Node version. Currently, our Typescript targets es2023. ## Installation From 9b1af0d67205bf53da6fc2e6962e60d903d0d582 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 17:36:23 -0400 Subject: [PATCH 03/11] docs: update component compat table --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0f0ec5566e..41e2b842e7 100644 --- a/README.md +++ b/README.md @@ -83,15 +83,14 @@ For exhaustive server and runtime version compatibility matrices, please refer t The following table describes add-on component version compatibility for the Node.js driver. Only packages with versions in these supported ranges are stable when used in combination. -| Component | `mongodb@3.x` | `mongodb@4.x` | `mongodb@5.x` | `mongodb@<6.12` | `mongodb@>=6.12` | `mongodb@>=7` | -| ------------------------------------------------------------------------------------ | ------------------ | ------------------ | ------------------ | --------------- | ------------------ | ------------------- | -| [bson](https://www.npmjs.com/package/bson) | ^1.0.0 | ^4.0.0 | ^5.0.0 | ^6.0.0 | ^6.0.0 | ^7.0.0 | -| [bson-ext](https://www.npmjs.com/package/bson-ext) | ^1.0.0 \|\| ^2.0.0 | ^4.0.0 | N/A | N/A | N/A | N/A | -| [kerberos](https://www.npmjs.com/package/kerberos) | ^1.0.0 | ^1.0.0 \|\| ^2.0.0 | ^1.0.0 \|\| ^2.0.0 | ^2.0.1 | ^2.0.1 | ^7.0.0 | -| [mongodb-client-encryption](https://www.npmjs.com/package/mongodb-client-encryption) | ^1.0.0 | ^1.0.0 \|\| ^2.0.0 | ^2.3.0 | ^6.0.0 | ^6.0.0 | ^7.0.0 | -| [mongodb-legacy](https://www.npmjs.com/package/mongodb-legacy) | N/A | ^4.0.0 | ^5.0.0 | ^6.0.0 | ^6.0.0 | N/A | -| [@mongodb-js/zstd](https://www.npmjs.com/package/@mongodb-js/zstd) | N/A | ^1.0.0 | ^1.0.0 | ^1.1.0 | ^1.1.0 \|\| ^2.0.0 | ^7.0.0 | - +| Component | `mongodb@3.x` | `mongodb@4.x` | `mongodb@5.x` | `mongodb@<6.12` | `mongodb@>=6.12` | `mongodb@7.x` | +| ------------------------------------------------------------------------------------ | ------------------ | ------------------ | ------------------ | --------------- | ------------------ | ------------- | +| [bson](https://www.npmjs.com/package/bson) | ^1.0.0 | ^4.0.0 | ^5.0.0 | ^6.0.0 | ^6.0.0 | ^7.0.0 | +| [bson-ext](https://www.npmjs.com/package/bson-ext) | ^1.0.0 \|\| ^2.0.0 | ^4.0.0 | N/A | N/A | N/A | N/A | +| [kerberos](https://www.npmjs.com/package/kerberos) | ^1.0.0 | ^1.0.0 \|\| ^2.0.0 | ^1.0.0 \|\| ^2.0.0 | ^2.0.1 | ^2.0.1 | ^7.0.0 | +| [mongodb-client-encryption](https://www.npmjs.com/package/mongodb-client-encryption) | ^1.0.0 | ^1.0.0 \|\| ^2.0.0 | ^2.3.0 | ^6.0.0 | ^6.0.0 | ^7.0.0 | +| [mongodb-legacy](https://www.npmjs.com/package/mongodb-legacy) | N/A | ^4.0.0 | ^5.0.0 | ^6.0.0 | ^6.0.0 | N/A | +| [@mongodb-js/zstd](https://www.npmjs.com/package/@mongodb-js/zstd) | N/A | ^1.0.0 | ^1.0.0 | ^1.1.0 | ^1.1.0 \|\| ^2.0.0 | ^7.0.0 | #### Typescript Version From 0d525f495014d5b8f8f0ce44f8f49eb7a0a614f4 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 18:07:01 -0400 Subject: [PATCH 04/11] docs: fixups --- etc/notes/CHANGES_7.0.0.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index 0661c1eedf..ca80da8008 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -17,15 +17,15 @@ The main focus of this release was usability improvements and a streamlined API. - [Optional peer dependency releases and version bumps](#optional-peer-dependency-releases-and-version-bumps) - [🔐 AWS authentication](#%EF%B8%8F-aws-authentication) - [@aws-sdk/credential-providers is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication) - - [Custom AWS Credential Provider Takes Highest Precedence](#custom-aws-credential-provider-takes-highest-precedence) - - [Explicitly Provided Credentials No Longer Accepted With MONGODB-AWS Authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication) + - [Custom AWS credential provider takes highest precedence](#custom-aws-credential-provider-takes-highest-precedence) + - [Explicitly provided credentials no longer accepted with MONGODB-AWS authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication) - [⚙️ Error handling improvements](#️%EF%B8%8F-error-handling-improvements) - - [Dropping a Collection No Longer Throws When NS not Found](#dropping-a-collection-no-longer-throws-when-ns-not-found) - - [Aggregate with write concern + explain no longer throws client-side](#aggregate-with-write-concern--explain-no-longer-throws-client-side) + - [Dropping a collection returns false instead of thowing when NS not found](#dropping-a-collection-returns-false-instead-of-throwing-when-ns-not-found) + - [Aggregate with write concern and explain no longer throws client-side](#aggregate-with-write-concern-and-explain-no-longer-throws-client-side) - [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror) - - ['PoolRequstedRetry' Error Label Renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) + - ['PoolRequstedRetry' error label renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) - [💥 Misc breaking improvements](#%EF%B8%8F-misc-breaking-improvements) - - [Change Streams No Longer Whitelist $changeStream Stage Options](#change-streams-no-longer-whitelist-changestream-stage-options) + - [Change streams no longer whitelist $changeStream stage options](#change-streams-no-longer-whitelist-changestream-stage-options) - [Cursors no longer provide a default batchSize of 1000 for getMores](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) - [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts) - [☀️ Misc non-breaking improvements](#️%EF%B8%8F-misc-non-breaking-improvements) @@ -55,7 +55,7 @@ This driver version has been updated to use `bson@7.0.0` and `mongodb-connection ### Optional peer dependency releases and version bumps -- `@mongodb-js/zstd` optional peer depedency 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) +- `@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.x` @@ -69,6 +69,8 @@ Additionally, the driver is now compatible with the following packages: ## 🔐 AWS authentication +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 authentication Previous 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. @@ -95,11 +97,11 @@ const client = new MongoClient('mongodb<+srv>://:/?authMechanism=MON ## ⚙️ Error handling improvements -### Dropping a collection no longer throws when NS not found +### Dropping a collection returns false instead of throwing when NS not found -This will now return `false` instead. +This change has been made for consistency with the common drivers specifications. -### Aggregate with write concern + explain no longer throws client-side +### Aggregate with write concern and explain no longer throws client-side This will now throw a `MongoServerError` instead. @@ -123,7 +125,7 @@ Uses are now able to pass any option to `collection.watch()` and if it is invali In 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 bet set on `getMore` commands if a batchSize has been explicitly configured for the cursor. +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. ### Auto encryption options now include default filenames in TS @@ -139,7 +141,7 @@ var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'mongo 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.dlyib'; // OK +var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.dylib'; // OK ``` ## ☀️ Misc non-breaking improvements @@ -150,7 +152,7 @@ The MongoClient connect function will now run a handshake regardless of credenti ### MongoClient.close() no longer sends endSessions if the topology does not have session support -`MongoClient.close()` attempts to free up any server resources that the client has instantiated, including sessions. Previously, `MongoClient.close()` unconditionally attempted to killall sessions, regardless of whether or not the topology actually supports sessions. +`MongoClient.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. From 7231ab746f3cc9fbc6946558fe5d119d77b02a9d Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 20:34:58 -0400 Subject: [PATCH 05/11] docs: maybe fix toc --- etc/notes/CHANGES_7.0.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index ca80da8008..fd3171c521 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -11,27 +11,27 @@ The main focus of this release was usability improvements and a streamlined API. ## Contents -- [🛠️ Runtime and dependency updates](#️%EF%B8%8F-runtime-and-dependency-updates) +- [🛠️ Runtime and dependency updates](#%EF%B8%8F-runtime-and-dependency-updates) - [Minimum Node.js version is now v20.19.0](#minimum-nodejs-version-is-now-v20190) - [`bson` and `mongodb-connection-string-url` versions 7.0.0](#bson-and-mongodb-connection-string-url-versions-700) - [Optional peer dependency releases and version bumps](#optional-peer-dependency-releases-and-version-bumps) -- [🔐 AWS authentication](#%EF%B8%8F-aws-authentication) +- [🔐 AWS authentication](#-aws-authentication) - [@aws-sdk/credential-providers is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication) - [Custom AWS credential provider takes highest precedence](#custom-aws-credential-provider-takes-highest-precedence) - [Explicitly provided credentials no longer accepted with MONGODB-AWS authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication) -- [⚙️ Error handling improvements](#️%EF%B8%8F-error-handling-improvements) +- [⚙️ Error handling improvements](#%EF%B8%8F-error-handling-improvements) - [Dropping a collection returns false instead of thowing when NS not found](#dropping-a-collection-returns-false-instead-of-throwing-when-ns-not-found) - [Aggregate with write concern and explain no longer throws client-side](#aggregate-with-write-concern-and-explain-no-longer-throws-client-side) - [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror) - ['PoolRequstedRetry' error label renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) -- [💥 Misc breaking improvements](#%EF%B8%8F-misc-breaking-improvements) +- [💥 Misc breaking improvements](#-misc-breaking-improvements) - [Change streams no longer whitelist $changeStream stage options](#change-streams-no-longer-whitelist-changestream-stage-options) - [Cursors no longer provide a default batchSize of 1000 for getMores](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) - [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts) -- [☀️ Misc non-breaking improvements](#️%EF%B8%8F-misc-non-breaking-improvements) +- [☀️ Misc non-breaking improvements](#%EF%B8%8F-misc-non-breaking-improvements) - [Improve `MongoClient.connect()` consistency across environments](#improve-mongoclientconnect-consistency-across-environments) - [MongoClient.close() no longer sends endSessions if the topology does not have session support](#mongoclientclose-no-longer-sends-endsessions-if-the-topology-does-not-have-session-support) -- [📜 Removal of deprecated functionality](#%EF%B8%8F-removal-of-deprecated-functionality) +- [📜 Removal of deprecated functionality](#-removal-of-deprecated-functionality) - [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform) - [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed) - [Internal ClientMetadata properties have been removed](#internal-clientmetadata-properties-have-been-removed) From 5ff6763f18d4023986fcfa32c42368b72af6d522 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Wed, 22 Oct 2025 20:44:20 -0400 Subject: [PATCH 06/11] docs: format closing section --- etc/notes/CHANGES_7.0.0.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index fd3171c521..16495f7091 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -37,6 +37,7 @@ The main focus of this release was usability improvements and a streamlined API. - [Internal ClientMetadata properties have been removed](#internal-clientmetadata-properties-have-been-removed) - [`CommandOptions.noResponse` option removed](#commandoptionsnoresponse-option-removed) - [Assorted deprecated type, class, and option removals](#assorted-deprecated-type-class-and-option-removals) +- [⚠️ ALL BREAKING CHANGES](#%EF%B8%8F-all-breaking-changes) ## 🛠️ Runtime and dependency updates @@ -240,12 +241,9 @@ CancellationToken; - **NODE-6988:** require aws sdk for aws auth ([#4659](https://github.com/mongodb/node-mongodb-native/issues/4659)) - **NODE-5545:** remove deprecated objects ([#4704](https://github.com/mongodb/node-mongodb-native/issues/4704)) ([cfbada6](https://github.com/mongodb/node-mongodb-native/commit/cfbada66ceb017bdb8fa1ff39257e1ab49ee9e25)) -### Features +### Non-breaking - **NODE-4243:** drop collection checks ns not found ([#4742](https://github.com/mongodb/node-mongodb-native/issues/4742)) ([a8d7c5f](https://github.com/mongodb/node-mongodb-native/commit/a8d7c5ff6c68ad57291641b2eb14cc27d91508ae)) - **NODE-7223:** run checkout on connect regardless of credentials ([#4715](https://github.com/mongodb/node-mongodb-native/issues/4715)) ([c5f74ab](https://github.com/mongodb/node-mongodb-native/commit/c5f74abe27acd8661f17046b1740ac74de1be082)) - **NODE-7260:** update bson alpha to latest ([#4748](https://github.com/mongodb/node-mongodb-native/issues/4748)) ([4e88559](https://github.com/mongodb/node-mongodb-native/commit/4e88559e8785973dc2124a54d5e850a00616bb16)) - -### Bug Fixes - - **NODE-7232:** only send endSessions during client close if the topology supports sessions ([#4722](https://github.com/mongodb/node-mongodb-native/issues/4722)) ([cc85ebf](https://github.com/mongodb/node-mongodb-native/commit/cc85ebf246b20e0bae59e1bdcdf0f9c74ea01979)) From 3c8664931233bb00af16cd96c2b574a4e3c9d4da Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Thu, 23 Oct 2025 10:01:45 -0400 Subject: [PATCH 07/11] docs: clean up to address comments --- etc/notes/CHANGES_7.0.0.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index 16495f7091..b3d531f80e 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -2,7 +2,7 @@ ## About -The following is a detailed collection of the changes in the major v6 release of the `mongodb` package for Node.js. +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] @@ -82,7 +82,7 @@ npm install @aws-sdk/credential-providers ### Custom AWS credential provider takes highest precedence -When 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, with the exception of URI parameters or credentials passed directly to the `MongoClient`. +When 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. ### Explicitly provided credentials no longer accepted with MONGODB-AWS authentication @@ -245,5 +245,4 @@ CancellationToken; - **NODE-4243:** drop collection checks ns not found ([#4742](https://github.com/mongodb/node-mongodb-native/issues/4742)) ([a8d7c5f](https://github.com/mongodb/node-mongodb-native/commit/a8d7c5ff6c68ad57291641b2eb14cc27d91508ae)) - **NODE-7223:** run checkout on connect regardless of credentials ([#4715](https://github.com/mongodb/node-mongodb-native/issues/4715)) ([c5f74ab](https://github.com/mongodb/node-mongodb-native/commit/c5f74abe27acd8661f17046b1740ac74de1be082)) -- **NODE-7260:** update bson alpha to latest ([#4748](https://github.com/mongodb/node-mongodb-native/issues/4748)) ([4e88559](https://github.com/mongodb/node-mongodb-native/commit/4e88559e8785973dc2124a54d5e850a00616bb16)) - **NODE-7232:** only send endSessions during client close if the topology supports sessions ([#4722](https://github.com/mongodb/node-mongodb-native/issues/4722)) ([cc85ebf](https://github.com/mongodb/node-mongodb-native/commit/cc85ebf246b20e0bae59e1bdcdf0f9c74ea01979)) From aa16decc95ebd877aa4cc72d1166e39db92c2e82 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Thu, 23 Oct 2025 10:19:36 -0400 Subject: [PATCH 08/11] docs: Alex's edits Co-authored-by: Alex Bevilacqua --- etc/notes/CHANGES_7.0.0.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index b3d531f80e..4b0c8fa848 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -16,7 +16,7 @@ The main focus of this release was usability improvements and a streamlined API. - [`bson` and `mongodb-connection-string-url` versions 7.0.0](#bson-and-mongodb-connection-string-url-versions-700) - [Optional peer dependency releases and version bumps](#optional-peer-dependency-releases-and-version-bumps) - [🔐 AWS authentication](#-aws-authentication) - - [@aws-sdk/credential-providers is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication) + - [`@aws-sdk/credential-providers` is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication) - [Custom AWS credential provider takes highest precedence](#custom-aws-credential-provider-takes-highest-precedence) - [Explicitly provided credentials no longer accepted with MONGODB-AWS authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication) - [⚙️ Error handling improvements](#%EF%B8%8F-error-handling-improvements) @@ -25,16 +25,16 @@ The main focus of this release was usability improvements and a streamlined API. - [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror) - ['PoolRequstedRetry' error label renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) - [💥 Misc breaking improvements](#-misc-breaking-improvements) - - [Change streams no longer whitelist $changeStream stage options](#change-streams-no-longer-whitelist-changestream-stage-options) - - [Cursors no longer provide a default batchSize of 1000 for getMores](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) + - [Change streams no longer whitelist `$changeStream` stage options](#change-streams-no-longer-whitelist-changestream-stage-options) + - [Cursors no longer provide a default `batchSize` of 1000 for `getMore`s](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) - [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts) - [☀️ Misc non-breaking improvements](#%EF%B8%8F-misc-non-breaking-improvements) - [Improve `MongoClient.connect()` consistency across environments](#improve-mongoclientconnect-consistency-across-environments) - - [MongoClient.close() no longer sends endSessions if the topology does not have session support](#mongoclientclose-no-longer-sends-endsessions-if-the-topology-does-not-have-session-support) + - [`MongoClient.close()` no longer sends `endSessions` if the topology does not have session support](#mongoclientclose-no-longer-sends-endsessions-if-the-topology-does-not-have-session-support) - [📜 Removal of deprecated functionality](#-removal-of-deprecated-functionality) - [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform) - [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed) - - [Internal ClientMetadata properties have been removed](#internal-clientmetadata-properties-have-been-removed) + - [Internal `ClientMetadata` properties have been removed](#internal-clientmetadata-properties-have-been-removed) - [`CommandOptions.noResponse` option removed](#commandoptionsnoresponse-option-removed) - [Assorted deprecated type, class, and option removals](#assorted-deprecated-type-class-and-option-removals) - [⚠️ ALL BREAKING CHANGES](#%EF%B8%8F-all-breaking-changes) @@ -43,7 +43,7 @@ The main focus of this release was usability improvements and a streamlined API. ### Minimum Node.js version is now v20.19.0 -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](https://nodejs.dev/en/about/releases/) to keep up with the latest security updates and modern language features. +The minimum supported Node.js version is now [v20.19.0](https://nodejs.org/en/blog/release/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](https://nodejs.dev/en/about/releases/) 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. @@ -72,7 +72,7 @@ Additionally, the driver is now compatible with the following packages: 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 authentication +### `@aws-sdk/credential-providers` is now required for MONGODB-AWS authentication Previous 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. @@ -95,7 +95,7 @@ import { MongoClient } from 'mongodb'; const client = new MongoClient('mongodb<+srv>://:/?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. ## ⚙️ Error handling improvements ### Dropping a collection returns false instead of throwing when NS not found @@ -118,19 +118,19 @@ The `PoolClearedError` thrown in cases where the connection pool was cleared now ## 💥 Misc breaking improvements -### Change streams no longer whitelist $changeStream stage options +### Change streams no longer whitelist `$changeStream` stage options -Uses are now able to pass any option to `collection.watch()` and if it is invalid in the $changeStream stage of the pipeline the server will error. This is to allow users to provide newly added options quickly that are not in our public types. +Uses are now able to pass any option to `collection.watch()` and if it is invalid in the `$changeStream` stage of the pipeline the server will error. This is to allow users to provide newly added options quickly that are not in our public types. -### Cursors no longer provide a default batchSize of 1000 for getMores +### Cursors no longer provide a default `batchSize` of 1000 for `getMore`s -In 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. +In driver versions <7.0, the driver provides a default `batchSize` of 1000 for each [`getMore`](https://www.mongodb.com/docs/manual/reference/command/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. +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. ### Auto encryption options now include default filenames in TS -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: +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: ```typescript var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'some path'; // ERROR @@ -149,9 +149,9 @@ var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_c ### Improve `MongoClient.connect()` consistency across environments -The 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. +The `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 support +### `MongoClient.close()` no longer sends `endSessions` if the topology does not have session support `MongoClient.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. @@ -175,7 +175,7 @@ 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. -### Internal ClientMetadata properties have been removed +### Internal `ClientMetadata` properties have been removed Previous versions of the driver unintentionally made properties used when constructing client metadata public. These properties have now been made internal. The full list of properties is: From aac995cb614ec88e103ac35c6c9ad85afc961b54 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Thu, 23 Oct 2025 18:15:45 -0400 Subject: [PATCH 09/11] docs: swap new and previous columns for dep table --- etc/notes/CHANGES_7.0.0.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index 4b0c8fa848..4336a2f78a 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -62,11 +62,11 @@ This driver version has been updated to use `bson@7.0.0` and `mongodb-connection Additionally, the driver is now compatible with the following packages: -| Dependency | Allowed Range | Previous Range | -| ----------------------------- | ------------- | -------------- | -| @aws-sdk/credential-providers | ^3.806.0 | ^3.188.0 | -| gcp-metadata | ^7.0.1 | ^5.2.0 | -| socks | ^2.8.6 | ^2.7.1 | +| 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 | ## 🔐 AWS authentication From 76669ebe61a62295383679c09c5b29026e3b34d7 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Thu, 23 Oct 2025 19:13:38 -0400 Subject: [PATCH 10/11] docs: revisions based on Bailey's review --- etc/notes/CHANGES_7.0.0.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index 4336a2f78a..0d8418c3df 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -25,7 +25,7 @@ The main focus of this release was usability improvements and a streamlined API. - [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror) - ['PoolRequstedRetry' error label renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry) - [💥 Misc breaking improvements](#-misc-breaking-improvements) - - [Change streams no longer whitelist `$changeStream` stage options](#change-streams-no-longer-whitelist-changestream-stage-options) + - [Change streams no longer filter `$changeStream` stage options](#change-streams-no-longer-filter-changestream-stage-options) - [Cursors no longer provide a default `batchSize` of 1000 for `getMore`s](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores) - [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts) - [☀️ Misc non-breaking improvements](#%EF%B8%8F-misc-non-breaking-improvements) @@ -34,7 +34,7 @@ The main focus of this release was usability improvements and a streamlined API. - [📜 Removal of deprecated functionality](#-removal-of-deprecated-functionality) - [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform) - [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed) - - [Internal `ClientMetadata` properties have been removed](#internal-clientmetadata-properties-have-been-removed) + - [Internal `ClientMetadata` properties have been removed from the public API](#internal-clientmetadata-properties-have-been-removed-from-the-public-api) - [`CommandOptions.noResponse` option removed](#commandoptionsnoresponse-option-removed) - [Assorted deprecated type, class, and option removals](#assorted-deprecated-type-class-and-option-removals) - [⚠️ ALL BREAKING CHANGES](#%EF%B8%8F-all-breaking-changes) @@ -86,7 +86,7 @@ When providing a custom AWS credential provider via the auth mechanism property ### Explicitly provided credentials no longer accepted with MONGODB-AWS authentication -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 installed required AWS SDK will now fetch credentials using the environment, endpoints, or a custom credential provider. +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: @@ -95,7 +95,9 @@ import { MongoClient } from 'mongodb'; const client = new MongoClient('mongodb<+srv>://:/?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. + ## ⚙️ Error handling improvements ### Dropping a collection returns false instead of throwing when NS not found @@ -118,9 +120,9 @@ The `PoolClearedError` thrown in cases where the connection pool was cleared now ## 💥 Misc breaking improvements -### Change streams no longer whitelist `$changeStream` stage options +### Change streams no longer filter `$changeStream` stage options -Uses are now able to pass any option to `collection.watch()` and if it is invalid in the `$changeStream` stage of the pipeline the server will error. This is to allow users to provide newly added options quickly that are not in our public types. +Users 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. ### Cursors no longer provide a default `batchSize` of 1000 for `getMore`s @@ -175,9 +177,9 @@ 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. -### Internal `ClientMetadata` properties have been removed +### Internal `ClientMetadata` properties have been removed from the public API -Previous versions of the driver unintentionally made properties used when constructing client metadata public. These properties have now been made internal. The full list of properties is: +Previous versions of the driver unintentionally exposed the following properties that have now been made internal: ``` MongoClient.options.additionalDriverInfo From 35e0ea9f471357f3e2635284b12f62b3c0ad0242 Mon Sep 17 00:00:00 2001 From: Daria Pardue Date: Tue, 4 Nov 2025 11:05:05 -0500 Subject: [PATCH 11/11] pull in fixes into v7 guide --- etc/notes/CHANGES_7.0.0.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/etc/notes/CHANGES_7.0.0.md b/etc/notes/CHANGES_7.0.0.md index 0d8418c3df..71395d6449 100644 --- a/etc/notes/CHANGES_7.0.0.md +++ b/etc/notes/CHANGES_7.0.0.md @@ -31,6 +31,8 @@ The main focus of this release was usability improvements and a streamlined API. - [☀️ Misc non-breaking improvements](#%EF%B8%8F-misc-non-breaking-improvements) - [Improve `MongoClient.connect()` consistency across environments](#improve-mongoclientconnect-consistency-across-environments) - [`MongoClient.close()` no longer sends `endSessions` if the topology does not have session support](#mongoclientclose-no-longer-sends-endsessions-if-the-topology-does-not-have-session-support) + - [Wrap socket write in a try/catch to ensure errors can be properly wrapped](#wrap-socket-write-in-a-trycatch-to-ensure-errors-can-be-properly-wrapped) + - [`ClientEncryption.rewrapManyDataKey()` options now correctly marked as optional](#clientEncryptionrewrapManyDataKey-options-now-correctly-marked-as-optional) - [📜 Removal of deprecated functionality](#-removal-of-deprecated-functionality) - [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform) - [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed) @@ -159,6 +161,14 @@ The `MongoClient` connect function will now run a handshake regardless of creden Now, `MongoClient.close()` only attempts to clean up sessions if the topology supports sessions. +### Wrap socket write in a try/catch to ensure errors can be properly wrapped + +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 optional + +The 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. + ## 📜 Removal of deprecated functionality ### Cursor and ChangeStream `stream()` method no longer accepts a transform @@ -248,3 +258,5 @@ CancellationToken; - **NODE-4243:** drop collection checks ns not found ([#4742](https://github.com/mongodb/node-mongodb-native/issues/4742)) ([a8d7c5f](https://github.com/mongodb/node-mongodb-native/commit/a8d7c5ff6c68ad57291641b2eb14cc27d91508ae)) - **NODE-7223:** run checkout on connect regardless of credentials ([#4715](https://github.com/mongodb/node-mongodb-native/issues/4715)) ([c5f74ab](https://github.com/mongodb/node-mongodb-native/commit/c5f74abe27acd8661f17046b1740ac74de1be082)) - **NODE-7232:** only send endSessions during client close if the topology supports sessions ([#4722](https://github.com/mongodb/node-mongodb-native/issues/4722)) ([cc85ebf](https://github.com/mongodb/node-mongodb-native/commit/cc85ebf246b20e0bae59e1bdcdf0f9c74ea01979)) +- **NODE-7067:** Wrap socket write in a try/catch to ensure errors can be properly wrapped ([#4759](https://github.com/mongodb/node-mongodb-native/issues/4759)) ([66c18b7](https://github.com/mongodb/node-mongodb-native/commit/66c18b7ee948e43847b324b25b552c2ff9ca851c)) +- **NODE-7247:** clarify #rewrapManyDataKey() parameter types ([#4760](https://github.com/mongodb/node-mongodb-native/issues/4760)) ([cb522bf](https://github.com/mongodb/node-mongodb-native/commit/cb522bfd0c45086a821e4918c0f1af33c68cfa7a))