Navigation
This version of the documentation is archived and no longer supported.

setFeatureCompatibilityVersion

Definition

setFeatureCompatibilityVersion

New in version 3.4.

Enables or disables MongoDB 3.4 features that persist data that are backwards-incompatible with MongoDB 3.2. You can only issue the setFeatureCompatibilityVersion against the admin database.

The command takes the following form:

db.adminCommand( { setFeatureCompatibilityVersion: <version> } )

where <version> can be:

  • "3.4" to enable the backward incompatible features, or
  • "3.2" to disable these features.

Note

  • For a standalone, run the command on the standalone mongod instance.
  • For a replica set, run the command on the primary. A majority of the data-bearing members must be available.
  • For a sharded cluster, run the command on a mongos instance.

Behavior

Affected Features

The following 3.4 features persist data that earlier MongogDB 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.

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.

Conflicts with Background Operations

Certain background operations, such as index builds, may prevent execution of setFeatureCompatibilityVersion. Use currentOp to identify any ongoing operations.

Default Values

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

Idempotency

This command must perform writes to an internal system collection. If for any reason the command does not complete successfully, you can safely retry the command as the operation is idempotent.

Access Control

To run setFeatureCompatibilityVersion if your deployment enforces access control, you must have a role that grants the following privilege:

{
  resource: { db: "$setFeatureCompatibilityVersion", collection: "version" },
  actions: [ "update" ]
}

The clusterAdmin and clusterManager roles grant privileges to run setFeatureCompatibilityVersion. [1]

The clusterAdmin also grants privileges to view featureCompatibilityVersion.

Alternatively, you can create a custom role with just the privileges to run setFeatureCompatibilityVersion and getParameter to view featureCompatibilityVersion:

db.getSiblingDB("admin").createRole({
   role: "fcvRole",
   privileges: [
      { resource: { db: "$setFeatureCompatibilityVersion", collection: "version" }, actions: [ "update" ] },
      { resource: { cluster: true }, actions: [ "getParameter" ] }
   ],
   roles: [ ]
})
[1]For MongoDB 3.4.0-3.4.16, readWriteAnyDatabase role also grants privileges to run setFeatureCompatibilityVersion.

Examples

Enable 3.4 Backwards Incompatible Features

To enable the 3.4 backwards-incompatible features, run the setFeatureCompatibilityVersion command against the admin database:

Note

  • For a standalone, run the command on the standalone mongod instance.
  • For a replica set, run the command on the primary. A majority of the data-bearing members must be available.
  • For a sharded cluster, run the command on a mongos instance.
db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )

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.

Disable 3.4 Backwards Incompatible Features

To disable the 3.4 backwards-incompatible features, run the setFeatureCompatibilityVersion command against the admin database:

Note

  • For a standalone, run the command on the standalone mongod instance.
  • For a replica set, run the command on the primary. A majority of the data-bearing members must be available.
  • For a sharded cluster, run the command on a mongos instance.
db.adminCommand( { setFeatureCompatibilityVersion: "3.2" } )

Setting the featureCompatibilityVersion to "3.2 disables the use of these features and does not remove existing usage of these features.

If performed as part of a downgrade to 3.2 procedure, you must also manually remove the existing usage before downgrading the binaries. For details, see Remove 3.4 Incompatible Features.

View FeatureCompatibilityVersion

To view the featureCompatibilityVersion for a mongod instance, run the following command on a mongod instance:

Note

The operation is undefined on the mongos instances.

db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )