setFeatureCompatibilityVersion
On this page
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.
Compatibility
This command is available in deployments hosted in the following environments:
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
The command takes the following form:
db.adminCommand( { setFeatureCompatibilityVersion: <version>, writeConcern: { wtimeout: <timeout> } } )
The values for the version
are:
Version | Description |
---|---|
"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.4 Deployments Disables the 4.4 features that persist data incompatible with MongoDB 4.2. |
writeConcern
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 thewtimeout
default.
Behavior
Conflicts with Background Operations
Certain background operations may prevent
execution of setFeatureCompatibilityVersion
. Use
currentOp
to identify any ongoing operations.
Sync Failures
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.
Default Values
Deployments | featureCompatibilityVersion |
---|---|
For new 5.0 deployments | "5.0" |
For 5.0 deployments upgraded from 4.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.
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
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. 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 thesetFeatureCompatibilityVersion
command has run successfully against the deployment, thefeatureCompatibilityVersion
has the form:"featureCompatibilityVersion" : { "version" : <version> } If the
mongod
is in a partially upgraded or downgraded state, thefeatureCompatibilityVersion
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 themongos
, the command will fail, and thefeatureCompatibilityVersion
of the config servers will include thetargetVersion
field.Or if a replica set becomes read only while
setFeatureCompatibilityVersion
is running, the command will fail, and thefeatureCompatibilityVersion
of the replica set will include thetargetVersion
field as well.
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 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 } } )