Skip to content

Commit 638da2c

Browse files
dariakpdariakp
committed
docs: create v7 migration guide
1 parent 05f329e commit 638da2c

1 file changed

Lines changed: 249 additions & 0 deletions

File tree

‎etc/notes/CHANGES_7.0.0.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Changes in the MongoDB Node.js Driver v7
2+
3+
## About
4+
5+
The following is a detailed collection of the changes in the major v6 release of the `mongodb` package for Node.js.
6+
The main focus of this release was usability improvements and a streamlined API. Read on for details!
7+
8+
> [!IMPORTANT]
9+
> This is a list of changes relative to v6.21.0 of the driver. ALL changes listed below are BREAKING unless indicated otherwise.
10+
> Users migrating from an older version of the driver are advised to upgrade to at least v6.21.0 before adopting v7.
11+
12+
## Contents
13+
14+
- [🛠️ Runtime and dependency updates](#️%EF%B8%8F-runtime-and-dependency-updates)
15+
- [Minimum Node.js version is now v20.19.0](#minimum-nodejs-version-is-now-v20190)
16+
- [`bson` and `mongodb-connection-string-url` versions 7.0.0](#bson-and-mongodb-connection-string-url-versions-700)
17+
- [Optional peer dependency releases and version bumps](#optional-peer-dependency-releases-and-version-bumps)
18+
- [🔐 AWS authentication](#%EF%B8%8F-aws-authentication)
19+
- [@aws-sdk/credential-providers is now required for MONGODB-AWS authentication](#aws-sdkcredential-providers-is-now-required-for-mongodb-aws-authentication)
20+
- [Custom AWS Credential Provider Takes Highest Precedence](#custom-aws-credential-provider-takes-highest-precedence)
21+
- [Explicitly Provided Credentials No Longer Accepted With MONGODB-AWS Authentication](#explicitly-provided-credentials-no-longer-accepted-with-mongodb-aws-authentication)
22+
- [⚙️ Error handling improvements](#️%EF%B8%8F-error-handling-improvements)
23+
- [Dropping a Collection No Longer Throws When NS not Found](#dropping-a-collection-no-longer-throws-when-ns-not-found)
24+
- [Aggregate with write concern + explain no longer throws client-side](#aggregate-with-write-concern--explain-no-longer-throws-client-side)
25+
- [All encryption-related errors now subclass MongoError](#all-encryption-related-errors-now-subclass-mongoerror)
26+
- ['PoolRequstedRetry' Error Label Renamed to 'PoolRequestedRetry'](#poolrequstedretry-error-label-renamed-to-poolrequestedretry)
27+
- [💥 Misc breaking improvements](#%EF%B8%8F-misc-breaking-improvements)
28+
- [Change Streams No Longer Whitelist $changeStream Stage Options](#change-streams-no-longer-whitelist-changestream-stage-options)
29+
- [Cursors no longer provide a default batchSize of 1000 for getMores](#cursors-no-longer-provide-a-default-batchsize-of-1000-for-getmores)
30+
- [Auto encryption options now include default filenames in TS](#auto-encryption-options-now-include-default-filenames-in-ts)
31+
- [☀️ Misc non-breaking improvements](#️%EF%B8%8F-misc-non-breaking-improvements)
32+
- [Improve `MongoClient.connect()` consistency across environments](#improve-mongoclientconnect-consistency-across-environments)
33+
- [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)
34+
- [📜 Removal of deprecated functionality](#%EF%B8%8F-removal-of-deprecated-functionality)
35+
- [Cursor and ChangeStream `stream()` method no longer accepts a transform](#cursor-and-changestream-stream-method-no-longer-accepts-a-transform)
36+
- [MONGODB-CR AuthMechanism has been removed](#mongodb-cr-authmechanism-has-been-removed)
37+
- [Internal ClientMetadata properties have been removed](#internal-clientmetadata-properties-have-been-removed)
38+
- [`CommandOptions.noResponse` option removed](#commandoptionsnoresponse-option-removed)
39+
- [Assorted deprecated type, class, and option removals](#assorted-deprecated-type-class-and-option-removals)
40+
41+
## 🛠️ Runtime and dependency updates
42+
43+
### Minimum Node.js version is now v20.19.0
44+
45+
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.
46+
47+
Notably, the driver now offers native support for explicit resource management. `Symbol.asyncDispose` implementations are available on the `MongoClient`, `ClientSession`, `ChangeStream` and on cursors.
48+
49+
> [!Note]
50+
> 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.
51+
52+
### `bson` and `mongodb-connection-string-url` versions 7.0.0
53+
54+
This driver version has been updated to use `[email protected]` and `[email protected]`, 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).
55+
56+
### Optional peer dependency releases and version bumps
57+
58+
- `@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)
59+
- `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)
60+
- `mongodb-client-encryption` optional peer dependency minimum version raised to `7.0.0`, dropped support for `6.x`
61+
62+
Additionally, the driver is now compatible with the following packages:
63+
64+
| Dependency | Allowed Range | Previous Range |
65+
| ----------------------------- | ------------- | -------------- |
66+
| @aws-sdk/credential-providers | ^3.806.0 | ^3.188.0 |
67+
| gcp-metadata | ^7.0.1 | ^5.2.0 |
68+
| socks | ^2.8.6 | ^2.7.1 |
69+
70+
## 🔐 AWS authentication
71+
72+
### @aws-sdk/credential-providers is now required for MONGODB-AWS authentication
73+
74+
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.
75+
76+
```bash
77+
npm install @aws-sdk/credential-providers
78+
```
79+
80+
### Custom AWS credential provider takes highest precedence
81+
82+
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`.
83+
84+
### Explicitly provided credentials no longer accepted with MONGODB-AWS authentication
85+
86+
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.
87+
88+
This means that for AWS authentication, all client URIs MUST now be specified as:
89+
90+
```ts
91+
import { MongoClient } from 'mongodb';
92+
93+
const client = new MongoClient('mongodb<+srv>://<host>:<port>/?authMechanism=MONGODB-AWS');
94+
```
95+
96+
## ⚙️ Error handling improvements
97+
98+
### Dropping a collection no longer throws when NS not found
99+
100+
This will now return `false` instead.
101+
102+
### Aggregate with write concern + explain no longer throws client-side
103+
104+
This will now throw a `MongoServerError` instead.
105+
106+
### All encryption-related errors now subclass MongoError
107+
108+
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`.
109+
110+
Now, all errors thrown during encryption are subclasses of `MongoError`.
111+
112+
### 'PoolRequstedRetry' error label renamed to 'PoolRequestedRetry'
113+
114+
The `PoolClearedError` thrown in cases where the connection pool was cleared now fixes the typo in the error label.
115+
116+
## 💥 Misc breaking improvements
117+
118+
### Change streams no longer whitelist $changeStream stage options
119+
120+
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.
121+
122+
### Cursors no longer provide a default batchSize of 1000 for getMores
123+
124+
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.
125+
126+
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.
127+
128+
### Auto encryption options now include default filenames in TS
129+
130+
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:
131+
132+
```typescript
133+
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'some path'; // ERROR
134+
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'mongocryptd'; // OK
135+
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] =
136+
'/usr/local/bin/mongocryptd'; // OK
137+
var path: AutoEncryptionOptions['extraOptions']['mongocryptdSpawnPath'] = 'mongocryptd.exe'; // OK
138+
139+
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'some path'; // ERROR
140+
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.so'; // OK
141+
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.dll'; // OK
142+
var path: AutoEncryptionOptions['extraOptions']['cryptSharedLibPath'] = 'mongo_crypt_v1.dlyib'; // OK
143+
```
144+
145+
## ☀️ Misc non-breaking improvements
146+
147+
### Improve `MongoClient.connect()` consistency across environments
148+
149+
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.
150+
151+
### MongoClient.close() no longer sends endSessions if the topology does not have session support
152+
153+
`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.
154+
155+
Now, `MongoClient.close()` only attempts to clean up sessions if the topology supports sessions.
156+
157+
## 📜 Removal of deprecated functionality
158+
159+
### Cursor and ChangeStream `stream()` method no longer accepts a transform
160+
161+
Cursors and ChangeStreams no longer accept a `transform` function. `ReadableStream.map()` can be used instead:
162+
163+
```typescript
164+
// before
165+
const stream = cursor.stream({ transform: JSON.stringify });
166+
167+
// after
168+
const stream = cursor.stream().map(JSON.stringify);
169+
```
170+
171+
### MONGODB-CR AuthMechanism has been removed
172+
173+
This mechanism has been unsupported as of MongoDB 4.0 and attempting to use it will still raise an error.
174+
175+
### Internal ClientMetadata properties have been removed
176+
177+
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:
178+
179+
```
180+
MongoClient.options.additionalDriverInfo
181+
MongoClient.options.metadata
182+
MongoClient.options.extendedMetadata
183+
MongoOptions.additionalDriverInfo
184+
MongoOptions.metadata
185+
MongoOptions.extendedMetadata
186+
ConnectionOptions.metadata
187+
ConnectionOptions.extendedMetadata
188+
```
189+
190+
### `CommandOptions.noResponse` option removed
191+
192+
This option was never intended to be public, and never worked properly for user-facing APIs. It has now been removed.
193+
194+
### Assorted deprecated type, class, and option removals
195+
196+
```ts
197+
GridFSFile.contentType;
198+
GridFSFile.aliases;
199+
GridFSBucketWriteStreamOptions.contentType;
200+
GridFSBucketWriteStreamOptions.aliases;
201+
CloseOptions;
202+
ResumeOptions;
203+
MongoClientOptions.useNewUrlParser;
204+
MongoClientOptions.useUnifiedTopology;
205+
CreateCollectionOptions.autoIndexId;
206+
FindOptions<TSchema>; // now no generic type
207+
ClientMetadataOptions;
208+
FindOneOptions.batchSize;
209+
FindOneOptions.limit;
210+
FindOneOptions.noCursorTimeout;
211+
ReadPreference.minWireVersion;
212+
ServerCapabilities;
213+
CommandOperationOptions.retryWrites; // is a global option on the MongoClient
214+
ClientSession.transaction;
215+
Transaction;
216+
CancellationToken;
217+
```
218+
219+
## ⚠️ ALL BREAKING CHANGES
220+
221+
- **NODE-7259:** use alphas of all supporting packages ([#4746](https://github.com/mongodb/node-mongodb-native/issues/4746))
222+
- **NODE-5510:** dont filter change stream options ([#4723](https://github.com/mongodb/node-mongodb-native/issues/4723))
223+
- **NODE-6296:** remove cursor default batch size of 1000 ([#4729](https://github.com/mongodb/node-mongodb-native/issues/4729))
224+
- **NODE-7150:** update peer dependency matrix for 3rd party peer deps ([#4720](https://github.com/mongodb/node-mongodb-native/issues/4720))
225+
- **NODE-7046:** remove AWS uri/options support ([#4689](https://github.com/mongodb/node-mongodb-native/issues/4689))
226+
- **NODE-4808:** remove support for stream() transform on cursors and change streams ([#4728](https://github.com/mongodb/node-mongodb-native/issues/4728))
227+
- **NODE-6377:** remove noResponse option ([#4724](https://github.com/mongodb/node-mongodb-native/issues/4724))
228+
- **NODE-6473:** remove MONGODB-CR auth ([#4717](https://github.com/mongodb/node-mongodb-native/issues/4717))
229+
- **NODE-5994:** Remove metadata-related properties from public driver API ([#4716](https://github.com/mongodb/node-mongodb-native/issues/4716))
230+
- **NODE-7016:** remove `beta` namespace and move resource management into driver ([#4719](https://github.com/mongodb/node-mongodb-native/issues/4719))
231+
- **NODE-4184:** don't throw on aggregate with write concern and explain ([#4718](https://github.com/mongodb/node-mongodb-native/issues/4718))
232+
- **NODE-7043, NODE-7217:** adopt mongodb-client-encryption v7 ([#4705](https://github.com/mongodb/node-mongodb-native/issues/4705))
233+
- **NODE-6065:** throw MongoRuntimeError instead of MissingDependencyError in crypto connection ([#4711](https://github.com/mongodb/node-mongodb-native/issues/4711))
234+
- **NODE-6584:** improve typing for filepaths in AutoEncryptionOptions ([#4341](https://github.com/mongodb/node-mongodb-native/issues/4341))
235+
- **NODE-6334:** rename PoolRequstedRetry to PoolRequestedRetry ([#4696](https://github.com/mongodb/node-mongodb-native/issues/4696))
236+
- **NODE-7174:** drop support for Node16 and Node18 ([#4668](https://github.com/mongodb/node-mongodb-native/issues/4668))
237+
- **NODE-7047:** use custom credential provider first after URI ([#4656](https://github.com/mongodb/node-mongodb-native/issues/4656))
238+
- **NODE-6988:** require aws sdk for aws auth ([#4659](https://github.com/mongodb/node-mongodb-native/issues/4659))
239+
- **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))
240+
241+
### Features
242+
243+
- **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))
244+
- **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))
245+
- **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))
246+
247+
### Bug Fixes
248+
249+
- **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))

0 commit comments

Comments
 (0)