Upgrade MongoDB to 2.6

In the general case, the upgrade from MongoDB 2.4 to 2.6 is abinary-compatible “drop-in” upgrade: shut down the mongodinstances and replace them with mongod instances running2.6. However, before you attempt any upgrade, familiarize yourselfwith the content of this document, particularly theUpgrade Recommendations and Checklists, the procedure for upgradingsharded clusters, and the considerations forreverting to 2.4 after running 2.6.

Upgrade Recommendations and Checklists

When upgrading, consider the following:

Upgrade Requirements

To upgrade an existing MongoDB deployment to 2.6, you must be running2.4. If you’re running a version of MongoDB before 2.4, you _must_upgrade to 2.4 before upgrading to 2.6. SeeUpgrade MongoDB to 2.4 for the procedure to upgrade from2.2 to 2.4.

If you use MongoDB Cloud Manager Backup, ensure that you’re running at least versionv20131216.1 of the Backup agent before upgrading. Version 1.4.0 ofthe backup agent followed v20131216.1

Preparedness

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

To begin the upgrade procedure, connect a 2.6 mongo shell toyour MongoDB 2.4 mongos or mongod and run thedb.upgradeCheckAllDBs() to check your data set forcompatibility. This is a preliminary automated check. Assess andresolve all issues identified by db.upgradeCheckAllDBs().

Some changes in MongoDB 2.6 require manual checks andintervention. See Compatibility Changes in MongoDB 2.6 for anexplanation of these changes. Resolve all incompatibilities in yourdeployment before continuing.

For a deployment that uses authentication and authorization, be sureyou have at least one user in the admin database with the roleuserAdminAnyDatabasebefore upgrading the MongoDBbinaries. For deployments currently usingauthentication and authorization, see the consideration fordeployments that use authentication and authorization.

Authentication

MongoDB 2.6 includes significant changes to the authorization model,which requires changes to the way that MongoDB stores users’credentials. As a result, in addition to upgrading MongoDB processes,if your deployment uses authentication and authorization, afterupgrading all MongoDB process to 2.6 you must also upgrade theauthorization model.

Before beginning the upgrade process for a deployment that usesauthentication and authorization:

  • Ensure that at least one user exists in the admin database withthe role userAdminAnyDatabase.
  • If your application performs CRUD operations on the<database>.system.users collection or uses adb.addUser()-like method, then you mustupgrade those drivers (i.e. client libraries) beforemongod or mongos instances.
  • You must fully complete the upgrade procedure for all MongoDBprocesses before upgrading the authorization model.

After you begin to upgrade a MongoDB deployment that usesauthentication to 2.6, you cannot modify existing user data untilyou complete the authorization user schema upgrade.

See Upgrade User Authorization Data to 2.6 Format for a complete discussionof the upgrade procedure for the authorization model includingadditional requirements and procedures.

Downgrade Limitations

Once upgraded to MongoDB 2.6, you cannot downgrade to any versionearlier than MongoDB 2.4. If you created text or 2dsphereindexes while running 2.6, you can only downgrade to MongoDB 2.4.10 orlater.

Package Upgrades

If you installed MongoDB from the MongoDB apt or yum repositories,upgrade to 2.6 using the package manager.

For Debian, Ubuntu, and related operating systems, type these commands:

  1. sudo apt-get update
  2. sudo apt-get install mongodb-org

For Red Hat Enterprise, CentOS, Fedora, or Amazon Linux:

  1. sudo yum install mongodb-org

If you did not install the mongodb-org package, and installed a subsetof MongoDB components replace mongodb-org in the commands above withthe appropriate package names.

See installation instructions for Ubuntu, RHEL,Debian for a list of theavailable packages and complete MongoDB installation instructions.

Upgrade MongoDB Processes

Upgrade Standalone mongod Instance to MongoDB 2.6

The following steps outline the procedure to upgrade a standalonemongod from version 2.4 to 2.6. To upgrade from version2.2 to 2.6, upgrade to version 2.4first, and then follow the procedure toupgrade from 2.4 to 2.6.

Upgrade a Replica Set to 2.6

The following steps outline the procedure to upgrade a replica set fromMongoDB 2.4 to MongoDB 2.6. To upgrade from MongoDB 2.2 to 2.6,upgrade all members of the replica set to version 2.4first, and then follow the procedure toupgrade from MongoDB 2.4 to 2.6.

You can upgrade from MongoDB 2.4 to 2.6 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.4 binarywith the 2.6 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 the2.6 binary and start the new instance.

Replica set failover is not instant but will render the setunavailable accept writes until the failover processcompletes. Typically this takes 30 seconds or more: schedule theupgrade procedure during a scheduled maintenance window.

Upgrade a Sharded Cluster to 2.6

Only upgrade sharded clusters to 2.6 if all members of thecluster are currently running instances of 2.4. The only supportedupgrade path for sharded clusters running 2.2 is via 2.4. The upgradeprocess checks all components of the cluster and will produce warningsif any component is running version 2.2.

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 2.6 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 2.6, or if youneed to avoid reconfiguring a production mongos instance,you can use a new 2.6 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 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. upgrade of config server to v5 successful
  2. Config database is at version v5

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 v2.6.

Upgrade and restart without the —upgrade option theother mongos instances in the sharded cluster. Afterupgrading all the mongos, seeComplete Sharded Cluster Upgrade for information onupgrading the other cluster components.

Complete Sharded Cluster Upgrade

After you have successfully upgraded allmongos instances,you can upgrade the other instances in your MongoDB deployment.

Warning

Do not upgrade mongod instances until after you haveupgraded allmongos instances.

While the balancer is still disabled, upgrade the components of yoursharded cluster in the following order:

  • Upgrade all 3 mongod config server instances, leavingthe first system in the mongos —configdb argument to upgradelast.
  • Upgrade each shard, one at a time, upgrading the mongodsecondaries before running replSetStepDown andupgrading the primary of each shard.

When this process is complete, re-enable thebalancer.

Upgrade Procedure

Once upgraded to MongoDB 2.6, you cannot downgrade to any versionearlier than MongoDB 2.4. If you have text or 2dsphere indexes,you can only downgrade to MongoDB 2.4.10 or later.

Except as described on this page, moving between 2.4 and 2.6 is adrop-in replacement:

Stop the existing mongod instance.

For example, on Linux, run 2.4 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 2.6 mongod with the samedbPath:

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

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