Upgrade MongoDB to 3.0
On this page
In the general case, the upgrade from MongoDB 2.6 to 3.0 is a
binary-compatible "drop-in" upgrade: shut down the
instances and replace them with
mongod instances running
3.0. However, before you attempt any upgrade please familiarize
yourself with the content of this document, particularly the procedure
for upgrading sharded clusters.
If you need guidance on upgrading to 3.0, MongoDB offers consulting to help ensure a smooth transition without interruption to your MongoDB application.
Upgrade Recommendations and Checklists
When upgrading, consider the following:
To upgrade an existing MongoDB deployment to 3.0, you must be running 2.6. If you're running a version of MongoDB before 2.6, you must upgrade to 2.6 before upgrading to 3.0. See Upgrade to 2.6 for the procedure to upgrade from 2.4 to 2.6. Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4.
If your existing MongoDB deployment is already running with
authentication and authorization, your user data model
must be at least version 3. To verify the version of your existing
authSchema, see MongoDB 2.4 User Model Removed. To upgrade your
authSchema version, see
Upgrade Authorization Data for details.
Before upgrading MongoDB, always test your application in a staging environment before deploying the upgrade to your production environment.
Some changes in MongoDB 3.0 require manual checks and intervention. Before beginning your upgrade, see the Compatibility Changes in MongoDB 3.0 document to ensure that your applications and deployments are compatible with MongoDB 3.0. Resolve the incompatibilities in your deployment before starting the upgrade.
Once upgraded to MongoDB 3.0, you cannot downgrade to a version lower than 2.6.8.
If you upgrade to 3.0 and have run
cannot downgrade to 2.6 without disabling
restoring a pre-upgrade backup, as
MONGODB-CR credentials used in 2.6. See
MONGODB-CR Users to Use
Upgrade MongoDB Processes
mongod Instance to MongoDB 3.0
The following steps outline the procedure to upgrade a standalone
mongod from version 2.6 to 3.0. To upgrade from version
2.4 to 3.0, upgrade to version 2.6
first, and then use the following procedure to upgrade from 2.6 to 3.0.
If you installed MongoDB from the MongoDB
repositories, you should upgrade to 3.0 using your package manager. Follow the
appropriate installation instructions
for your Linux system. This will involve adding a repository for the new
release, then performing the actual upgrade.
Otherwise, you can manually upgrade MongoDB:
Download 3.0 binaries.
Download binaries of the latest release in the 3.0 series from the MongoDB Download Page. See Install MongoDB for more information.
Change Storage Engine for Standalone to WiredTiger
To change the storage engine for a standalone
instance to WiredTiger, see
Change Standalone to WiredTiger.
Upgrade a Replica Set to 3.0
If the oplog contains entries generated by versions of MongoDB that precede version 2.2.1, you must wait for the entries to be overwritten by later versions before you can upgrade to MongoDB 3.0. For more information, see Replica Set Oplog Format Change
Stricter validation in MongoDB 3.0 of replica set configuration may invalidate previously-valid replica set configuration, preventing replica sets from starting in MongoDB 3.0. For more information, see Replica Set Configuration Validation.
All replica set members must be running version 2.6 before you can upgrade them to version 3.0. To upgrade a replica set from an earlier MongoDB version, upgrade all members of the replica set to version 2.6 first, and then follow the procedure to upgrade from MongoDB 2.6 to 3.0.
You can upgrade from MongoDB 2.6 to 3.0 using a "rolling" upgrade to minimize downtime by upgrading the members individually while the other members are available:
Upgrade secondary members of the replica set.
Upgrade the secondary members of the set one at a time by
shutting down the
mongod and replacing the 2.6 binary
with the 3.0 binary. After upgrading a
wait for the member to recover to
before upgrading the next instance.
To check the member's state, issue
rs.status() in the
Step down the replica set primary.
rs.stepDown() in the
mongo shell to
step down the primary and force the set to failover.
expedites the failover procedure and is preferable to shutting down
the primary directly.
Upgrade the primary.
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
3.0 binary and start the new instance.
Replica set failover is not instant and will render the set unavailable to accept writes until the failover process completes. This may take 30 seconds or more: schedule the upgrade procedure during a scheduled maintenance window.
Change Replica Set Storage Engine to WiredTiger
To change the storage engine for a replica set to WiredTiger, see Change Replica Set to WiredTiger.
Upgrade a Sharded Cluster to 3.0
Only upgrade sharded clusters to 3.0 if all members of the cluster are currently running instances of 2.6. The only supported upgrade path for sharded clusters running 2.4 is via 2.6. The upgrade process checks all components of the cluster and will produce warnings if any component is running version 2.4.
The upgrade process does not require any downtime. However, while you upgrade the sharded cluster, ensure that clients do not make changes to the collection meta-data. For example, during the upgrade, do not do any of the following:
any operation that creates a database
any other operation that modifies the cluster metadata 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.
Upgrade Sharded Clusters
Optional but Recommended. As a precaution, take a backup of the
config database before upgrading the sharded cluster.
Disable the Balancer.
Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
Upgrade the cluster's meta data.
Start a single 3.0
mongos instance with
configDB pointing to the cluster's config servers and with
To run a
mongos with the
--upgrade option, you
can upgrade an existing
mongos instance to 3.0, or if you
need to avoid reconfiguring a production
you can use a new 3.0
mongos that can reach all the config
To upgrade the meta data, run:
mongos --configdb <configDB string> --upgrade
You can include the
to output the log messages to a file instead of the standard
output. Also include any other options required to start
mongos instances in your cluster, such as
mongos will output informational log
<timestamp> I SHARDING [mongosMain] MongoS version 3.0.0 starting: ... ... <timestamp> I SHARDING [mongosMain] starting upgrade of config server from v5 to v6 <timestamp> I SHARDING [mongosMain] starting next upgrade step from v5 to v6 <timestamp> I SHARDING [mongosMain] about to log new metadata event: ... <timestamp> I SHARDING [mongosMain] checking that version of host ... is compatible with 2.6 ... <timestamp> I SHARDING [mongosMain] upgrade of config server to v6 successful ... <timestamp> I SHARDING [mongosMain] distributed lock 'configUpgrade/...' unlocked. <timestamp> I - [mongosMain] Config database is at version v6
mongos will exit upon completion of the
The upgrade will prevent any chunk moves or splits from occurring during the upgrade process. If the data files have many sharded collections or if failed processes hold stale locks, acquiring the locks for all collections can take seconds or minutes. Watch the log for progress updates.
mongos --upgrade process completes successfully.
mongos will exit upon completion of the meta data
upgrade process. If successful, the process will log the following
<timestamp> I SHARDING [mongosMain] upgrade of config server to v6 successful ... <timestamp> I - [mongosMain] Config database is at version v6
After a successful upgrade, restart the
mongos fails to start, check the log for more
mongos instance loses its connection to the config
servers during the upgrade or if the upgrade is otherwise
unsuccessful, you may always safely retry the upgrade.
Upgrade the remaining
mongos instances to 3.0.
Upgrade and restart without the
--upgrade option the
mongos instances in the sharded cluster.
After you have successfully upgraded all
instances, you can proceed to upgrade the other components in your
Upgrade the config servers.
After you have successfully upgraded all
instances, upgrade all 3
mongod config server instances,
leaving the first config server listed in the
mongos --configdb argument to upgrade last.
Upgrade the shards.
Upgrade each shard, one at a time, upgrading the
secondaries before running
replSetStepDown and upgrading
the primary of each shard.
Re-enable the balancer.
Once the upgrade of sharded cluster components is complete, Re-enable the balancer.
Change Sharded Cluster Storage Engine to WiredTiger
For a sharded cluster in MongoDB 3.0, you can choose to update the shards to use WiredTiger storage engine and have the config servers use MMAPv1. If you update the config servers to use WiredTiger, you must update all three config servers to use WiredTiger.
To change a sharded cluster to use WiredTiger, see Change Sharded Cluster to WiredTiger.
MONGODB-CR Users to Use
After upgrading the binaries, see Upgrade to SCRAM for details on
SCRAM-SHA-1 upgrade scenarios.
General Upgrade Procedure
Except as described on this page, moving between 2.6 and 3.0 is a drop-in replacement:
Stop the existing
For example, on Linux, run 2.6
mongod with the
--shutdown option as follows:
mongod --dbpath /var/mongod/data --shutdown
/var/mongod/data with your MongoDB
See also the Stop
mongod Processes for alternate methods of