翻译或纠错本页面

Compatibility Changes in MongoDB 3.0

On this page

The following 3.0 changes can affect the compatibility with older versions of MongoDB. See 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.mmapv1.journal.commitIntervalMs
storage.journal.debugFlags storage.mmapv1.journal.debugFlags
storage.nsSize storage.mmapv1.nsSize
storage.preallocDataFiles storage.mmapv1.preallocDataFiles
storage.quota.enforced storage.mmapv1.quota.enforced
storage.quota.maxFilesPerDB storage.mmapv1.quota.maxFilesPerDB
storage.smallFiles storage.mmapv1.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.

参见

Change Storage Engine to WiredTiger sections in 将MongoDB升级到3.0

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:

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 command 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).

警告

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:

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

参见

MongoDB Tools Enhancements

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:

注解

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-SHA-1 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 a limit().

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:

The minimum 3.0-compatible driver versions are:

Driver Language Minimum 3.0-Compatible Version
C 1.1.0
C++ 1.0.0
C# 1.10
Java 2.13
Node.js 1.4.29
Perl 0.708.0.0
PHP 1.6
Python 2.8
Motor 0.4
Ruby 1.12
Scala 2.8.0

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(), and db.collection.indexStats()

The following commands and methods are deprecated in MongoDB 3.0:

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.

© MongoDB, Inc 2008-2017. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.

Report a Problem