setFeatureCompatibilityVersion

Definition

• setFeatureCompatibilityVersion

New in version 3.4.

Changed in version 3.6.

Enables or disables the features that persist data incompatible withearlier versions of MongoDB. You can only issue thesetFeatureCompatibilityVersion against the admindatabase.

The command takes the following form:

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

The values for the version are:

VersionDescription"4.2"Available on MongoDB 4.2 Deployments

Enables the 4.2 features that persist data incompatiblewith MongoDB 4.0.

Enabling these backwards-incompatible features can complicate thedowngrade process since you must remove any persistedbackwards-incompatible features before you downgrade.

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."4.0"Available on MongoDB 4.0 and 4.2 Deployments

• • If set on MongoDB 4.0 deployments,
  • Enables the 4.0 features that persist data incompatiblewith MongoDB 3.6.

Enabling these backwards-incompatible features can complicate thedowngrade process since you must remove any persistedbackwards-incompatible features before you downgrade.

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.

• • If set on MongoDB 4.2 deployments,
  • Disables the 4.2 features that persist dataincompatible with MongoDB 4.0."3.6"Available on MongoDB 3.6 and 4.0 Deployments
• • If set on MongoDB 3.6 deployments,
  • Enables the 3.6 features that persist dataincompatible with MongoDB 3.4.

Enabling these backwards-incompatible features can complicate thedowngrade process since you must remove any persistedbackwards-incompatible features before you downgrade.

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.

• • If set on MongoDB 4.0 deployments,
  • Disables the 4.0 features that persist dataincompatible with MongoDB 3.6."3.4"Available on MongoDB 3.4 and MongoDB 3.6 Deployments
• • If set on MongoDB 3.4 deployments,
  • Enables the 3.4 features that persist dataincompatible with MongoDB 3.2.

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.

• • If set on MongoDB 3.6 deployments,
  • Disables the 3.6 features that persist dataincompatible with MongoDB 3.4."3.2"Available on MongoDB 3.4 Deployments

Disables the 3.4 features that persist dataincompatible with MongoDB 3.2.

Note

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

Behavior

Conflicts with Background Operations

Certain background operations may preventexecution of setFeatureCompatibilityVersion. UsecurrentOp to identify any ongoing operations.

Default Values

Idempotency

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

Examples

View FeatureCompatibilityVersion

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

Note

The operation is undefined on the mongos instances. For asharded cluster that has access control enabled, to run the commandagainst a member of the shard replica set, you must connect to themember as a shard local user.

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

In the results document, the format of thefeatureCompatibilityVersion depends on the MongoDB version. Clickon the tab for the appropriate MongoDB version.

• For MongoDB 3.6 or greater
• For MongoDB 3.4

For MongoDB 3.6 or greater mongod instances:

• If the deployment has the default featureCompatibilityVersion, orif the setFeatureCompatibilityVersion command has runsuccessfully against the deployment, thefeatureCompatibilityVersion has the form:

"featureCompatibilityVersion" : {
   "version" : <version>
}

• If the mongod is in a partially upgraded or downgradedstate, the featureCompatibilityVersion has the following form:

"featureCompatibilityVersion" : {
   "version" : <version> ,
   "targetVersion" : <target version>
}

For instance, if a sharded cluster has a shard replica set that isread only when you run setFeatureCompatibilityVersioncommand against the mongos, the command will fail, and thefeatureCompatibilityVersion of the config servers will includethe targetVersion field.

Or if a replica set becomes read only whilesetFeatureCompatibilityVersion is running, the commandwill fail, and the featureCompatibilityVersion of the replica setwill include the targetVersion field as well.

For MongoDB 3.4 mongod instances:

"featureCompatibilityVersion" : <version>

Set Feature Compatibility Version on MongoDB 4.2 Deployments

• Enable 4.2 Backwards Incompatible Features
• Disable 4.2 Backwards Incompatible Features

To enable the 4.2 features that persist data incompatible withMongoDB 4.0, set the feature compatibilityto "4.2" on the MongoDB 4.2 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

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

db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )

To disable the 4.2 features that persist data incompatible withMongoDB 4.0, set the feature compatibilityto "4.0" on the MongoDB 4.2 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

• For a standalone, run the command on the standalonemongod instance.
• For a replica set, run the command on the primary. A majority of thedata-bearing members must be available.
• For a sharded cluster, run the command on a mongosinstance.
• "4.0" featureCompatibilityVersion is supported on MongoDB4.0 and MongoDB 4.2 deployments only.

db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )

If run as part of the downgrade process from MongoDB 4.2 to MongoDB4.0, you must also remove all persisted features that areincompatible with 4.0. See theappropriate downgrade procedures.

Set Feature Compatibility Version on MongoDB 4.0 Deployments

• Enable 4.0 Backwards Incompatible Features
• Disable 4.0 Backwards Incompatible Features

To enable the 4.0 features that persist data incompatible withMongoDB 3.6, set the feature compatibilityto "4.0" on the MongoDB 4.0 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

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

db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )

To disable the 4.0 features that persist data incompatible withMongoDB 3.6, set the feature compatibilityto "3.6" on the MongoDB 4.0 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

• For a standalone, run the command on the standalonemongod instance.
• For a replica set, run the command on the primary. A majority of thedata-bearing members must be available.
• For a sharded cluster, run the command on a mongosinstance.
• "3.6" featureCompatibilityVersion is supported on MongoDB3.6 and MongoDB 4.0 Deployments Only.

db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } )

If run as part of the downgrade process from MongoDB 4.0 to MongoDB3.6, you must also remove all persisted features that areincompatible with 3.6. See theappropriate downgrade procedures.

Set Feature Compatibility Version on MongoDB 3.6 Deployments

• Enable 3.6 Backwards Incompatible Features
• Disable 3.6 Backwards Incompatible Features

To enable the 3.6 features that persist data incompatible withMongoDB 3.4, set the feature compatibilityto "3.6" on the MongoDB 3.6 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

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

db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } )

To disable the 3.6 features that persist data incompatible withMongoDB 3.4, set the feature compatibilityto "3.4" on the MongoDB 3.6 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

• For a standalone, run the command on the standalonemongod instance.
• For a replica set, run the command on the primary. A majority of thedata-bearing members must be available.
• For a sharded cluster, run the command on a mongosinstance.
• "3.4" featureCompatibilityVersion is supported on MongoDB3.6 and MongoDB 3.4 Deployments Only.

db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )

If run as part of the downgrade process from MongoDB 3.6 to MongoDB3.4, you must also remove all persisted features that areincompatible with 3.4. See theappropriate downgrade procedures.

Set Feature Compatibility Version on MongoDB 3.4 Deployments

• Enable 3.4 Backwards Incompatible Features
• Disable 3.4 Backwards Incompatible Features

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.

To enable the 3.4 features that are backward incompatible, set the feature compatibilityto "3.4" on the MongoDB 3.4 deployment:

Note

Run the setFeatureCompatibilityVersion command againstthe admin database.

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

db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )

To disable the 3.4 backwards-incompatible features, set the feature compatibilityto "3.2" on the MongoDB 3.4 deployment:

Note

Run the setFeatureCompatibilityVersion command against theadmin database.

• For a standalone, run the command on the standalonemongod instance.
• For a replica set, run the command on the primary. A majority of thedata-bearing members must be available.
• For a sharded cluster, run the command on a mongosinstance.
• "3.2" featureCompatibilityVersion is supported on MongoDB3.4 and MongoDB 3.2 Deployments Only.

db.adminCommand( { setFeatureCompatibilityVersion: "3.2" } )

Setting the featureCompatibilityVersion to "3.2" disables theuse of these features but does not remove existing usage of thesefeatures.

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