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
mongod 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.
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
authSchema 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
authSchemaUpgrade, you cannot downgrade to 2.6 without disabling
--auth or restoring a pre-upgrade backup, as
authSchemaUpgrade discards the
MONGODB-CR credentials used in 2.6. See Upgrade Existing MONGODB-CR Users to Use SCRAM-SHA-1.
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
zypper 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:
- 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 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
mongod instance, wait for the member to recover to
SECONDARY state before upgrading the next instance. To check the member’s state, issue
rs.status() in the
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.
To change the storage engine for a replica set to WiredTiger, see Change Replica Set to WiredTiger.
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.
Optional but Recommended. As a precaution, take a backup of the
config database before upgrading the sharded cluster.
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
mongos instance, you can use a new 3.0
mongos that can reach all the config servers.
To upgrade the meta data, run:
You can include the
--logpath option 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