Downgrade 8.3 Replica Set to 8.2

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 8.3 to 8.2, you must remove 8.3 features that are incompatible with 8.2. For a list of incompatible features and how to remove them, see Downgrade Considerations.

Downgrade Feature Compatibility Version (FCV)

To downgrade the FCV of your replica set:

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

5. Downgrade the featureCompatibilityVersion to "8.2".

   Important

   After you modify the featureCompatibilityVersion and enable new features, you cannot downgrade the binary version without assistance from support. Make sure to evaluate your upgrade path before proceeding.

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

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

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 } )

   HIDE OUTPUT

   "featureCompatibilityVersion" : { "version" : "8.2" }

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

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

Download the latest 8.2 binaries

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

• For any versions, major or minor, you can upgrade or downgrade to its adjacent neighbors. For example, you can downgrade from 8.3 to 8.2 or upgrade from 7.0 to 8.0.

• For all versions, major or minor, you can downgrade to the immediately previous major version. For example, from 8.3 to 8.0.

• For any minor version, you can upgrade to the immediately next version. For example, from 8.2 to 8.3.

If you need to downgrade from 8.3, downgrade to the latest patch release of 8.2.

Replace the 8.3 binaries with the downloaded 8.2 binaries

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

mongod --version

The command output should indicate a 8.2 release.

Downgrade secondary members of the replica set

Downgrade each secondary member of the replica set, one at a time:

1. Shut down the member.

   To shut down the mongod process, use mongosh to 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>

   To learn more about starting a mongod process, see Start mongod Processes.

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. After the member is in SECONDARY stage, downgrade the next secondary.

Downgrade the arbiter replica set member, if any

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

Downgrade the arbiter member of the replica set:

1. Shut down the member.

   To shutdown 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>

   To learn more about starting a mongod process, see Start mongod Processes.

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.

Downgrade the primary

1. Step down the primary.

   In mongosh, use rs.stepDown() to step down the primary and force the normal failover procedure.

   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. Replace and restart the former primary mongod.

   1. Shut down the member.

      To perform a shutdown of the primary, use mongosh to connect to the primary and run the following command:

      db.adminCommand( { shutdown: 1 } )

   2. Restart mongod with the 8.2 binary.

      To start a mongod process, run the following command:

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

      To learn more about starting a mongod process, see Start mongod Processes.