In the general case, the upgrade from MongoDB 2.4 to 2.6 is a binary-compatible “drop-in” upgrade: shut down the mongod instances and replace them with mongod instances running 2.6. However, before you attempt any upgrade, familiarize yourself with the content of this document, particularly the Upgrade Recommendations and Checklists, the procedure for upgrading sharded clusters, and the considerations for reverting to 2.4 after running 2.6.
When upgrading, consider the following:
To upgrade an existing MongoDB deployment to 2.6, you must be running 2.4. If you’re running a version of MongoDB before 2.4, you must upgrade to 2.4 before upgrading to 2.6. See Upgrade MongoDB to 2.4 for the procedure to upgrade from 2.2 to 2.4.
If you use MongoDB Cloud Manager Backup, ensure that you’re running at least version v20131216.1 of the Backup agent before upgrading. Version 1.4.0 of the backup agent followed v20131216.1
Before upgrading MongoDB always test your application in a staging environment before deploying the upgrade to your production environment.
To begin the upgrade procedure, connect a 2.6 mongo shell to your MongoDB 2.4 mongos or mongod and run the db.upgradeCheckAllDBs() to check your data set for compatibility. This is a preliminary automated check. Assess and resolve all issues identified by db.upgradeCheckAllDBs().
Some changes in MongoDB 2.6 require manual checks and intervention. See Compatibility Changes in MongoDB 2.6 for an explanation of these changes. Resolve all incompatibilities in your deployment before continuing.
For a deployment that uses authentication and authorization, be sure you have at least one user in the admin database with the role userAdminAnyDatabase before upgrading the MongoDB binaries. For deployments currently using authentication and authorization, see the consideration for deployments that use authentication and authorization.
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, after upgrading all MongoDB process to 2.6 you must also upgrade the authorization model.
Before beginning the upgrade process for a deployment that uses authentication and authorization:
admin database with the role userAdminAnyDatabase.<database>.system.users collection or uses a db.addUser()-like method, then you must
upgrade those drivers (i.e. client libraries) before
mongod or mongos instances.After you begin to upgrade a MongoDB deployment that uses authentication to 2.6, you cannot modify existing user data until you complete the authorization user schema upgrade.
See Upgrade User Authorization Data to 2.6 Format for a complete discussion of the upgrade procedure for the authorization model including additional requirements and procedures.
Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier than MongoDB 2.4. If you created text or 2dsphere indexes while running 2.6, you can only downgrade to MongoDB 2.4.10 or later.
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:
For Red Hat Enterprise, CentOS, Fedora, or Amazon Linux:
If you did not install the mongodb-org package, and installed a subset of MongoDB components replace mongodb-org in the commands above with the appropriate package names.
See installation instructions for Ubuntu, RHEL, Debian for a list of the available packages and complete MongoDB installation instructions.
mongod Instance to MongoDB 2.6¶The following steps outline the procedure to upgrade a standalone mongod from version 2.4 to 2.6. To upgrade from version 2.2 to 2.6, upgrade to version 2.4 first, and then follow the procedure to upgrade from 2.4 to 2.6.
mongod instance. Replace the existing binary with the 2.6 mongod binary and restart mongod.The following steps outline the procedure to upgrade a replica set from MongoDB 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.4 first, and then follow the procedure to upgrade from MongoDB 2.4 to 2.6.
You can upgrade from MongoDB 2.4 to 2.6 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.4 binary with the 2.6 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 mongo shell.
Use rs.stepDown() in the mongo shell to step down the primary and force the set to failover. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.
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 accept writes until the failover process completes. Typically this takes 30 seconds or more: schedule the upgrade procedure during a scheduled maintenance window.
Only upgrade sharded clusters to 2.6 if all members of the cluster are currently running instances of 2.4. The only supported upgrade path for sharded clusters running 2.2 is via 2.4. The upgrade process checks all components of the cluster and will produce warnings if any component is running version 2.2.
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:
sh.enableSharding()sh.shardCollection()sh.addShard()db.createCollection()db.collection.drop()db.dropDatabase()Optional but Recommended. As a precaution, take a backup of the config database before upgrading the sharded cluster.
Turn off the balancer in the sharded cluster, as described in Disable the Balancer.
Start a single 2.6 mongos instance with the configDB pointing to the cluster’s config servers and with the --upgrade option.
To run a mongos with the --upgrade option, you can upgrade an existing mongos instance to 2.6, or if you need to avoid reconfiguring a production mongos instance, you can use a new 2.6 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 --sslOnNormalPorts or --sslPEMKeyFile.
The mongos will exit upon completion of the --upgrade process.
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.¶The mongos will exit upon completion of the meta data upgrade process. If successful, the process will log the following messages:
After a successful upgrade, restart the mongos instance. If mongos fails to start, check the log for more information.
If the 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.
mongos instances to v2.6.¶Upgrade and restart without the --upgrade option the other mongos instances in the sharded cluster. After upgrading all the mongos, see Complete Sharded Cluster Upgrade for information on upgrading the other cluster components.
After you have successfully upgraded all mongos instances, you can upgrade the other instances in your MongoDB deployment.
While the balancer is still disabled, upgrade the components of your sharded cluster in the following order:
mongod config server instances, leaving the first system in the mongos --configdb argument to upgrade last.mongod secondaries before running replSetStepDown and upgrading the primary of each shard.When this process is complete, re-enable the balancer.
Once upgraded to MongoDB 2.6, you cannot downgrade to any version earlier 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 a drop-in replacement:
mongod instance.¶For example, on Linux, run 2.4 mongod with the --shutdown option as follows:
Replace /var/mongod/data with your MongoDB dbPath. See also the Stop mongod Processes for alternate methods of stopping a mongod instance.