Downgrade 4.2 Replica Set to 4.0

Before you attempt any downgrade, familiarize yourself with the contentof this document.

Downgrade Path

Once upgraded to 4.2, if you need to downgrade, we recommend downgrading to the latest patch release of 4.0.

If you downgrade, you can only downgrade to a 4.0.12 or later version.You cannot downgrade to a 4.0.11 or earlier version.

Considerations

Starting in MongoDB 4.2, change streams areavailable regardless of the "majority" read concernsupport; that is, read concern majority support can be eitherenabled (default) or disabledto use change streams.

In MongoDB 4.0 and earlier, change streams areavailable only if "majority" read concern support isenabled (default).

Once you downgrade to 4.0-series, change streams will be disabled ifyou have disabled read concern "majority".

Create Backup

Optional but Recommended. Create a backup of your database.

Access Control

If your replica set has access control enabled, your downgrade userprivileges must include privileges to list and manage indexes acrossdatabases. A user with root role has the requiredprivileges.

Prerequisites

To downgrade from 4.2 to 4.0, you must remove incompatible featuresthat are persisted and/or update incompatible configuration settings.These include:

1. Downgrade Feature Compatibility Version (fCV)

Tip

To downgrade the featureCompatibilityVersion of your shardedcluster:

  • Connect a mongo shell to the primary.

  • Downgrade the featureCompatibilityVersion to "4.0".

  1. db.adminCommand({setFeatureCompatibilityVersion: "4.0"})

The setFeatureCompatibilityVersion command performs writesto an internal system collection and is idempotent. If for any reasonthe command does not complete successfully, retry the command on theprimary.

  • To ensure that all members of the replica set reflect the updatedfeatureCompatibilityVersion, connect to each replica set member andcheck the featureCompatibilityVersion:
  1. db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )

All members should return a result that includes:

  1. "featureCompatibilityVersion" : { "version" : "4.0" }

If any member returns a featureCompatibilityVersion of "4.2",wait for the member to reflect version "4.0" before proceeding.

For more information on the returned featureCompatibilityVersionvalue, see View FeatureCompatibilityVersion.

2. Remove FCV 4.2 Persisted Features

The following steps are necessary only if fCV has ever been set to"4.2".

Remove all persisted 4.2 features that are incompatible with 4.0.

2a. Index Key Size

Starting in MongoDB 4.2, for featureCompatibilityVersion (fCV)set to "4.2" or greater, MongoDB removes the Index KeyLimit. For fCV set to "4.0", the limit still applies.

If you have an index with keys that exceed the Index KeyLimit once fCV is set to "4.0",consider changing the index to a hashed index or to indexing acomputed value. You can also temporarily usefailIndexKeyTooLong set to false before resolvingthe problem. However, with failIndexKeyTooLong set tofalse, queries that use these indexes can return incompleteresults.

2b. Index Name Length

Starting in MongoDB 4.2, for featureCompatibilityVersion (fCV)set to "4.2" or greater, MongoDB removes the Index NameLength. For fCV set to "4.0", the limit still applies.

If you have an index with a name that exceeds the Index NameLength once fCV is set to "4.0",drop and recreate the index with a shorter name.

  1. db.collection.dropIndex( <name | index specification> )
  2.  
  3. db.collection.createIndex(
  4.    { <index specification> },
  5.    { name: <shorter name> }
  6. }

See

db.collection.dropIndex() and db.collection.createIndex()

2c. Unique Index Version

With featureCompatibilityVersion (fCV) "4.2", MongoDB uses anew internal format for unique indexes that is incompatible withMongoDB 4.0. The new internal format applies to both existing uniqueindexes as well as newly created/rebuilt unique indexes.

If fCV has ever been set to "4.2", use the following script todrop and recreate all unique indexes.

Tip

Perform this operation after you have resolved any indexkey size and index namelength issues first.

  • Script
  1. // A script to rebuild unique indexes after downgrading fcv 4.2 to 4.0.
  2. // Run this script to drop and recreate unique indexes
  3. // for backwards compatibility with 4.0.
  4.  
  5. db.adminCommand("listDatabases").databases.forEach(function(d){
  6.    let mdb = db.getSiblingDB(d.name);
  7.  
  8.    mdb.getCollectionInfos( { type: "collection" } ).forEach(function(c){
  9.       let currentCollection = mdb.getCollection(c.name);
  10.  
  11.       currentCollection.getIndexes().forEach(function(idx){
  12.          if (idx.unique){
  13.             print("Dropping and recreating the following index:" + tojson(idx))
  14.  
  15.             assert.commandWorked(mdb.runCommand({dropIndexes: c.name, index: idx.name}));
  16.  
  17.             let res = mdb.runCommand({ createIndexes: c.name, indexes: [idx] });
  18.             if (res.ok !== 1)
  19.                assert.commandWorked(res);
  20.          }
  21.       });
  22.    });
  23. });

2d. Remove Wildcard Indexes

For featureCompatibilityVersion (fCV) set to "4.2", MongoDBsupports creating Wildcard Indexes. You must drop allwildcard indexes before downgrading to fCV "4.0".

Use the following script to drop and recreate all wildcard indexes:

  1. // A script to drop wildcard indexes before downgrading fcv 4.2 to 4.0.
  2. // Run this script to drop wildcard indexes
  3. // for backwards compatibility with 4.0.
  4.  
  5. db.adminCommand("listDatabases").databases.forEach(function(d){
  6.    let mdb = db.getSiblingDB(d.name);
  7.    mdb.getCollectionInfos({ type: "collection" }).forEach(function(c){
  8.       let currentCollection = mdb.getCollection(c.name);
  9.       currentCollection.getIndexes().forEach(function(idx){
  10.  
  11.          var key = Object.keys(idx.key);
  12.          if (key[0].includes("$**")) {
  13.  
  14.            print("Dropping index: " + idx.name + " from " + idx.ns);
  15.  
  16.            let res = mdb.runCommand({dropIndexes: currentCollection, index: idx.name});
  17.            assert.commandWorked(res);
  18.  
  19.          }
  20.  
  21.       });
  22.    });
  23. });

Important

Downgrading to fCV "4.0" during an in-progress wildcard indexbuild does not automatically drop or kill the index build. Theindex build can complete after downgrading to fcv "4.0",resulting in a valid wildcard index on the collection. Startingthe 4.0 binary against against that data directory will result instartup failures.

Use db.currentOp() to check for any in-progress wildcardindex builds. Once any in-progress wildcard index builds complete,run the script to drop them before downgrading tofCV "4.0".

2e. View Definitions/Collection Validation Definitions that Include 4.2 Operators

Before downgrading the binaries, modify read-only view definitions and collection validation definitionsthat include the 4.2 operators, such as$set, $unset, $replaceWith.

You can modify a view either by:

You can modify the colleciton validation expressions by:

3. Update tls-Prefixed Configuration

Starting in MongoDB 4.2, MongoDB adds "tls"-prefixed options asaliases for the "ssl"-prefixed options.

If your deployments or clients use the "tls"-prefixed options,replace with the corresponding "ssl"-prefixed options for themongod, the mongos, and the mongo shelland drivers.

4. Prepare Downgrade from zstd Compression

zstd Data Compression

Important

If you also usezstd Journal Compression, perform thesesteps after you perform the prerequisite steps for thejournal compressor.

The zstd compression library is available starting inversion 4.2. For any member that has data stored using zstdcompression, the downgrade procedure will require an initial syncfor that member. To prepare:

  • Create a new empty data directory forthe mongod instance. This directory will be usedin the downgrade procedure below.

Important

Ensure that the user account running mongod hasread and write permissions for the new directory.

If you use command-line options instead, you will have to updatethe options in the procedure below.

Repeat for any other members that used zstd compression.

zstd Journal Compression

The zstd compression library is available for journal datacompression starting in version 4.2.

For any member that uses zstd library for its journalcompressor:

Note

The following procedure involves restarting the replica member as astandalone without the journal.

  • Perform a clean shutdown of the mongod instance:
  1. db.getSiblingDB('admin').shutdownServer()
  1. storage:
  2.    journal:
  3.       enabled: false
  4. #replication:
  5. #   replSetName: replA
  6. setParameter:
  7.     disableLogicalSessionCacheRefresh: true

If you use command-line options instead of a configuration file, youwill have to update the command-line option during the restart.

  • Restart the mongod instance:

    • If you are using a configuration file:
  1. mongod -f <path/to/myconfig.conf>
  1. -

If you are using command-line options instead of aconfiguration file,

  1.   - Include the [<code>--nojournal</code>]($1cde9863b9db90a4.md#cmdoption-mongod-nojournal) option
  2.   - Remove any [replication command-line options]($1cde9863b9db90a4.md#cli-mongod-replica-set) (such as [<code>--replSet</code>]($1cde9863b9db90a4.md#cmdoption-mongod-replset)):
  3.   - Set parameter <code>disableLogicalSessionCacheRefresh</code>to <code>true</code> in the [<code>--setParameter</code>]($1cde9863b9db90a4.md#cmdoption-mongod-setparameter) option.
  1. mongod --nojournal --setParameter disableLogicalSessionCacheRefresh=true  ...
  • Perform a clean shutdown of the mongod instance:
  1. db.getSiblingDB('admin').shutdownServer()

Confirm that the process is no longer running.

  1. storage:
  2.    wiredTiger:
  3.       engineConfig:
  4.          journalCompressor: <newValue>
  5. replication:
  6.    replSetName: replA

If you use command-line options instead of a configuration file, youwill have to update the command-line options during the restartbelow.

  • Restart the mongod instance as a replica set member:

    • If you are using a configuration file:
  1. mongod -f <path/to/myconfig.conf>
  1. -

If you are using command-line options instead of a configurationfile:

  1.   - Remove the [<code>--nojournal</code>]($1cde9863b9db90a4.md#cmdoption-mongod-nojournal) option.
  2.   - Remove the [<code>--wiredTigerJournalCompressor</code>]($1cde9863b9db90a4.md#cmdoption-mongod-wiredtigerjournalcompressor) command-line option to usethe default journal compressor or update to a new value.
  3.   - Include your [replication command-line options]($1cde9863b9db90a4.md#cli-mongod-replica-set) as well as any additionaloptions for your replica set member.
  4.   - Remove the <code>disableLogicalSessionCacheRefresh</code> parameter.
  1. mongod --wiredTigerJournalCompressor <differentCompressor|none> --replSet ...

Note

If you encounter an unclean shutdown for a mongodduring the downgrade procedure such that you need to use thejournal files to recover, recover theinstance using the 4.2 mongod and then retry thedowngrade of the instance.

zstd Network Compression

The zstd compression library is available for networkmessage compression starting in version 4.2.

To prepare for the downgrade:

If you use command-line options instead, you will have to updatethe options in the procedure below.

Important

Messages are compressed when both parties enable networkcompression. Otherwise, messages between the parties areuncompressed.

Procedure

Warning

Before proceeding with the downgrade procedure, ensure that allreplica set members, including delayed replica set members, reflectthe prerequisite changes. That is, check thefeatureCompatibilityVersion and the removal of incompatiblefeatures for each node before downgrading.

Download the latest 4.0 binaries.

Using either a package manager or a manual download, get the latestrelease in the 4.0 series. If using a package manager, add a newrepository for the 4.0 binaries, then perform the actual downgradeprocess.

Once upgraded to 4.2, if you need to downgrade, we recommend downgrading to the latest patch release of 4.0.

Downgrade secondary members of the replica set.

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

  1. db.adminCommand( { shutdown: 1 } )
  • Replace the 4.2 binary with the 4.0 binary and restart.

Note

If you use command-line options instead of a configuration file,update the command-line options as appropriate during the restart.

  • Wait for the member to recover to SECONDARY state. To checkthe member’s state, connect a mongo shell to themember and run rs.status() method.

  • Once the member is in SECONDARY stage, downgrade the nextsecondary.

Downgrade arbiter replica set member, if any.

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

Downgrade the arbiter member ofthe replica set:

  1. db.adminCommand( { shutdown: 1 } )
  • Delete the arbiter data directory. Thestorage.dbPath configuration setting or—dbpath command line option specify thedata directory of the arbiter mongod.
  1. rm -rf /path/to/mongodb/datafiles
  • Replace the 4.2 binary with the 4.0 binary and restart.

Note

If you use command-line options instead of a configuration file,update the command-line options as appropriate during the restart.

  • Wait for the member to recover to ARBITER state. To checkthe member’s state, connect a mongo shell to themember and run rs.status() method.

Step down the primary.

Use rs.stepDown() in the mongo shell tostep down the primary and force the normal failover procedure.

  1. rs.stepDown()

rs.stepDown() expedites the failover procedure and ispreferable to shutting down the primary directly.

Replace and restart the former primary.

When rs.status() shows that the primary has stepped downand another member has assumed PRIMARY state:

  • Shut down the previous primary.
  1. db.adminCommand( { shutdown: 1 } )
  • Replace the mongod binary withthe 4.0 binary and restart.

Note

If you use command-line options instead of a configuration file,update the command-line options as appropriate during the restart.