Docs4dev
Docs
mongodb / v3.6 / reference / release-notes-2.4-upgrade.html

Upgrade MongoDB to 2.4

On this page

In the general case, the upgrade from MongoDB 2.2 to 2.4 is a binary-compatible “drop-in” upgrade: shut down the mongod instances and replace them with mongod instances running 2.4. However, before you attempt any upgrade please familiarize yourself with the content of this document, particularly the procedure for upgrading sharded clusters and the considerations for reverting to 2.2 after running 2.4.

Upgrade Recommendations and Checklist

When upgrading, consider the following:

  • For all deployments using authentication, upgrade the drivers (i.e. client libraries), before upgrading the mongod instance or instances.

  • To upgrade to 2.4 sharded clusters must upgrade following the meta-data upgrade procedure.

  • If you’re using 2.2.0 and running with authorization enabled, you will need to upgrade first to 2.2.1 and then upgrade to 2.4. See Rolling Upgrade Limitation for 2.2.0 Deployments Running with auth Enabled.

  • If you have system.users documents (i.e. for authorization) that you created before 2.4 you must ensure that there are no duplicate values for the user field in the system.users collection in any database. If you do have documents with duplicate user fields, you must remove them before upgrading.

    See Security Enhancements for more information.

Upgrade Standalone mongod Instance to MongoDB 2.4

  1. Download binaries of the latest release in the 2.4 series from the MongoDB Download Page . See Install MongoDB for more information.
  2. Shutdown your mongod instance. Replace the existing binary with the 2.4 mongod binary and restart mongod.

Upgrade a Replica Set from MongoDB 2.2 to MongoDB 2.4

You can upgrade to 2.4 by performing a “rolling” upgrade of the set by upgrading the members individually while the other members are available to minimize downtime. Use the following procedure:

  1. Upgrade the secondary members of the set one at a time by shutting down the mongod and replacing the 2.2 binary with the 2.4 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.

  2. Use the mongo shell method rs.stepDown() to step down the primary to allow the normal failover procedure. rs.stepDown() expedites the failover procedure and is preferable to shutting down the primary directly.

    Once the primary has stepped down and another member has assumed PRIMARY state, as observed in the output of rs.status(), shut down the previous primary and replace mongod binary with the 2.4 binary and start the new process.

    Note

    Replica set failover is not instant but will render the set unavailable to read or accept writes until the failover process completes. Typically this takes 10 seconds or more. You may wish to plan the upgrade during a predefined maintenance window.

Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4

Important

Only upgrade sharded clusters to 2.4 if all members of the cluster are currently running instances of 2.2. The only supported upgrade path for sharded clusters running 2.0 is via 2.2.

Overview

Upgrading a sharded cluster from MongoDB version 2.2 to 2.4 (or 2.3) requires that you run a 2.4 mongos with the --upgrade option, described in this procedure. The upgrade process does not require downtime.

The upgrade to MongoDB 2.4 adds epochs to the meta-data for all collections and chunks in the existing cluster. MongoDB 2.2 processes are capable of handling epochs, even though 2.2 did not require them. This procedure applies only to upgrades from version 2.2. Earlier versions of MongoDB do not correctly handle epochs. See Cluster Meta-data Upgrade for more information.

After completing the meta-data upgrade you can fully upgrade the components of the cluster. With the balancer disabled:

  • Upgrade all mongos instances in the cluster.
  • Upgrade all 3 mongod config server instances.
  • Upgrade the mongod instances for each shard, one at a time.

See Upgrade Sharded Cluster Components for more information.

Cluster Meta-data Upgrade

Considerations

Beware of the following properties of the cluster upgrade process:

  • Before you start the upgrade, ensure that the amount of free space on the filesystem for the config database is at least 4 to 5 times the amount of space currently used by the config database data files.

    Additionally, ensure that all indexes in the config database are {v:1} indexes. If a critical index is a {v:0} index, chunk splits can fail due to known issues with the {v:0} format. {v:0} indexes are present on clusters created with MongoDB 2.0 or earlier.

    The duration of the metadata upgrade depends on the network latency between the node performing the upgrade and the three config servers. Ensure low latency between the upgrade process and the config servers.

  • While the upgrade is in progress, you cannot make changes to the collection meta-data. For example, during the upgrade, do not perform:

  • Once you upgrade to 2.4 and complete the upgrade procedure do not use 2.0 mongod and mongos processes in your cluster. 2.0 process may re-introduce old meta-data formats into cluster meta-data.

The upgraded config database will require more storage space than before, to make backup and working copies of the config.chunks and config.collections collections. As always, if storage requirements increase, the mongod might need to pre-allocate additional data files. See How can I get information on the storage use of a database? for more information.

Meta-data Upgrade Procedure

Changes to the meta-data format for sharded clusters, stored in the config database, require a special meta-data upgrade procedure when moving to 2.4.

Do not perform operations that modify meta-data while performing this procedure. See Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4 for examples of prohibited operations.

  1. Before you start the upgrade, ensure that the amount of free space on the filesystem for the config database is at least 4 to 5 times the amount of space currently used by the config database data files.

    Additionally, ensure that all indexes in the config database are {v:1} indexes. If a critical index is a {v:0} index, chunk splits can fail due to known issues with the {v:0} format. {v:0} indexes are present on clusters created with MongoDB 2.0 or earlier.

    The duration of the metadata upgrade depends on the network latency between the node performing the upgrade and the three config servers. Ensure low latency between the upgrade process and the config servers.

    To check the version of your indexes, use db.collection.getIndexes().

    If any index on the config database is {v:0}, you should rebuild those indexes by connecting to the mongos and either: rebuild all indexes using the db.collection.reIndex() method, or drop and rebuild specific indexes using db.collection.dropIndex() and then db.collection.ensureIndex(). If you need to upgrade the _id index to {v:1} use db.collection.reIndex().

    You may have {v:0} indexes on other databases in the cluster.

  2. Turn off the balancer in the sharded cluster, as described in Disable the Balancer.

    Optional

    For additional security during the upgrade, you can make a backup of the config database using mongodump or other backup tools.

  3. Ensure there are no version 2.0 mongod or mongos processes still active in the sharded cluster. The automated upgrade process checks for 2.0 processes, but network availability can prevent a definitive check. Wait 5 minutes after stopping or upgrading version 2.0 mongos