Navigation
This is an upcoming (i.e. in progress) version of the manual.
  • Release Notes >
  • Release Notes for MongoDB 4.2 (Development Series 4.1.x)

Release Notes for MongoDB 4.2 (Development Series 4.1.x)

MongoDB 4.2 is currently in development as part of the 4.1 development series.

Warning

While the 4.1-dev-series are available, these versions of MongoDB are for testing purposes only and not for production use.

Multi-Document Transactions: Sharded Clusters

MongoDB 4.2 adds the ability to perform multi-document transactions against sharded clusters.

Sharded Clusters Transactions (Beta)

To join the beta program for sharded clusters transactions, sign up at Distributed Transactions Beta Sign-Up.

The feature requires all members of the sharded clusters to have featureCompatibilityVersion of 4.2.

Removed MMAPv1 Storage Engine

MongoDB 4.2 removes the deprecated MMAPv1 storage engine.

If your 4.0 deployment uses MMAPv1, you must change the deployment to WiredTiger Storage Engine before upgrading to MongoDB 4.2. For details, see:

MMAPv1 Specific Configuration Options

MongoDB removes the following MMAPv1 specific configuration options:

Configuration File Setting Command-line Option
storage.mmapv1.journal.commitIntervalMs  
storage.mmapv1.journal.debugFlags mongod --journalOptions
storage.mmapv1.nsSize mongod --nssize
storage.mmapv1.preallocDataFiles mongod --noprealloc
storage.mmapv1.quota.enforced mongod --quota
storage.mmapv1.quota.maxFilesPerDB mongod --quotaFiles
storage.mmapv1.smallFiles mongod --smallfiles
storage.repairPath mongod --repairpath
replication.secondaryIndexPrefetch mongod --replIndexPrefetch

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 Binaries, Commands and Methods

MongoDB removes the MMAPv1 specific options:

Removed Commands and Methods

Removed Command Removed Method Notes
group db.collection.group() Use db.collection.aggregate() with the $group stage instead.
eval   The MongoDB 4.2 mongo shell methods db.eval() and db.collection.copyTo() can only be run when connected to MongoDB 4.0 or earlier.
copydb  

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

As an alternative, users can use mongodump and mongorestore or write a script using the drivers.

clone  

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

As an alternative, users can use mongodump and mongorestore or write a script using the drivers.

geoNear  

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

For more information, see Remove Support for the geoNear Command.

parallelCollectionScan    
repairDatabase db.repairDatabase() For more information, see Remove Support for the repairDatabase Command.

Remove maxScan Option

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.

Sharded Clusters

To maintain the atomicity guarantees of transactions across shards, use the coordinated backup and restore services provided by MongoDB Atlas or MongoDB Ops Manager. Manual backups and restores do not maintain the atomicity guarantees of transactions across shards.

Security Improvements

Add TLS Options

MongoDB 4.2 adds TLS options for the mongod, the mongos, and the mongo shell to replace the corresponding SSL options (deprecated in 4.2). The new TLS options provide identical functionality as the deprecated SSL options as MongoDB has always supported TLS 1.0 and later.

Deprecate SSL Options

MongoDB 4.2 deprecates the SSL options for the mongod, the mongos, and the mongo shell as well as the corresponding net.ssl Options configuration file options.

Use the new TLS options instead.

Add Parameter tlsWithholdClientCertificate

MongoDB 4.2 adds tlsWithholdClientCertificate to setParameter for mongod and mongos. Set to true to stop the mongod acting as a client during intra-cluster communication from sending its configured TLS certificate to the remote mongod. Use with settings allowing inbound connections without certificates.

Add tlsClusterCAFile Option

MongoDB 4.2 adds the --tlsClusterCAFile option/net.tls.clusterCAFile for mongod and mongos, which specifies a .pem file for validating the TLS certificate from a client establishing a connection. This lets you use separate Certificate Authorities to verify the client to server and server to client portions of the TLS handshake.

See also

Add TLS Options

passwordPrompt()

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

For example:

db.createUser( {
   user:"user123",
   pwd: passwordPrompt(),   // Instead of specifying the password in cleartext
   roles:[ "readWrite" ]
} )

Keyfile Format Change to YAML

Starting in MongoDB 4.2, keyfiles for internal membership authentication use YAML format to allow for multiple keys in a keyfile. The YAML format accepts content of:

  • a single key string (same as in earlier versions),
  • multiple key strings (each string must be enclosed in quotes), or
  • sequence of key strings.

The YAML format is compatible with the existing single-key keyfiles that use the text file format.

The new format allows for rolling upgrade of the keys without downtime. See Rotate Keys for Replica Sets and Rotate Keys for Sharded Clusters.

General Security Enhancements

Aggregation Improvements

$out Stage Enhancements

MongoDB 4.2 adds a new syntax for the $out aggregation stage. With the new syntax, you can:

  • merge the output with an existing collection
  • replace the content of an existing collection with the output
  • output to a collection in a different database
  • output to an existing sharded collection.

An example of using the new syntax to merge output with an existing collection in a different database is:

{ $out: { to : "employees", mode : "insertDocuments", db : "hr" } }

With the older, still-supported syntax, you can only replace the content of an existing collection with the output and you cannot output to a sharded collection.

An example of the old syntax is:

{ $out: "stock" }

Aggregation Trigonometry Expressions

MongoDB 4.2 adds new trigonometry expressions for use in aggregation pipelines.

Trigonometry expressions perform trigonometric operations on numbers. Values that represent angles are always input or output in radians. Use $degreesToRadians and $radiansToDegrees to convert between degree and radian measurements.

Name Description
$sin Returns the sine of a value that is measured in radians.
$cos Returns the cosine of a value that is measured in radians.
$tan Returns the tangent of a value that is measured in radians.
$asin Returns the inverse sin (arc sine) of a value in radians.
$acos Returns the inverse cosine (arc cosine) of a value in radians.
$atan Returns the inverse tangent (arc tangent) of a value in radians.
$atan2 Returns the inverse tangent (arc tangent) of y / x in radians, where y and x are the first and second values passed to the expression respectively.
$asinh Returns the inverse hyperbolic sine (hyperbolic arc sine) of a value in radians.
$acosh Returns the inverse hyperbolic cosine (hyperbolic arc cosine) of a value in radians.
$atanh Returns the inverse hyperbolic tangent (hyperbolic arc tangent) of a value in radians.
$degreesToRadians Converts a value from degrees to radians.
$radiansToDegrees Converts a value from radians to degrees.

Aggregation Arithmetic Expressions

MongoDB 4.2 adds the $round aggregation expression. Use $round to round numerical values to a specific digit or decimal place.

MongoDB 4.2 adds expanded functionality and new syntax to $trunc. Use $trunc with the new syntax to truncate numerical values to a specific digit or decimal place.

New Stages

$planCacheStats

MongoDB 4.2 adds a new aggregation pipeline stage $planCacheStats that provides plan cache information for a collection.

The $planCacheStats aggregation stage is preferred over the PlanCache.getPlansByQuery() method/planCacheListPlans command and PlanCache.listQueryShapes() method/planCacheListQueryShapes command.

$set

MongoDB 4.2 adds a new aggregation pipeline stage $set that adds new fields to documents. The stage outputs documents that contains all existing fields from the input documents as well as the newly added fields. The new $set stage is an alias to the $addFields stage.

Change Stream

startAfter Option for Change Streams

MongoDB 4.2 adds startAfter as an option for Change Streams, which starts a new change stream after the event indicated by a resume token. With this option, you can start a change stream from an invalidate event, thereby guaranteeing no missed notifications after the previous stream was invalidated.

Change Streams Resume Tokens

MongoDB 4.2 uses the version 1 (i.e. v1) change streams resume tokens, introduced in version 4.0.7.

Wildcard Indexes

MongoDB 4.2 adds wildcard indexes to support workloads where users query against custom fields or a large variety of fields in a collection. Administrators can create a wildcard index on a subset of fields or all fields in a document, instead of creating multiple indexes to support each user’s unique data access patterns.

MongoDB indexes any scalar values associated with the specified field path or paths, where the index key includes the full path to the field. For fields that contain subdocuments, MongoDB descends into the document and creates index keys for any field-value pairs in the document. For fields that are arrays, MongoDB creates an index key for each value in the array similar to multikey indexing behavior.

Important

Wildcard indexes are not designed to replace workload-based index planning. For more information on creating indexes to support queries, see Create Indexes to Support Your Queries.

Wildcard indexes are a type of sparse index, where the index only contains entries for fields with non-empty values, e.g. a scalar value or null.

You can create a wildcard index using the createIndexes database command or its shell helpers db.collection.createIndex() and db.collection.createIndexes(). For examples of creating a wildcard index, see Create a Wildcard Index.

You must set the mongod featureCompatibilityVersion (fCV) to 4.2 before you can create wildcard indexes. For instructions on setting the fCV, see 4.2 Feature Compatibility.

Wildcard Index Limitations

  • Wildcard indexes do not support the following index types or properties:

  • Wildcard indexes do not support the following query operator patterns:

  • You cannot shard a collection using a wildcard index as the shard key.

  • For queries that specify multiple fields covered by a wildcard index, the wildcard index can support at most one of the fields in the query. For queries using the query $or or the aggregation $or operators, the query planner can use a single wildcard index to satisfy the independent $or arguments. The query planner selects which wildcard index field to support for any given query.

    The query planner can also use the wildcard index to support sort() operations only if:

    • The sort field is included in the wildcard index, and
    • The sort field was also included in the query predicate, and
    • The query planner selected the sort field for satisfying the query.

Platform Support

  • MongoDB 4.2 (Community & Enterprise) adds support for:
    • Ubuntu 18.04 on ARM64.
  • MongoDB 4.2 (Community & Enterprise) removes support for:
    • Ubuntu 14.04.
    • macOS 10.11.

See Supported Platforms.

MongoDB Tools

FIPS Mode

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

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

--uri Option

Starting in version 4.2,

  • For the following command-line tools, if the write concern is specified in both the --uri connection string and the --writeConcern option, the --writeConcern option overrides the one in the connection string:
  • For the following command-line tools, if the read preference is specified in both the --uri connection string and the --readPreference option, the --readPreference option overrides the one in the connection string:

General Improvements

Traffic Recorder

MongoDB 4.2 adds a traffic recorder to capture all incoming wire protocol traffic to a mongod/mongos instance (and the instance’s responses) and output to a specified file.

The serverStatus command and the db.serverStatus() method include a new trafficRecording metrics in their output.

outputConfig Option

MongoDB 4.2 adds the --outputConfig option for mongod and mongos, which outputs the resolved YAML configuration document to stdout and halts the server instance.

Remove Index Key Size Limit

Starting in MongoDB 4.2, for featureCompatibilityVersion set to "4.2" or greater, MongoDB removes the Index Key Limit. For fCV set to "4.0", the limit still applies.

Remove Index Name Length Limit

Starting in version 4.2, for featureCompatibilityVersion set to "4.2" or greater, MongoDB removes the Index Name Length limit of 127 byte maximum. In previous versions or MongoDB versions with featureCompatibilityVersion (fCV) set to "4.0", index names must fall within the limit.

Improvements to dropIndexes

Drop multiple indexes

Starting in MongoDB 4.2, you can specify multiple indexes to the dropIndexes command and its mongo shell helper db.collection.dropIndexes(). To specify multiple indexes to drop, pass an array of index names to dropIndexes/db.collection.dropIndexes().

Externally Sourced Values for Configuration Files

MongoDB supports using expansion directives in configuration files to load externally sourced values. Expansion directives can load values for specific configuration file options or load the entire configuration file.

The following expansion directives are available:

Expansion Directive Description
__rest Allows users to specify a REST endpoint as the external source for configuration file options or the full configuration file.
__exec Allows users to specify a shell or terminal command as the external source for configuration file options or the full configuration file.

For complete documentation, see Externally Sourced Configuration File Values.

currentOp

MongoDB 4.2 adds a new option idleCursors to the $currentOp aggregation stage in order to return information on idle cursors.

In addition, MongoDB 4.2 adds the following new fields to the documents returned from the $currentOp aggregation stage, currentOp command, and db.currentOp() helper:

$currentOp currentOp/db.currentOp() Description
$currentOp.type currentOp.type Specifies whether the reported operation is an op, idleSession, or idleCursor.
$currentOp.cursor currentOp.cursor Specifies cursor details. Available when returning getmore operations or idleCursor information.
$currentOp.effectiveUsers currentOp.effectiveUsers Specifies users associated with the operation.
$currentOp.userImpersonators currentOp.userImpersonators Specifies users that are impersonating the effective users for the operation.

See also 4.2 current op compatibility changes

Logging

  • Added INITSYNC component to log messages.

  • Added ELECTION component to log messages.

  • For debug messages, include the verbosity level (i.e. D[1-5]). For example, if verbosity level is 2, MongoDB logs D2. In previous versions, MongoDB log messages only specified D for Debug level.

  • 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 ...
    
  • MongoDB 4.2 adds a usedDisk indicator to the profiler log messages and diagnostic log messages for the aggregate operation. The usedDisk indicates whether any stages of an aggregate operation wrote data to temporary files due to memory restrictions. For more information on aggregation memory restrictions, see Memory Restrictions.

  • Starting in version 4.2 (also available starting in 4.0.6), secondary members of a replica set now log oplog entries that take longer than the slow operation threshold to apply. These messages are logged for the secondaries under the REPL component with the text applied op: <oplog entry> took <num>ms.

    2018-11-16T12:31:35.886-0500 I REPL   [repl writer worker 13] applied op: command { ... }, took 112ms
    

    The slow oplog application logging on secondaries are:

    For more information on setting the slow operation threshold, see

  • 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 MongoDB 4.2 (and in 4.0.9), for slow operations, the profiler entries and diagnostic log messages include storage information.

  • Starting in MongoDB 4.2, the profiler entries and the diagnostic log messages (i.e. mongod/mongos log messages) for read/write operations include:

    • queryHash to help identify slow queries with the same query shape.
    • planCacheKey to provide more insight into the query plan cache for slow queries.

    See queryHash and planCacheKey.

zstd Availability

Starting in version 4.2, MongoDB supports zstd for:

queryHash and planCacheKey

  • queryHash

    To help identify slow queries with the same query shape, starting in MongoDB 4.2, each query shape is associated with a queryHash. The queryHash is a hexadecimal string that represents a hash of the query shape and is dependent only on the query shape.

    Note

    As with any hash function, two different query shapes may result in the same hash value. However, the occurrence of hash collisions between different query shapes is unlikely.

  • planCacheKey

    To provide more insight into the query plan cache, MongoDB 4.2 introduces the planCacheKey.

    planCacheKey is a hash of the key for the plan cache entry associated with the query.

    Note

    Unlike the queryHash, the planCacheKey is a function of both the query shape and the currently available indexes for the shape. That is, if indexes that can support the query shape are added/dropped, the planCacheKey value may change whereas the queryHash value would not change.

    See also

    planCacheKey

  • The queryHash and planCacheKey are available in:

The fields are also available in operations that return information about the query plan cache:

$regex and $not

Starting in MongoDB 4.2 (and 4.0.7), $not operator can perform logical NOT operation on $regex operator expressions as well as on regular expression objects (i.e. /pattern/).

In 4.0 and earlier versions, you could use $not operator with regular expression objects (i.e. /pattern/) but not with $regex operator expressions.

Kill Own Cursors

Starting in MongoDB 4.2, users can always kill their own cursors, regardless of whether the users have the privilege to killCursors. As such, the killCursors privilege has no effect starting in MongoDB 4.2.

In MongoDB 4.0, users required the killCursors privilege in order to kill their own cursors.

collStats Improvements

Starting in MongoDB 4.2, the $collStats aggregation, the collStats command, and the mongo shell helper db.collection.stats return information on indexes that are currently being built.

For details, see:

Starting in MongoDB 4.2, the $collStats aggregation, the collStats command, and the mongo shell helper db.collection.stats return the scaleFactor used to scale the various size data.

dbStats Improvements

Starting in MongoDB 4.2, the dbStats command, and the mongo shell helper db.stats() return the scaleFactor used to scale the various size data.

New Parameters

MongoDB 4.2 adds the parameter replBatchLimitBytes to configure the maximum oplog application batch size. The parameter is also available starting in MongoDB 4.0.10.

Retryable Writes on Certain Single-Document Upserts

MongoDB 4.2 will retry certain single-document upserts (update with upsert: true and multi: false) that encounter a duplicate key exception. See Duplicate Key Errors on Upsert for conditions.

Prior to MongoDB 4.2, MongoDB would not retry upsert operations that encountered a duplicate key error.

Changes Affecting Compatibility

Some changes can affect compatibility and may require user actions. For a detailed list of compatibility changes, see Compatibility Changes in MongoDB 4.2 (Development Series 4.1.x).

Upgrade Procedures

Feature Compatibility Version

To upgrade, the 4.0 instances must have featureCompatibilityVersion set to 4.0. To check the version:

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

For specific details on verifying and setting the featureCompatibilityVersion as well as information on other prerequisites/considerations for upgrades, refer to the individual upgrade instructions:

If you need guidance on upgrading to 4.2, MongoDB offers major version upgrade services to help ensure a smooth transition without interruption to your MongoDB application.

Report an Issue

To report an issue, see https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for instructions on how to file a JIRA ticket for the MongoDB server or one of the related projects.