setFeatureCompatibilityVersion
On this page
- Definition
- Syntax
- Command Fields
- Behavior
- Conflicts with Background Operations
- Default Values
- Idempotency
- Cluster-to-Cluster Replication and User Write Blocking
- Feature Compatibility in Arbiters
- Examples
- Get FeatureCompatibilityVersion
- 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 Feature Compatibility Version on MongoDB 4.2 Deployments
- Set Write Concern Timeout
Definition
setFeatureCompatibilityVersion
Enables or disables the features that persist data incompatible with earlier versions of MongoDB. You can only issue the
setFeatureCompatibilityVersion
against theadmin
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.
Syntax
The command has the following syntax:
db.adminCommand( { setFeatureCompatibilityVersion: <version>, writeConcern: { wtimeout: <timeout> } } )
Command Fields
The possible values for 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 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.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 thewtimeout
default.
Behavior
Conflicts with Background Operations
Certain background operations may prevent
execution of setFeatureCompatibilityVersion
. Use
currentOp
to identify any ongoing operations.
Default Values
Deployments | featureCompatibilityVersion |
---|---|
For new 6.0 deployments | "6.0" |
For 6.0 deployments upgraded from 5.0 | |
For new 5.0 deployments | "5.0" |
For 5.0 deployments upgraded from 4.4 | |
For new 4.4 deployments | "4.4" |
For 4.4 deployments upgraded from 4.2 | |
For new 4.2 deployments | "4.2" |
For 4.2 deployments upgraded from 4.0 |
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.
Cluster-to-Cluster Replication and User Write Blocking
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.
If you enabled cluster-to-cluster replication, disable it.
If you enabled user write blocking, disable it:
db.runCommand( { setUserWriteBlockMode: 1, global: false } ) Wait for the previous command to complete.
Downgrade the feature compatibility version using
setFeatureCompatibilityVersion
.
Feature Compatibility in Arbiters
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.
Examples
Get FeatureCompatibilityVersion
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.
Set Feature Compatibility Version on MongoDB 6.0 Deployments
Enable 6.0 Backwards Incompatible Features
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.
db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
Disable 6.0 Backwards Incompatible Features
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.
Set Feature Compatibility Version on MongoDB 5.0 Deployments
Enable 5.0 Backwards Incompatible Features
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.
db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
Disable 5.0 Backwards Incompatible Features
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.
Set Feature Compatibility Version on MongoDB 4.4 Deployments
Enable 4.4 Backwards Incompatible Features
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.
db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
Disable 4.4 Backwards Incompatible Features
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.
Set Feature Compatibility Version on MongoDB 4.2 Deployments
Enable 4.2 Backwards Incompatible Features
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.
db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
Set Write Concern Timeout
The following example sets the optional write concern wtimeout
field to 5000 (5 seconds).
Note
Run the setFeatureCompatibilityVersion
command against
the admin
database.
db.adminCommand( { setFeatureCompatibilityVersion: "5.0", writeConcern: { wtimeout: 5000 } } )