Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Downgrade MongoDB from 3.0

On this page

  • Downgrade Recommendations and Checklist
  • Downgrade MongoDB Processes

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

When downgrading, consider the following:

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

Important

If you upgrade to MongoDB 3.0 and have run authSchemaUpgrade, you cannot downgrade to the 2.6 series without disabling --auth.

Follow the downgrade procedures:

Note

Optional. Consider compacting collections after downgrading. Otherwise, older versions will not be able to reuse free space regions larger than 2MB created while running 3.0. This can result in wasted space but no data loss following the downgrade.

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

To change storage engine to MMAPv1 for a standalone mongod instance, you will need to manually export and upload the data using mongodump and mongorestore.

1
2
mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username and password if running with authorization enabled. See mongodump for available options.

3

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

4

Restart the 3.0 mongod, specifying the newly created data directory for MMAPv1 as the --dbpath. You do not have to specify --storageEngine as MMAPv1 is the default.

mongod --dbpath <newMMAPv1DBPath>

Specify additional options as appropriate.

5
mongorestore <exportDataDestination>

Specify additional options as appropriate. See mongorestore for available options.

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

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

1

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

2

Shut down your mongod instance. Replace the existing binary with the 2.6 mongod binary and restart mongod.

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

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

Note

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

To change the storage engine to MMAPv1 for an existing secondary replica set member, remove the member's data and perform an initial sync:

1

Stop the mongod instance for the secondary member.

2

Prepare --dbpath directory for initial sync.

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

3

Restart the 3.0 mongod, specifying the MMAPv1 data directory as the --dbpath. Specify additional options as appropriate 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 will perform an initial sync. The length of the initial sync process depends on the size of the database and network connection between members of the replica set.

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

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

The following steps outline a "rolling" downgrade process for the replica set. The "rolling" downgrade process minimizes downtime by downgrading the members individually while the other members are available:

1

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

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

  2. Replace the 3.0 binary with the 2.6 binary and restart.

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

2

Use rs.stepDown() in the mongo shell to step 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.
3

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, shut down the previous primary and replace the mongod binary with the 2.6 binary and start the new instance.

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

While the downgrade is in progress, you cannot make changes to the collection meta-data. For example, during the downgrade, do not do any of the following:

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

To change the storage engine to MMAPv1, refer to the procedure in Change Storage Engine to MMAPv1 for replica set members and Change Storage Engine to MMAPv1 for standalone mongod as appropriate for your shards.

Note

During this process, only two config servers will be running at any given time to ensure that the sharded cluster's metadata is read only.

1

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

2
3
mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username and password if running with authorization enabled. See mongodump for available options.

4

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

5

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

mongod --dbpath <newMMAPv1DBPath> --configsvr
6
mongorestore <exportDataDestination>

Specify additional options as appropriate. See mongorestore for available options.

7
8
9
mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username and password if running with authorization enabled. See mongodump for available options.

10

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

11

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

mongod --dbpath <newMMAPv1DBPath> --configsvr
12
mongorestore <exportDataDestination>

Specify additional options as appropriate. See mongorestore for available options

13
mongodump --out <exportDataDestination>

Specify additional options as appropriate, such as username and password if running with authorization enabled. See mongodump for available options.

14

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

15

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

mongod --dbpath <newMMAPv1DBPath> --configsvr
16
mongorestore <exportDataDestination>

Specify additional options as appropriate. See mongorestore for available options

17

Restart the second config server, specifying the newly created MMAPv1 data directory as the --dbpath. Specify additional options as appropriate.

mongod --dbpath <newMMAPv1DBPath> --configsvr

Once all three config servers are up, the sharded cluster's metadata is available for writes.

18

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

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

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

1

Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

2

For each shard:

  1. Downgrade the mongod secondaries before downgrading the primary.

  2. To downgrade the primary, run replSetStepDown and downgrade.

3

Downgrade all 3 mongod config server instances, leaving the first system in the mongos --configdb argument to downgrade last.

4

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

5

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

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

1

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 of stopping a mongod instance.

2

Ensure you start the 2.6 mongod with the same dbPath:

mongod --dbpath /var/mongod/data

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

←  Upgrade to SCRAMRelease Notes for MongoDB 2.6 →