Upgrade to the Latest Revision of MongoDB¶

On this page

Before Upgrading
Upgrade Procedure
Upgrade a MongoDB Instance
Replace the Existing Binaries
Upgrade Sharded Clusters
Upgrade Replica Sets
Additional Resources

Revisions provide security patches, bug fixes, and new or changed features that do not contain any backward breaking changes. Always upgrade to the latest revision in your release series. The third number in the MongoDB version number indicates the revision.

Before Upgrading¶

Ensure you have an up-to-date backup of your data set. See MongoDB Backup Methods.
Consult the following documents for any special considerations or compatibility issues specific to your MongoDB release:
- The release notes, located at Release Notes.
- The documentation for your driver. See Drivers and Driver Compatibility pages for more information.
If your installation includes replica sets, plan the upgrade during a predefined maintenance window.
Before you upgrade a production environment, use the procedures in this document to upgrade a staging environment that reproduces your production environment, to ensure that your production configuration is compatible with all changes.

Upgrade Procedure¶

Important

Always backup all of your data before upgrading MongoDB.

Upgrade each mongod and mongos binary separately, using the procedure described here. When upgrading a binary, use the procedure Upgrade a MongoDB Instance.

Follow this upgrade procedure:

For deployments that use authentication, first upgrade all of your MongoDB drivers. To upgrade, see the documentation for your driver as well as the Driver Compatibility page.
Upgrade sharded clusters, as described in Upgrade Sharded Clusters.
Upgrade any standalone instances. See Upgrade a MongoDB Instance.
Upgrade any replica sets that are not part of a sharded cluster, as described in Upgrade Replica Sets.

Upgrade a MongoDB Instance¶

To upgrade a mongod or mongos instance, use one of the following approaches:

Upgrade the instance using the operating system’s package management tool and the official MongoDB packages. This is the preferred approach. See Install MongoDB.
Upgrade the instance by replacing the existing binaries with new binaries. See Replace the Existing Binaries.

Replace the Existing Binaries¶

Important

Always backup all of your data before upgrading MongoDB.

This section describes how to upgrade MongoDB by replacing the existing binaries. The preferred approach to an upgrade is to use the operating system’s package management tool and the official MongoDB packages, as described in Install MongoDB.

To upgrade a mongod or mongos instance by replacing the existing binaries:

Download the binaries for the latest MongoDB revision from the MongoDB Download Page and store the binaries in a temporary location. The binaries download as compressed files that uncompress to the directory structure used by the MongoDB installation.
Shutdown the instance.
Replace the existing MongoDB binaries with the downloaded binaries.
Restart the instance.

Upgrade Sharded Clusters¶

To upgrade a sharded cluster:

Disable the cluster’s balancer, as described in Disable the Balancer.
Upgrade each mongos instance by following the instructions below in Upgrade a MongoDB Instance. You can upgrade the mongos instances in any order.
Upgrade each mongod config server individually starting with the last config server listed in your mongos --configdb string and working backward. To keep the cluster online, make sure at least one config server is always running. For each config server upgrade, follow the instructions below in Upgrade a MongoDB Instance
Example

Given the following config string:
```
mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019
```
You would upgrade the config servers in the following order:
1. cfg2.example.net
2. cfg1.example.net
3. cfg0.example.net
Upgrade each shard.
- If a shard is a replica set, upgrade the shard using the procedure below titled Upgrade Replica Sets.
- If a shard is a standalone instance, upgrade the shard using the procedure below titled Upgrade a MongoDB Instance.
Re-enable the balancer, as described in Enable the Balancer.

Upgrade Replica Sets¶

To upgrade a replica set, upgrade each member individually, starting with the secondaries and finishing with the primary. Plan the upgrade during a predefined maintenance window.

Upgrade Secondaries¶

Upgrade each secondary separately as follows:

Upgrade the secondary’s mongod binary by following the instructions below in Upgrade a MongoDB Instance.
After upgrading a secondary, wait for the secondary to recover to the SECONDARY state before upgrading the next instance. To check the member’s state, issue rs.status() in the mongo shell.

The secondary may briefly go into STARTUP2 or RECOVERING. This is normal. Make sure to wait for the secondary to fully recover to SECONDARY before you continue the upgrade.

Upgrade the Primary¶

Step down the primary to initiate the normal failover procedure. Using one of the following:
- The rs.stepDown() helper in the mongo shell.
- The replSetStepDown database command.
During failover, the set cannot accept writes. Typically this takes 10-20 seconds. Plan the upgrade during a predefined maintenance window.

Note

Stepping down the primary is preferable to directly shutting down the primary. Stepping down expedites the failover procedure.
Once the primary has stepped down, call the rs.status() method from the mongo shell until you see that another member has assumed the PRIMARY state.
Shut down the original primary and upgrade its instance by following the instructions below in Upgrade a MongoDB Instance.

Additional Resources¶

Getting ready for MongoDB 3.2? Get our help.

← Store a JavaScript Function on the Server Monitor MongoDB With SNMP on Linux →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.