Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Compatibility Changes in MongoDB 4.0

On this page

  • Remove Support for MONGODB-CR
  • Deprecate MMAPv1
  • x.509 Authentication Certificate Restrictions
  • Replica Sets
  • Sharded Clusters
  • 4.0 Feature Compatibility
  • General
  • Disable TLS 1.0
  • AES-GCM
  • mongo Shell
  • Removed Binary and Deprecated Fields/Commands

The following 4.0 changes can affect the compatibility with older versions of MongoDB.

Starting in version 4.0, MongoDB removes support for the deprecated MongoDB Challenge-Response (MONGODB-CR) authentication mechanism.

Since version 3.0, MongoDB has not supported the creation of MONGODB-CR users unless the deployment had been upgraded from a 2.6 or earlier deployment that already had MONGODB-CR users and had not upgraded the authentication schema.

If your deployment has user credentials stored in MONGODB-CR schema, you must upgrade to Salted Challenge Response Authentication Mechanism (SCRAM) before you upgrade to version 4.0.

MongoDB 4.0 removes the authSchemaUpgrade command . The command, available in MongoDB 3.0 through MongoDB 3.6, supports the upgrade process for systems with MONGODB-CR users to SCRAM users.

If your deployment has user credentials stored in MONGODB-CR schema, you must upgrade to Salted Challenge Response Authentication Mechanism (SCRAM) before you upgrade to version 4.0.

The method db.copyDatabase() cannot copy from a mongod instance that enforces MONGODB-CR authentication.

The command copydb cannot copy from a mongod instance that enforces MONGODB-CR authentication. In conjunction with this change, MongoDB 4.0 removes the copydbgetnonce command.

Starting in version 4.0, MongoDB deprecates the MMAPv1 storage engine.

To change your MMAPv1 storage engine deployment to WiredTiger Storage Engine, see:

Starting in MongoDB 4.0, if you specify any of the following x.509 authentication options, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication:

  • --sslAllowInvalidCertificates or net.ssl.allowInvalidCertificates: true for MongoDB 4.0 and later

  • --tlsAllowInvalidCertificates or net.tls.allowInvalidCertificates: true for MongoDB 4.2 and later

If you are using invalid certificates to perform x.509 authentication, update your certificates to valid certificates. For example, you may sign your existing certificates with a trusted CA, or if using a custom CA, specify that CA using net.ssl.CAFile.

Starting in version 4.0, MongoDB removes the deprecated replica set protocol version 0 pv0.

Before upgrading to MongoDB 4.0, you must upgrade to pv1.

To upgrade to pv1, connect a mongo shell to the replica set primary and perform the following sequence of operations:

cfg = rs.conf();
cfg.protocolVersion=1;
rs.reconfig(cfg);

To reduce the likelihood of w:1 rollbacks, you can also reconfigure the replica set to a higher settings.catchUpTimeoutMillis setting.

For more information on pv1, see Replica Set Protocol Version.

MongoDB 4.0 removes support for the deprecated master-slave replication. Before you can upgrade to MongoDB 4.0, if your deployment uses master-slave replication, you must upgrade to a replica set.

To convert from master-slave replication to a replica set, see Convert a Master-Slave Deployment to a Replica Set.

Starting in MongoDB 4.0, you cannot specify --nojournal option or storage.journal.enabled: false for replica set members that use the WiredTiger storage engine.

You cannot specify --noIndexBuildRetry or storage.indexBuildRetry with --replSet or replication.replSetName. That is, you cannot use --noIndexBuildRetry or storage.indexBuildRetry for a mongod instance that is part of a replica set.

MongoDB 4.0 removes the limit on the amount of data that can be rolled back. In previous versions, a mongod instance will not roll back more than 300 megabytes of data and requires manual intervention if more than 300 megabytes of data need to be rolled back.

Starting in MongoDB 4.0, the rollback time limit defaults to 1 day and is configurable using the new parameter rollbackTimeLimitSecs. In earlier versions, the rollback time limit is not configurable and is set to 30 minutes.

mongos uses "majority" write concern for the following operations that affect the sharded cluster metadata:

Command
Method
Note
addShard
Changed in MongoDB 3.6

Some features in 4.0 require not just the 4.0 binaries but the featureCompatibilityVersion set to 4.0. These features include:

  • The geospatial query operators $near and $nearSphere now supports querying on sharded collections.

  • For the create command (and the mongo shell db.createCollection() method), you cannot set the option autoIndexId to false when creating collections in databases other than the local database.

  • When authentication is enabled, running the listDatabases command without the listDatabases action privilege returns a list of all databases on which the user running the command has the find action privilege. In previous versions, running the command without the listDatabases action resulted in an Unauthorized response.

  • The default value of taskExecutorPoolSize changed from 0 to 1. On Linux, to restore the previous behavior for a 4.0 deployment, set taskExecutorPoolSize to 0 and AsyncRequestsSenderUseBaton to false.

  • MongoDB 4.0 removes the ability to set transportLayer and net.transportLayer to legacy for mongod and mongos instances. The transportLayer setting is automatically set to asio and cannot be modified.

  • Starting in MongoDB 4.0, the reIndex command and its helper db.collection.reIndex() take a Global exclusive (W) lock and will block other operations until it finishes.

  • If the value specified for fields other than year, isoYear, and timezone is outside the valid range, $dateFromParts carries or subtracts the difference from other date parts to calculate the date. In previous versions, values that exceed the range result in an error.

  • Changed behavior of the killCursors privilege action. Prior to MongoDB 4.0, a user could kill any cursor if they knew that cursor's ID. As of MongoDB 4.0, the killCursors privilege grants the user the ability to kill any cursor associated with a currently authenticated user. If the user does not have permission to kill a cursor, killCursors returns an error.

  • MongoDB 4.0 adds a killAnyCursor privilege action that grants the user permission to kill any cursor for the specified collection.

  • The mongos binary cannot connect to mongod instances whose feature compatibility version (fCV) is greater than that of the mongos. For example, you cannot connect a MongoDB 4.0 version mongos to a 4.2 sharded cluster with fCV set to 4.2. You can, however, connect a MongoDB 4.0 version mongos to a 4.2 sharded cluster with fCV set to 4.0.

  • Starting in 4.0, MongoDB resolves localhost IP address as configured instead of assuming 127.0.0.1.

If you use max() with min() to specify a range, the bound specified by max() must be greater than the bound specified by min().

In previous versions, the bounds could be equal but would scan no index entries, always resulting in an empty result set.

MongoDB binaries (mongod, mongos, and mongo) disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available.

If you need to support TLS 1.0:

On macOS, to connect mongo shell version 3.6.4 or earlier to a MongoDB 4.0+ deployment requires explicit enabling of TLS 1.0.

MongoDB Enterprise on Windows no longer supports AES256-GCM as a block cipher for encryption at rest. This usage is only supported on Linux.

The mongosh method show collections is similar to:

db.runCommand(
{
listCollections: 1.0,
authorizedCollections: true,
nameOnly: true
}
)
  • For users with the required access, show collections lists the non-system collections for the database.

  • For users without the required access, show collections lists only the collections for which the users has privileges.

When a version 4.0 mongo shell is connected to an earlier version MongoDB deployment that does not support authorizedCollections and nameOnly options,

The db.getCollectionNames() is equivalent to:

db.runCommand(
{
listCollections: 1.0,
authorizedCollections: true,
nameOnly: true
}
)
  • For users with the required access (privileges that grant listCollections action on the database), the method lists the names of all collections for the database.

  • For users without the required access, the method lists only the collections for which the users has privileges. For example, if a user has find on a specific collection in a database, the method would return just that collection.

MongoDB 4.0 removes the mongoperf binary.

MongoDB 4.0 deprecates the copydb and the clone commands and their mongo shell helpers db.copyDatabase() and db.cloneDatabase().

As alternatives, users can use mongodump and mongorestore (with the mongorestore options --nsFrom and --nsTo) or write a script using the drivers.

For example, to copy the test database from a local instance running on the default port 27017 to the examples database on the same instance, you can:

  1. Use mongodump to dump the test database to an archive mongodump-test-db:

    mongodump --archive="mongodump-test-db" --db=test
  2. Use mongorestore with --nsFrom and --nsTo to restore (with database name change) from the archive:

    mongorestore --archive="mongodump-test-db" --nsFrom='test.*' --nsTo='examples.*'

Tip

Include additional options as necessary, such as to specify the uri or host, username, password and authentication database.

Alternatively, instead of using an archive file, you can mongodump the test database to the standard output stream and pipe into mongorestore:

mongodump --archive --db=test | mongorestore --archive --nsFrom='test.*' --nsTo='examples.*'
  • MongoDB removes the obsolete logUserIds parameter. Use Auditing instead.

MongoDB drops support for the $isolated operator. If you have an existing partial index that includes the $isolated operator or a view that includes a $isolated operator, recreate the index or view without the operator in the definition before upgrading.

Instead of the $isolated operator, use transactions instead.

MongoDB 4.0 deprecates the geoNear command. Use one of the following operations instead.

MongoDB deprecates the option maxScan for the find command and the mongo shell helper cursor.maxScan(). Instead, use maxTimeMS option or the helper cursor.maxTimeMS().

What is MongoDB? →