Navigation

Compatibility Changes in MongoDB 5.0

On this page

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

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:

Removed Commands

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

Removed Command Alternative
db.collection.copyTo() $out
db.collection.ensureIndex() db.collection.createIndex()
db.collection.save()
db.collection.insertOne()
db.collection.insertMany()
db.resetError() Not available
geoSearch One of the Geospatial Query Operators
Mongo.getSecondaryOk() Mongo.getReadPrefMode()
Mongo.isCausalConsistency Not available
Mongo.setSecondaryOk() Mongo.setReadPref()
rs.secondaryOk() Mongo.setReadPref()
resetError Not available
shardConnPoolStats connPoolStats
unsetSharding Not available

Removed Parameters

MongoDB 5.0 removes the following server parameters:

Removed Parameters Description
cachePressureThreshold MongoDB 5.0 removes the cachePressureThreshold server parameter. Due to changes in how WiredTiger calculates snapshot window size this parameter is no longer relevant.
shouldMultiDocTxnCreateCollectionAndIndexes MongoDB 5.0 removes the shouldMultiDocTxnCreateCollectionAndIndexes server parameter. In 5.0+, collection and index creation inside of transactions is always enabled. You can no longer use the server parameter to disable this behavior.

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.

currentOp Output Change

Starting in MongoDB 5.0, the $currentOp.remainingOperationTimeEstimated metric is only present on the recipient shard when a resharding operation is taking place.

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

enableMajorityReadConcern Is Not Configurable

Starting in MongoDB 5.0, enableMajorityReadConcern and --enableMajorityReadConcern cannot be changed and are always set to true due to storage engine improvements.

In earlier versions of MongoDB, enableMajorityReadConcern and --enableMajorityReadConcern are configurable and can be set to false to prevent storage cache pressure from immobilizing a deployment with a three-member primary-secondary-arbiter (PSA) architecture.

If you are using a three-member primary-secondary-arbiter (PSA) architecture, consider the following:

  • The write concern "majority" can cause performance issues if a secondary is unavailable or lagging. For advice on how to mitigate these issues, see Mitigate Performance Issues with PSA Replica Set.
  • If you are using a global default "majority" and the write concern is less than the size of the majority, your queries may return stale (not fully replicated) data.

secondaryDelaySecs Configuration Setting

Starting in MongoDB 5.0, secondaryDelaySecs replaces slaveDelay. This change is not backwards compatible.

Host Names Required for Split Horizon DNS

To configure cluster nodes for split horizon DNS, use host names instead of IP addresses.

Starting in MongoDB v5.0, replSetInitiate and replSetReconfig reject configurations that use IP addresses instead of hostnames.

Use disableSplitHorizonIPCheck to modify nodes that cannot be updated to use host names. The parameter only applies to the configuration commands.

mongod and mongos do not rely on disableSplitHorizonIPCheck for validation at startup. Legacy mongod and mongos instances that use IP addresses instead of host names will start after an upgrade.

Instances that are configured with IP addresses log a warning to use host names instead of IP addresses.

Non-transactional Reads on config.transactions

Starting in MongoDB 5.0, non-transaction reads are not allowed on the config.transactions collection with the following read concerns and options:

Manual Oplog Writes

Starting in MongoDB 5.0, it is no longer possible to perform manual write operations to the oplog on a cluster running as a replica set. Performing write operations to the oplog when running as a standalone instance should only be done with guidance from MongoDB Support.

Automatic Reconfiguration for New Voting Replica Set Members

Starting in MongoDB 5.0, a newly added secondary does not count as a voting member and cannot be elected until it has reached the SECONDARY state.

When a new voting node is added to a replica set, replSetReconfig will internally add a newlyAdded field to the node’s configuration. Nodes with the newlyAdded field do not count towards the current number of voting nodes. When initial sync completes and the node reaches SECONDARY state, the newlyAdded field is automatically removed.

Note

  • Configurations that attempt to add a field named newlyAdded will error even if run with { force: true }.
  • If an existing node has a newlyAdded field, using rs.reconfig() to change the configuration will not remove the newlyAdded field. The newlyAdded field will be appended to the user provided configuration.
  • replSetGetConfig will remove any newlyAdded fields from its output. If you would like to see any newlyAdded fields, you can query the local.system.replset collection directly.

Removed Customizable Values For getLastErrorDefaults

Starting in MongoDB 5.0, you cannot specify a default write concern with settings.getLastErrorDefaults other than the default of { w: 1, wtimeout: 0 } . Instead, use the setDefaultRWConcern command to set the default read or write concern configuration for a replica set or sharded cluster.

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 ( { } ):

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

Update Operator Processing Order

Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. Fields with numeric names are processed in numeric order. See Update Operators Behavior for details.

Aggregation Pipeline Operator Parameter Limits

The following aggregation pipeline operators now have a 64-bit integer value maximum 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.

Field Type in MongoDB 5.0 Type in MongoDB 4.4 and earlier (mongod) Type in MongoDB 4.4 and earlier (mongos)
sizeOnDisk integer double integer
totalSize integer double integer
totalSizeMb integer not present (see below) integer

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

TLS Connection X509 Certificate Startup Warning

Starting in MongoDB 5.0, mongod and mongos now issue a startup warning when their certificates do not include a Subject Alternative Name attribute.

The following platforms do not support common name validation:

  • iOS 13 and higher
  • MacOS 10.15 and higher
  • Go 1.15 and higher

Clients using these platforms will not authenticate to MongoDB servers that use x.509 certificates whose hostnames are specified by CommonName attributes.

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. This change also applies to MongoDB 4.4.3+, 4.2.12+, 4.0.22+, and 3.6.22+.
  • 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.

Deprecations

Deprecated Description
mongo The legacy mongo shell has been deprecated in MongoDB v5.0. The replacement is mongosh.
db.printSlaveReplicationInfo() Deprecated since version 4.4.1: Use db.printSecondaryReplicationInfo() instead.
rs.printSlaveReplicationInfo() Deprecated since version 4.4.1: Use rs.printSecondaryReplicationInfo() instead.
security.clusterIpSourceWhitelist Deprecated in version 5.0: Use security.clusterIpSourceAllowlist instead.
--clusterIpSourceWhitelist Deprecated in version 5.0: Use --clusterIpSourceAllowlist instead.
logout Deprecated in version 5.0: Disconnect from the server to end your session instead.
db.logout() Deprecated in version 5.0: Disconnect from the server to end your session instead.
local audit message field Deprecated in version 5.0: Use the localEndpoint field in the clientMetadata audit message instead.

Deprecated Wire Protocol Opcodes

MongoDB 5.0 deprecates the following wire protocol opcodes:

  • OP_REPLY
  • OP_UPDATE
  • OP_INSERT
  • OP_QUERY
  • OP_GET_MORE
  • OP_DELETE
  • OP_KILL_CURSORS

Newer driver versions use OP_MSG instead of these deprecated opcodes.

The related commands and methods are also deprecated in MongoDB 5.0:

  • getLastError
  • db.getLastError()
  • db.getLastErrorObj()

To ensure your driver uses the most up-to-date wire protocol, upgrade your driver to a 5.0-compatible version.

Any code explicitly using getLastError, db.getLastError(), or db.getLastErrorObj() should instead use the CRUD API to issue the write with the desired write concern. Information about the success or failure of the write operation will be provided directly by the driver as a return value.

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:

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