Docs Menu
Docs Home
/
MongoDB Manual
/
Release Notes
/
5.0

Compatibility Changes in MongoDB 5.0

On this page

  • Certain Commands Only Accept Recognized Parameters
  • Removed Commands
  • Removed Parameters
  • Removed Index Types
  • Removed Metrics
  • Removed Raspberry Pi Support
  • TTL expireAfterSeconds Behavior When Set to NaN
  • Shell Changes
  • Replica Sets
  • Read Concern snapshot on Capped Collections
  • local is the Default Read Concern
  • New cursor.map() Return Type
  • Update Operator Changes
  • $setWindowFields Stage with Transactions and Snapshot Read Concern
  • Aggregation Pipeline Operator Parameter Limits
  • listDatabases Output Changes
  • Security
  • Map-Reduce
  • Auditing
  • Reduce Risk of Stale Chunks in Sharded Transactions
  • General Changes
  • 5.0 Feature Compatibility

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()
db.collection.save()
Not available
Mongo.getSecondaryOk()
Mongo.isCausalConsistency
Not available
Mongo.setSecondaryOk()
rs.secondaryOk()
Not available
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.
connPoolMaxShardedConnsPerHost
MongoDB 5.0 removes the connPoolMaxShardedConnsPerHost server parameter.
connPoolMaxShardedInUseConnsPerHost
MongoDB 5.0 removes the connPoolMaxShardedInUseConnsPerHost server parameter.
shardedConnPoolIdleTimeoutMinutes
MongoDB 5.0 removes the shardedConnPoolIdleTimeoutMinutes server parameter.

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.

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

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:

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

Replica Set Write Acknowledgement

Starting in MongoDB 5.0, replica set members in the STARTUP2 state do not participate in write majorities.

Tip

See also:

Write Concern for Replica Sets

Implicit Default Write Concern

Starting in MongoDB 5.0, the implicit default write concern is w: majority. However, special considerations are made for deployments containing arbiters:

  • The voting majority of a replica set is 1 plus half the number of voting members, rounded down. If the number of data-bearing voting members is not greater than the voting majority, the default write concern is { w: 1 }.

  • In all other scenarios, the default write concern is { w: "majority" }.

Specifically, MongoDB uses the following formula to determine the default write concern:

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

For example, consider the following deployments and their respective default write concerns:

Non-Arbiters
Arbiters
Voting Nodes
Majority of Voting Nodes
Implicit Default Write Concern
2
1
3
2
{ w: 1 }
4
1
5
3
{ w: "majority" }

  • In the first example:

    • There are 2 non-arbiters and 1 arbiter for a total of 3 voting nodes.

    • The majority of voting nodes (1 plus half of 3, rounded down) is 2.

    • The number of non-arbiters (2) is equal to the majority of voting nodes (2), resulting in an implicit write concern of { w: 1 }.

  • In the second example:

    • There are 4 non-arbiters and 1 arbiter for a total of 5 voting nodes.

    • The majority of voting nodes (1 plus half of 5, rounded down) is 3.

    • The number of non-arbiters (4) is greater than the majority of voting nodes (3), resulting in an implicit write concern of { w: "majority" }.

The { w: "majority" } default write concern provides a stronger durability guarantee in the event of an election, or if replica set members become unavailable.

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.

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

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.

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

Deprecated since version 4.4.1: Use db.printSecondaryReplicationInfo() instead.

Deprecated since version 4.4.1: Use rs.printSecondaryReplicationInfo() instead.

Deprecated in version 5.0: Use security.clusterIpSourceAllowlist instead.
Deprecated in version 5.0: Use --clusterIpSourceAllowlist instead.
Deprecated in version 5.0: Disconnect from the server to end your session instead.
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:

Back

5.0

Next

Upgrade 4.4 to 5.0