- Release Notes >
- Release Notes for MongoDB 4.2 >
- Compatibility Changes in MongoDB 4.2
Compatibility Changes in MongoDB 4.2¶
On this page
Removal of MMAPv1 Storage Engine¶
MongoDB 4.2 removes support for 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:
- Change Standalone to WiredTiger
- Change Replica Set to WiredTiger
- Change Sharded Cluster to WiredTiger
MMAPv1 Specific Configuration Options¶
MongoDB removes the following MMAPv1 specific configuration options:
| Removed Configuration File Setting | Removed 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 |
Note
Starting in version 4.2, MongoDB processes will not start with these options. Remove any MMAPv1 specific configuration options if using a WiredTiger deployment.
MMAPv1 Specific Parameters¶
MongoDB removes the following MMAPv1 parameters:
newCollectionsUsePowerOf2SizesreplIndexPrefetch
MMAPv1 Specific Command¶
MongoDB removes the MMAPv1 specific touch command.
MMAPv1 Specific Options for Commands and Methods¶
MongoDB removes the MMAPv1 specific options:
noPaddingandusePowerOf2SizesforcollModverboseforcollStatsflagsforcreatepaddingFactor,paddingBytes,preservePaddingfordb.createCollection().
MongoDB ignores the MMAPv1 specific option async for
fsync.
Removed or Deprecated Commands and Methods¶
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. 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:
Use
mongodumpto dump thetestdatabase to an archivemongodump-test-db:Use
mongorestorewith--nsFromand--nsToto restore (with database name change) from the archive:
Tip
Include additional options as necessary, such as to specify the uri or host, username, password and authentication database.
Alternatively, instead of using an archive file, you can
mongodump the test database to the standard
output stream and pipe into mongorestore:
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
geoNearcommand includes in its output a field nameddisthat included the distance information.For the
$geoNearstage, specify the distance field name indistanceField.The removed
geoNearcommand accepts abooleanvalue for theincludeLocsoption to include thelocfield.For the
$geoNearstage, specify the location field name inincludeLocs.The removed
geoNearcommand includes theavgDistanceandmaxDistanceof the returned results.You can use the aggregation pipeline to return the
avgDistanceandmaxDistanceas well. Specifically, after the$geoNearstage, include a$groupstage to calculate theavgDistanceandmaxDistance:
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 thecompactcommand. For details about the operation, seecompactcommand. - To rebuild indexes on a standalone, use the
reIndexcommand or its helperdb.collection.reIndex(). For details about the operation, seereIndexcommand anddb.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
mongoexportandmongoimport. - Users can use the aggregation pipeline
$outor$mergestages. - Write a script using the drivers.
Deprecated Plan Cache Commands/Methods¶
MongoDB deprecates the following:
PlanCache.getPlansByQuery()method/planCacheListPlanscommand.To get the cached query plans for a shape, use the$planCacheStatsaggregation stage instead. See Find Cache Entry Details for a Query Shape.PlanCache.listQueryShapes()method/planCacheListQueryShapescommand.To list the cached query shapes, use the$planCacheStatsaggregation stage instead. See List Query Shapes.
Aggregation¶
$out Stage Restrictions¶
$out and Views¶
The view definition pipeline cannot include
the $out stage. If you already have an existing view
that includes the $out stage, you can no longer create
new views from this existing view.
For existing views that include the $out stage, you
should either drop and
recreate the views without the
$out stage or use replace the view
definition with a new pipeline that does not contain the
$out stage.
$out and $lookup¶
$lookup stage cannot include the $out
stage in its nested pipeline field for the joined collection.$out and linearizable Read Concern Level¶
$out stage cannot be used in conjunction with read
concern "linearizable".$out and Explain¶
You cannot run the db.collection.explain() method (or the
explain command) in executionStats mode or
allPlansExecution mode if the aggregation pipeline contains the
$out stage.
If the aggregation pipeline contains the $out stage, to
view executionStats or allPlansExecution information, run
explain without the $out stage in order to return
explain results for the preceding stages.
Alternatively, you can run explain in queryPlanner mode for an
aggregation pipeline that contains the $out stage.
$out and majority Read Concern Level¶
Starting in MongoDB 4.2, you can specify read concern level "majority" for an
aggregation that includes an $out stage.
In MongoDB 4.0 and earlier, you cannot include the $out
stage to use "majority" read concern for the aggregation.
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.
Instead, you can rewrite the aggregation to the following pipeline:
See also
Transactions¶
- Starting in MongoDB 4.2, you cannot specify
killCursorsas the first operation in a transaction. - Starting in MongoDB 4.2, you cannot write to capped collections in transactions. Reads from capped collections are still supported in transactions.
- Starting in MongoDB 4.2, MongoDB removes the 16MB total size limit for a transaction. In version 4.2, MongoDB creates as many oplog entries as necessary to the encapsulate all write operations in a transaction. In previous versions, MongoDB creates a single entry for all write operations in a transaction, thereby imposing a 16MB total size limit for a transaction.
Change Streams¶
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).
See also
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.
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.
Extended JSON v2¶
Starting in version 4.2:
bsondump |
Uses Extended JSON v2.0 (Canonical mode) format. |
mongodump |
Use Extended JSON v2.0 (Canonical mode) format for the
metadata. Requires Tip In general, use corresponding versions of
|
mongoexport |
Creates output data in Extended JSON v2.0 (Relaxed mode) by
default.
Creates output data in Extended JSON v2.0 (Canonical mode) if
used with
--jsonFormat. |
mongoimport |
Expects import data to be in Extended JSON v2.0 (either
Relaxed or Canonical mode) by default.
Can recognize data that is in Extended JSON v1.0 format if the option
--legacy is specified.Tip In general, the versions of |
For details on MongoDB extended JSON v2, see MongoDB Extended JSON (v2).
--query Options¶
Starting in version 4.2, the query option for mongodump --query
and mongoexport --query must be in Extended JSON v2 format
(relaxed or canonical/strict mode), including enclosing the field
names and the operators in quotes, as in the following:
In earlier versions, the query options uses the Extended JSON v1 format and the field names and the operators do not need to be in quotes:
Replica Set State Changes¶
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.
4.2 Drivers Enable Retryable Writes by Default¶
The official MongoDB 3.6 and 4.0-compatible drivers required including the
retryWrites=true option in the connection
string to enable retryable writes for that connection.
The official MongoDB 4.2-compatible drivers enable Retryable Writes by
default. Applications upgrading to the 4.2-compatible drivers that require
retryable writes may omit the retryWrites=true
option. Applications upgrading to the 4.2-compatible drivers that require
disabling retryable writes must include
retryWrites=false in the connection string.
Important
The local database does not support retryable writes.
Applications which write to the local database will encounter
write errors upon upgrading to a 4.2-series driver unless
retryable writes are explicitly disabled.
General Changes¶
Indexes¶
Stronger Restrictions on reIndex¶
MongoDB implements a stronger restriction on running
reIndex command and db.collection.reIndex()
shell helper against a collection in a sharded cluster by disallowing
reIndex and db.collection.reIndex() on a
mongos.
Restriction on db.collection.dropIndex() Method¶
You cannot specify db.collection.dropIndex("*") to drop all non-_id indexes. Use
db.collection.dropIndexes() instead.
Duplicate Index Creation Attempt Error Message¶
MongoDB changes the returned response if you create an index with one name, and then try to create the index again with another name.
Starting in version 4.2, the createIndexes command and the
mongo shell helpers
db.collection.createIndex() and
db.collection.createIndexes() report an error if you create
an index with one name, and then try to create the same index again but
with another name.
In previous versions, MongoDB did not create the index again, but
would return a response object with ok value of 1 and a note
that implied that the index was not recreated. For example:
Hashed Index on PowerPC¶
For hashed indexes, MongoDB 4.2 ensures that the hashed value for the floating point value 263 on PowerPC is consistent with other platforms. In previous versions, the hashed value for the floating point value 263 on PowerPC is inconsistent with other platforms.
Although hashed indexes on a field that may contain floating point values greater than 253 is an unsupported configuration, clients may still insert documents where the indexed field has the value 263.
To list all hashed indexes for your deployment, see PowerPC and 263.
If the current MongoDB 4.0 sharded cluster on PowerPC contains hashed values for 263 as part of the shard key, additional considerations must be taken before upgrading the sharded cluster to 4.2. See Upgrade a Sharded Cluster to 4.2.
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$currentOpaggregation stage, along withcurrentOpcommand and thedb.currentOp()helper, now returns theoriginatingCommandfield as a nested field in the newcursorfield. In previous versions, theoriginatingCommandwas a top-level field for the associated"getmore"document. See also 4.2 currentOp Changes.
Server Status¶
- The
serverStatusanddb.serverStatusmethod returnopcountersandopcountersReplmetrics 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:Previously, the
syslogmessage text did not include the component. For example:Starting in MongoDB 4.2, the
getLogcommand truncates any event that contains more than 1024 characters. In earlier versions,getLogtruncates 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 specifiedDfor Debug level.
Wire Protocol¶
- MongoDB no longer supports the deprecated internal
OP_COMMANDand the correspondingOP_COMMANDREPLYwire protocol.
killCursors Changes¶
Transactions¶
Starting in MongoDB 4.2, you cannot specify killCursors as
the first operation in a transaction.
Privileges¶
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 in MongoDB 4.2+.
In MongoDB 3.6.3 through MongoDB 4.0.x, users required the
killCursors privilege in order to kill their own cursors
when access control is enabled.
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:
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.
- The explicit specification of nonAtomic: false option.
Balancer State and Autosplit¶
Starting in MongoDB 4.2:
The
balancerStartcommand and themongoshell helper methodssh.startBalancer()andsh.setBalancerState(true)also enable auto-splitting for the sharded cluster.To disable auto-splitting when the balancer is enabled, you can usesh.disableAutoSplit().The
balancerStopcommand and themongoshell helper methodssh.stopBalancer()andsh.setBalancerState(false)also disable auto-splitting for the sharded cluster.To enable auto-splitting when the balancer is disabled, you can usesh.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:
serverStatuscommand anddb.serverStatus()method.$currentOpaggregation pipeline stage,currentOpcommand, anddb.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:
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
mongosinstances andmongodshard members; or - Use the
flushRouterConfigcommand on allmongosinstances andmongodshard members before reading or writing to that database.
- Restart all
- If you use the
movePrimarycommand to move unsharded collections, either:- Restart all
mongosinstances andmongodshard members; or - Use the
flushRouterConfigcommand on allmongosinstances andmongodshard members before reading or writing to that database.
- Restart all
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 (and 4.0.9) 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 (and 4.0.9) 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:
trueon Windows.trueon Linux where MongoDB Enterprise binaries are linked againstlibldap_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:
Sharded Collections and Replace Documents¶
Starting in MongoDB 4.2,
Replace document operations, such as
db.collection.replaceOne()or db.collection.update( query, replacement, … ), attempt to target a single shard, first 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, the operation attempts to target using the replacement document.
For a replace document operation that includes
upsert: trueand is on a sharded collection, thefiltermust include an equality match on the full shard key.
4.2 Feature Compatibility¶
Some features in 4.2 require not just the 4.2 binaries but the featureCompatibilityVersion (fCV) set to 4.2. These features include:
- Distributed transactions.
- Removal of
Index Key Limitfor MongoDB versions with fCV set to 4.2+. In concert with the removal of this limit, thefailIndexKeyTooLongparameter has no effect for MongoDB versions with fCV set to 4.2+ and only applies for MongoDB 2.6 through MongoDB versions with fCV set to"4.0"or earlier. - Removal of
Index Name Lengthfor MongoDB versions with fCV set to 4.2+. - New internal format for unique indexes. The new format applies to both existing unique indexes as well as newly created/rebuilt unique indexes.
- Starting in MongoDB 4.2, users can no longer use the query filter
$type: 0as a synonym for$exists:false. To query for null or missing fields, see Query for Null or Missing Fields. - MongoDB 4.2 adds wildcard indexes to support workloads where users query against custom fields or a large variety of fields in a collection.