Compatibility Changes in MongoDB 3.0
On this page
The following 3.0 changes can affect the compatibility with older versions of MongoDB. See Release Notes for MongoDB 3.0 for the full list of the 3.0 changes.
Storage Engine
Configuration File Options Changes
With the introduction of additional storage engines in 3.0, some configuration file options have changed:
Previous Setting | New Setting |
---|---|
storage.journal.commitIntervalMs | |
storage.journal.debugFlags | |
storage.nsSize | |
storage.preallocDataFiles | |
storage.quota.enforced | |
storage.quota.maxFilesPerDB | |
storage.smallFiles |
3.0 mongod
instances are backward compatible with existing
configuration files, but will issue warnings when if you attempt to
use the old settings.
Data Files Must Correspond to Configured Storage Engine
The files in the dbPath
directory must correspond
to the configured storage engine (i.e. --storageEngine
).
mongod
will not start if dbPath
contains
data files created by a storage engine other than the one specified by
--storageEngine
.
WiredTiger and Driver Version Compatibility
For MongoDB 3.0 deployments that use the WiredTiger storage engine, the
following operations return no output when issued in previous versions
of the mongo
shell or drivers:
show collections
show tables
Use the 3.0 mongo
shell or the 3.0 compatible version of the official drivers when
connecting to 3.0 mongod
instances that use WiredTiger. The
2.6.8 mongo
shell is also compatible with 3.0
mongod
instances that use WiredTiger.
db.fsyncLock()
is not Compatible with WiredTiger
With WiredTiger the db.fsyncLock()
and
db.fsyncUnlock()
operations cannot guarantee that the data
files do not change. As a result, do not use these methods to ensure
consistency for the purposes of creating backups.
Support for touch
Command
If a storage engine does not support the touch
, then the
touch
command will return an error.
The MMAPv1 storage engine supports
touch
.The WiredTiger storage engine does not support
touch
.
Dynamic Record Allocation
MongoDB 3.0 no longer supports dynamic record allocation and deprecates paddingFactor.
MongoDB 3.0 deprecates the newCollectionsUsePowerOf2Sizes
parameter such that you can no longer use the parameter to disable the
power of 2 sizes allocation for a collection. Instead, use the
collMod with the noPadding
flag or the db.createCollection() method with the noPadding
option. Only set noPadding
for collections with workloads that
consist only of inserts or in-place updates (such as incrementing
counters).
Warning
Only set noPadding
to true
for collections whose
workloads have no update operations that cause documents to grow,
such as for collections with workloads that are insert-only. For
more information, see No Padding Allocation Strategy.
For more information, see MMAPv1 Record Allocation Behavior Changes.
Replication Changes
Replica Set Oplog Format Change
MongoDB 3.0 is not compatible with oplog entries generated by versions of MongoDB before 2.2.1. If you upgrade from one of these versions, you must wait for new oplog entries to overwrite all old oplog entries generated by one of these versions before upgrading to 3.0.0 or earlier.
Secondaries may abort if they replay a pre-2.6 oplog with an index build operation that would fail on a 2.6 or later primary.
Replica Set Configuration Validation
MongoDB 3.0 provides a stricter validation of replica set configuration settings and replica sets invalid replica set configurations.
Stricter validations include:
Arbiters can only have
1
vote. Previously, arbiters could also have a value of0
formembers[n].votes
. If an arbiter has any value other than1
formembers[n].votes
, you must fix the setting.Non-arbiter members can only have value of
0
or1
formembers[n].votes
. If a non-arbiter member has any other value formembers[n].votes
, you must fix the setting._id
in the Replica Set Configuration must specify the same name as that specified by--replSet
orreplication.replSetName
. Otherwise, you must fix the setting.Disallows
0
forsettings.getLastErrorDefaults
value. Ifsettings.getLastErrorDefaults
value is0
, you must fix the setting.settings
can only contain the recognized settings. Previously, MongoDB ignored unrecognized settings. Ifsettings
contains unrecognized settings, you must remove the unrecognized settings.
To fix the settings before upgrading to MongoDB 3.0, connect to the
primary and reconfigure
your replica set to
valid configuration settings.
If you have already upgraded to MongoDB 3.0, you must downgrade
to MongoDB 2.6 first and then fix the
settings. Once you have reconfigured
the
replica set, you can re-upgrade to MongoDB 3.0.
Change of w: majority
Semantics
A write concern with a w: majority value is satisfied when a majority of the voting members replicates a write operation. In previous versions, majority referred a majority of all voting and non-voting members of the set.
Remove local.slaves
Collection
MongoDB 3.0 removes the local.slaves
collection that tracked the
secondaries' replication progress. To track the replication progress,
use the rs.status()
method.
Replica Set State Change
The FATAL
replica set state does not exist as of 3.0.0.
HTTP Interface
The HTTP Interface (i.e. net.http.enabled
) no longer
reports replication data.
MongoDB Tools Changes
Require a Running MongoDB Instance
The 3.0 versions of MongoDB tools, mongodump
,
mongorestore
, mongoexport
,
mongoimport
, mongofiles
, and
mongooplog
, must connect to running MongoDB instances and
these tools cannot directly modify the data files with --dbpath
as in previous versions. Ensure that you start your mongod
instance(s) before using these tools.
Removed Options
Removed
--dbpath
,--journal
, and--filter
options formongodump
,mongorestore
,mongoimport
,mongoexport
, andbsondump
.Removed
--locks
option formongotop
.Removed
--noobjcheck
option forbsondump
andmongorestore
.Removed
--csv
option formongoexport
. Use the new--type
option to specify the export format type (csv
orjson
).
Sharded Cluster Setting
Remove releaseConnectionsAfterResponse
Parameter
MongoDB now always releases connections after response.
releaseConnectionsAfterResponse
parameter is no longer available.
Security Changes
MongoDB 2.4 User Model Removed
MongoDB 3.0 completely removes support for the deprecated 2.4 user
model. MongoDB 3.0 will exit with an error message if there is user
data with the 2.4 schema, i.e. if authSchema
version is less than
3
.
To verify the version of your existing 2.6 schema, query the
system.version
collection in the admin
database:
Note
You must have privileges to query the collection.
use admin db.system.version.find( { _id: "authSchema" })
If you are currently using auth
and you have schema version 2 or 3,
the query returns the currentVersion
of the existing authSchema
.
If you do not currently have any users or you are using
authSchema
version 1, the query will not return any result.
If your authSchema
version is less
than 3
or the query does not return any results, see Upgrade User Authorization Data to 2.6 Format to
upgrade the authSchema
version before upgrading to MongoDB 3.0.
After upgrading MongoDB to 3.0 from 2.6, to use the new SCRAM-SHA-1
challenge-response mechanism if you have existing user data, you will
need to upgrade the authentication schema a second time. This upgrades
the MONGODB-CR
user model to SCRAM-SHA-1
user model. See
Upgrade to SCRAM for details.
Localhost Exception Changed
In 3.0, the localhost exception changed so that these connections only
have access to create the first user on the admin
database. In previous versions, connections that gained access using
the localhost exception had unrestricted access to the MongoDB
instance.
See Localhost Exception for more information.
db.addUser()
Removed
3.0 removes the legacy db.addUser()
method. Use
db.createUser()
and db.updateUser()
instead.
TLS/SSL Configuration Option Changes
MongoDB 3.0 introduced new net.ssl.allowConnectionsWithoutCertificates
configuration file setting and --sslAllowConnectionsWithoutCertificates
command line option for mongod
and mongos
. These
options replace previous net.ssl.weakCertificateValidation
and
--sslWeakCertificateValidation
options, which became
aliases. Update your configuration to ensure future compatibility.
TLS/SSL Certificates Validation
By default, when running in SSL mode, MongoDB instances will only
start if its certificate (i.e. net.ssl.PEMKeyFile
) is valid.
You can disable this behavior with the
net.ssl.allowInvalidCertificates
setting or the
--sslAllowInvalidCertificates
command line option.
To start the mongo
shell with --ssl
, you must explicitly
specify either the --sslCAFile
or --sslAllowInvalidCertificates
option at startup. See TLS/SSL Configuration for Clients for more
information.
TLS/SSL Certificate Hostname Validation
By default, MongoDB validates the hostnames of hosts attempting to connect
using certificates against the hostnames listed in those certificates. In
certain deployment situations this behavior may be undesirable. It is now
possible to disable such hostname validation without disabling validation of
the rest of the certificate information with the
net.ssl.allowInvalidHostnames
setting or the
--sslAllowInvalidHostnames
command line option.
SSLv3 Ciphers Disabled
In light of vulnerabilities in legacy SSL ciphers, these ciphers have been explicitly disabled in MongoDB. No configuration changes are necessary.
mongo
Shell Version Compatibility
Versions of the mongo
shell before 3.0 are not
compatible with 3.0 deployments of MongoDB that enforce access
control. If you have a 3.0 MongoDB deployment that requires
access control, you must use 3.0 versions of the mongo
shell.
HTTP Status Interface and REST API Compatibility
Neither the HTTP status interface nor the REST API support the SCRAM-SHA-1 challenge-response user authentication mechanism introduced in version 3.0.
Indexes
Remove dropDups
Option
dropDups
option is no longer available for
createIndex()
,
ensureIndex()
, and createIndexes
.
Changes to Restart Behavior during Background Indexing
For 3.0 mongod
instances, if a background index build is in
progress when the mongod
process terminates, when the
instance restarts the index build will restart as foreground index
build. If the index build encounters any errors, such as a duplicate
key error, the mongod
will exit with an error.
To start the mongod
after a failed index build, use the
storage.indexBuildRetry
or --noIndexBuildRetry
to skip the
index build on start up.
2d
Indexes and Geospatial Near Queries
For $near
queries that use a 2d index:
MongoDB no longer uses a default limit of 100 documents.
Specifying a
batchSize()
is no longer analogous to specifying alimit()
.
For $nearSphere
queries that use a 2d index,
MongoDB no longer uses a default limit of 100 documents.
Driver Compatibility Changes
Each officially supported driver has release a version that includes support for all new features introduced in MongoDB 3.0. Upgrading to one of these version is strongly recommended as part of the upgrade process.
A driver upgrade is necessary in certain scenarios due to changes in functionality:
Use of the
SCRAM-SHA-1
authentication methodUse of functionality that calls
listIndexes
orlistCollections
The minimum 3.0-compatible driver versions are:
General Compatibility Changes
findAndModify
Return Document
In MongoDB 3.0, when performing an update with
findAndModify
that also specifies upsert: true
and
either the new
option is not set or new: false
,
findAndModify
returns null
in the value
field if
the query
does not match any document, regardless of the sort
specification.
In previous versions, findAndModify
returns an empty
document {}
in the value
field if a sort
is specified for
the update, and upsert: true
, and the new
option is not set or
new: false
.
upsert:true
with a Dotted _id
Query
When you execute an update()
with upsert:
true
and the query matches no existing document, MongoDB will refuse
to insert a new document if the query specifies conditions on the
_id
field using dot notation.
This restriction ensures that the order of fields embedded in the
_id
document is well-defined and not bound to the order specified in
the query.
If you attempt to insert a document in this way, MongoDB will raise an
error. For example, consider the following update operation. Since the
update operation specifies upsert:true
and the query specifies
conditions on the _id
field using dot notation, then the update will
result in an error when constructing the document to insert.
db.collection.update( { "_id.name": "Robert Frost", "_id.uid": 0 }, { "categories": ["poet", "playwright"] }, { upsert: true } )
Deprecate Access to system.indexes
and system.namespaces
MongoDB 3.0 deprecates direct access to system.indexes
and
system.namespaces
collections. Use the createIndexes
and listIndexes
commands instead. See also
WiredTiger and Driver Version Compatibility.
Collection Name Validation
MongoDB 3.0 more consistently enforces the collection naming restrictions. Ensure your application does not create or depend on invalid collection names.
Platform Support
Commercial support is no longer provided for MongoDB on 32-bit platforms (Linux and Windows). Linux RPM and DEB packages are also no longer available. However, binary archives are still available.
Linux Package Repositories
Non-Enterprise MongoDB Linux packages for 3.0 and later are in a new repository. Follow the appropriate Linux installation instructions to install the 3.0 packages from the new location.
Removed/Deprecated Commands
The following commands and methods are no longer available in MongoDB 3.0:
closeAllDatabases
getoptime
text
indexStats
,db.collection.getIndexStats()
, anddb.collection.indexStats()
The following commands and methods are deprecated in MongoDB 3.0:
diagLogging
eval
,db.eval()
db.collection.copyTo()
In addition, you cannot use the now deprecated eval
command or the db.eval()
method to invoke mapReduce
or
db.collection.mapReduce()
.
Date and Timestamp Comparison Order
MongoDB 3.0 no longer treats the Timestamp and the Date data types as equivalent for comparison purposes. Instead, the Timestamp data type has a higher comparison/sort order (i.e. is "greater") than the Date data type. If your application relies on the equivalent comparison/sort order of Date and Timestamp objects, modify your application accordingly before upgrading.
Server Status Output Change
The serverStatus
command and the
db.serverStatus()
method no longer return workingSet
,
indexCounters
, and recordStats
sections in the output.
Unix Socket Permissions Change
Unix domain socket file permission now defaults to 0700
. To change
the permission, MongoDB provides the
net.unixDomainSocket.filePermissions
setting as well as the
--filePermission
option.
cloneCollection
The cloneCollection command and the db.cloneCollection() method will now return an error if the collection already exists, instead of inserting into it.