Upgrade to the Latest Revision of MongoDB

MongoDB versioning have the formX.Y.Z where Z refers to the revision/patch number.Revisions provide security patches, bug fixes, and new or changedfeatures that generally do not contain any backward breaking changes.Always upgrade to the latest revision in your release series.

For more information on versioning, see MongoDB Versioning.

Before Upgrading

Backup

Ensure you have an up-to-date backup of your data set. SeeMongoDB Backup Methods.

Compatibility Considerations

  • Consult the following documents for any special considerations orcompatibility issues specific to your MongoDB release:

Important

  • Starting in MongODB 4.2, MongoDB removes support for Ubuntu 16.04PPCLE.
  • Starting in MongoDB 3.6.13, MongoDB 3.6-series removes support forUbuntu 16.04 PPCLE.
  • Starting in MongoDB 3.4.21, MongoDB 3.4-series removes support forUbuntu 16.04 PPCLE.

Maintenance Window

If your installation includes replica sets, planthe upgrade during a predefined maintenance window.

Change Streams

Starting in MongoDB 4.0.7, change streams use a version 1 v1 resumetokens. MongoDB versions earlier than 4.0.7 use v0 resume tokens.

When upgrading from MongoDB 4.0.6 or earlier to MongoDB 4.0.7 or later,a client may try to resume change streams using the new v1 resumetoken when connected to a member that has not been updated (i.e. onlyaccepts v0 or BinData token) and fail. In such cases, the clientmust wait for the upgrade to complete before resuming change streams.

3-Member PSA Architecture

Starting in MongoDB 3.6, MongoDB enables support for"majority" read concern by default.

You can disable read concern "majority" to preventthe storage cache pressure from immobilizing a deployment with aprimary-secondary-arbiter (PSA) architecture. However,

  • Disabling "majority" read concern disables supportfor Change Streams for MongoDB 4.0 and earlier. For MongoDB4.2+, disabling read concern "majority" has no effect on changestreams availability.

  • Disabling "majority" read concern affects support fortransactions on sharded clusters. Specifically:

    • A transaction cannot use read concern "snapshot" ifthe transaction involves a shard that has disabled readconcern “majority”.
    • A transaction that writes to multiple shards errors if any of thetransaction’s read or write operations involves a shard that hasdisabled read concern "majority".However, it does not affect transactionson replica sets. For transactions on replica sets, you can specifyread concern "majority" (or "snapshot"or "local" ) for multi-document transactions even ifread concern "majority" is disabled.

For more information, see Disable Read Concern Majority.

Staging Environment Check

Before you upgrade a production environment, use the procedures in thisdocument to upgrade a staging environment that reproduces yourproduction environment, to ensure that your production configuration iscompatible with all changes.

Upgrade Procedure

Important

Always backup all of your data before upgrading MongoDB.

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

Follow this upgrade procedure:

Upgrade a MongoDB Instance

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

  • Upgrade the instance using the operating system’s package managementtool and the official MongoDB packages. This is the preferredapproach. See Install MongoDB.
  • Upgrade the instance by replacing the existing binaries with newbinaries. 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 existingbinaries. The preferred approach to an upgrade is to use the operatingsystem’s package management tool and the official MongoDB packages, asdescribed in Install MongoDB.

To upgrade a mongod or mongos instance byreplacing the existing binaries:

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

Upgrade Replica Sets

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

Note

Starting in MongoDB 4.0.7, change streams use a version 1 v1resume tokens. MongoDB versionsearlier than 4.0.7 use v0 resume tokens or BinData resume tokens.

When upgrading from MongoDB 4.0.0-4.0.6 to MongoDB 4.0.7 or later,a client may try to resume change streams using the new v1resume token when connected to a member that has not been updated(i.e. only accepts v0 token or BinData) and fail. In such cases, theclient must wait for the upgrade to complete before resuming changestreams.

Upgrade Secondaries

Upgrade each secondary separately as follows:

  • Upgrade the secondary’s mongod binary by following theinstructions in Upgrade a MongoDB Instance.

  • After upgrading a secondary, wait for the secondary to recover tothe SECONDARY state before upgrading the next instance. Tocheck the member’s state, issue rs.status() in themongo shell.

The secondary may briefly go into STARTUP2 or RECOVERING.This is normal. Make sure to wait for the secondary to fully recoverto 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 takes10-20 seconds. Plan the upgrade during a predefined maintenancewindow.

Note

Stepping down the primary is preferable to directlyshutting down the primary. Stepping down expedites thefailover procedure.

  • Once the primary has stepped down, call the rs.status()method from the mongo shell until you see that anothermember has assumed the PRIMARY state.

  • Shut down the original primary and upgrade its instance byfollowing the instructions in Upgrade a MongoDB Instance.

Upgrade Sharded Clusters

Changed in version 3.4: The procedure applies to 4.2. To make revision upgrades forother versions of MongoDB sharded clusters, refer to the appropriateversion of the manual.

Note

Starting in MongoDB 4.0.7, change streams use a version 1 v1resume tokens. MongoDB versionsearlier than 4.0.7 use v0 resume tokens or BinData resume tokens.

When upgrading from MongoDB 4.0.6 or earlier to 4.0.7 or later, themembers of the sharded clusters will continue to produce v0 orBinData resume tokens until the mongos instance(s)are updated. Upgraded mongos instances will beginproducing v1 change stream resume tokens. These tokens cannot beused to resume a stream on a mongos that has not yetbeen upgraded to 4.0.7 or later.

To upgrade a 4.2 sharded cluster:

To upgrade the config server replica set, use the procedures inUpgrade Replica Sets.