Compatibility Changes in MongoDB 4.2

MMAPv1 Specific Configuration Options

MongoDB removes the following MMAPv1 specific configuration options:

MMAPv1 Specific Parameters

MongoDB removes the following MMAPv1 parameters:

• newCollectionsUsePowerOf2Sizes

• replIndexPrefetch

MMAPv1 Specific Command

MongoDB removes the MMAPv1 specific touch command.

MMAPv1 Specific Options for Commands and Methods

MongoDB removes the MMAPv1 specific options:

• noPadding and usePowerOf2Sizes for collMod

• verbose for collStats

• flags for create

• paddingFactor, paddingBytes, preservePadding for db.createCollection().

MongoDB ignores the MMAPv1 specific option async for fsync.

Remove Support for the group Command

Starting in version 4.2, MongoDB removes the group command (deprecated since version 3.4) and its mongo shell helper db.collection.group().

Use db.collection.aggregate() with the $group stage instead.

Remove Support for the eval Command

Starting in version 4.2, MongoDB removes the eval command. The eval command has been deprecated since version 3.0.

The associated MongoDB 4.2 mongo shell methods db.eval() and db.collection.copyTo() can only be run when connected to MongoDB 4.0 or earlier.

Remove Support for the copydb and clone Commands

Starting in version 4.2, MongoDB removes the deprecated copydb command and clone command.

The corresponding mongo shell helpers db.copyDatabase() and db.cloneDatabase() can only be run when connected to MongoDB 4.0 or earlier.

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.*'

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.*'

Remove Support for the parallelCollectionScan Command

Starting in version 4.2, MongoDB removes the parallelCollectionScan command.

Remove maxScan

MongoDB removes the deprecated option maxScan for the find command and the mongo shell helper cursor.maxScan(). Use either the maxTimeMS option for the find command or the helper cursor.maxTimeMS() instead.

Remove Support for the geoNear Command

Starting in version 4.2, MongoDB removes the geoNear command. Use the $geoNear aggregation stage instead.

The options for $geoNear are similar to the removed geoNear command with the following exceptions:

• The removed geoNear command includes in its output a field named dis that included the distance information.

  For the $geoNear stage, specify the distance field name in distanceField.

• The removed geoNear command accepts a boolean value for the includeLocs option to include the loc field.

  For the $geoNear stage, specify the location field name in includeLocs.

• The removed geoNear command includes the avgDistance and maxDistance of the returned results.

  You can use the aggregation pipeline to return the avgDistance and maxDistance as well. Specifically, after the $geoNear stage, include a $group stage to calculate the avgDistance and maxDistance:

  db.places.aggregate([
     { $geoNear: { near: <...>, distanceField: "dis", includeLocs: "loc", spherical: true, ... } },
     { $group: { _id: null, objectsLoaded: { $sum: 1 }, maxDistance:
           { $max: "$dis" }, avgDistance: { $avg: "$dis" } } }
  ])

  Tip

  See also:

  Remove limit and num Options from $geoNear

Remove Support for the repairDatabase Command

Starting in version 4.2, MongoDB removes the repairDatabase command and its mongo shell helper db.repairDatabase() as well as the repairDatabase privilege.

As alternatives:

• To compact data for a mongod, use the compact command. For details about the operation, see compact command.

• To rebuild indexes on a standalone, use the reIndex command or its helper db.collection.reIndex(). For details about the operation, see reIndex command and db.collection.reIndex() reference pages.

• To recover data for a standalone, use mongod --repair. See Recover a Standalone after an Unexpected Shutdown for details.

Remove Support for getPrevError Command

Starting in version 4.2, MongoDB removes the deprecated getPrevError command and its mongo shell helper db.getPrevError().

Deprecate Support for cloneCollection

MongoDB deprecates the cloneCollection command and its mongo shell helper db.cloneCollection()

As alternatives,

• Users can use mongoexport and mongoimport.

• Users can use the aggregation pipeline $out or $merge stages.

• Write a script using the drivers.

Deprecated Plan Cache Commands/Methods

MongoDB deprecates the following:

• PlanCache.getPlansByQuery() method/planCacheListPlans command.

  To get the cached query plans for a hash, use the $planCacheStats aggregation stage instead. See Find Cache Entry Details for a Query Hash.

• PlanCache.listQueryShapes() method/planCacheListQueryShapes command.

$out Stage Restrictions

Remove limit and num Options from $geoNear

Starting in version 4.2, MongoDB removes the limit and num options for the $geoNear stage as well as the default limit of 100 documents. To limit the results of $geoNear, use the $geoNear stage with the $limit stage.

For example, the following aggregation where the $geoNear stage contains the num option is no longer valid in 4.2.

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "distance",
        num: 5,                 // Not supported in 4.2
        spherical: true
     }
   }
])

Instead, you can rewrite the aggregation to the following pipeline:

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "distance",
        spherical: true
     }
   },
   { $limit: 5 }
])

Availability

Starting in MongoDB 4.2, change streams are available regardless of the "majority" read concern support; that is, read concern majority support can be either enabled (default) or disabled to use change streams.

In MongoDB 4.0 and earlier, change streams are available only if "majority" read concern support is enabled (default).

Default Collation

Starting in MongoDB 4.2, change streams use simple binary comparisons unless an explicit collation is provided. In earlier versions, change streams opened on a single collection (db.collection.watch()) would inherit that collection's default collation.

Resume Token Modification

Starting in MongoDB 4.2, change streams will throw an exception if the change stream aggregation pipeline modifies an event's _id field.

FIPS Mode

Starting in version 4.2, MongoDB removes the --sslFIPSMode option for the following programs:

• mongodump

• mongoexport

• mongofiles

• mongoimport

• mongorestore

• mongostat

• mongotop

The programs will use FIPS compliant connections to mongod / mongos if the mongod / mongos instances are configured to use FIPS mode.

Extended JSON v2

Starting in version 4.2:

For details on MongoDB extended JSON v2, see MongoDB Extended JSON (v2).

mongoexport -d=test -c=records -q='{ "a": { "$gte": 3 }, "date": { "$lt": { "$date": "2016-01-01T00:00:00.000Z" } } }' --out=exportdir/myRecords.json

mongoexport -d=test -c=records -q='{ a: { $gte: 3 }, date: { $lt: { "$date": "2016-01-01T00:00:00.000Z" } } }' --out=exportdir/myRecords.json

Primary Step Down

Starting in MongoDB 4.2, replSetStepDown (and replSetReconfig that results in a step down) no longer closes all client connections. However, writes that were in progress are killed.

In MongoDB 4.0 and earlier, replSetStepDown closes all client connections during the step down.

ROLLBACK State

Starting in version 4.2, MongoDB kills all in-progress user operations when a member enters the ROLLBACK state.

Indexes

{
   "ok" : 0,
   "errmsg" : "Index with name: x_1 already exists with a different name",
   "code" : 85,
   "codeName" : "IndexOptionsConflict"
}

{
   "numIndexesBefore" : 2,
   "numIndexesAfter" : 2,
   "note" : "all indexes already exist",
   "ok" : 1
}

min()/max()

Starting in MongoDB 4.2, when specifying min()/max() for a db.collection.find() operation, you must explicitly specify the index for min()/max() with the cursor.hint() method unless the find() query is an equality condition on the _id field { _id: <value> }.

Similarly, when specifying min/max in the find command, you must also explicitly specify the hint for the min/max index.

In previous versions, you could run min()/max() (or the corresponding min/max fields in the command) with or without explicitly hinting the index regardless of the query condition. If run without the hint in 4.0 and earlier, MongoDB selects the index using the fields in the indexBounds; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous.

CurrentOp

• When reporting on "getmore" operations, the $currentOp aggregation stage, along with currentOp command and the db.currentOp() helper, now returns the originatingCommand field as a nested field in the new cursor field. In previous versions, the originatingCommand was a top-level field for the associated "getmore" document. See also 4.2 currentOp Changes.

Server Status

• The serverStatus and db.serverStatus() method return opcounters and opcountersRepl metrics as 64-bit integers (i.e. NumberLong) instead of 32-bit integers (i.e. NumberInt).

Logging

• When logging to syslog, the format of the message text includes the component. For example:

  ...  ACCESS   [repl writer worker 5] Unsupported modification to roles collection ...

  Previously, the syslog message text did not include the component. For example:

  ... [repl writer worker 1] Unsupported modification to roles collection ...

• Starting in MongoDB 4.2, the getLog command truncates any event that contains more than 1024 characters. In earlier versions, getLog truncates after 512 characters.

• Starting in version 4.2, MongoDB logs the debug verbosity level. For example, if verbosity level is 2, MongoDB logs D2.

  In previous versions, MongoDB log messages only specified D for Debug level.

Wire Protocol

• MongoDB no longer supports the deprecated internal OP_COMMAND and the corresponding OP_COMMANDREPLY wire protocol.

killCursors Changes

Removes AsyncRequestsSenderUseBaton Parameter

In MongoDB 4.2+ deployment, MongoDB removes the AsyncRequestsSenderUseBaton parameter and always enables the performance enhancement controlled by the parameter.

Stricter Validation of count Syntax

Starting in version 4.2, MongoDB implements a stricter validation of the option names for the count command. The command now errors if you specify an unknown option name.

In previous versions, MongoDB ignores invalid option names.

Causal Consistency Sessions

Starting in MongoDB 4.2, the following commands no longer support afterClusterTime:

• dbHash command

• mapReduce command

• validate command

As such, these operations cannot be associated with causally consistent sessions.

Removes fastmodinsert Metric

MongoDB 4.2 removes the deprecated fastmodinsert metric from various outputs, including the explain executionStats, the profiler output, etc.

Map-Reduce

Starting in version 4.2, MongoDB deprecates:

• The map-reduce option to create a new sharded collection as well as the use of the sharded option for map-reduce. To output to a sharded collection, create the sharded collection first. MongoDB 4.2 also deprecates the replacement of an existing sharded collection.

Balancer State and Autosplit

Starting in MongoDB 6.1, automatic chunk splitting is not performed. This is because of balancing policy improvements. Auto-splitting commands still exist, but do not perform an operation. For details, see Balancing Policy Changes.

In MongoDB versions earlier than 6.1:

• The balancerStart command and the mongo shell helper methods sh.startBalancer() and sh.setBalancerState(true) also enable auto-splitting for the sharded cluster.

  To disable auto-splitting when the balancer is enabled, you can use sh.disableAutoSplit().

• The balancerStop command and the mongo shell helper methods sh.stopBalancer() and sh.setBalancerState(false) also disable auto-splitting for the sharded cluster.

  To enable auto-splitting when the balancer is disabled, you can use sh.enableAutoSplit().

The mongo methods sh.enableBalancing(namespace) and sh.disableBalancing(namespace) have no affect on the auto-splitting.

Lock Diagnostics Reporting

Starting in version 4.2, MongoDB reports on ReplicationStateTransition lock information.

In addition, MongoDB 4.2 separates ParallelBatchWriterMode lock information from Global lock information. Earlier MongoDB versions report ParallelBatchWriterMode lock information as part of Global locks.

For operations that report on lock information, see:

• serverStatus command and db.serverStatus() method.

• $currentOp aggregation pipeline stage, currentOp command, and db.currentOp() method.

findAndModify Query/Sort/Projection Argument Validation

Starting in MongoDB 4.2 (and 4.0.12+ and 3.6.14+), the findAndModify command and its associated mongo shell methods error if the specified query, sort, or projection argument is not a document.

In earlier versions, the operation treated non-document query or sort argument as an empty document {}.

See:

• findAndModify

• db.collection.findOneAndDelete()

• db.collection.findOneAndReplace()

• db.collection.findOneAndUpdate()

• db.collection.findAndModify()

dropDatabase and movePrimary

Starting in MongoDB 4.2,

• If you drop a database and create a new database with the same name, either:

  • Restart all mongos instances and mongod shard members; or

  • Use the flushRouterConfig command on all mongos instances and mongod shard members before reading or writing to that database.

• If you use the movePrimary command to move unsharded collections, either:

  • Restart all mongos instances and mongod shard members; or

  • Use the flushRouterConfig command on all mongos instances and mongod shard members before reading or writing to that database.

This ensures that mongos and shard instances refresh their metadata cache. Otherwise, the you may miss data on reads, and may not write data to the correct shard. To recover, you must manually intervene.

In earlier versions, you only need to restart or run flushRouterConfig on the mongos instances.

For more information, see dropDatabase and movePrimary.

libldap and libldap_r

For MongoDB 4.2 Enterprise binaries linked against libldap (such as when running on RHEL), access to the libldap is synchronized, incurring some performance/latency costs.

For MongoDB 4.2 Enterprise binaries linked against libldap_r, there is no change in behavior from earlier MongoDB versions.

Connection Pooling and LDAP Server

Starting in version 4.2, MongoDB changes the ldapUseConnectionPool default values to:

• true on Windows.

• true on Linux where MongoDB Enterprise binaries are linked against libldap_r.

That is, on those systems, MongoDB, by default, uses connection pooling to connect to the LDAP server for authentication/authorization.

In earlier versions (versions 4.0.9+), MongoDB uses false as the default value for ldapUseConnectionPool. That is, MongoDB, by default, does not use connection pooling to connect to the LDAP server for authentication/authorization.

See ldapUseConnectionPool for details.

Removal of system.indexes and system.namespaces Collections

Starting in version 4.2, MongoDB removes the system.indexes and system.namespaces collections (deprecated since v3.0).

With the removal of these collections, built-in roles clusterManager, clusterMonitor, dbAdmin, read, restore, and other roles that inherit from these roles no longer provide privileges to directly access system.indexes and system.namespaces collections.

Arbiter Downgrade Requires Clearing Data Directory

MongoDB 4.2 arbiter data files are incompatible with MongoDB 4.0. Downgrading from MongoDB 4.2 to 4.0 requires deleting arbiter data files as an intermediary step. Running a MongoDB 4.0 arbiter against MongoDB 4.2 data files may result in unexpected behavior.

The downgrade instructions for replica sets and sharded clusters include specific steps for downgrading arbiters from 4.2 to 4.0:

• Downgrade 4.2 Replica Set to 4.0.

• Downgrade 4.2 Sharded Cluster to 4.0.

Sharded Collections and Replace Documents

Starting in MongoDB 4.2,

• Operations which replace documents, such as replaceOne() or update() (when used with a replacement document), will first attempt to target a single shard by using the query filter. If the operation cannot target a single shard by the query filter, it then attempts to target by the replacement document. In earlier versions, these operations only attempt to target using the replacement document.

• The save() method is deprecated: use the insertOne() or replaceOne() method instead. The save() method cannot be used with sharded collections that are not sharded by _id, and attempting to do so will result in an error.

• For a replace document operation that includes upsert: true and is on a sharded collection, the filter must include an equality match on the full shard key.