Compatibility Changes in MongoDB 3.4

The following 3.4 changes can affect the compatibility with olderversions of MongoDB.

See also Release Notes for MongoDB 3.4.

Sharded Cluster Changes

shardsvr Requirement

For a 3.4 sharded cluster, mongod instances for theshards must explicitly specify its role as a shardsvr,either via the configuration file settingsharding.clusterRole or via the command line option—shardsvr.

Note

Default port for mongod instances with the shardsvrrole is 27018. To use a different port, specifynet.port setting or —port option.

3.4 mongos and Earlier Versions of mongod

Version 3.4 mongos instances cannot connect to earlierversions of mongod instances.

Removal for Configuration Options

MongoDB 3.4 removes the following configuration options fromthe mongos:

  • sharding.chunkSize configuration file setting and—chunkSize command-line option
  • sharding.autoSplit configuration file setting and—noAutoSplit command-line option

Removal of Support for SCCC Config Servers

3.4 sharded clusters no longer support the use of mirrored (SCCC)mongod instances as config servers. The use of SCCC configservers, deprecated in the 3.2 release, is no longer valid. Instead,deploy your config servers as a replica set (CSRS).

To upgrade your sharded cluster to version 3.4, the config servers mustbe running as a replica set.

To convert your existing config servers from SCCC to CSRS, see theMongoDB 3.4 manual Upgrade Config Servers to Replica Set.

See also

Sharded Cluster Release Notes Section

Initial Sync and renameCollection

If a collection is renamed on the sync source while an initialsync is running, the initial sync processfails and restarts to avoid possible data corruption. SeeSERVER-26117.

Operations that rename collections include:

As such, when upgrading from 3.2.11 or earlier versions to 3.4, initialsyncs may start failing if they encounter renameCollectionoperations.

In MongoDB versions 3.2.11 or earlier versions, initial sync processwould proceed when encountering renameCollection operations, whichcould potentially corrupt data. See SERVER-4941.

Deprecated Operations

group

Mongodb 3.4 deprecates the following commands and mongoshell methods:

Use db.collection.aggregate() ordb.collection.mapReduce() instead.

aggregate without cursor

MongoDB 3.6 removes the use of aggregate commandwithout the cursor option unless the command includes theexplain option. Unless you include the explain option, you mustspecify the cursor option.

  • To indicate a cursor with the default batch size, specify cursor:{}.
  • To indicate a cursor with a non-default batch size, use cursor: {batchSize: <num> }.

Stricter Validation of Collection and Index Specifications

Stricter Validation of Collection Options

MongoDB 3.4 enforces a stricter validation of collection options duringcreate and db.createCollection() operations;namely, the specified options must be valid options supported bycreate and db.createCollection().

For example, the following operation is no longer valid:

  1. db.createCollection( "myCappedCollection", { cappedtypo: true, size: 5242880 } )

Stricter Validation of Index Specifications

MongoDB 3.4 enforces a stricter validation of index specificationduring createIndexes anddb.collection.createIndex() operations. The enforcement doesnot apply to existing indexes.

Stricter validation include the following:

  • Ensuring that the value in the index key pattern key: value isvalid. Specifically, value can be:

ValueDescriptionA number greater than 0For ascending indexA number less than 0For descending indexString “text”, “2dsphere”, “2d”, or “hashed”For special index types

For example, the following operations are no longer valid:

  1. db.collection.createIndex( { x: 0 } );
  2. db.collection.createIndex( { y: "text2d" } );
  3. db.collection.createIndex( { z: NaN } );
  4. db.collection.createIndex( { x: 1, unique: true } )
  • Ensuring that the specified index options are valid. Previous versions ignoredinvalid options. For example, the following operations are no longervalid:
  1. db.collection.createIndex( { y: 1 }, { uniques2: true} );
  2. db.collection.createIndex( { z: 1 }, { expireAfterSec: 350 } )

General Compatibility Changes

  • Updates to namespace restrictions: in MongodDB 3.4, the $character is no longer supported in database names.

Important

You must drop any databases that contain a $ in its namebefore upgrading to MongoDB 3.4.

  • Removal of deprecated textSearchEnabled parameter. Starting fromversion 2.6, MongoDB enables the text search feature by default.

  • Removal of mongosniff. In MongoDB 3.4,mongosniff is replaced by mongoreplay, whichoffers a more flexible superset of mongosniff’sfunctionality.

  • Updates to $project specification behavior: emptydocuments in $project specifications produce an error.

  • If you include a hint() that specifies asparse index when you perform acount() of all documents in a collection (i.e. withan empty query predicate), the sparse index is used even if the sparseindex results in an incorrect count.

  1. db.collection.insert({ _id: 1, y: 1 } );
  2. db.collection.createIndex( { x: 1 }, { sparse: true } );
  3.  
  4. db.collection.find().hint( { x: 1 } ).count();

To obtain the correct count, do not hint() with asparse index when performing a count of alldocuments in a collection.

  1. db.collection.find().count();
  2.  
  3. db.collection.createIndex({ y: 1 });
  4. db.collection.find().hint({ y: 1 }).count();

Previous versions ignored the hint if the use of the sparse indexwould result in an incomplete count.

User Roles Changes

The privileges of the following built-in roles no longer apply to thelocal and config databases:

readAnyDatabaseStarting in 3.4, to provide read privileges on the localdatabase, create a user in the admin database withread role in the local database. See alsoclusterManager and clusterMonitor rolefor access to the config and local databases.
readWriteAnyDatabaseStarting in 3.4, to provide readWrite privileges on thelocal database, create a user in the admin database withreadWrite role in the local database. See alsoclusterManager and clusterMonitor rolefor access to the config and local databases.
userAdminAnyDatabase
dbAdminAnyDatabaseStarting in 3.4, to provide dbAdmin privileges on thelocal database, create a user in the admin database withdbAdmin role in the local database. See alsoclusterManager and clusterMonitor rolefor access to the config and local databases.

Correspondingly, the following built-in roles include additional readand write privileges on local and config databases:

Backwards Incompatible Features

The following 3.4 features persist data that earlier MongoDB versionscannot correctly handle and require thatfeatureCompatibilityVersion be set to "3.4":

If featureCompatibilityVersion: "3.4", indexes created in MongoDB3.4 default to v: 2 . Otherwise, new indexes default to v: 1.

To set the featureCompatibilityVersion, seesetFeatureCompatibilityVersion command.

Warning

Enabling these backwards-incompatible features can complicatethe downgrade process. For details,see Remove 3.4 Incompatible Features.

It is recommended that after upgrading, you allow your deployment torun without enabling these features for a burn-in period to ensurethe likelihood of downgrade is minimal. When you are confident thatthe likelihood of downgrade is minimal, enable these features.

3.4 deployments have the following defaultfeatureCompatibilityVersion values:

3.4 DeploymentsfeatureCompatibilityVersion
For new deployments"3.4"
For deployments upgraded from 3.2"3.2" until you setFeatureCompatibilityVersionto "3.4".

Earlier versions of MongoDB will not start if the database containsviews, collation specifications, or v:2 indexes. If the datacontains the decimal data type, operations against these documents mayfail. See Downgrade MongoDB 3.4 to 3.2 for details. If you needto downgrade, you must remove data related to these incompatiblefeatures from your database before downgrading the binaries.

Driver Compatibility Changes

To use the various new features such as the new Decimal Type andCollation with a MongoDB driver, an upgrade to a driver versionthat supports these features is necessary.

Single Element $in With upsert

When an upsert operation finds no matching documents, it creates adocument to insert based on the equality statements in the query and thenapplies the update modifiers to this seeded document. For example:

  1. db.c.drop()
  2. db.c.update( { a : 3, b: "foo" }, { $set : { c : 15 } }, { upsert : true } )
  3. db.c.find()
  4. { "_id" : ObjectId("59c03009529946822d0afb8c"), "a" : 3, "b" : "foo", "c" : 15 }

Prior to 3.4, a single-element $in query did not seed the upsertdocument. In the example below, the $addToSet update expressionis successful because of this behavior:

  1. db.c.drop()
  2. db.c.update( { a : { $in : [1] } }, { $addToSet : { a : 2 } }, { upsert : true } )
  3. db.c.find()
  4. { "_id" : ObjectId("58bdb00eb39e8f87607e9222"), "a" : [ 2 ] }

In 3.4 and newer versions, however, a single-element $in behaveslike an equality statement for upserts. If the query includes this conditionon a field, the field value is set to the element.

As a result of this behavior, certain upsert operations may fail in 3.4. Inexample above, the $addToSet upsert would fail because the afield would be seeded with a single value, and $addToSet cannot beapplied to a scalar field. To avoid this error, you must wrap the $inexpression in an $elemMatch expression:

  1. db.c.drop()
  2. db.c.update(
  3.    { a : { $elemMatch : { $in : [ 2 ] } } },
  4.    { $addToSet : { a: 3 } },
  5.    { upsert: true } )
  6. db.c.find()
  7. { "_id" : ObjectId("..."), "a" : [ 3 ] }