Compatibility Changes in MongoDB 4.0

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

Remove Support for MONGODB-CR

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

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

If your deployment has user credentials stored in MONGODB-CRschema, you must upgrade to Salted Challenge ResponseAuthentication Mechanism (SCRAM)before youupgrade to version 4.0. For information on upgrading to SCRAM, seeUpgrade 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 upgradeprocess for systems with MONGDB-CR users to SCRAM users.

If your deployment has user credentials stored in MONGODB-CRschema, you must upgrade to Salted Challenge ResponseAuthentication Mechanism (SCRAM)before youupgrade to version 4.0. For information on upgrading to SCRAM, seeUpgrade to SCRAM.

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

The method db.copyDatabase() cannot copy from amongod instance that enforces MONGODB-CRauthentication.

The command copydb cannot copy from amongod instance that enforces MONGODB-CRauthentication. In conjunction with this change, MongoDB 4.0 removesthe copydbgetnonce command.

Deprecate MMAPv1

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

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

x.509 Authentication Certificate Restrictions

Starting in MongoDB 4.0, if you specify—sslAllowInvalidCertificates ornet.ssl.allowInvalidCertificates: true (or in MongoDB 4.2, thealias —tlsAllowInvalidateCertificates ornet.tls.allowInvalidCertificates: true) when using x.509authentication, an invalid certificate is only sufficient toestablish a TLS/SSL connection but is insufficient forauthentication.

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

Replica Sets

Remove pv0 for Replica Sets

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

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

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

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

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

For more information on pv1, seeReplica Set Protocol Version.

Remove Master-Slave Replication

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

To convert your master-slave replication, seeConvert 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 theWiredTiger storage engine.

Index Builds and Replica Sets

You cannot specify —noIndexBuildRetry or storage.indexBuildRetry with—replSet orreplication.replSetName. That is, you cannot use—noIndexBuildRetry orstorage.indexBuildRetry for a mongod instancethat is part of a replica set.

Rollback Limit

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

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

Sharded Clusters

mongos uses "majority" for thefollowing operations that affect the sharded cluster metadata:

CommandMethodNote
addShardsh.addShard()
createdb.createCollection()
dropdb.collection.drop()
dropDatabasedb.dropDatabase()Changed in MongoDB 3.6
enableShardingsh.enableSharding()
movePrimary
renameCollectiondb.collection.renameCollection()
shardCollectionsh.shardCollection()
removeShard
setFeatureCompatibilityVersion

4.0 Feature Compatibility

Some features in 4.0 require not just the 4.0 binaries but thefeatureCompatibilityVersion 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 mongoshell db.createCollection() method), you cannot set theoption autoIndexId to false when creating collections indatabases other than the local database.
  • When authentication is enabled, runningthe listDatabases command without thelistDatabases action privilege returns a list of alldatabases on which the user running the command has thefind action privilege. In previous versions, runningthe command without the listDatabases action resultedin an Unauthorized response.
  • The default value of taskExecutorPoolSize changed from0 to 1. On Linux, to restore the previous behavior for a 4.0 deployment, settaskExecutorPoolSize to 0 andAsyncRequestsSenderUseBaton to false.
  • MongoDB 4.0 removes the ability to set transportLayer andnet.transportLayer to legacy for mongod andmongos instances. The transportLayer setting isautomatically set to asio and cannot be modified.
  • Starting in MongoDB 4.0, the reIndex command and itshelper db.collection.reIndex() take a Globalexclusive (W) lock and will block other operations until itfinishes.
  • If the value specified for fields other than year, isoYear,and timezone is outside the valid range,$dateFromParts carries or subtracts the difference fromother date parts to calculate the date. In previous versions, valuesthat 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 thatcursor’s ID. As of MongoDB 4.0, the killCursorsprivilege grants the user the ability to kill any cursor associatedwith a currently authenticated user. If the user does not havepermission to kill a cursor, killCursors returns an error.
  • MongoDB 4.0 adds a killAnyCursor privilege action thatgrants the user permission to kill any cursor for the specifiedcollection.
  • Starting in MongoDB 4.0, the mongos binary will crash whenattempting to connect to mongod instances whosefeature compatibility version (fCV) is greater thanthat of the mongos. For example, you cannot connecta MongoDB 4.0 version mongos to a 4.2sharded cluster with fCV set to 4.2. Youcan, however, connect a MongoDB 4.0 versionmongos to a 4.2 sharded cluster with fCV set to 4.0.
  • Starting in 4.0, MongoDB resolves localhost IP address asconfigured instead of assuming 127.0.0.1.

cursor.min() and cursor.max()

If you use max() with min() tospecify a range, the bound specified by max() must begreater than the bound specified by min().

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

Disable TLS 1.0

MongoDB binaries (mongod, mongos, andmongo) disables support for TLS 1.0 encryption onsystems where TLS 1.1+ is available.

If you need to support TLS 1.0:

The —sslDisabledProtocolsoption is available for the mongo shell in:

  • MongoDB version 4.0+
  • MongoDB version 3.6.5+
  • MongoDB version 3.4.15+

On macOS, to connect mongo shell version 3.6.4 orearlier to a MongoDB 4.0+ deployment requires explicit enabling of TLS1.0.

AES-GCM

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

mongo Shell

show collections

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

  1. db.runCommand( { listCollections: 1.0, authorizedCollections: true, nameOnly: true } )
  • For users with the required access, show collections lists thenon-system collections for the database.
  • For users without the required access, show collections listsonly the collections for which the users has privileges.

When a version 4.0 mongo shell is connected to anearlier version MongoDB deployment that does not supportauthorizedCollections and nameOnly options,

  • A user must have the required access to runlistCollection.
  • If a user does not have required access and runs showcollections, MongoDB uses theauthenticatedUserPrivileges fieldreturned by connectionStatus to return an approximatelist of collections for the user.

db.getCollectionNames()

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

  1. db.runCommand( { listCollections: 1.0, authorizedCollections: true, nameOnly: true } )
  • For users with the required access (privileges that grantlistCollections action on the database), the methodlists the names of all collections for the database.
  • For users without the required access, the method lists only thecollections for which the users has privileges. For example, if auser has find on a specific collection in adatabase, 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 copydband the clone commands and theirmongo shell helpersdb.copyDatabase() anddb.cloneDatabase().

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

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

  • Use mongodump to dump the test database toan archive mongodump-test-db:
  1. mongodump --archive="mongodump-test-db" --db=test
  1. mongorestore --archive="mongodump-test-db" --nsFrom='test.*' --nsTo='examples.*'

Tip

Include additional options as necessary, such as to specifythe uri or host, username, password and authenticationdatabase.

Alternatively, instead of using an archive file, you canmongodump the test database to the standardoutput stream and pipe into mongorestore:

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

Parameters

  • MongoDB removes the obsolete logUserIds parameter. UseAuditing instead.

$isolated Operator

MongoDB drops support for the $isolated operator. If you have anexisting partial index that includes the $isolated operator or aview that includes a $isolated operator, recreate the index orview 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 thefollowing operations instead.

maxScan Option

MongoDB deprecates the option maxScan for the findcommand and the mongo shell helpercursor.maxScan(). Instead, use maxTimeMS option or thehelper cursor.maxTimeMS().

Output Field Changes