Downgrade MongoDB from 3.2

Before you attempt any downgrade, familiarize yourself with the contentof this document, particularly the Downgrade Recommendations and Checklistand the procedure for downgrading sharded clusters.

Downgrade Recommendations and Checklist

When downgrading, consider the following:

Downgrade Path

To downgrade, use the latest version in the 3.0-series.

Preparedness

• Remove or downgrade version 3 text indexes before downgrading MongoDB 3.2 to 3.0.
• Remove or downgrade version 3 2dsphere indexes before downgrading MongoDB 3.2 to 3.0.

Procedures

Follow the downgrade procedures:

• To downgrade sharded clusters, see Downgrade a 3.2 Sharded Cluster.
• To downgrade replica sets, see Downgrade a 3.2 Replica Set.
• To downgrade a standalone MongoDB instance, see Downgrade a Standalone mongod Instance.

Prerequisites

Text Index Version Check

If you have version 3 text indexes (i.e. the default version for textindexes in MongoDB 3.2), drop the version 3 text indexes beforedowngrading MongoDB. After the downgrade,recreate the dropped text indexes.

To determine the version of your text indexes, rundb.collection.getIndexes() to view index specifications. Fortext indexes, the method returns the version information in the fieldtextIndexVersion. For example, the following shows that thetext index on the quotes collection is version 3.

{
   "v" : 1,
   "key" : {
      "_fts" : "text",
      "_ftsx" : 1
   },
   "name" : "quote_text_translation.quote_text",
   "ns" : "test.quotes",
   "weights" : {
      "quote" : 1,
      "translation.quote" : 1
   },
   "default_language" : "english",
   "language_override" : "language",
   "textIndexVersion" : 3
}

2dsphere Index Version Check

If you have version 3 2dsphere indexes (i.e. the default versionfor 2dsphere indexes in MongoDB 3.2), drop the version 32dsphere indexes before downgrading MongoDB. After the downgrade,recreate the 2dsphere indexes.

To determine the version of your 2dsphere indexes, rundb.collection.getIndexes() to view index specifications. For2dsphere indexes, the method returns the version information in the field2dsphereIndexVersion. For example, the following shows that the2dsphere index on the locations collection is version 3.

{
   "v" : 1,
   "key" : {
      "geo" : "2dsphere"
   },
   "name" : "geo_2dsphere",
   "ns" : "test.locations",
   "sparse" : true,
   "2dsphereIndexVersion" : 3
}

Partial Indexes Check

Before downgrading MongoDB, drop any partial indexes.

Downgrade a Standalone mongod Instance

The following steps outline the procedure to downgrade a standalonemongod from version 3.2 to 3.0.

Download the latest 3.0 binaries.

For the downgrade, use the latest release in the 3.0 series.

Restart with the latest 3.0 mongod instance.

Important

If your mongod instance is using the WiredTiger storage engine, you must include the—storageEngine option (or storage.engine ifusing the configuration file) with the 3.0 binary.

Shut down your mongod instance. Replace the existingbinary with the downloaded mongod binary and restart.

Downgrade a 3.2 Replica Set

The following steps outline a “rolling” downgrade process for thereplica set. The “rolling” downgrade process minimizes downtime bydowngrading the members individually while the other members areavailable:

Downgrade the protocolVersion.

Connect a mongo shell to the current primary anddowngrade the replication protocol:

cfg = rs.conf();
cfg.protocolVersion=0;
rs.reconfig(cfg);

Downgrade secondary members of the replica set.

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

• Shut down the mongod. See Stop mongod Processes for instructions on safely terminating mongod processes.

• Replace the 3.2 binary with the 3.0 binary and restart.

Important

If your mongod instance is using the WiredTiger storage engine, you must include the—storageEngine option (or storage.engine ifusing the configuration file) with the 3.0 binary.

• Wait for the member to recover to SECONDARY state before downgrading the next secondary. To check the member’s state, use the rs.status() method in the mongo shell.

Step down the primary.

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

rs.stepDown()

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

Replace and restart former primary mongod.

When rs.status() shows that the primary has stepped downand another member has assumed PRIMARY state, shut down theprevious primary and replace the mongod binary withthe 3.0 binary and start the new instance.

Important

If your mongod instance is using the WiredTiger storage engine, you must include the—storageEngine option (or storage.engine ifusing the configuration file) with the 3.0 binary.

Replica set failover is not instant but will render the set unavailable towrites and interrupt reads until the failover processcompletes. Typically this takes 10 seconds or more. You may wish toplan the downgrade during a predetermined maintenance window.

Downgrade a 3.2 Sharded Cluster

Requirements

While the downgrade is in progress, you cannot make changes to thecollection metadata. For example, during the downgrade, donot do any of the following:

• sh.enableSharding()
• sh.shardCollection()
• sh.addShard()
• db.createCollection()
• db.collection.drop()
• db.dropDatabase()
• any operation that creates a database
• any other operation that modifies the cluster meta-data in anyway. See Sharding Reference for a complete list ofsharding commands. Note, however, that not all commands on theSharding Reference page modifies the cluster meta-data.

Downgrade a Sharded Cluster with SCCC Config Servers

Disable the Balancer.

Turn off the balancer in thesharded cluster, as described inDisable the Balancer.

Downgrade each shard, one at a time.

For each replica set shard:

• Downgrade the protocolVersion.
• Downgrade the mongod secondaries before downgradingthe primary.
• To downgrade the primary, run replSetStepDown and then downgrade.For details on downgrading a replica set, see Downgrade a 3.2 Replica Set.

Downgrade the SCCC config servers.

If the sharded cluster uses 3 mirrored mongod instancesfor the config servers, downgrade all three instances in reverseorder of their listing in the —configdb option formongos. For example, if mongos has thefollowing —configdb listing:

--configdb confserver1,confserver2,confserver3

Downgrade first confserver3, then confserver2, and lastly,confserver1. If your mongod instance is using theWiredTiger storage engine, you mustinclude the —storageEngine option (orstorage.engine if using the configuration file) with the3.0 binary.

mongod --configsvr --dbpath <path> --port <port> --storageEngine <storageEngine>

Downgrade the mongos instances.

Downgrade the binaries and restart.

Re-enable the balancer.

Once the downgrade of sharded cluster components iscomplete, re-enable the balancer.

Downgrade a Sharded Cluster with CSRS Config Servers

Disable the Balancer.

Turn off the balancer in thesharded cluster, as described inDisable the Balancer.

Check the minOpTimeUpdaters value.

If the sharded cluster uses CSRS, for each shard, checkthe minOpTimeUpdaters value to see if it is zero. AminOpTimeUpdaters value of zero indicates that there are nomigrations in progress. A non-zero value indicates either that amigration is in progress or that a previously completed migrationhas somehow failed to clear the minOpTimeUpdaters value andshould be cleared.

To check the value, for each shard, connect to the primary member(or if a shard is a standalone, connect to the standalone) andquery the system.version collection in the admin databasefor the minOpTimeRecovery document:

use admin
db.system.version.findOne( { _id: "minOpTimeRecovery" }, { minOpTimeUpdaters: 1 } )

If minOpTimeUpdaters is non-zero, clear the value by steppingdown the current primary. The value is cleared when a new primarygets elected.

rs.stepDown()

If the shard is a standalone, restart the shard to clear the value.

Prepare CSRS Config Servers for downgrade.

If the sharded cluster uses CSRS:

• Remove secondary members from the replica set to have only a primary and twosecondaries and only the primary can vote and be eligible to beprimary; i.e. the other two members have 0 forvotes and priority.

Connect a mongo shell to the primary and run:

rs.reconfig(
   {
      "_id" : <name>,
      "configsvr" : true,
      "protocolVersion" : NumberLong(1),
      "members" : [
         {
            "_id" : 0,
            "host" : "<host1>:<port1>",
            "priority" : 1,
            "votes" : 1
         },
         {
            "_id" : 1,
            "host" : "<host2>:<port2>",
            "priority" : 0,
            "votes" : 0
         },
         {
            "_id" : 2,
            "host" : "<host3>:<port3>",
            "priority" : 0,
            "votes" : 0
         }
      ]
   }
)

• Step down the primary using replSetStepDown against the admin database.Ensure enough time for the secondaries to catch up.

Connect a mongo shell to the primary and run:

db.adminCommand( { replSetStepDown: 360, secondaryCatchUpPeriodSecs: 300 })

• Shut down all members of the config server replica set,the mongos instances, and the shards.

• If you are rolling back to MMAPv1:

  • Start a CSRS member asa standalone; i.e. without the —replSetor, if using a configuration file, replication.replSetName.

  • Run mongodump to dump the config database, thenshutdown the CSRSmember.

mongodump --db "config"

Include all other options as required by your deployment.

• Create a data directory for the new mongod instancethat will run with the MMAPv1 storage engine. mongod must haveread and write permissions for the data directory.

mongod with MMAPv1 will not start with data files created witha different storage engine.

• Restart the mongod as a MMAPv1 standalone i.e. with—storageEngine mmapv1 and withoutthe —replSet or, if using aconfiguration file, replication.replSetName.

• Use mongorestore —drop to restore the config dump tothe new MMAPv1 mongod.

mongorestore --db="config" --drop /path/to/dump

• Repeat for each member of the CSRS.

Optionally, once the sharded cluster is online and working as expected,delete the WiredTiger data directories.

• Restart each config server as standalone 3.2 mongod;i.e. without the —replSet or, if using a configurationfile, replication.replSetName.

mongod --configsvr --dbpath <path> --port <port> --storageEngine <storageEngine>

Update the protocolVersion for each shard.

Restart each replica set shard and update the protocolVersion.

Connect a mongo shell to the current primary anddowngrade the replication protocol:

cfg = rs.conf();
cfg.protocolVersion=0;
rs.reconfig(cfg);

Downgrade the mongos instances.

Important

As the config servers changed from a replica set to threemirrored mongod instances, update the—configdb setting. All mongos must use thesame —configdb string.

Downgrade the binaries and restart.

Downgrade Config Servers.

Downgrade the binaries and restart. Downgrade in reverse order oftheir listing in the —configdb option formongos.

If your mongod instance is using the WiredTiger storage engine, you must include the—storageEngine option (or storage.engine ifusing the configuration file) with the 3.0 binary.

mongod --configsvr --dbpath <path> --port <port> --storageEngine <storageEngine>

Downgrade each shard, one at a time.

For each shard, remove the minOpTimeRecovery document from theadmin.system.version collection using the following removeoperation. If the shard is a replica set, issue the remove operationon the primary of the replica set for each shard:

use admin
db.system.version.remove(
   { _id: "minOpTimeRecovery" },
   { writeConcern: { w: "majority", wtimeout: 30000 } }
)

Note

If the cluster is running with authentication enabled, you must have auser with the proper privileges to remove the minOpTimeRecoverydocument from the admin.system.version collection. The followingoperation creates a downgrade user on the admin database with theproper privileges:

use admin;
 
db.createRole({
  role: "downgrade_csrs",
  privileges: [
     { resource: { db: "admin", collection: "system.version"}, actions: [ "remove" ] },
  ],
  roles: [  ]
});
 
db.createUser({
  user: "downgrade",
  roles: [
    { role: "downgrade_csrs", db: "admin" }
  ]
});

For each replica set shard, downgrade the mongod binariesand restart. If your mongod instance is using theWiredTiger storage engine, you must includethe —storageEngine option (or storage.engine ifusing the configuration file) with the 3.0 binary.

• Downgrade the mongod secondaries before downgradingthe primary.
• To downgrade the primary, run replSetStepDown and then downgrade.For details on downgrading a replica set, see Downgrade a 3.2 Replica Set.

Optionally, drop the local database from the SCCC members if it exists.

Re-enable the balancer.

Once the downgrade of sharded cluster components iscomplete, re-enable the balancer.