Upgrade MongoDB to 3.0

In the general case, the upgrade from MongoDB 2.6 to 3.0 is abinary-compatible “drop-in” upgrade: shut down the mongodinstances and replace them with mongod instances running3.0. However, before you attempt any upgrade please familiarizeyourself with the content of this document, particularly the procedurefor upgrading sharded clusters.

If you need guidance on upgrading to 3.0, MongoDB offers consultingto help ensure a smooth transition without interruption to yourMongoDB application.

Upgrade Recommendations and Checklists

When upgrading, consider the following:

Upgrade Requirements

To upgrade an existing MongoDB deployment to 3.0, you must be running2.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.4to 2.6. Once upgraded to MongoDB 2.6, you cannot downgrade to anyversion earlier than MongoDB 2.4.

If your existing MongoDB deployment is already running withauthentication and authorization, your user data model authSchemamust be at least version 3. To verify the version of your existingauthSchema, see MongoDB 2.4 User Model Removed. To upgrade yourauthSchema version, seeUpgrade Authorization Data for details.

Preparedness

Before upgrading MongoDB, always test your application in a stagingenvironment before deploying the upgrade to your productionenvironment.

Some changes in MongoDB 3.0 require manual checks and intervention.Before beginning your upgrade, see theCompatibility Changes in MongoDB 3.0 document to ensure that yourapplications and deployments are compatible with MongoDB 3.0. Resolvethe incompatibilities in your deployment before starting the upgrade.

Downgrade Limitations

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

If you upgrade to 3.0 and have run authSchemaUpgrade, youcannot downgrade to 2.6 without disabling —auth orrestoring a pre-upgrade backup, as authSchemaUpgradediscards the MONGODB-CR credentials used in 2.6. SeeUpgrade Existing MONGODB-CR Users to Use SCRAM-SHA-1.

Upgrade MongoDB Processes

Upgrade Standalone mongod Instance to MongoDB 3.0

The following steps outline the procedure to upgrade a standalonemongod from version 2.6 to 3.0. To upgrade from version2.4 to 3.0, upgrade to version 2.6first, and then use the following procedure to upgrade from 2.6 to 3.0.

Upgrade Binaries

If you installed MongoDB from the MongoDB apt, yum, or zypperrepositories, you should upgrade to 3.0 using your package manager. Follow theappropriate installation instructionsfor your Linux system. This will involve adding a repository for the newrelease, 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 theMongoDB Download Page. See Install MongoDB for moreinformation.

Replace 2.6 binaries.

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

Change Storage Engine for Standalone to WiredTiger

To change the storage engine for a standalone mongodinstance to WiredTiger, seeChange Standalone to WiredTiger.

Upgrade a Replica Set to 3.0

Prerequisites

Upgrade Binaries

You can upgrade from MongoDB 2.6 to 3.0 using a “rolling” upgrade tominimize downtime by upgrading the members individually while the othermembers are available:

Upgrade secondary members of the replica set.

Upgrade the secondary members of the set one at a time byshutting down the mongod and replacing the 2.6 binarywith the 3.0 binary. After upgrading a mongod instance,wait for the member to recover to SECONDARY statebefore upgrading the next instance.To check the member’s state, issue rs.status() in themongo shell.

Step down the replica set primary.

Use rs.stepDown() in the mongo shell tostep down the primary and force the set to failover. rs.stepDown()expedites the failover procedure and is preferable to shutting downthe primary directly.

Upgrade the primary.

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 with the3.0 binary and start the new instance.

Replica set failover is not instant and will render the setunavailable to accept writes until the failover processcompletes. This may take 30 seconds or more: schedule theupgrade 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 thecluster are currently running instances of 2.6. The only supportedupgrade path for sharded clusters running 2.4 is via 2.6. The upgradeprocess checks all components of the cluster and will produce warningsif any component is running version 2.4.

Considerations

The upgrade process does not require any downtime. However, while youupgrade the sharded cluster, ensure that clients do not make changesto the collection meta-data. For example, during the upgrade, do notdo any of the following:

Upgrade Sharded Clusters

Optional but Recommended. As a precaution, take a backup of theconfig database before upgrading the sharded cluster.

Disable the Balancer.

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

Upgrade the cluster’s meta data.

Start a single 3.0 mongos instance withthe configDB pointing to the cluster’s config servers and withthe —upgrade option.

To run a mongos with the —upgrade option, youcan upgrade an existing mongos instance to 3.0, or if youneed to avoid reconfiguring a production mongos instance,you can use a new 3.0 mongos that can reach all the configservers.

To upgrade the meta data, run:

  1. mongos --configdb <configDB string> --upgrade

You can include the —logpath optionto output the log messages to a file instead of the standardoutput. Also include any other options required to startmongos instances in your cluster, such as—sslOnNormalPorts or—sslPEMKeyFile.

The 3.0 mongos will output informational logmessages.

  1. <timestamp> I SHARDING [mongosMain] MongoS version 3.0.0 starting: ...
  2. ...
  3. <timestamp> I SHARDING [mongosMain] starting upgrade of config server from v5 to v6
  4. <timestamp> I SHARDING [mongosMain] starting next upgrade step from v5 to v6
  5. <timestamp> I SHARDING [mongosMain] about to log new metadata event: ...
  6. <timestamp> I SHARDING [mongosMain] checking that version of host ... is compatible with 2.6
  7. ...
  8. <timestamp> I SHARDING [mongosMain] upgrade of config server to v6 successful
  9. ...
  10. <timestamp> I SHARDING [mongosMain] distributed lock 'configUpgrade/...' unlocked.
  11. <timestamp> I -        [mongosMain] Config database is at version v6

The mongos will exit upon completion of the—upgrade process.

The upgrade will prevent any chunk moves or splits from occurringduring the upgrade process. If the data files have many shardedcollections or if failed processes hold stale locks,acquiring the locks for all collections can takeseconds or minutes. Watch the log for progress updates.

Ensure mongos —upgrade process completes successfully.

The mongos will exit upon completion of the meta dataupgrade process. If successful, the process will log the followingmessages:

  1. <timestamp> I SHARDING [mongosMain] upgrade of config server to v6 successful
  2. ...
  3. <timestamp> I -        [mongosMain] Config database is at version v6

After a successful upgrade, restart the mongos instance.If mongos fails to start, check the log for moreinformation.

If the mongos instance loses its connection to the configservers during the upgrade or if the upgrade is otherwiseunsuccessful, you may always safely retry the upgrade.

Upgrade the remaining mongos instances to 3.0.

Upgrade and restart without the —upgrade option theother mongos instances in the sharded cluster.

After you have successfully upgraded allmongosinstances, you can proceed to upgrade the other components in yoursharded cluster.

Warning

Do not upgrade the mongod instances until after you haveupgraded all the mongos instances.

Upgrade the config servers.

After you have successfully upgraded allmongosinstances, upgrade all 3 mongod config server instances,leaving the first config server listed in themongos —configdb argument to upgrade last.

Upgrade the shards.

Upgrade each shard, one at a time, upgrading the mongodsecondaries before running replSetStepDown and upgradingthe primary of each shard.

Re-enable the balancer.

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

Change Sharded Cluster Storage Engine to WiredTiger

For a sharded cluster in MongoDB 3.0, you can choose to update theshards to use WiredTiger storage engine and have the config servers useMMAPv1. If you update the config servers to use WiredTiger, you mustupdate all three config servers to use WiredTiger.

To change a sharded cluster to use WiredTiger, seeChange Sharded Cluster to WiredTiger.

Upgrade Existing MONGODB-CR Users to Use SCRAM-SHA-1

After upgrading the binaries, see Upgrade to SCRAM for details onSCRAM-SHA-1 upgrade scenarios.

General Upgrade 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 2.6 mongod with the—shutdown option as follows:

  1. 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 3.0 mongod with the samedbPath:

  1. mongod --dbpath /var/mongod/data

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