Deprecation Warnings

Sponsor #native_company# — #native_desc#

There are several deprecations in the MongoDB Node.js driver that Mongoose users should be aware of. Mongoose provides options to work around these deprecation warnings, but you need to test whether these options cause any problems for your application. Please report any issues on GitHub.

Summary

To fix all deprecation warnings, follow the below steps:

  • mongoose.set('useNewUrlParser', true);
  • mongoose.set('useFindAndModify', false);
  • mongoose.set('useCreateIndex', true);
  • mongoose.set('useUnifiedTopology', true);
  • Replace update() with updateOne(), updateMany(), or replaceOne()
  • Replace remove() with deleteOne() or deleteMany().
  • Replace count() with countDocuments(), unless you want to count how many documents are in the whole collection (no filter). In the latter case, use estimatedDocumentCount().

Read below for more a more detailed description of each deprecation warning.

The useNewUrlParser Option

By default, mongoose.connect() will print out the below warning:

  1. DeprecationWarning: current URL string parser is deprecated, and will be
  2. removed in a future version. To use the new parser, pass option
  3. { useNewUrlParser: true } to MongoClient.connect.

The MongoDB Node.js driver rewrote the tool it uses to parse MongoDB connection strings. Because this is such a big change, they put the new connection string parser behind a flag. To turn on this option, pass the useNewUrlParser option to mongoose.connect() or mongoose.createConnection().

  1. mongoose.connect(uri, { useNewUrlParser: true });
  2. mongoose.createConnection(uri, { useNewUrlParser: true });

You can also set the global useNewUrlParser option to turn on useNewUrlParser for every connection by default.

  1. // Optional. Use this if you create a lot of connections and don't want
  2. // to copy/paste `{ useNewUrlParser: true }`.
  3. mongoose.set('useNewUrlParser', true);

To test your app with { useNewUrlParser: true }, you only need to check whether your app successfully connects. Once Mongoose has successfully connected, the URL parser is no longer important. If you can’t connect with { useNewUrlParser: true }, please open an issue on GitHub.

findAndModify()

If you use Model.findOneAndUpdate(), by default you’ll see one of the below deprecation warnings.

  1. DeprecationWarning: Mongoose: `findOneAndUpdate()` and `findOneAndDelete()` without the `useFindAndModify` option set to false are deprecated. See: https://mongoosejs.com/docs/deprecations.html#findandmodify
  2. DeprecationWarning: collection.findAndModify is deprecated. Use findOneAndUpdate, findOneAndReplace or findOneAndDelete instead.

Mongoose’s findOneAndUpdate() long pre-dates the MongoDB driver’s findOneAndUpdate() function, so it uses the MongoDB driver’s findAndModify() function instead. You can opt in to using the MongoDB driver’s findOneAndUpdate() function using the useFindAndModify global option.

  1. // Make Mongoose use `findOneAndUpdate()`. Note that this option is `true`
  2. // by default, you need to set it to false.
  3. mongoose.set('useFindAndModify', false);

You can also configure useFindAndModify by passing it through the connection options.

  1. mongoose.connect(uri, { useFindAndModify: false });

This option affects the following model and query functions. There are no intentional backwards breaking changes, so you should be able to turn this option on without any code changes. If you discover any issues, please open an issue on GitHub.

ensureIndex()

If you define indexes in your Mongoose schemas, you’ll see the below deprecation warning.

  1. DeprecationWarning: collection.ensureIndex is deprecated. Use createIndexes
  2. instead.

By default, Mongoose 5.x calls the MongoDB driver’s ensureIndex() function. The MongoDB driver deprecated this function in favor of createIndex(). Set the useCreateIndex global option to opt in to making Mongoose use createIndex() instead.

  1. mongoose.set('useCreateIndex', true);

You can also configure useCreateIndex by passing it through the connection options.

  1. mongoose.connect(uri, { useCreateIndex: true });

There are no intentional backwards breaking changes with the useCreateIndex option, so you should be able to turn this option on without any code changes. If you discover any issues, please open an issue on GitHub.

remove()

The MongoDB driver’s remove() function is deprecated in favor of deleteOne() and deleteMany(). This is to comply with the MongoDB CRUD specification, which aims to provide a consistent API for CRUD operations across all MongoDB drivers.

  1. DeprecationWarning: collection.remove is deprecated. Use deleteOne,
  2. deleteMany, or bulkWrite instead.

To remove this deprecation warning, replace any usage of remove() with deleteMany(), unless you specify the single option to remove(). The single option limited remove() to deleting at most one document, so you should replace remove(filter, { single: true }) with deleteOne(filter).

  1. // Replace this:
  2. MyModel.remove({ foo: 'bar' });
  3. // With this:
  4. MyModel.deleteMany({ foo: 'bar' });
  6. // Replace this:
  7. MyModel.remove({ answer: 42 }, { single: true });
  8. // With this:
  9. MyModel.deleteOne({ answer: 42 });

useUnifiedTopology

By default, mongoose.connect() will print out the below warning:

  1. DeprecationWarning: current Server Discovery and Monitoring engine is
  2. deprecated, and will be removed in a future version. To use the new Server
  3. Discover and Monitoring engine, pass option { useUnifiedTopology: true } to
  4. the MongoClient constructor.

Mongoose 5.7 uses MongoDB driver 3.3.x, which introduced a significant refactor of how it handles monitoring all the servers in a replica set or sharded cluster. In MongoDB parlance, this is known as server discovery and monitoring.

To opt in to using the new topology engine, use the below line:

  1. mongoose.set('useUnifiedTopology', true);

The useUnifiedTopology option removes support for several connection options that are no longer relevant with the new topology engine:

  • autoReconnect
  • reconnectTries
  • reconnectInterval

When you enable useUnifiedTopology, please remove those options from your mongoose.connect() or createConnection() calls.

If you find any unexpected behavior, please open up an issue on GitHub.

update()

Like remove(), the update() function is deprecated in favor of the more explicit updateOne(), updateMany(), and replaceOne() functions. You should replace update() with updateOne(), unless you use the multi or overwrite options.

  1. collection.update is deprecated. Use updateOne, updateMany, or bulkWrite
  2. instead.
  1. // Replace this:
  2. MyModel.update({ foo: 'bar' }, { answer: 42 });
  3. // With this:
  4. MyModel.updateOne({ foo: 'bar' }, { answer: 42 });
  6. // If you use `overwrite: true`, you should use `replaceOne()` instead:
  7. MyModel.update(filter, update, { overwrite: true });
  8. // Replace with this:
  9. MyModel.replaceOne(filter, update);
  11. // If you use `multi: true`, you should use `updateMany()` instead:
  12. MyModel.update(filter, update, { multi: true });
  13. // Replace with this:
  14. MyModel.updateMany(filter, update);

count()

The MongoDB server has deprecated the count() function in favor of two separate functions, countDocuments() and estimatedDocumentCount().

  1. DeprecationWarning: collection.count is deprecated, and will be removed in a future version. Use collection.countDocuments or collection.estimatedDocumentCount instead

The difference between the two is countDocuments() can accept a filter parameter like find(). The estimatedDocumentCount() function is faster, but can only tell you the total number of documents in a collection. You cannot pass a filter to estimatedDocumentCount().

To migrate, replace count() with countDocuments() unless you do not pass any arguments to count(). If you use count() to count all documents in a collection as opposed to counting documents that match a query, use estimatedDocumentCount() instead of countDocuments().

  1. // Replace this:
  2. MyModel.count({ answer: 42 });
  3. // With this:
  4. MyModel.countDocuments({ answer: 42 });
  6. // If you're counting all documents in the collection, use
  7. // `estimatedDocumentCount()` instead.
  8. MyModel.count();
  9. // Replace with:
  10. MyModel.estimatedDocumentCount();
  12. // Replace this:
  13. MyModel.find({ answer: 42 }).count().exec();
  14. // With this:
  15. MyModel.find({ answer: 42 }).countDocuments().exec();
  17. // Replace this:
  18. MyModel.find().count().exec();
  19. // With this, since there's no filter
  20. MyModel.find().estimatedDocumentCount().exec();

GridStore

If you’re using gridfs-stream, you’ll see the below deprecation warning:

  1. DeprecationWarning: GridStore is deprecated, and will be removed in a
  2. future version. Please use GridFSBucket instead.

That is because gridfs-stream relies on a deprecated MongoDB driver class. You should instead use the MongoDB driver’s own streaming API.

  1. // Replace this:
  2. const conn = mongoose.createConnection('mongodb://localhost:27017/gfstest');
  3. const gfs = require('gridfs-store')(conn.db);
  4. const writeStream = gfs.createWriteStream({ filename: 'test.dat' });
  6. // With this:
  7. const conn = mongoose.createConnection('mongodb://localhost:27017/gfstest');
  8. const gridFSBucket = new mongoose.mongo.GridFSBucket(conn.db);
  9. const writeStream = gridFSBucket.openUploadStream('test.dat');