Downgrade MongoDB from 3.0
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.
Downgrade Recommendations and Checklist
When downgrading, consider the following:
Downgrade Path
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
.
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
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.
Downgrade MongoDB Processes
Downgrade a Standalone mongod
Instance
If you have changed the storage engine to WiredTiger
, change the
storage engine to MMAPv1 before downgrading to 2.6.
Change Storage Engine to MMAPv1
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
.
Export the data using mongodump
.
mongodump --out <exportDataDestination>
Specify additional options as appropriate, such as username and
password if running with authorization enabled. See
mongodump
for available options.
Create data directory for MMAPv1.
Create a new data directory for MMAPv1. Ensure that the user
account running mongod
has read and write permissions for
the new directory.
Restart the mongod
with MMAPv1.
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.
Upload the exported data using mongorestore
.
mongorestore <exportDataDestination>
Specify additional options as appropriate. See
mongorestore
for available options.
Downgrade Binaries
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.
Download 2.6 binaries.
Download binaries of the latest release in the 2.6 series from the MongoDB Download Page. See Install MongoDB for more information.
Downgrade a 3.0 Replica Set
If you have changed the storage engine to WiredTiger, change the storage 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 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:
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 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.
Restart the secondary member with MMAPv1.
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.
Downgrade Binaries
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:
Downgrade secondary members of the replica set.
Downgrade each secondary member of the replica set, one at a time:
Shut down the
mongod
. See Stopmongod
Processes for instructions on safely terminatingmongod
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 thers.status()
method in themongo
shell.
Step down the primary.
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.
Replace and restart former primary mongod
.
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.
Downgrade a 3.0 Sharded Cluster
Requirements
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:
any operation that creates a database
any other operation that modifies the cluster meta-data in any way. See Sharding Reference for a complete list of sharding commands. Note, however, that not all commands on the Sharding Reference page modifies the cluster meta-data.
Change Storage Engine to MMAPv1
If you have changed the storage engine to WiredTiger, change the storage engine to MMAPv1 before downgrading to 2.6.
Change Shards to Use MMAPv1
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.
Change Config Servers to Use MMAPv1
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.
Disable the Balancer.
Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
For the second config server, create a new data directory for MMAPv1.
Ensure that the user account running mongod
has 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. See
mongorestore
for available options.
Export data of the third config server.
mongodump --out <exportDataDestination>
Specify additional options as appropriate, such as username and
password if running with authorization enabled. See
mongodump
for available options.
For the third config server, create a new data directory for MMAPv1.
Ensure that the user account running mongod
has read and write permissions for the new directory.
Restart the third 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 third config server.
mongorestore <exportDataDestination>
Specify additional options as appropriate. See
mongorestore
for available options
For the first config server, create data directory for MMAPv1.
Ensure that the user account running mongod
has read and write permissions for the new directory.
Restart the first 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 first config server.
mongorestore <exportDataDestination>
Specify additional options as appropriate. See
mongorestore
for available options
Enable writes to the sharded cluster's metadata.
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.
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 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.
Disable the Balancer.
Turn off the balancer in the sharded cluster, as described in Disable 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, leaving
the first system in the mongos --configdb
argument to
downgrade last.
Re-enable the balancer.
Once the upgrade of sharded cluster components is complete, re-enable the balancer.
General Downgrade Procedure
Except as described on this page, moving between 2.6 and 3.0 is a drop-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 of
stopping a mongod
instance.