Downgrade MongoDB from 3.0

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

Once upgraded to MongoDB 3.0, you cannot downgrade to a versionlower than 2.6.8.

Important

If you upgrade to MongoDB 3.0 and have runauthSchemaUpgrade, you cannot downgrade to the 2.6series without disabling —auth.

Procedures

Follow the downgrade procedures:

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

Note

Optional. Consider compacting collectionsafter downgrading. Otherwise, older versions will not be able toreuse free space regions larger than 2MB created while running 3.0.This can result in wasted space but no data loss following thedowngrade.

Downgrade MongoDB Processes

Downgrade a Standalone mongod Instance

If you have changed the storage engine to WiredTiger, change thestorage engine to MMAPv1 before downgrading to 2.6.

Change Storage Engine to MMAPv1

To change storage engine to MMAPv1 for a standalone mongodinstance, you will need to manually export and upload the data usingmongodump and mongorestore.

Ensure 3.0 mongod is running with WiredTiger.

Export the data using mongodump.

mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username andpassword if running with authorization enabled. Seemongodump for available options.

Create data directory for MMAPv1.

Create a new data directory for MMAPv1. Ensure that the useraccount running mongod has read and write permissions forthe new directory.

Restart the mongod with MMAPv1.

Restart the 3.0 mongod, specifying the newly created datadirectory for MMAPv1 as the —dbpath. You do not have tospecify —storageEngine as MMAPv1 is the default.

mongod --dbpath <newMMAPv1DBPath>

Specify additional options as appropriate.

Upload the exported data using mongorestore.

mongorestore <exportDataDestination>

Specify additional options as appropriate. Seemongorestore for available options.

Downgrade Binaries

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

Once upgraded to MongoDB 3.0, you cannot downgrade to a versionlower than 2.6.8.

Download 2.6 binaries.

Download binaries of the latest release in the 2.6 series from theMongoDB Download Page. See Install MongoDB for moreinformation.

Replace with 2.6 binaries.

Shut down your mongod instance. Replace the existingbinary with the 2.6 mongod binary and restartmongod.

Downgrade a 3.0 Replica Set

If you have changed the storage engine to WiredTiger, change thestorage engine to MMAPv1 before downgrading to 2.6.

Change Storage Engine to MMAPv1

You can update members to use the MMAPv1 storage engine in a rollingmanner.

Note

When running a replica set with mixed storage engines, performancecan vary according to workload.

To change the storage engine to MMAPv1 for an existing secondaryreplica set member, remove the member’s data and perform aninitial sync:

Shutdown the secondary member.

Stop the mongod instance for the secondary member.

Prepare data directory for MMAPv1.

Prepare —dbpath directory for initial sync.

For the stopped secondary member, either delete the content of thedata directory or create a new data directory. If creating a newdirectory, ensure that the user account running mongod hasread and write permissions for the new directory.

Restart the secondary member with MMAPv1.

Restart the 3.0 mongod, specifying the MMAPv1 datadirectory as the —dbpath. Specify additional options asappropriate for the member. You do not have to specify—storageEngine since MMAPv1 is the default.

mongod --dbpath <preparedMMAPv1DBPath>

Since no data exists in the —dbpath, the mongod willperform an initial sync. The length of the initial sync processdepends on the size of the database and network connection betweenmembers of the replica set.

Repeat for the remaining the secondary members. Once all the secondarymembers have switched to MMAPv1, step down the primary, and update thestepped-down member.

Downgrade Binaries

Once upgraded to MongoDB 3.0, you cannot downgrade to a versionlower than 2.6.8.

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 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.0 binary with the 2.6 binary and restart.
• 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 is
• preferable 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 2.6 binary and start the new instance.

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.0 Sharded Cluster

Requirements

While the downgrade is in progress, you cannot make changes to thecollection meta-data. 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.

Change Storage Engine to MMAPv1

If you have changed the storage engine to WiredTiger, change thestorage engine to MMAPv1 before downgrading to 2.6.

Change Shards to Use MMAPv1

To change the storage engine to MMAPv1, refer to the procedure inChange Storage Engine to MMAPv1 for replica set members and Change Storage Engine toMMAPv1 for standalone mongod asappropriate for your shards.

Change Config Servers to Use MMAPv1

Note

During this process, only two config servers will be running at anygiven time to ensure that the sharded cluster’s metadata isread only.

Disable the Balancer.

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

Stop the last config server listed in the mongos’ configDB setting.

Export data of the second config server listed in the mongos’ configDB setting.

mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username andpassword if running with authorization enabled. Seemongodump for available options.

For the second config server, create a new data directory for MMAPv1.

Ensure that the user account running mongodhas read and write permissions for the new directory.

Restart the second config server with MMAPv1.

Specify the newly created MMAPv1 data directory as the—dbpath as well as any additional options as appropriate.

mongod --dbpath <newMMAPv1DBPath> --configsvr

Upload the exported data using mongorestore to the second config server.

mongorestore <exportDataDestination>

Specify additional options as appropriate. Seemongorestore for available options.

Shut down the second config server.

Restart the third config server.

Export data of the third config server.

mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username andpassword if running with authorization enabled. Seemongodump for available options.

For the third config server, create a new data directory for MMAPv1.

Ensure that the user account running mongodhas read and write permissions for the new directory.

Restart the third config server with MMAPv1.

Specify the newlycreated MMAPv1 data directory as the —dbpath as wellas any additional options as appropriate.

mongod --dbpath <newMMAPv1DBPath> --configsvr

Upload the exported data using mongorestore to the third config server.

mongorestore <exportDataDestination>

Specify additional options as appropriate. Seemongorestore for available options

Export data of the first config server listed in the mongos’ configDB setting.

mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username andpassword if running with authorization enabled. Seemongodump for available options.

For the first config server, create data directory for MMAPv1.

Ensure that the user account running mongodhas read and write permissions for the new directory.

Restart the first config server with MMAPv1.

Specify the newlycreated MMAPv1 data directory as the —dbpath as wellas any additional options as appropriate.

mongod --dbpath <newMMAPv1DBPath> --configsvr

Upload the exported data using mongorestore to the first config server.

mongorestore <exportDataDestination>

Specify additional options as appropriate. Seemongorestore for available options

Enable writes to the sharded cluster’s metadata.

Restart the second config server, specifying the newly createdMMAPv1 data directory as the —dbpath. Specifyadditional options as appropriate.

mongod --dbpath <newMMAPv1DBPath> --configsvr

Once all three config servers are up, the sharded cluster’s metadatais available for writes.

Re-enable the balancer.

Once all three config servers are up and running with WiredTiger,Re-enable the balancer.

Downgrade Binaries

Once upgraded to MongoDB 3.0, you cannot downgrade to a versionlower than 2.6.8.

The downgrade procedure for a sharded cluster reverses the order of theupgrade procedure. The version v6 config database is backwardscompatible with MongoDB 2.6.

Disable the Balancer.

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

Downgrade each shard, one at a time.

For each shard:

• Downgrade the mongod secondaries before downgrading the primary.
• To downgrade the primary, run replSetStepDown and downgrade.

Downgrade the config servers.

Downgrade all 3 mongod config server instances, leavingthe first system in the mongos —configdb argument todowngrade last.

Downgrade the mongos instances.

Downgrade and restart each mongos, one at a time. Thedowngrade process is a binary drop-in replacement.

Re-enable the balancer.

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

General Downgrade Procedure

Except as described on this page, moving between 2.6 and 3.0 is adrop-in replacement:

Stop the existing mongod instance.

For example, on Linux, run 3.0 mongod with the—shutdown option as follows:

mongod --dbpath /var/mongod/data --shutdown

Replace /var/mongod/data with your MongoDB dbPath.See also the Stop mongod Processes for alternate methods ofstopping a mongod instance.

Start the new mongod instance.

Ensure you start the 2.6 mongod with the samedbPath:

mongod --dbpath /var/mongod/data

Replace /var/mongod/data with your MongoDB dbPath.