Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon DocumentDB in-place major version upgrade

Amazon DocumentDB makes new versions of database engines generally available only after extensive testing. You can choose how and when to upgrade your Amazon DocumentDB clusters to the new version.

Currently, Amazon DocumentDB supports three major versions: Amazon DocumentDB 3.6, 4.0, and 5.0. You can perform an in-place major version upgrade (MVU) of your database while keeping the same endpoints, storage, and tags of the clusters and can continue using your applications without any modifications. This feature is available for free in all regions where Amazon DocumentDB 5.0 is available.

Prerequisites and limitations

The following are prerequisites and limitations to in-place major version upgrade that you may need to understand and act on before performing the upgrade:

Best practices for in-place major version upgrades

Test in-place major version upgrades using cloned clusters

Before an in-place major version upgrade

During an in-place major version upgrade

You can monitor progress of your in-place major version upgrade by subscribing to cluster maintenance events. When the upgrade completes, you will receive the “Database cluster major version has been upgraded” event. This and other events occurring during the upgrade appear in the ‘Events and Tags’ section of the cluster detail page in the Amazon DocumentDB console. The cluster status then changes from ‘upgrading’ to ‘available’.

From CLI, you can run aws docdb create-event-subscription to create events and aws docdb describe-events to monitor progress. You can also setup event notifications for the above events to Amazon SNS as the target to be notified via email, push messages, and other methods. For more information, see Subscribing to Amazon DocumentDB Event Subscriptions.

In-place major version upgrade generates the following events during the upgrade:

Events are also visible on the console under the Events page:

In the Amazon CLI, you can use the following commands to track progress:

aws docdb describe-events --source-identifier $CLUSTER_NAME --source-type db-cluster
{
    "Events": [
        {
            "SourceIdentifier": "mycluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster engine version upgrade started.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2023-07-11T23:20:32.444000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:xxxx:cluster:mycluster"
        }
    ]
}

After an in-place major version upgrade

For Amazon DocumentDB 3.6, add a tag to the cluster to differentiate that the cluster was upgraded to Amazon DocumentDB 5.0 from Amazon DocumentDB 3.6 as opposed to a newly created Amazon DocumentDB 5.0 cluster. Refer to the section on differences between an upgraded Amazon DocumentDB 5.0 cluster and a new Amazon DocumentDB 5.0 cluster.

Take a manual snapshot after the in-place major version upgrade finishes in case you need to restore to the post-upgrade state. The automatic snapshot process will resume as soon as in-place major version upgrade completes. The manual snapshot will not incur any charges as long as it is within the retention period.

To use the new features associated with Amazon DocumentDB 5.0, for example, client-side field level encryption, we recommend upgrading your driver version to the MongoDB 5.0 API version. For more information, see What's new in Amazon DocumentDB 5.0 for a list of Amazon DocumentDB 5.0 features.

Fully test the upgraded Amazon DocumentDB 5.0 cluster to ensure everything is working as expected.

Performing an in-place major version upgrade

Using the Amazon Web Services Management Console

To perform an in-place major version upgrade using the Amazon Web Services Management Console:

1. Sign into the Amazon Web Services Management Console and open the Amazon DocumentDB console.

2. In the Clusters table, select the source cluster, click Actions, and then Modify.

   

3. On the Modify cluster dialog in the Cluster specifications section, choose the targeted database version (5.0) from the Engine version drop down menu.

   

4. In the Cluster options section, choose the appropriate cluster parameter group (default.docdb5.0) or a custom created parameter group.

   

5. Once complete, scroll down and choose Continue.

6. In the Scheduling of modifications section, choose your preferred scheduling plan: apply immediately or apply in the next maintenance window.

   Then choose Modify cluster.

   

7. In the clusters table, note the status of your cluster as it is being upgraded:

   

Using the Amazon CLI

Use the modify-db-cluster API with desired engine version and allow-major-version-upgrade flag set:

aws docdb modify-db-cluster \
 ‐‐db-cluster-identifier $CLUSTER_NAME \
 ‐‐allow-major-version-upgrade \
 ‐‐engine-version 5.0 \
 ‐‐apply-immediately \
 ‐‐cluster-parameter-group $PARAMETER_GROUP \
 ‐‐region $REGION

Troubleshooting an in-place major version upgrade

In case of a failure, the in-place major version upgrade will attempt a rollback of the upgrade to assume the last operational state of the cluster before the upgrade started. A successful rollback will generate an event: "Database cluster is in a state that cannot be upgraded: DocumentDB cluster is in a state where major version upgrade cannot be completed successfully." At this point, you should reach out to the Amazon support team to troubleshoot and re-attempt the version upgrade. You can continue using your workload as before. In any other rare scenarios where the upgrade is taking longer than expected, please reach out to Amazon support team for assistance.

Differences between Amazon DocumentDB 3.6/4.0 to 5.0 upgraded clusters and new Amazon DocumentDB 5.0 clusters