Navigation

Compatibility Changes in MongoDB 4.0

On this page

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

Remove Support for MONGODB-CR

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. For information on upgrading to SCRAM, see Upgrade to SCRAM.

Removal of authSchemaUpgrade Command

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 MONGDB-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. For information on upgrading to SCRAM, see Upgrade to SCRAM.

Remove MONGODB-CR Support from db.copyDatabase() and copydb

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.

Deprecate MMAPv1

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

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

x.509 Authentication Certificate Restrictions

Starting in MongoDB 4.0, if you specify --sslAllowInvalidCertificates or net.ssl.allowInvalidCertificates: true (or in MongoDB 4.2, the alias --tlsAllowInvalidateCertificates or net.tls.allowInvalidCertificates: true) when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is insufficient for authentication.

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.

Replica Sets

Remove pv0 for Replica Sets

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:

copy 
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.

Remove Master-Slave Replication

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.

Journaling and Replica Sets

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.

Index Builds and Replica Sets

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.

Rollback Limit

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.

Sharded Clusters

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

Command Method Note
addShard sh.addShard()  
create db.createCollection()  
drop db.collection.drop()  
dropDatabase db.dropDatabase() Changed in MongoDB 3.6
enableSharding sh.enableSharding()  
movePrimary    
renameCollection db.collection.renameCollection()  
shardCollection sh.shardCollection()  
removeShard    
setFeatureCompatibilityVersion    

4.0 Feature Compatibility

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

General

  • 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.
  • Starting in MongoDB 4.0, the mongos binary will crash when attempting to 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.

cursor.min() and cursor.max()

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.

Disable TLS 1.0

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.

AES-GCM

MongoDB Enterprise on Windows no longer supports AES256-GCM. This cipher is now available only on Linux.

mongo Shell

show collections

Starting in version 4.0 of the mongo shell, show collections is equivalent to:

copy 
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,

  • A user must have the required access to run listCollection.
  • If a user does not have required access and runs show collections, MongoDB uses the authenticatedUserPrivileges field returned by connectionStatus to return an approximate list of collections for the user.

db.getCollectionNames()

Starting in version 4.0 of the mongo shell, db.getCollectionNames() is equivalent to:

copy 
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.

Removed Binary and Deprecated Fields/Commands

mongoperf

MongoDB 4.0 removes the mongoperf binary.

copydb and clone Commands

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:

    copy 
    mongodump --archive="mongodump-test-db" --db=test

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

    copy 
    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:

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

Parameters

  • MongoDB removes the obsolete logUserIds parameter. Use Auditing instead.

$isolated Operator

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.

geoNear Command

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

maxScan Option

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().

Output Field Changes

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.