What's New

Node.js Version

The minimum supported version of Node.js is now v12.9 or greater for version 4 of the driver. Support for our 3.x branches will continue until summer 2022 to allow time to upgrade.

Cursor Improvements

Our Cursor implementation is now updated to make it clear what is possible before and after execution of an operation.

const fc = collection.find({a: 2.3}).skip(1)
for await (const doc of fc) {
  console.log(doc)
  fc.limit(1) // incorrect usage, cursor already executing
}

There was inconsistency surrounding how the cursor would error if a setting was applied after cursor execution began. Now, the cursor will throw an error when attempting to apply operations in an invalid state, similar to the following:

MongoError: Cursor is already initialized

• Affected classes:

  • AbstractCursor

  • FindCursor

  • AggregationCursor

  • ChangeStreamCursor (This is the underlying cursor for ChangeStream)

  • ListCollectionsCursor

const cursor = collection.find({})
const stream = cursor.stream()
stream.on("data", data => console.log)
stream.on("error", () => client.close())

MongoClientOptions Interface

With type hinting, you should find that options passed to a MongoClient are enumerated and discoverable. We've made a large effort to process all options in the driver to give early warnings about incompatible settings to get your app up and running in a correct state quickly.

• checkServerIdentity is no longer checked before being passed to the underlying Node API. Previously, accepted values were false, or a function. Now, the argument must be a function. Specifying a boolean will result in an error being thrown.

• It is no longer required to specify useUnifiedTopology or useNewUrlParser.

createCollection()

This method no longer supports a strict option, which returned an error if the collection did not exist. To assert the existence of a collection, use the listCollections() method instead.

const collections = (await db.listCollections({}, { nameOnly: true })
  .toArray()).map(
    ({name}) => name
  );
if (!collections.includes(myNewCollectionName)) {
  throw new Error(`${myNewCollectionName} doesn't exist`);
}

BulkWriteError → MongoBulkWriteError

BulkWriteError is now renamed to MongoBulkWriteError.

When running bulk operations that make writes you can encounter errors depending on your settings. Import the new class name MongoBulkWriteError when testing for errors in bulk operations.

DB

DB is no longer an EventEmitter. Listen for events directly from your MongoClient instance.

Collection.group()

The Collection.group() helper, deprecated since MongoDB 3.4, is now removed. Use the aggregation pipeline $group operator instead.

Authentication

• gssapiServiceName is now removed. Use authMechanismProperties.SERVICE_NAME in the URI or as an option on MongoClientOptions.

  Example

  ?authMechanismProperties.SERVICE_NAME
  // or
  new MongoClient(url, { SERVICE_NAME: "alternateServiceName" })

• Specifying username and password as options is only supported in the URI or as an option on MongoClientOptions.

  Example

  new MongoClient("mongodb://username:password@<host><port>")
  // or
  new MongoClient(url, { auth: { username: "<>", password: "<>" } })

GridStore Removal

The GridStore API (already deprecated in 3.x) is now replaced with GridFSBucket. For more information on GridFS, see the mongodb manual.

Below are some snippets that represent equivalent operations.

// old way
const gs = new GridStore(db, filename, mode[, options])
// new way
const bucket = new GridFSBucket(client.db('test')[,options])

bucket.openDownloadStreamByName(filename, { start: 0, end: 100 })

await client.connect();
const filename = 'test.txt'; // whatever local file name you want
const db = client.db();
const bucket = new GridFSBucket(db);
fs.createReadStream(filename)
  .pipe(bucket.openUploadStream(filename))
  .on('error', console.error)
  .on('finish', () => {
    console.log('done writing to db!');
    bucket
      .find()
      .toArray()
      .then(files => {
        console.log(files);
        bucket
          .openDownloadStreamByName(filename)
          .pipe(fs.createWriteStream('downloaded_' + filename))
          .on('error', console.error)
          .on('finish', () => {
            console.log('done downloading!');
            client.close();
          });
      });
  });

// old way
GridStore.unlink(db, name, callback);
// new way
bucket.delete(file_id);

const fileMetaDataList: GridFSFile[] = bucket.find({}).toArray();

Unified Topology

• We internally now only manage a unifiedTopology when you connect to a mongod. The differences between this and previous versions is detailed here.

• It is no longer required to specify useUnifiedTopology or useNewUrlParser.

• You must use the new directConnection option to connect to uninitialized replica set members.

Explain

Support is now added for fine-grained verbosity modes. You can learn more about each mode here.

Command Monitoring

The instrument() method is now removed. Use command monitoring instead. See our guide on command monitoring for more information.