Upgrade to the Latest Revision of MongoDB

Backup

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

Compatibility Considerations

• 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.

Maintenance Window

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

Change Streams

Starting in MongoDB 4.0.7, change streams use a version 1 v1 resume tokens. 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 resume token when connected to a member that has not been updated (i.e. only accepts v0 or BinData token) and fail. In such cases, the client must 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 prevent the storage cache pressure from immobilizing a deployment with a primary-secondary-arbiter (PSA) architecture. However,

• Disabling "majority" read concern has no effect on change streams availability.

• Disabling "majority" read concern prevents collMod commands which modify an index from rolling back. If such an operation needs to be rolled back, you must resync the affected nodes with the primary node.

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

  • A transaction cannot use read concern "snapshot" if the transaction involves a shard that has disabled read concern "majority".

  • A transaction that writes to multiple shards errors if any of the transaction's read or write operations involves a shard that has disabled read concern "majority".

  However, it does not affect transactions on replica sets. For transactions on replica sets, you can specify read concern "majority" (or "snapshot" or "local" ) for distributed transactions even if read 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 this document to upgrade a staging environment that reproduces your production environment, to ensure that your production configuration is compatible with all changes.

Upgrade Secondaries

Upgrade each secondary separately as follows:

1. Upgrade the secondary's mongod binary by following the instructions in Upgrade a MongoDB Instance.

2. 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

1. 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.

2. 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.

3. Shut down the original primary and upgrade its instance by following the instructions in Upgrade a MongoDB Instance.