Compatibility Changes in MongoDB 3.4¶

On this page

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

Sharded Cluster Changes¶

`shardsvr` Requirement¶

For a 3.4 sharded cluster, mongod instances for the shards must explicitly specify its role as a shardsvr, either via the configuration file setting sharding.clusterRole or via the command line option --shardsvr.

Note

Default port for mongod instances with the shardsvr role is 27018. To use a different port, specify net.port setting or --port option.

3.4 `mongos` and Earlier Versions of `mongod`¶

Version 3.4 mongos instances cannot connect to earlier versions of mongod instances.

Removal for Configuration Options¶

MongoDB 3.4 removes the following configuration options from the 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 config servers, 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 must be running as a replica set.

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

Initial Sync and `renameCollection`¶

If a collection is renamed on the sync source while an initial sync is running, the initial sync process fails and restarts to avoid possible data corruption. See SERVER-26117.

Operations that rename collections include:

renameCollection command and db.collection.renameCollection() method.
Aggregation (db.collection.aggregate() method or aggregate command) with the $out stage.
Map-reduce (db.collection.mapReduce() method or mapReduce command) with the out option.
convertToCapped command.

As such, when upgrading from 3.2.11 or earlier versions to 3.4, initial syncs may start failing if they encounter renameCollection operations.

In MongoDB versions 3.2.11 or earlier versions, initial sync process would proceed when encountering renameCollection operations, which could potentially corrupt data. See SERVER-4941.

Deprecated Operations¶

`group`¶

Mongodb 3.4 deprecates the following commands and mongo shell methods:

group command and db.collection.group(). Use db.collection.aggregate() or db.collection.mapReduce() instead.

`aggregate` without `cursor`¶

MongoDB 3.4 deprecates the use of aggregate command without the cursor option, unless the pipeline includes the explain option. When returning aggregation results inline using the aggregate command, specify the cursor option using the default batch size cursor: {} or specify the batch size in the cursor option 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 during create and db.createCollection() operations; namely, the specified options must be valid options supported by create and db.createCollection().

For example, the following operation is no longer valid:

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

Stricter Validation of Index Specifications¶

MongoDB 3.4 enforces a stricter validation of index specification during createIndexes and db.collection.createIndex() operations. The enforcement does not apply to existing indexes.

Stricter validation include the following:

Ensuring that the value in the index key pattern key: value is valid. Specifically, value can be:

Value	Description
A number greater than 0	For ascending index
A number less than 0	For descending index
String “text”, “2dsphere”, “2d”, or “hashed”	For special index types

For example, the following operations are no longer valid:

db.collection.createIndex( { x: 0 } );
db.collection.createIndex( { y: "text2d" } );
db.collection.createIndex( { z: NaN } );
db.collection.createIndex( { x: 1, unique: true } )

Ensuring that the specified index options are valid. Previous versions ignored invalid options. For example, the following operations are no longer valid:
```
db.collection.createIndex( { y: 1 }, { uniques2: true} );
db.collection.createIndex( { z: 1 }, { expireAfterSec: 350 } )
```

General Compatibility Changes¶

Removal of deprecated textSearchEnabled parameter. Starting from version 2.6, MongoDB enables the text search feature by default.
Removal of mongosniff. In MongoDB 3.4, mongosniff is replaced by mongoreplay, which offers a more flexible superset of mongosniff’s functionality.
Updates to $project specification behavior: empty documents in $project specifications produce an error.
If you include a hint() that specifies a sparse index when you perform a count() of all documents in a collection (i.e. with an empty query predicate), the sparse index is used even if the sparse index results in an incorrect count.
```
db.collection.insert({ _id: 1, y: 1 } );
db.collection.createIndex( { x: 1 }, { sparse: true } );

db.collection.find().hint( { x: 1 } ).count();
```
To obtain the correct count, do not hint() with a sparse index when performing a count of all documents in a collection.
```
db.collection.find().count();

db.collection.createIndex({ y: 1 });
db.collection.find().hint({ y: 1 }).count();
```
Previous versions ignored the hint if the use of the sparse index would result in an incomplete count.

User Roles Changes¶

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

`readAnyDatabase`	Starting in 3.4, to provide `read` privileges on the `local` database, create a user in the `admin` database with `read` role in the `local` database. See also `clusterManager` and `clusterMonitor` role for access to the `config` and `local` databases.
`readWriteAnyDatabase`	Starting in 3.4, to provide `readWrite` privileges on the `local` database, create a user in the `admin` database with `readWrite` role in the `local` database. See also `clusterManager` and `clusterMonitor` role for access to the `config` and `local` databases.
`userAdminAnyDatabase`
`dbAdminAnyDatabase`	Starting in 3.4, to provide `dbAdmin` privileges on the `local` database, create a user in the `admin` database with `dbAdmin` role in the `local` database. See also `clusterManager` and `clusterMonitor` role for access to the `config` and `local` databases.

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

Backwards Incompatible Features¶

The following 3.4 features persist data that earlier MongoDB versions cannot correctly handle and require that featureCompatibilityVersion be set to "3.4":

Views
Collation and Case-Insensitive Indexes
Decimal Type
Index version v: 2. v:2 indexes add support for collation and decimal data type. Earlier index versions support neither collation nor the decimal data type.

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

To set the featureCompatibilityVersion, see setFeatureCompatibilityVersion command.

Warning

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

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

3.4 deployments have the following default featureCompatibilityVersion values:

3.4 Deployments	`featureCompatibilityVersion`
For new deployments	`"3.4"`
For deployments upgraded from 3.2	`"3.2"` until you `setFeatureCompatibilityVersion` to `"3.4"`.

Earlier versions of MongoDB will not start if the database contains views, collation specifications, or v:2 indexes. If the data contains the decimal data type, operations against these documents may fail. See Downgrade MongoDB 3.4 to 3.2 for details. If you need to downgrade, you must remove data related to these incompatible features from your database before downgrading the binaries.

Driver Compatibility Changes¶

To use the various new features such as the new Decimal Type and Collation with a MongoDB driver, an upgrade to a driver version that supports these features is necessary.

Single Element `$in` With `upsert`¶

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

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

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

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

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

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

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

← 3.4 Changelog Upgrade a Standalone to 3.4 →