Upgrade the Major Version of an ApsaraDB for MongoDB Database - ApsaraDB for MongoDB

This topic describes the supported major version upgrade paths for ApsaraDB for MongoDB instances and the upgrade procedure.

Precautions

Protocol requirement: To upgrade the major version of a sharded cluster instance, the instance must use the MongoDB Protocol.
Upgrade process and impact:
- Automatic restarts: The upgrade is a rolling process that automatically restarts the instance two to three times. We recommend performing the upgrade during off-peak hours and ensure that your application has a reconnection mechanism.
- Performance impact: Starting from MongoDB 5.0, the default writeConcern changes from {w:1} to {w:majority}. If you upgrade your instance's major version from 4.4 to 5.0, you may experience a noticeable degradation in write performance.
  Note
  - For multi-version upgrades, such as from v3.0 to v4.2, the system performs the upgrade sequentially through each intermediate version. A transient disconnection occurs after each version upgrade.
  - We recommend that applications in a production environment connect to the database using a Connection String URI.
    Using a Connection String URI to connect to an instance ensures that the connected node is always the primary node. This prevents your application's read and write operations from being affected by a failover. For more information about how to connect to a database using a Connection String URI, see Connect to a replica set instance or Connect to a sharded cluster instance.
Balancer status: During the upgrade of a sharded cluster instance, the balancer is disabled and then re-enabled after the upgrade is complete.
Version downgrade: You cannot downgrade the major version after an upgrade.
Backup and restoration: After you upgrade the major version of a database, you cannot restore data to the ApsaraDB for MongoDB instance from a backup of an earlier major version. You can download the backup file and restore the data to a self-managed database. For more information about how to restore backup data to a self-managed database, see Restore data from a cloud disk backup or Restore data from a local disk backup.
Upgrade duration: Upgrade duration depends on factors like data volume, the number of databases and tables, and the version span. The following estimates are for reference only, as actual times may vary.
- Instances with cloud disks: Approximately 15 minutes.
- Instances with local disks: For upgrades to an adjacent version, the upgrade takes several minutes, similar to an instance restart.

Supported upgrade paths

You can upgrade the major version of a database in the ApsaraDB for MongoDB console. However, the available target versions vary based on the instance's architecture, instance type, and current version. The details are as follows:

Architecture	Instance type	Current major version	Available upgrade versions
Standalone architecture	General-purpose with cloud disk	MongoDB 4.0	No higher major version is available for upgrade.
Standalone architecture	General-purpose with cloud disk	MongoDB 3.4	In-place upgrade is not supported. To upgrade the major version, you can create a new instance and use it to replace the original instance.
Replica set architecture	General-purpose with cloud disk Dedicated with cloud disk	MongoDB 8.0	MongoDB 8.3 (Submit a ticket to apply)
		MongoDB 7.0	MongoDB 8.0
		MongoDB 6.0	MongoDB 7.0
		MongoDB 5.0	MongoDB 6.0
		MongoDB 4.4	MongoDB 5.0 When you upgrade an instance from v4.4 to v5.0, the default writeConcern changes from `{w:1}` to `{w:majority}`. This may cause a decrease in write performance and an increase in write latency. Confirm this impact is acceptable before you upgrade.
	General-purpose with local disk Dedicated with local disk Dedicated Physical Server	MongoDB 4.2	In-place upgrade is not supported. To upgrade the major version, you can create a new instance and use it to replace the original instance.
		MongoDB 4.0	MongoDB 4.2
		MongoDB 3.4	MongoDB 4.0 MongoDB 4.2
		MongoDB 3.2
		MongoDB 3.0
Sharded cluster architecture	Dedicated with cloud disk	MongoDB 8.0	MongoDB 8.3 (Submit a ticket to apply)
		MongoDB 7.0	MongoDB 8.0
		MongoDB 6.0	MongoDB 7.0
		MongoDB 5.0	MongoDB 6.0
		MongoDB 4.4	MongoDB 5.0 When you upgrade an instance from v4.4 to v5.0, the default writeConcern changes from `{w:1}` to `{w:majority}`. This may cause a decrease in write performance and an increase in write latency. Confirm this impact is acceptable before you upgrade.
	General-purpose with local disk Dedicated with local disk Dedicated Physical Server	MongoDB 4.2	In-place upgrade is not supported. To upgrade the major version, you can create a new instance and use it to replace the original instance.
		MongoDB 4.0	MongoDB 4.2
		MongoDB 3.4	MongoDB 4.0 MongoDB 4.2
		MongoDB 3.2
		MongoDB 3.0

If you need to upgrade the major version across different architectures or storage types, first create an instance with the target major version and then use Data Transmission Service (DTS) to migrate data from the source to the new instance.
See the following topics for data migration instructions:

Compatibility tests

Before you upgrade the major version, perform a compatibility test.

Review the release notes for each major version in your upgrade path and update your client code to ensure compatibility.
(Optional) Use data restoration to test major version compatibility.
Important
Data restoration incurs additional costs.
1. Use data restoration to create a new instance with the same major version as your current instance.
2. Upgrade the major version of the new instance.
3. Test your updated client against the new instance to check for compatibility issues.
  If compatibility issues arise, use the error messages to debug and modify your client code.
4. After the test 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 based on the instance architecture.
In the upper-left corner of the page, select the resource group and region where your instance is located.
Click the ID of the target instance, or click Manage in the Actions column for the instance.
In the Specification Information section, hover over Upgrade Database Version and click the target major version.
In the Upgrade Database Version dialog box, click Confirm.