Skip to content

Commit 131341f

Browse files
nbbeekennbbeeken
committed
wip
1 parent fe71106 commit 131341f

File tree

1 file changed

+210
-3
lines changed

1 file changed

+210
-3
lines changed

‎docs/CHANGES_4.0.0.md‎

Lines changed: 210 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,41 @@
11
# Changes in 4.x
22

3-
WIP
3+
_Hello dear reader, **thank you** for adopting version 4.x of the mongodb driver, from the bottom of our developer hearts we thank you so much for taking the time to upgrade to our latest and greatest offering of a stunning database experience.
4+
We hope you enjoy your upgrade experience and this guide gives you all the answers you are searching for.
5+
If anything, and we mean anything, hinders you upgrade experience please let us know via [JIRA](https://jira.mongodb.org/browse/NODE).
6+
We know breaking changes are hard but they are sometimes for the best.
7+
Anyway, enjoy the guide, see you at the end!_
8+
9+
## Removed deprecations
10+
11+
- `Collection.prototype.find / findOne options:`
12+
- `fields` - use `projection` instead
13+
- `Collection.prototype.save` - use `insertOne` instead
14+
- `Collection.prototype.dropAllIndexes`
15+
- `Collection.prototype.ensureIndex`
16+
- `Collection.prototype.findAndModify` - use `findOneAndUpdate`/`findOneAndReplace`
17+
- `Collection.prototype.findAndRemove` - use `findOneAndDelete` instead
18+
- `Collection.prototype.parallelCollectionScan`
19+
- `MongoError.create`
20+
- `Topology.destroy`
21+
- `Cursor.prototype.each` - `forEach`
22+
- `Db.prototype.eval`
23+
- `Db.prototype.ensureIndex`
24+
- `Db.prototype.profilingInfo`
25+
- `MongoClient.prototype.logout`
26+
- `MongoClient.prototype.addUser: Creating a user without roles`
27+
- `MongoClient.prototype.connect`
28+
- `Remove MongoClient.isConnected` - calling connect is a no-op if already connected
29+
- `Remove MongoClient.logOut`
430

531
## Versioned API
632

7-
Versioned API is a new feature in MongoDB 5.0 that allows user-selectable API versions, subsets of MongoDB server semantics, to be declared on a client. During communication with a server, clients with a declared API version will force the server to behave in a manner compatible with the API version. Declaring an API version on a client can be used to ensure consistent responses from a server, providing long term API stability for an application. The declared API version is applied to all commands run through the client, including those sent through the generic RunCommand helper. Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to undefined behaviour.
33+
Versioned API is a new feature in MongoDB 5.0 that allows user-selectable API versions, subsets of MongoDB server semantics, to be declared on a client.
34+
During communication with a server, clients with a declared API version will force the server to behave in a manner compatible with the API version.
35+
Declaring an API version on a client can be used to ensure consistent responses from a server, providing long term API stability for an application. The declared API version is applied to all commands run through the client, including those sent through the generic RunCommand helper.
36+
Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to undefined behavior.
837

9-
### Declare an API version on a client:
38+
### Declare an API version on a client
1039

1140
```javascript
1241
// Declare API version "1" for the client
@@ -37,3 +66,181 @@ client = new MongoClient(uri, { serverApi: { version: '1', deprecationErrors: tr
3766

3867
// Note: since API version "1" is the initial version, there are no deprecated commands to provide as an example yet.
3968
```
69+
70+
### Typescript
71+
72+
We've migrated the driver to Typescript! Users can now harness the power of type hinting and intellisense in editors that support it to develop their MongoDB applications. Users don't even have to adopt Typescript to get the benefits. Along with the type hinting there's consistent docs formatting that editors should be able to display while developing.
73+
Recently we migrated our BSON library to TypeScript as well, this version of the driver pulls in those changes.
74+
75+
#### Community Types users (@types/mongodb)
76+
77+
If you are a user of the community types (@types/mongodb) there will likely be issues adopting the types from our codebase. Unfortunately we could not achieve a one to one match in types due to the details of writing the codebase in Typescript vs definitions for the user layer API.
78+
79+
## Key Changes
80+
81+
### NodeJS Version
82+
83+
We now require node 12.9 or greater for version 4 of the driver.
84+
If that's outside your support matrix at this time, that's okay!
85+
Bug fix support for our 3.x branch will not be ending until summer 2022!
86+
87+
### Cursor changes
88+
89+
#### AbstractCursor, FindCursor, AggregationCursor, ChangeStreamCursor, ListCollectionsCursor
90+
91+
Our Cursor implementation has been updated to make more clear what is possible before and after execution of an operation. Take this example:
92+
93+
```javascript
94+
const cursor = collection.find({ a: 2.3 }).skip(1)
95+
for await (const doc of cursor) {
96+
console.log(doc);
97+
fc.limit(1) // bad.
98+
}
99+
```
100+
101+
Prior to the this release there was inconsistency surrounding how the cursor would error if a setting like limit was applied after cursor execution had begun, that is now more clear since something like this throws: `Cursor is already initialized`
102+
103+
#### Stream API
104+
105+
The Cursor no longer extends Readable directly, it must be transformed into a stream by calling cursor.stream(), for example:
106+
107+
```javascript
108+
const cursor = collection.find({});
109+
const stream = cursor.stream()
110+
stream.on("data", data => console.log(data));
111+
stream.on("end", () => client.close());
112+
```
113+
114+
### MongoClientOptions interface
115+
116+
With type hinting users should find that the options passed to a MongoClient are completely enumerated and easily discoverable. We have made a big effort to process all options up front to give early warnings about incompatible settings to get your app up and running correctly quicker!
117+
118+
#### Check Server Identity Inconsistency
119+
120+
Specifying `checkServerIdentity === false` is different from it being leaving it `undefined`.
121+
3.x intercepted `checkServerIdentity: false` and turned it into a no-op function which is the required way to skip checking the server identity by nodejs. This option is only for testing anyway and it didn't make sense for our library to intercept an option that is exposed directly from nodejs.
122+
123+
### db.collection
124+
125+
No longer supports a strict option which would return an error if the collection does not exist. If you require your application to assert a collection's existence, please use:
126+
127+
```javascript
128+
const collections = (await db.listCollections({}, { nameOnly: true }).toArray())
129+
.map(({name}) => name); // map to get string[]
130+
if (!collections.includes(myNewCollectionName)) {
131+
await db.createCollection(myNewCollectionName)
132+
}
133+
```
134+
135+
### BulkWriteError renamed to MongoBulkWriteError
136+
137+
When running a bulk operation that makes writes, depending on your settings, you can encounter write errors. User's testing for `BulkWriteErrors` should be sure to import the new class name `MongoBulkWriteError`.
138+
139+
### Db no longer emits events
140+
141+
The Db instance is no longer an EventEmitter, all events your application is concerned with can be listened to directly from the MongoClient instance.
142+
143+
### Collection.group() removed
144+
145+
the collection group helper has been deprecated in MongoDB since 3.4 and is now removed from the Driver. The same functionality can be achieved using the aggregation pipeline's $group operator.
146+
147+
### Authentication
148+
149+
Specifying username and password as options are supported in only these two formats:
150+
151+
- `new MongoClient(url, { auth: { username: '', password: '' } })`
152+
- `new MongoClient('mongodb://username:[email protected]')`
153+
154+
#### Kerberos / GSSAPI
155+
156+
`gssapiServiceName` has been removed.
157+
Users should use authMechanismProperties.SERVICE_NAME like so:
158+
159+
- In a URI query param: `?authMechanismProperties=SERVICE_NAME:alternateServiceName`
160+
- Or as an option: `{ authMechanismProperties: { SERVICE_NAME: 'alternateServiceName' } }`
161+
162+
### GridStore has been removed
163+
164+
The deprecated GirdStore API has been removed from the driver. You can find migration details here
165+
166+
Equivalencies:
167+
168+
```javascript
169+
// old way
170+
const gs = new GridStore(db, filename, mode[, options])
171+
// new way
172+
const bucket = new GridFSBucket(client.db('test')[, options])
173+
```
174+
175+
Since GridFSBucket uses NodeJS Stream API you can replicate file seek-ing by using the start and end options creating a downloadStream from your GridFSBucket
176+
177+
```javascript
178+
bucket.openDownloadStreamByName(filename, { start: 23, end: 52 })
179+
```
180+
181+
#### Upload / Download example
182+
183+
``` javascript
184+
await client.connect();
185+
const filename = 'test.txt' // whatever local file name you want
186+
const db = client.db()
187+
const bucket = new GridFSBucket(db)
188+
189+
fs.createReadStream(filename)
190+
.pipe(bucket.openUploadStream(filename))
191+
.on('error', console.error)
192+
.on('finish', () => {
193+
console.log('done writing to db!')
194+
195+
bucket.find().toArray().then((files) => {
196+
console.log(files)
197+
198+
bucket.openDownloadStreamByName(filename)
199+
.pipe(fs.createWriteStream('downloaded_' + filename))
200+
.on('error', console.error)
201+
.on('finish', () => {
202+
console.log('done downloading!')
203+
client.close()
204+
})
205+
})
206+
})
207+
```
208+
209+
GridFSBucket does not need to be closed like GridStore
210+
211+
Deleting files hasn't changed much:
212+
213+
```javascript
214+
GridStore.unlink(db, name, callback)
215+
bucket.delete(file_id)
216+
```
217+
218+
File metadata that used to be accessible on the GridStore instance can be found by querying the bucket
219+
220+
```javascript
221+
bucket.find(filter).toArray()
222+
[{
223+
_id: ObjectId,
224+
length: number,
225+
chunkSize: number,
226+
uploadDate: Date,
227+
filename: string,
228+
md5: Binary
229+
}]
230+
```
231+
232+
For more information on GridFS [see the docs](https://docs.mongodb.com/manual/core/gridfs/).
233+
234+
### Unified Topology Only
235+
236+
We internally now only manage a unifiedTopology when you connect to your MongoDB. The [differences are described in detail here](https://mongodb.github.io/node-mongodb-native/3.6/reference/unified-topology/).
237+
238+
**NOTE:** With the unified topology, in order to connect to replicaSet nodes that have not been initialized you must use the new `directConnection` option.
239+
240+
### Instrument function removal
241+
242+
TODO
243+
244+
---
245+
246+
_And that's a wrap, thanks for upgrading! You've been a great audience!_

0 commit comments

Comments
 (0)