Docs Menu

setFeatureCompatibilityVersion

On this page

  • Definition
  • Syntax
  • Behavior
  • Examples
setFeatureCompatibilityVersion

Enables or disables the features that persist data incompatible with earlier versions of MongoDB. You can only issue the setFeatureCompatibilityVersion against the admin database.

Warning

Enabling backwards-incompatible features can complicate the downgrade process since you must remove any persisted backwards-incompatible features before you downgrade.

It is recommended that after upgrading, you allow your deployment to run without enabling backwards-incompatible 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.

The command takes the following form:

db.adminCommand( {
setFeatureCompatibilityVersion: <version>,
writeConcern: { wtimeout: <timeout> }
} )

The values for the version are:

Version
Description
"6.0"

Available on MongoDB 6.0 Deployments

Enables the 6.0 features that persist data incompatible with MongoDB 5.0.

"5.0"

Available on MongoDB 5.0 Deployments

Enables the 5.0 features that persist data incompatible with MongoDB 4.4.

"4.4"

Available on MongoDB 4.4 and 5.0 Deployments

Enables the 4.4 features that persist data incompatible with MongoDB 4.2.

"4.2"

Available on MongoDB 4.2 and 4.4 Deployments

Enables the 4.2 features that persist data incompatible with MongoDB 4.0.

The optional writeConcern specifies the write concern wtimeout value in milliseconds:

  • The time period that the primary waits for acknowledgment from the majority of the replica set members. If the acknowledgment is not received in the time period, the operation fails.
  • Default is 60000 milliseconds. Use a longer time period if the secondary members of the replica set have a delay that exceeds the wtimeout default.
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.

Certain background operations may prevent execution of setFeatureCompatibilityVersion. Use currentOp to identify any ongoing operations.

Deployments
featureCompatibilityVersion
For new 6.0 deployments
"6.0"
For 6.0 deployments upgraded from 5.0
"5.0" until you setFeatureCompatibilityVersion to "6.0".
For new 5.0 deployments
"5.0"
For 5.0 deployments upgraded from 4.4
"4.4" until you setFeatureCompatibilityVersion to "5.0".
For new 4.4 deployments
"4.4"
For 4.4 deployments upgraded from 4.2
"4.2" until you setFeatureCompatibilityVersion to "4.4".
For new 4.2 deployments
"4.2"
For 4.2 deployments upgraded from 4.0
"4.0" until you setFeatureCompatibilityVersion to "4.2".

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.

Starting in MongoDB 6.0, if you need to downgrade the feature compatibility version, ensure you disable cluster-to-cluster replication and user write blocking.

  1. If you enabled cluster-to-cluster replication, disable it.
  2. If you enabled user write blocking, disable it:

    db.runCommand( { setUserWriteBlockMode: 1, global: false } )
  3. Wait for the previous command to complete.
  4. Downgrade the feature compatibility version using setFeatureCompatibilityVersion.

Arbiters do not replicate the admin.system.version collection. Because of this, arbiters always have a Feature Compatibility Version equal to the downgrade version of the binary, regardless of the FCV value of the replica set.

For example, an arbiter in a MongoDB 5.0 cluster, has an FCV value of 4.4.

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. For a sharded cluster that has access control enabled, to run the command against a member of the shard replica set, you must connect to the member as a shard local user.

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

The output from this command will resemble one of the following, depending on the current state of the mongod:

  • If the deployment has the default featureCompatibilityVersion, or if the setFeatureCompatibilityVersion command has run successfully against the deployment, the featureCompatibilityVersion has the form:

    "featureCompatibilityVersion" : {
    "version" : <version>
    }
  • If the mongod is in a partially upgraded or downgraded state, the featureCompatibilityVersion has the following form:

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

    For instance, if a sharded cluster has a shard replica set that is read only when you run setFeatureCompatibilityVersion command against the mongos, the command will fail, and the featureCompatibilityVersion of the config servers will include the targetVersion field.

    Or if a replica set becomes read only while setFeatureCompatibilityVersion is running, the command will fail, and the featureCompatibilityVersion of the replica set will include the targetVersion field as well.

To enable the 6.0 features that persist data incompatible with MongoDB 5.0, set the feature compatibility to "6.0" on the MongoDB 6.0 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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: "6.0" } )

To disable the 6.0 features that persist data incompatible with MongoDB 5.0, set the feature compatibility to "5.0" on the MongoDB 6.0 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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.
  • "5.0" featureCompatibilityVersion is supported on MongoDB 5.0 and MongoDB 6.0 deployments only.
db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )

If run as part of the downgrade process from MongoDB 6.0 to MongoDB 5.0, you must also remove all persisted features that are incompatible with 5.0. See the appropriate downgrade procedures.

To enable the 5.0 features that persist data incompatible with MongoDB 4.4, set the feature compatibility to "5.0" on the MongoDB 5.0 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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: "5.0" } )

To disable the 5.0 features that persist data incompatible with MongoDB 4.4, set the feature compatibility to "4.4" on the MongoDB 5.0 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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.
  • "4.4" featureCompatibilityVersion is supported on MongoDB 4.4 and MongoDB 5.0 deployments only.
db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )

If run as part of the downgrade process from MongoDB 5.0 to MongoDB 4.4, you must also remove all persisted features that are incompatible with 4.4. See the appropriate downgrade procedures.

To enable the 4.4 features that persist data incompatible with MongoDB 4.2, set the feature compatibility to "4.4" on the MongoDB 4.4 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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: "4.4" } )

To disable the 4.4 features that persist data incompatible with MongoDB 4.2, set the feature compatibility to "4.2" on the MongoDB 4.4 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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.
  • "4.2" featureCompatibilityVersion is supported on MongoDB 4.2 and MongoDB 4.4 deployments only.
db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )

If run as part of the downgrade process from MongoDB 4.4 to MongoDB 4.2, you must also remove all persisted features that are incompatible with 4.2. See the appropriate downgrade procedures.

To enable the 4.2 features that persist data incompatible with MongoDB 4.0, set the feature compatibility to "4.2" on the MongoDB 4.2 deployment:

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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: "4.2" } )

The following example sets the optional write concern wtimeout field to 5000 (5 seconds).

Note

Run the setFeatureCompatibilityVersion command against the admin database.

  • 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: "5.0",
writeConcern: { wtimeout: 5000 }
} )
←  setAuditConfigsetIndexCommitQuorum →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.