Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

setFeatureCompatibilityVersion

On this page

  • Definition
  • Compatibility
  • Syntax
  • Command Fields
  • setFeatureCompatibilityVersion
  • confirm
  • writeConcern
  • Behavior
  • Downgrade with Backward-Incompatible Data
  • Downgrade Policy Changes in MongoDB 7.0
  • Conflicts with Background Operations
  • Sync Failures
  • Default Values
  • Idempotency
  • Cluster-to-Cluster Sync and User Write Blocking
  • Feature Compatibility in Arbiters
  • Examples
  • Get FeatureCompatibilityVersion
  • Set Feature Compatibility Version on MongoDB 7.0 Deployments
  • Set Feature Compatibility Version on MongoDB 6.0 Deployments
  • Set Feature Compatibility Version on MongoDB 5.0 Deployments
  • Set Feature Compatibility Version on MongoDB 4.4 Deployments
  • Set Write Concern Timeout
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.

This command is available in deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This command has limited support in M0, M2, M5, and M10 clusters. For more information, see Unsupported Commands.

Changed in version 7.0.

The command has the following syntax:

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

The setFeatureCompatibilityVersion command takes the following fields:

Required

The possible values for version are:

Version
Description
"7.0"

Available on MongoDB 7.0 Deployments

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

"6.0"

Available on MongoDB 6.0 and 7.0 Deployments

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

"5.0"

Available on MongoDB 5.0 and 6.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.4 Deployments

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

Required

New in version 7.0.

Set to true to confirm the feature compatibility change and allow the operation to proceed.

If you omit the confirm parameter or set confirm to a value other than true, the command fails and returns a warning about modifying the feature compatibility version. The warning states that after you upgrade or downgrade your cluster's fCV, you cannot downgrade the binary version without support assistance.

Optional

The 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.

If you try to downgrade the fCV of a cluster that contains incompatible data in the downloaded version, you receive a CannotDowngrade error. When this error occurs, the cluster remains in the transitionary downgrading state.

To move the cluster out of the downgrading state, either:

  • Modify your cluster data to remove backwards-incompatible features, then re-run the setFeatureCompatibilityVersion command with the downgraded version to set the fCV to the downgraded version.

  • Run the setFeatureCompatibilityVersion command with the original upgraded version to set the fCV back to the original version.

    Important

    Setting the fCV to the original version stops the downgrade procedure and changes the fCV back to the upgraded version. This procedure does not reset the cluster back to the state before the fCV downgrade began.

    If a failed fCV downgrade's internal metadata is not cleaned up, any subsequent FCV upgrade attempt fails with an error message. You must complete the fCV downgrade before trying to upgrade the fCV.

Starting in MongoDB 7.0, you cannot downgrade your deployment's fCV to or from a rapid release version of MongoDB.

If you upgrade or downgrade your deployment's fCV, you cannot downgrade your deployment's binary version without assistance from support.

To learn more, see Downgrade 7.0 to 6.0.

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

If you trigger a setFeatureCompatibilityVersion change during an initial sync, the sync may fail with an OplogOperationUnsupported error message when replaying entries on the oplog application phase. The sync following this attempt succeeds because the operation phase no longer replays the operation.

Deployments
featureCompatibilityVersion
For new 7.0 deployments
"7.0"
For 7.0 deployments upgraded from 6.0
"6.0" until you setFeatureCompatibilityVersion to "7.0".
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.

For more information on MongoDB Cluster-to-Cluster Sync, see the documentation.

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 getParameter command on a mongod instance:

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

The output resembles:

{
featureCompatibilityVersion: { version: '5.0' },
ok: 1,
'$clusterTime': {
clusterTime: Timestamp({ t: 1660318752, i: 5 }),
signature: {
hash: Binary(Buffer.from("ce0cff3621e9b089fa6d8e9a1e1efc1a1ff15dab", "hex"), 0),
keyId: Long("7129893797260951557")
}
},
operationTime: Timestamp({ t: 1660318752, i: 5 })
}

Note

The operation is undefined on the mongos instances.

On a sharded cluster that has access control enabled, you must connect to the shard as a shard local user to run the command.

To enable the 7.0 features that persist data incompatible with MongoDB 6.0, set the feature compatibility to "7.0" on the MongoDB 7.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: "7.0",
confirm: true
}
)

To disable the 7.0 features that persist data incompatible with MongoDB 6.0, set the feature compatibility to "6.0" on the MongoDB 7.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.

  • "6.0" featureCompatibilityVersion is supported on MongoDB 6.0 and MongoDB 7.0 deployments only.

db.adminCommand(
{
setFeatureCompatibilityVersion: "6.0",
confirm: true
}
)

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

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.

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.

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 }
} )
←  setClusterParametersetIndexCommitQuorum →