Downgrade 4.2 Standalone to 4.0

Downgrade 4.2 Standalone 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.

Create Backup

Optional but Recommended. Create a backup of your database.

Access Control

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

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)

To downgrade the featureCompatibilityVersion of your shardedcluster:

Connect a mongo shell to the mongod instance.
Downgrade the featureCompatibilityVersion to "4.0".

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 themongod instance.

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. These include:

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.

db.collection.dropIndex( <name | index specification> )
 
db.collection.createIndex(
   { <index specification> },
   { name: <shorter name> }
}

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 indexname length issues first.

Script

// A script to rebuild unique indexes after downgrading fcv 4.2 to 4.0.
// Run this script to drop and recreate unique indexes
// for backwards compatibility with 4.0.
 
db.adminCommand("listDatabases").databases.forEach(function(d){
   let mdb = db.getSiblingDB(d.name);
 
   mdb.getCollectionInfos( { type: "collection" } ).forEach(function(c){
      let currentCollection = mdb.getCollection(c.name);
 
      currentCollection.getIndexes().forEach(function(idx){
         if (idx.unique){
            print("Dropping and recreating the following index:" + tojson(idx))
 
            assert.commandWorked(mdb.runCommand({dropIndexes: c.name, index: idx.name}));
 
            let res = mdb.runCommand({ createIndexes: c.name, indexes: [idx] });
            if (res.ok !== 1)
               assert.commandWorked(res);
         }
      });
   });
});

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:

// A script to drop wildcard indexes before downgrading fcv 4.2 to 4.0.
// Run this script to drop wildcard indexes
// for backwards compatibility with 4.0.
 
db.adminCommand("listDatabases").databases.forEach(function(d){
   let mdb = db.getSiblingDB(d.name);
   mdb.getCollectionInfos({ type: "collection" }).forEach(function(c){
      let currentCollection = mdb.getCollection(c.name);
      currentCollection.getIndexes().forEach(function(idx){
 
         var key = Object.keys(idx.key);
         if (key[0].includes("$**")) {
 
           print("Dropping index: " + idx.name + " from " + idx.ns);
 
           let res = mdb.runCommand({dropIndexes: currentCollection, index: idx.name});
           assert.commandWorked(res);
 
         }
 
      });
   });
});

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.

For the $set stage, use the $addFieldsstage instead.
For the $replaceWith stage, use the$replaceRoot stage instead.
For the $unset stage, use the $projectstage instead.

You can modify a view either by:

dropping the view (db.myview.drop() method) andrecreating the view (db.createView() method) or
using the collMod command.

You can modify the colleciton validation expressions by:

using the collMod command.

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

The zstd compression library is available starting inversion 4.2.

If your standalone has any data using zstd compression:

Tip

Perform this step after all the other prerequisite steps havebeen performed.

Stop all writes to your instance.
Create a mongodump of your database beforestarting the downgrade; mongodump outputsuncompressed data.

mongodump --host=<myhost> --port=<port> --out=mystandalone.uncompressed.fcv4.0

Include any other options, such as —username, —password, and—authenticationDatabase if your standalone enforces accesscontrol.

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 a configuration file, update the file to prepare forthe downgrade procedure:
- Deletestorage.wiredTiger.collectionConfig.blockCompressorto use the default compressor (snappy) orset to another 4.0 supported compressor.
- Update storage.dbPath to the newdata directory.

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

zstd Journal Compression

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

If the mongod instance uses zstd library forits journal compressor:

If using a configuration file, deletestorage.wiredTiger.engineConfig.journalCompressor touse the default compressor (snappy) or set to another 4.0supported compressor.
If using command-line options instead, you will have to update theoptions in the procedure below.

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:

For the mongod instance that uses zstd for network messagecompression and uses a configuration file, update thenet.compression.compressors setting to prepare for therestart during the downgrade procedure.

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

For any client that specifies zstd in its URIconnection string, update to remove zstd from thelist.
For any mongo shell that specifies zstd in its—networkMessageCompressors, update to remove zstd from thelist.

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 theprerequisites have been completed.

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.

Restart with the latest 4.0 mongod instance.

Shut down your mongod instance. To safely terminatethe mongod process, you can connect amongo shell to the instance and run:

db.adminCommand( { shutdown: 1 } )

For additional methods to safely terminate yourmongod instance, seeStop mongod Processes.

Replace the 4.2 binary with the downloaded 4.0mongod 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.

If your command-line options include “tls”-prefixedoptions, update to “ssl”-prefixed options.
If the mongod instance used zstd data compression,
- Update —dbpath to the new directory(created during the prerequisites).
- Remove —wiredTigerCollectionBlockCompressor to use the defaultsnappy compressor (or, alternatively, explicitly set to a4.0 supported compressor).
If the mongod instance used zstd journalcompression,
- Remove —wiredTigerJournalCompressor to use the default snappycompressor (or, alternatively, explicitly set to a 4.0 supportedcompressor).
If the mongod instance included zstd networkmessage compression,
- Remove —networkMessageCompressors to enable message compressionusing the default snappy,zlib compressors. Alternatively,explicitly specify the compressor(s).

If switching from zstd compression, restore data.

Skip this step if you have not downgraded from a standalone thatused zstd compression.

If you have downgraded from a standalone that used zstd, youhave created a dump of your data as a prerequisite. Use mongorestoreto restore that data to your 4.0 standalone.

mongorestore --host=<myhost> --port=<port>  mystandalone.uncompressed.fcv4.0