|
| 1 | +# Migrating from 7.x to 8.x |
| 2 | + |
| 3 | +<style> |
| 4 | + ul > li { |
| 5 | + padding: 4px 0px; |
| 6 | + } |
| 7 | +</style> |
| 8 | + |
| 9 | +There are several backwards-breaking changes |
| 10 | +you should be aware of when migrating from Mongoose 7.x to Mongoose 8.x. |
| 11 | + |
| 12 | +If you're still on Mongoose 6.x or earlier, please read the [Mongoose 6.x to 7.x migration guide](migrating_to_7.html) and upgrade to Mongoose 7.x first before upgrading to Mongoose 8. |
| 13 | + |
| 14 | +* [Removed `rawResult` option for `findOneAndUpdate()`](#removed-rawresult-option-for-findoneandupdate) |
| 15 | +* [Changed behavior for `findOneAndUpdate()` with `orFail()` and upsert](#changed-behavior-for-findoneandupdate-with-orfail-and-upsert) |
| 16 | +* [MongoDB Node Driver 6.0](#mongodb-node-driver-6) |
| 17 | +* [Removed `findOneAndRemove()`](#removed-findoneandremove) |
| 18 | +* [Removed id Setter](#removed-id-setter) |
| 19 | + |
| 20 | +<h2 id="removed-rawresult-option-for-findoneandupdate"><a href="#removed-rawresult-option-for-findoneandupdate">Removed <code>rawResult</code> option for <code>findOneAndUpdate()</code></a></h2> |
| 21 | + |
| 22 | +The `rawResult` option for `findOneAndUpdate()`, `findOneAndReplace()`, and `findOneAndDelete()` has been replaced by the `includeResultMetadata` option. |
| 23 | + |
| 24 | +```javascript |
| 25 | +const filter = { name: 'Will Riker' }; |
| 26 | +const update = { age: 29 }; |
| 27 | + |
| 28 | +const res = await Character.findOneAndUpdate(filter, update, { |
| 29 | + new: true, |
| 30 | + upsert: true, |
| 31 | + // Replace `rawResult: true` with `includeResultMetadata: true` |
| 32 | + includeResultMetadata: true |
| 33 | +}); |
| 34 | +``` |
| 35 | + |
| 36 | +`includeResultMetadata` in Mongoose 8 behaves identically to `rawResult`. |
| 37 | + |
| 38 | +<h2 id="changed-behavior-for-findoneandupdate-with-orfail-and-upsert"><a href="#changed-behavior-for-findoneandupdate-with-orfail-and-upsert">Changed behavior for <code>findOneAndUpdate()</code> with <code>orFail()</code> and upsert</a></h2> |
| 39 | + |
| 40 | +In Mongoose 7, `findOneAndUpdate(filter, update, { upsert: true }).orFail()` would throw a `DocumentNotFoundError` if a new document was upserted. |
| 41 | +In other words, `findOneAndUpdate().orFail()` always threw an error if no document was found, even if a new document was upserted. |
| 42 | + |
| 43 | +In Mongoose 8, `findOneAndUpdate(filter, update, { upsert: true }).orFail()` always succeeds. |
| 44 | +`findOneAndUpdate().orFail()` now throws a `DocumentNotFoundError` if there's no document returned, rather than if no document was found. |
| 45 | + |
| 46 | +<h2 id="mongodb-node-driver-6"><a href="#mongodb-node-driver-6">MongoDB Node Driver 6</a></h2> |
| 47 | + |
| 48 | +Mongoose 8 uses [v6.x of the MongoDB Node driver](https://github.com/mongodb/node-mongodb-native/blob/main/HISTORY.md#600-2023-08-28). |
| 49 | +There's a few noteable changes in MongoDB Node driver v6 that affect Mongoose: |
| 50 | + |
| 51 | +1. The `ObjectId` constructor no longer accepts strings of length 12. In Mongoose 7, `new mongoose.Types.ObjectId('12charstring')` was perfectly valid. In Mongoose 8, `new mongoose.Types.ObjectId('12charstring')` throws an error. |
| 52 | + |
| 53 | +<h2 id="removed-findoneandremove"><a href="#removed-findoneandremove">Removed <code>findOneAndRemove()</code></a></h2> |
| 54 | + |
| 55 | +In Mongoose 7, `findOneAndRemove()` was an alias for `findOneAndDelete()` that Mongoose supported for backwards compatibility. |
| 56 | +Mongoose 8 no longer supports `findOneAndRemove()`. |
| 57 | +Use `findOneAndDelete()` instead. |
| 58 | + |
| 59 | +<h2 id="removed-id-setter"><a href="#removed-id-setter">Removed id Setter</a></h2> |
| 60 | + |
| 61 | +In Mongoose 7.4, Mongoose introduced an `id` setter that made `doc.id = '0'.repeat(24)` equivalent to `doc._id = '0'.repeat(24)`. |
| 62 | +In Mongoose 8, that setter is now removed. |
0 commit comments