Navigation

Upgrade MongoDB to 3.2

On this page

Before you attempt any upgrade, please familiarize yourself with the content of this document.

If you need guidance on upgrading to 3.2, MongoDB offers 3.2 upgrade services to help ensure a smooth transition without interruption to your MongoDB application.

Upgrade Recommendations and Checklists

When upgrading, consider the following:

Upgrade Requirements

To upgrade an existing MongoDB deployment to 3.2, you must be running a 3.0-series release.

To upgrade from a 2.6-series release, you must upgrade to the latest 3.0-series release before upgrading to 3.2. For the procedure to upgrade from the 2.6-series to a 3.0-series release, see Upgrade to 3.0.

Preparedness

Before beginning your upgrade, see the Compatibility Changes in MongoDB 3.2 document to ensure that your applications and deployments are compatible with MongoDB 3.2. Resolve the incompatibilities in your deployment before starting the upgrade.

Before upgrading MongoDB, always test your application in a staging environment before deploying the upgrade to your production environment.

Upgrade Standalone mongod Instance to MongoDB 3.2

The following steps outline the procedure to upgrade a standalone mongod from version 3.0 to 3.2. To upgrade from version 2.6 to 3.2, upgrade to the latest 3.0-series release first, and then use the following procedure to upgrade from 3.0 to 3.2.

Upgrade with Package Manager

If you installed MongoDB from the MongoDB apt, yum, dnf, or zypper repositories, you should upgrade to 3.2 using your package manager. Follow the appropriate installation instructions for your Linux system. This will involve adding a repository for the new release, then performing the actual upgrade.

Manual Upgrade

Otherwise, you can manually upgrade MongoDB:

1

Download 3.2 binaries.

Download binaries of the latest release in the 3.2 series from the MongoDB Download Page. See Install MongoDB for more information.

2

Replace with 3.2 binaries

Shut down your mongod instance. Replace the existing binary with the 3.2 mongod binary and restart mongod.

Note

MongoDB 3.2 generates core dumps on some mongod failures. For production environments, you may prefer to turn off core dumps for the operating system, if not already.

Upgrade a Replica Set to 3.2

Prerequisites

All replica set members must be running version 3.0 before you can upgrade them to version 3.2. To upgrade a replica set from an earlier MongoDB version, upgrade all members of the replica set to the latest 3.0-series release first, and then follow the procedure to upgrade from MongoDB 3.0 to 3.2.

Upgrade Binaries

You can upgrade from MongoDB 3.0 to 3.2 using a “rolling” upgrade to minimize downtime by upgrading the members individually while the other members are available:

Avoid reconfiguring replica sets that contain members of different MongoDB versions as validation rules may differ across MongoDB versions.

1

Upgrade secondary members of the replica set.

Upgrade the secondary members of the replica set one at a time:

  • Shut down the mongod instance and replace the 3.0 binary with the 3.2 binary.
  • Restart the member and wait for the member to recover to SECONDARY state before upgrading the next secondary member. To check the member’s state, issue rs.status() in the mongo shell.
2

Step down the replica set primary.

Connect a mongo shell to the primary and use rs.stepDown() to step down the primary and force an election of a new primary:

3

Upgrade the primary.

When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, upgrade the stepped-down primary:

  • Shut down the stepped-down primary and replace the mongod binary with the 3.2 binary.
  • Restart.

Replica set failover is not instant and will render the set unavailable to accept writes until the failover process completes. This may take 30 seconds or more: schedule the upgrade procedure during a scheduled maintenance window.

Note

MongoDB 3.2 generates core dumps on some mongod failures. For production environments, you may prefer to turn off core dumps for the operating system, if not already.

Upgrade a Sharded Cluster to 3.2

Prerequisites

  • Version 3.0 or Greater

    To upgrade a sharded cluster to 3.2, all members of the cluster must be at least version 3.0. The upgrade process checks all components of the cluster and will produce warnings if any component is running version earlier than 3.0.

  • Stop Metadata Changes during the Upgrade

    During the upgrade, ensure that clients do not make changes to the collection metadata. For example, during the upgrade, do not perform any of the following operations:

    See the Sharding Reference for a complete list of sharding commands. Not all commands on the Sharding Reference page modify the cluster metadata.

  • Disable the balancer

  • Back up the config Database

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

Upgrade Binaries

1

Disable the Balancer.

Disable the balancer as described in Disable the Balancer.

2

Upgrade the shards.

Upgrade the shards one at a time. If the shards are replica sets, for each shard:

  1. Upgrade the secondary members of the replica set one at a time:

    • Shut down the mongod instance and replace the 3.0 binary with the 3.2 binary.
    • Restart the member and wait for the member to recover to SECONDARY state before upgrading the next secondary member. To check the member’s state, issue rs.status() in the mongo shell.

  2. Step down the replica set primary.

    Connect a mongo shell to the primary and use rs.stepDown() to step down the primary and force an election of a new primary:

    copy 
    rs.stepDown()

  3. When rs.status() shows that the primary has stepped down and another member has assumed PRIMARY state, upgrade the stepped-down primary:

    • Shut down the stepped-down primary and replace the mongod binary with the 3.2 binary.
    • Restart.
3

Upgrade the config servers.

Upgrade the config servers one at a time in reverse order of the configDB or --configdb setting for the mongos. That is, if the mongos has the following --configdb listing:

copy 
mongos --configdb confserver1:port1,confserver2:port2,confserver3:port2

Upgrade first confserver3, then confserver2, and lastly confserver1.

Starting with the last config server listed in the configDB setting:

  1. Stop the config server and replace with the 3.2 binary.

  2. Start the 3.2 binary with both the --configsvr and --port options:

    copy 
    mongod --configsvr --port <port> --dbpath <path>

    If using a configuration file, specify sharding.clusterRole: configsvr and net.port in the file:

    copy 
    sharding:
   clusterRole: configsvr
net:
   port: <port>
storage:
   dbpath: <path>

Repeat for the config server listed second in the configDB setting, and finally the config server listed first in the configDB setting.

4

Upgrade the mongos instances.

Replace each mongos instance with the 3.2 binary and restart.

copy 
mongos --configdb <cfgsvr1:port1>,<cfgsvr2:port2>,<cfgsvr3:port3>
5

Re-enable the balancer.

Re-enable the balancer as described in Enable the Balancer.

Note

MongoDB 3.2 generates core dumps on some mongod failures. For production environments, you may prefer to turn off core dumps for the operating system, if not already.

Once the sharded cluster binaries have been upgraded to 3.2, existing config servers will continue to run as mirrored mongod instances. For instructions on upgrading existing config servers to a replica set, see Upgrade Config Servers to Replica Set (requires MongoDB version 3.2.4 or later versions).

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.