Downgrade 6.0 Sharded Cluster to 5.0

Create Backup

Optional but Recommended. Create a backup of your database.

To learn how to create a backup, see Backup Methods for a Self-Managed Deployment.

Remove Backward-Incompatible Features

To downgrade from 6.0 to 5.0, you must remove 6.0 features that are incompatible with 5.0. For a list of incompatible features and how to remove them, see Downgrade Considerations.

Ensure No Resharding Operations are in Progress

Ensure that any resharding operations have successfully completed. If a recent resharding operation has failed due to a primary failover, you must first run the cleanupReshardCollection command before downgrading the featureCompatibilityVersion of your sharded cluster.

If a resharding operation is still running while you downgrade the featureCompatibilityVersion of your sharded cluster, the resharding operation will not complete.

Downgrade Feature Compatibility Version (fCV)

To downgrade the fCV of your sharded cluster:

1. Ensure that no initial sync is in progress. Running the setFeatureCompatibilityVersion command while an initial sync is in progress causes the initial sync to restart.

2. Ensure that no nodes have a newlyAdded field in their replica set configuration. Run the following command on each node in your replica set to verify this:

   use local
   db.system.replset.find( { "members.newlyAdded" : { $exists : true } } );

   The newlyAdded field only appears in a node's replica set configuration document during and shortly after an initial sync.

3. Ensure that no replica set member is in the ROLLBACK or RECOVERING state.

4. Use mongosh to connect to your mongos instance.

5. Downgrade the featureCompatibilityVersion to "5.0".

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

   The setFeatureCompatibilityVersion command performs writes to an internal system collection and is idempotent. If the command does not complete successfully, retry the command on the mongos instance.

   Note

   Troubleshooting

   • While setFeatureCompatibilityVersion is running on the sharded cluster, chunk migrations, splits, and merges can fail with ConflictingOperationInProgress.

   • If setFeatureCompatibilityVersion fails with a ManualInterventionRequired error, and the cluster has recently undergone a resharding operation that had failed due to an election, you must run the cleanupReshardCollection command before you attempt to run setFeatureCompatibilityVersion again.

6. To ensure that all members of the replica set have the updated featureCompatibilityVersion, connect to each replica set member and check the featureCompatibilityVersion:

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

   Tip

   Access Control

   For a sharded cluster that has access control enabled, to run the adminCommand on a shard replica set member, you must connect to the member as a shard local user.

   All members should return a result that includes:

   "featureCompatibilityVersion" : { "version" : "5.0" }

   If any member returns a featureCompatibilityVersion of "6.0", wait for the member to return version "5.0" before proceeding.

For more information on the returned featureCompatibilityVersion value, see Get FeatureCompatibilityVersion.

Download the latest 5.0 binaries.

Using either a package manager or a manual download, get the latest release in the 5.0 series. If using a package manager, add a new repository for the 5.0 binaries, then perform the actual downgrade process.

If you need to downgrade from 6.0, downgrade to the latest patch release of 5.0.

Replace the 6.0 binaries with the downloaded 5.0 binaries.

Ensure that the 5.0 binaries are in your System PATH. To confirm your binary version, run the following command:

mongod --version

The command output should indicate a 5.0-series release.

Disable the Balancer.

To disable the balancer, connect mongosh to a mongos instance in the sharded cluster, and run the following command:

sh.stopBalancer()

To verify that the balancer is disabled, run the following command:

sh.getBalancerState()

sh.getBalancerState() returns false if the balancer is disabled.

For more information on disabling the balancer, see Disable the Balancer.

Downgrade mongos.

1. To stop mongos, run the following command:

   db.shutdownServer()

2. Restart mongos with the 5.0 binary.

Downgrade each shard, one at a time.

1. Downgrade the shard's secondary members, one at a time.

   1. Shut down the member.

      To shut down the mongod process, use mongosh to connect to the deployment and run the following command:

      db.adminCommand( { shutdown: 1 } )

   2. Restart the member.

      To start a mongod process, run the following command:

      mongod --dbpath </path-to-data-folder>

   3. Wait for the member to enter the SECONDARY state.

      Before downgrading the next secondary, wait for the member to recover to the SECONDARY state. To check the member's state, use the rs.status() method in mongosh.

   4. Repeat the previous steps to downgrade each secondary member.

2. Downgrade the shard arbiter, if any.

   Skip this step if the replica set does not include an arbiter.

   Downgrade the arbiter member of the sharded cluster:

   1. Shut down the member.

      To shut down the arbiter, use mongosh to connect to the arbiter and run the following command:

      db.adminCommand( { shutdown: 1 } )

   2. Delete the contents of the arbiter data directory.

      To find the data directory of the arbiter mongod, check either the storage.dbPath configuration setting or --dbpath command line option.

      Run the following command:

      rm -rf /path/to/mongodb/datafiles/*

   3. Restart the arbiter.

      To start a mongod process, run the following command:

      mongod --dbpath </path-to-mongodb-datafiles>

   4. Wait for the member to enter the ARBITER state.

      Before downgrading the primary, wait for the member to recover to the ARBITER state. To check the member's state, use the rs.status() method in mongosh.

3. Downgrade the shard primary.

   1. Step down the primary.

      In mongosh, use rs.stepDown() to step down the primary and start an election for a new primary:

      rs.stepDown()

   2. Verify that the primary has stepped down.

      Run the following command:

      rs.status()

      Verify that the primary has stepped down and another member has assumed the PRIMARY state.

   3. Shut down the former primary member.

      To shut down the former primary, connect to the deployment using mongosh and run the following command:

      db.adminCommand( { shutdown: 1 } )

   4. Restart the mongod with the 5.0 binary.

      To start a mongod process, run the following command:

      mongod --dbpath </path-to-mongodb-datafiles>

   5. Repeat for the remaining shards.

Downgrade the config servers.

1. Downgrade the shard's secondary members of the config servers replica set (CSRS) one at a time:

   1. Shut down the secondary.

      Connect to the secondary and run the following command:

      db.adminCommand( { shutdown: 1 } )

   2. Restart the member.

      To start a mongod process, run the following command:

      mongod --dbpath </path-to-data-folder>

   3. Wait for the member to enter the SECONDARY state.

      Before downgrading the next secondary, wait for the member to recover to the SECONDARY state. To check the member's state, use the rs.status() method in mongosh.

   4. Repeat the previous steps to downgrade each secondary member.

2. Downgrade the config server primary.

   1. Step down the primary.

      In mongosh, run rs.stepDown() to step down the primary and start an election for a new primary:

      rs.stepDown()

   2. Verify that the primary has stepped down.

      Run the following command:

      rs.status()

      Verify that the primary has stepped down and another member has assumed the PRIMARY state.

   3. Shut down the former primary member.

      To shut down the former primary, connect to the deployment using mongosh and run the following command:

      db.adminCommand( { shutdown: 1 } )

   4. Restart the mongod with the 5.0 binary.

      To start a mongod process, run the following command:

      mongod --dbpath </path-to-mongodb-datafiles>

Re-enable the balancer.

After you downgrade all of the sharded cluster components, connect to a mongos and run the following command to re-enable the balancer:

sh.startBalancer()

The sh.startBalancer() method also enables auto-splitting for the sharded cluster.