Compatibility Changes in MongoDB 5.0

Platform Support

Certain Commands Only Accept Recognized Parameters

Starting in MongoDB 5.0, certain database commands raise an error if passed a parameter not explicitly accepted by the command. In MongoDB 4.4 and earlier, unrecognized parameters are silently ignored.

Affected Commands:

• abortTransaction

• aggregate

• authenticate

• collMod

• commitTransaction

• create

• createIndexes

• delete

• drop

• dropDatabase

• dropIndexes

• endSessions

• explain

• find

• findAndModify

• getMore

• hello

• insert

• killCursors

• listCollections

• listDatabases

• listIndexes

• ping

• refreshSessions

• update

Removed Commands

Starting in MongoDB 5.0, these database commands and mongo shell helper methods are removed:

Removed Parameters

MongoDB 5.0 removes the following server parameters:

Removed Index Types

MongoDB 5.0 removes the deprecated geoHaystack index. Use a 2d index instead.

Upgrading your MongoDB instance to 5.0 and setting featureCompatibilityVersion to 5.0 will delete any pre-existing geoHaystack indexes.

Removed Metrics

Starting in MongoDB 5.0, the serverStatus command does not output opReadConcernCounters, which contained the read concern level specified by query operations. Instead, the new readConcernCounters replaces opReadConcernCounters and contains additional information.

Starting in MongoDB 5.0, the serverStatus command does not output the cache pressure percentage threshold and the current cache pressure percentage under wiredTiger.snapshot-window-settings.

Removed Raspberry Pi Support

MongoDB 5.0 removes support for Raspberry Pi. To run MongoDB on Raspberry Pi, install version 4.4.

TTL expireAfterSeconds Behavior When Set to NaN

Starting in MongoDB 5.0, TTL indexes with expireAfterSeconds set to NaN experience a behavior change compared to earlier versions.

The behavior change affects:

• direct upgrades

• initial sync from earlier versions

• mongorestore from earlier versions

Performing any of those actions causes an expireAfterSeconds value of NaN to be treated as an expireAfterSeconds of 0. As a result, documents may expire immediately.

Starting in MongoDB 5.0.14 (and 6.0.2), the server will not use TTL indexes that have expireAfterSeconds set to NaN.

Shell Changes

The mongo shell has been deprecated in MongoDB v5.0. The replacement shell is mongosh.

Shell packaging also changes in MongoDB v5.0. Refer to the installation instructions for further details.

Replica Sets

if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ]
    defaultWriteConcern = { w: 1 }
else
    defaultWriteConcern = { w: "majority" }

Read Concern snapshot on Capped Collections

Starting in MongoDB 5.0, you cannot use read concern "snapshot" when reading from a capped collection.

local is the Default Read Concern

Starting in MongoDB 5.0, "local" is the default read concern level for read operations against the primary and secondaries.

This may introduce a significant latency increase for count queries that use a filter and for covered queries.

You can opt out of this behavior by setting the cluster-wide read concern with setDefaultRWConcern.

New cursor.map() Return Type

cursor.map() returned an Array in the legacy mongo shell. The return type is Cursor in mongosh. You can use .toArray() to convert the results.

Update Operator Changes

Starting in MongoDB 5.0, mongod no longer raises an error when you use the following update operators with an empty operand expression ( { } ):

• $addToSet

• $bit

• $currentDate

• $inc

• $max

• $min

• $mul

• $pop

• $pull

• $pullAll

• $push

• $rename

• $set

• $setOnInsert

• $unset

An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

$setWindowFields Stage with Transactions and Snapshot Read Concern

In MongoDB versions earlier than 5.3, the $setWindowFields aggregation pipeline stage cannot be used with transactions or the "snapshot" read concern.

Aggregation Pipeline Operator Parameter Limits

The following aggregation pipeline operators now have a 64-bit integer value maximum limit.

• $sort

• $limit

If you pass a value that exceeds this limit, the pipeline returns an invalid argument error.

listDatabases Output Changes

Starting in MongoDB 5.0, output from the listDatabases command running against a mongod is more consistent with output from listDatabases running against a mongos.

The following table shows the differences in data types for listDatabases output fields between MongoDB 5.0 and earlier versions. Only fields which differ between 5.0 and earlier versions are listed.

The output from listDatabases now includes the totalSizeMb field when run against either a mongos or a mongod. In MongoDB 4.4 and earlier, totalSizeMb only appears when run against mongos. totalSizeMb is the sum of the sizeOnDisk fields, expressed in megabytes.

When run against mongos, the shards field in the listDatabases output contains a field-value pair for each collection on a particular shard. Size values in the shards field are expressed as integers.

Security

Map-Reduce

Starting in version 5.0, MongoDB deprecates the map-reduce operation.

For examples of aggregation pipeline alternatives to map-reduce operations, see Map-Reduce to Aggregation Pipeline and Map-Reduce Examples.

Auditing

MongoDB 5.0 adds auditing capabilities that can be configured at runtime.

If auditLog.runtimeConfiguration is set to true, then the mongod and mongos configuration files can no longer set setParameter.auditAuthorizationSuccess or configure audit filters. If the server configuration files contain these settings the server will fail to start and will log an error.

If auditLog.runtimeConfiguration is set to false and an audit filter config document is present, then a startup warning will be issued but the server will not abort.

Reduce Risk of Stale Chunks in Sharded Transactions

Starting in MongoDB 5.0, if you change the transactionLifetimeLimitSeconds parameter, you must also change transactionLifetimeLimitSeconds to the same value on all config server replica set members. Keeping this value consistent:

• Ensures the routing table history is retained for at least as long as the transaction lifetime limit on the shard replica set members.

• Reduces the transaction retry frequency and therefore improves performance.

General Changes

Starting in MongoDB 5.0:

• For featureCompatibilityVersion set to "5.0" or greater, users can no longer write directly to the <database>.system.views collection.

• The reIndex command and the db.collection.reIndex() shell method may only be run on standalone instances.

• The number of aggregation pipeline stages allowed in a single pipeline is limited to 1000.

• Dropping the final collection in a database (or dropping the database itself) when directoryPerDB or --directoryperdb is enabled deletes the newly empty subdirectory for that database.

• The $subtract aggregation operator will convert the data type of the result if necessary to accurately represent the result value. See $subtract for the specific conversions.

• MongoDB removes the --serviceExecutor command-line option and the corresponding net.serviceExecutor configuration option.

• You may not authenticate as multiple simultaneous users on the same client session if the --apiStrict option is set. Attempting to authenticate as a new user while currently logged in as an existing user when the --apiStrict option is set will generate an error message once per authentication attempt. If you are not using the --apiStrict option, authenticating as a new user while currently logged in as an existing user will write a warning to the log once per authentication attempt.

• The weights option is only allowed for $text indexes.

• You must explicitly set the global default write concern before attempting to reconfigure a non-sharded replica set with a configuration that would change the implicit default write concern. To set the global default write concern, use the setDefaultRWConcern command.

• To set the replSetOplog size in mongosh, use the Double() constructor with the replSetResizeOplog command.

• Wildcard indexes are normalized after creation. The wildcardProjection document that defines the index may contain normalized syntax that differs from the original index creation statements.

• Passing "*" to dropIndexes or db.collection.dropIndexes() drops all indexes except for the _id index and the last remaining shard key index, if one exists. Attempts to explicitly drop the last remaining shard key index raise an error.

Starting in MongoDB 5.0.4 (and 4.4.10), the $mod operator returns an error if the divisor or remainder values evaluate to certain values. See $mod behavior.

5.0 Feature Compatibility

Some features in 5.0 require not just the 5.0 binaries but the featureCompatibilityVersion (fCV) set to 5.0. These features include:

• Creation of time series collections requires fCV set to 5.0+.

• Configuring Runtime Audit Filter Management requires fCV set to 5.0+.

• Usage of . and $ in field names requires fCV set to 5.0+.

• Resharding a collection requires fCV set to 5.0+.

Server Parameters

Starting in MongoDB 5.0.10 the default value for coordinateCommitReturnImmediatelyAfterPersistingDecision is false.