Upgrade MongoDB to 2.6
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.
Upgrade Recommendations and Checklists
When upgrading, consider the following:
Upgrade Requirements
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
Preparedness
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.
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, 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:
Ensure that at least one user exists in the
admin
database with the roleuserAdminAnyDatabase
.If your application performs CRUD operations on the
system.users
collection or uses adb.addUser()
-like method, then you must upgrade those drivers (i.e. client libraries) beforemongod
ormongos
instances.You must fully complete the upgrade procedure for all MongoDB processes before upgrading the authorization model.
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.
Downgrade Limitations
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.
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:
sudo apt-get update sudo apt-get install mongodb-org
For Red Hat Enterprise, CentOS, Fedora, or Amazon Linux:
sudo yum install mongodb-org
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.
Upgrade MongoDB Processes
Upgrade Standalone 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.
Download binaries of the latest release in the 2.6 series from the MongoDB Download Page. See Install MongoDB for more information.
Shut down your
mongod
instance. Replace the existing binary with the 2.6mongod
binary and restartmongod
.
Upgrade a Replica Set to 2.6
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 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.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.
Step down the replica set primary.
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.
Upgrade the primary.
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.
Upgrade a Sharded Cluster to 2.6
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.
Considerations
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 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:
mongos --configdb <configDB string> --upgrade
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.
Ensure 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:
upgrade of config server to v5 successful Config database is at version v5
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.
Upgrade the remaining 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.
Complete Sharded Cluster Upgrade
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:
Upgrade all 3
mongod
config server instances, leaving the first system in themongos --configdb
argument to upgrade last.Upgrade each shard, one at a time, upgrading the
mongod
secondaries before runningreplSetStepDown
and upgrading the primary of each shard.
When this process is complete, re-enable the balancer.
Upgrade Procedure
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:
Stop the existing mongod
instance.
For example, on Linux, run 2.4 mongod
with the
--shutdown
option as follows:
mongod --dbpath /var/mongod/data --shutdown
Replace /var/mongod/data
with your MongoDB dbPath
.
See also the Stop mongod
Processes for alternate methods of
stopping a mongod
instance.