Upgrade the major version of an ApsaraDB for MongoDB instance - ApsaraDB for MongoDB

This topic describes the major versions available for upgrades in ApsaraDB for MongoDB and how to upgrade the major version of an ApsaraDB for MongoDB instance.

Usage notes

Supported protocol: The sharded cluster instance that you want to upgrade must use the MongoDB protocol.
Upgrade method and its impacts:
- Automatic restart: Nodes in an instance are upgraded in turn. An instance is automatically restarted two or three times during an upgrade. We recommend that you perform the upgrade during off-peak hours and make sure that your application can automatically reconnect to the instance.
- Performance impacts: In MongoDB 5.0 and later versions, the default writeConcern is changed from {w:1}to {w:majority}. If the major version of your instance is upgraded from MongoDB 4.4 to 5.0, significant write performance degration may occur in the instance.
  Note
  - During a cross-version upgrade, the system gradually upgrades the instance version. Assume that you want the system to upgrade your instance from MongoDB 3.0 to 4.2. The system does not immediately upgrade the instance to MongoDB 4.2. Instead, the system gradually upgrades the instance to MongoDB 4.2. A transient disconnection occurs every time a major version upgrade is completed.
  - If your application runs in a production environment, we recommend that you use a connection string URI to connect your application to the instance. If you use this URI, the primary node is always connected and the read/write operations of your application are not affected by a primary/secondary switchover. For more information about how to use a connection string URI to connect to a database, see Connect to a replica set instance or Connect to a sharded cluster instance.
Balancer status: The balancer of a sharded cluster instance is disabled during an upgrade and is enabled after the upgrade.
Version downgrade: You cannot downgrade the major version of an instance after you upgrade it.
Backup and restoration: After you upgrade the major version of an instance, the backup data of an instance that uses an earlier major version cannot be restored to the upgraded instance. You can download the backup files of an instance that uses an earlier major version and restore the files to a self-managed database. For more information about how to restore backup data to a self-managed database, see Restore the instance data to a self-managed MongoDB database by using logical backup or Restore the instance data to a self-managed MongoDB database by using physical backup.
Upgrade duration: The upgrade duration depends on multiple factors, such as the amount of instance data, the number of databases and collections, and the version span. The following data is for reference only. The actual upgrade duration is subject to specific operations.
- For an instance that uses cloud disks, the upgrade duration is about 15 minutes.
- For an instance that uses local disks, the duration required for an upgrade to a nearby version is close to the duration required for instance restart, which is generally within several minutes.

MongoDB major versions available for upgrades

You can perform a major version upgrade in the ApsaraDB for MongoDB console. The following table lists the available MongoDB major versions and describes whether the versions are supported in different instance architectures and versions.

Instance architecture	Instance category	Current major version	Major version available for upgrade
Standalone instance	General-purpose cloud disk instance	MongoDB 4.0	No new major version is available for upgrade.
Standalone instance	General-purpose cloud disk instance	MongoDB 3.4	You cannot upgrade the major version of the instance. To upgrade the major version of an instance, you can create an instance and replace the old instance with the new instance.For information about how to create a standalone instance, see Create a standalone instance.
Replica set instance	Dedicated instance that uses cloud disks	MongoDB 7.0	No new major version is available for upgrade.
		MongoDB 6.0	MongoDB 7.0
		MongoDB 5.0	MongoDB 6.0
		MongoDB 4.4	MongoDB 5.0 After an instance is upgraded from MongoDB 4.4 to 5.0, write performance degration may occur in the instance and the write latency may increase due to the change of the default writeConcern from `{w:1}` to `{w:majority}`. Assess the potential impacts before you perform a major version upgrade.
	General-purpose instance that uses local disks Dedicated instance that uses local disks Dedicated host instance	MongoDB 4.2	You cannot upgrade the major version of the instance. To upgrade the major version of an instance, you can create an instance and replace the old instance with the new instance.For more information about how to create a replica set instance, see Create a replica set instance.
		MongoDB 4.0	MongoDB 4.2
		MongoDB 3.4	MongoDB 4.0 MongoDB 4.2
		MongoDB 3.2
		MongoDB 3.0
Sharded cluster instance	Dedicated instance that uses cloud disks	MongoDB 7.0	No new major version is available for upgrade.
		MongoDB 6.0	MongoDB 7.0
		MongoDB 5.0	MongoDB 6.0
		MongoDB 4.4	MongoDB 5.0 After an instance is upgraded from MongoDB 4.4 to 5.0, write performance degration may occur in the instance and the write latency may increase due to the change of the default writeConcern from `{w:1}` to `{w:majority}`. Assess the potential impacts before you perform a major version upgrade.
	General-purpose instance that uses local disks Dedicated instance that uses local disks Dedicated host instance	MongoDB 4.2	You cannot upgrade the major version of the instance. To upgrade the major version of an instance, you can create an instance and replace the old instance with the new instance. For more information about how to create a sharded cluster instance, see Create a sharded cluster instance.
		MongoDB 4.0	MongoDB 4.2
		MongoDB 3.4	MongoDB 4.0 MongoDB 4.2
		MongoDB 3.2
		MongoDB 3.0

To upgrade the major version of an instance across instance architectures or storage classes, create an instance running a major version to which you want to upgrade and then use Data Transmission Service (DTS) to migrate data from the source instance to the created instance. For more information about how to create an instance, see Create an instance.
For more information about how to migrate data, see the following topics:

Preparations: Compatibility testing

Before you upgrade the major version of an instance, perform the following steps to complete compatibility testing.

Check and modify the client code based on the major versions that are involved to prevent possible compatibility issues. For more information about how to modify the client code, see ApsaraDB for MongoDB major version upgrade
(Optional) Use the data restoration method to test compatibility between different major versions.
Important
Data restoration incurs additional fees.
1. Create an instance of the same major version for data restoration. For more information about how to restore data, see Data restoration.
2. Upgrade the major version of the new instance. For more information, see Procedure.
3. Verify whether the modified client has compatibility issues on the new instance.
  If compatibility issues occur, check and modify the client code again based on the error message until no compatibility issues occur.
4. After compatibility testing is complete, release the new instance.

Procedure

Log on to the ApsaraDB for MongoDB console.
In the left-side navigation pane, click Replica Set Instances or Sharded Cluster Instances.
In the upper-left corner of the page, select the resource group and region to which the desired instance belongs.
Click the ID of the instance or click Manage in the Actions column.
In the Specification Information section of the instance details page, click Upgrade Database Version and select the major version to which you want to upgrade the instance.
In the Upgrade Database Version message, click OK.