Compatibility Changes in MongoDB 4.0
On this page
The following 4.0 changes can affect the compatibility with older versions of MongoDB.
Remove Support for MONGODB-CR
Starting in version 4.0, MongoDB removes support for the deprecated
MongoDB Challenge-Response (MONGODB-CR
) authentication mechanism.
Since version 3.0, MongoDB has not supported the creation of
MONGODB-CR
users unless the deployment had been upgraded from a 2.6
or earlier deployment that already had MONGODB-CR
users and had not
upgraded the authentication schema.
If your deployment has user credentials stored in MONGODB-CR
schema, you must upgrade to Salted Challenge Response
Authentication Mechanism (SCRAM) before you
upgrade to version 4.0.
Removal of authSchemaUpgrade
Command
MongoDB 4.0 removes the authSchemaUpgrade
command . The command,
available in MongoDB 3.0 through MongoDB 3.6, supports the upgrade
process for systems with MONGODB-CR
users to SCRAM
users.
If your deployment has user credentials stored in MONGODB-CR
schema, you must upgrade to Salted Challenge Response
Authentication Mechanism (SCRAM) before you
upgrade to version 4.0.
Remove MONGODB-CR
Support from db.copyDatabase()
and copydb
The method db.copyDatabase()
cannot copy from a
mongod
instance that enforces MONGODB-CR
authentication.
The command copydb
cannot copy from a
mongod
instance that enforces MONGODB-CR
authentication. In conjunction with this change, MongoDB 4.0 removes
the copydbgetnonce
command.
Deprecate MMAPv1
Starting in version 4.0, MongoDB deprecates the MMAPv1 storage engine.
To change your MMAPv1 storage engine deployment to WiredTiger Storage Engine, see:
x.509 Authentication Certificate Restrictions
Starting in MongoDB 4.0, if you specify any of the following x.509 authentication options, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication:
--sslAllowInvalidCertificates
ornet.ssl.allowInvalidCertificates: true
for MongoDB 4.0 and later--tlsAllowInvalidCertificates
ornet.tls.allowInvalidCertificates: true
for MongoDB 4.2 and later
If you are using invalid certificates to perform x.509 authentication,
update your certificates to valid certificates. For example, you may
sign your existing certificates with a trusted CA, or if using a custom
CA, specify that CA using net.ssl.CAFile
.
Replica Sets
Remove pv0
for Replica Sets
Starting in version 4.0, MongoDB removes the deprecated replica set
protocol version 0 pv0
.
Before upgrading to MongoDB 4.0, you must upgrade to pv1
.
To upgrade to pv1
, connect a mongo
shell to the
replica set primary and perform the following sequence of operations:
cfg = rs.conf(); cfg.protocolVersion=1; rs.reconfig(cfg);
To reduce the likelihood of w:1
rollbacks,
you can also reconfigure the replica set to a higher
settings.catchUpTimeoutMillis
setting.
For more information on pv1
, see
Replica Set Protocol Version.
Remove Master-Slave Replication
MongoDB 4.0 removes support for the deprecated master-slave replication. Before you can upgrade to MongoDB 4.0, if your deployment uses master-slave replication, you must upgrade to a replica set.
To convert from master-slave replication to a replica set, see Convert a Master-Slave Deployment to a Replica Set.
Journaling and Replica Sets
Starting in MongoDB 4.0, you cannot specify --nojournal
option or
storage.journal.enabled: false
for replica set members that use the
WiredTiger storage engine.
Index Builds and Replica Sets
You cannot specify --noIndexBuildRetry
or storage.indexBuildRetry
with
--replSet
or
replication.replSetName
. That is, you cannot use
--noIndexBuildRetry
or storage.indexBuildRetry
for a
mongod
instance that is part of a replica set.
Rollback Limit
MongoDB 4.0 removes the limit on the amount of data that can be
rolled back. In previous versions,
a mongod
instance will not roll back more than 300
megabytes of data and requires manual intervention if more than 300
megabytes of data need to be rolled back.
Starting in MongoDB 4.0, the rollback time limit defaults to 1 day and
is configurable using the new parameter
rollbackTimeLimitSecs
. In earlier versions, the rollback
time limit is not configurable and is set to 30 minutes.
Sharded Clusters
mongos
uses "majority"
write concern
for the following operations that affect the sharded cluster
metadata:
Command | Method | Note |
---|---|---|
Changed in MongoDB 3.6 | ||
4.0
Feature Compatibility
Some features in 4.0 require not just the 4.0 binaries but the
featureCompatibilityVersion
set to 4.0
. These features include:
General
The geospatial query operators
$near
and$nearSphere
now supports querying on sharded collections.For the
create
command (and themongo
shelldb.createCollection()
method), you cannot set the optionautoIndexId
tofalse
when creating collections in databases other than thelocal
database.When authentication is enabled, running the
listDatabases
command without thelistDatabases
action privilege returns a list of all databases on which the user running the command has thefind
action privilege. In previous versions, running the command without thelistDatabases
action resulted in anUnauthorized
response.The default value of
taskExecutorPoolSize
changed from0
to1
. On Linux, to restore the previous behavior for a 4.0 deployment, settaskExecutorPoolSize
to0
and AsyncRequestsSenderUseBaton tofalse
.MongoDB 4.0 removes the ability to set
transportLayer
andnet.transportLayer
tolegacy
for mongod and mongos instances. ThetransportLayer
setting is automatically set toasio
and cannot be modified.Starting in MongoDB 4.0, the
reIndex
command and its helperdb.collection.reIndex()
take aGlobal exclusive (W) lock
and will block other operations until it finishes.If the value specified for fields other than
year
,isoYear
, andtimezone
is outside the valid range,$dateFromParts
carries or subtracts the difference from other date parts to calculate the date. In previous versions, values that exceed the range result in an error.Changed behavior of the
killCursors
privilege action. Prior to MongoDB 4.0, a user could kill any cursor if they knew that cursor's ID. As of MongoDB 4.0, thekillCursors
privilege grants the user the ability to kill any cursor associated with a currently authenticated user. If the user does not have permission to kill a cursor,killCursors
returns an error.MongoDB 4.0 adds a
killAnyCursor
privilege action that grants the user permission to kill any cursor for the specified collection.The
mongos
binary cannot connect tomongod
instances whose feature compatibility version (fCV) is greater than that of themongos
. For example, you cannot connect a MongoDB 4.0 versionmongos
to a 4.2 sharded cluster with fCV set to 4.2. You can, however, connect a MongoDB 4.0 versionmongos
to a 4.2 sharded cluster with fCV set to 4.0.
Starting in 4.0, MongoDB resolves
localhost
IP address as configured instead of assuming127.0.0.1
.
cursor.min()
and cursor.max()
If you use max()
with min()
to
specify a range, the bound specified by max()
must be
greater than the bound specified by min()
.
In previous versions, the bounds could be equal but would scan no index entries, always resulting in an empty result set.
Disable TLS 1.0
MongoDB binaries (mongod
, mongos
, and
mongo
) disables support for TLS 1.0 encryption on
systems where TLS 1.1+ is available.
If you need to support TLS 1.0:
For
mongod
instances, you can specifynone
tonet.ssl.disabledProtocols
or--sslDisabledProtocols none
.For
mongos
instances, you can specifynone
tonet.ssl.disabledProtocols
or--sslDisabledProtocols none
.For the
mongo
shell, you can specify--sslDisabledProtocols none
.The
--sslDisabledProtocols
option is available for themongo
shell in:MongoDB version 4.0+
MongoDB version 3.6.5+
MongoDB version 3.4.15+
On macOS, to connect mongo
shell version 3.6.4 or
earlier to a MongoDB 4.0+ deployment requires explicit enabling of TLS
1.0.
AES-GCM
MongoDB Enterprise on Windows no longer supports AES256-GCM
as a
block cipher for encryption at rest. This usage is only supported on Linux.
mongo
Shell
show collections
The mongosh
method show collections
is similar to:
db.runCommand( { listCollections: 1.0, authorizedCollections: true, nameOnly: true } )
For users with the required access,
show collections
lists the non-system collections for the database.For users without the required access,
show collections
lists only the collections for which the users has privileges.
When a version 4.0 mongo
shell is connected to an
earlier version MongoDB deployment that does not support
authorizedCollections
and nameOnly
options,
A user must have the required access to run
listCollections
.If a user does not have required access and runs
show collections
, MongoDB uses theauthenticatedUserPrivileges
field returned byconnectionStatus
to return an approximate list of collections for the user.
db.getCollectionNames()
The db.getCollectionNames()
is equivalent to:
db.runCommand( { listCollections: 1.0, authorizedCollections: true, nameOnly: true } )
For users with the required access (privileges that grant
listCollections
action on the database), the method lists the names of all collections for the database.For users without the required access, the method lists only the collections for which the users has privileges. For example, if a user has
find
on a specific collection in a database, the method would return just that collection.
Removed Binary and Deprecated Fields/Commands
mongoperf
MongoDB 4.0 removes the mongoperf
binary.
copydb
and clone
Commands
MongoDB 4.0 deprecates the copydb and the clone commands and their mongo shell helpers db.copyDatabase() and db.cloneDatabase().
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
mongodump
to dump thetest
database to an archivemongodump-test-db
:mongodump --archive="mongodump-test-db" --db=test Use
mongorestore
with--nsFrom
and--nsTo
to restore (with database name change) from the archive:mongorestore --archive="mongodump-test-db" --nsFrom='test.*' --nsTo='examples.*'
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
:
mongodump --archive --db=test | mongorestore --archive --nsFrom='test.*' --nsTo='examples.*'
Parameters
MongoDB removes the obsolete
logUserIds
parameter. Use Auditing instead.
$isolated
Operator
MongoDB drops support for the $isolated
operator. If you have an
existing partial index that includes the $isolated
operator or a
view that includes a $isolated
operator, recreate the index or
view without the operator in the definition before upgrading.
Instead of the $isolated
operator, use transactions instead.
geoNear
Command
MongoDB 4.0 deprecates the geoNear
command. Use one of the
following operations instead.
$geoNear
aggregation stage.$near
query operator.$nearSphere
query operator.
maxScan
Option
MongoDB deprecates the option maxScan
for the find
command and the mongo
shell helper
cursor.maxScan()
. Instead, use maxTimeMS
option or the
helper cursor.maxTimeMS()
.
Output Field Changes
The following fields returned from
replSetGetStatus
are deprecated:replSetGetStatus.syncingTo
replSetGetStatus.members[n].syncingTo
Use
replSetGetStatus.syncSourceHost
andreplSetGetStatus.members[n].syncSourceHost
instead.The
$currentOp
aggregation stage, thecurrentOp
command, anddb.currentOp()
helper no longer return thethreadId
field in their outputs.The
serverStatus
command now always returns0
for theasserts.warning
field.