View a markdown version of this page

Amazon DocumentDB in-place major version upgrade - Amazon DocumentDB
Supported upgrade pathsPrerequisitesBest practicesWhat changes after upgrading from Amazon DocumentDB 5.0 to 8.0Post-upgrade considerations for clusters upgraded from 3.6 or 4.0Performing the upgradeTroubleshooting

Amazon DocumentDB in-place major version upgrade

You can perform an in-place major version upgrade (MVU) of your Amazon DocumentDB cluster while keeping the same endpoints, storage, and tags. Your applications continue to work without modifications. This feature is available at no additional cost in all regions where Amazon DocumentDB is available.

Important

Your cluster will be unavailable during the upgrade and will experience multiple reboots. Do not connect to, read from, or write to the cluster after starting the upgrade. Downtime varies depending on the number of collections, indexes, databases, and instances. We recommend performing the upgrade during your maintenance window or low-utilization hours.

Once upgraded, you cannot downgrade to a previous version. You can restore your pre-upgrade snapshot to a new cluster if needed.

Supported upgrade paths

Source version Target version

Amazon DocumentDB 3.6

Amazon DocumentDB 5.0

Amazon DocumentDB 4.0

Amazon DocumentDB 5.0

Amazon DocumentDB 5.0

Amazon DocumentDB 8.0
Note

In-place MVU is not supported for global clusters or elastic clusters. To upgrade a global cluster, remove the secondary clusters, convert the primary to a regional cluster, perform the MVU, then recreate the global cluster by adding secondary clusters using the same names to retain your endpoints. You will incur I/O charges while the upgraded primary replicates data to the new secondaries. For detailed steps, see Removing a cluster from an Amazon DocumentDB global cluster.

Prerequisites

  • Instance type — Amazon DocumentDB 4.0+ does not support db.r4 instances. Modify any db.r4.* instances to db.r5.* instances or newer before upgrading. See Modifying an Amazon DocumentDB instance and Supported instance classes by region.

  • OS patches — Apply any pending OS maintenance actions on all instances before upgrading. See Amazon DocumentDB operating system updates.

    Note

    Pending cluster-level engine patches may hide instance OS patches. Apply engine patches first if needed. See Performing a patch update to a cluster's engine version.

  • Index limits on burstable instances (t-family instances) — If you have more than 3,000 indexes on burstable instances, scale up the primary to at least db.r5.large before upgrading. You can scale back down after the upgrade completes.

    Instance Maximum indexes for MVU

    db.t4g.medium

    3K

    db.t3.medium

    10K

  • Parameter group — We recommend having a custom cluster parameter group for the target version ready before upgrading. If one is not specified, the default parameter group for the target version will be used (for example, default.docdb5.0 or default.docdb8.0).

  • Manual snapshot — Create a manual snapshot before upgrading. The upgrade process creates an automatic snapshot named preupgrade-<name>-<version>-<timestamp>, but we strongly recommend having your own backup. See Creating a manual cluster snapshot.

    Note

    The auto snapshot created by the upgrade process will not be automatically deleted after the in-place major version upgrade has completed. This snapshot will not incur any charges as long as it is within the retention period. You can choose to delete this snapshot once you have verified a successful upgrade of your cluster.

    Image: the Snapshots navigation box showing a table of previously created snapshots.

Best practices

Before upgrade — testing with a clone

  1. Use Cloning a volume for an Amazon DocumentDB cluster to create a clone of your cluster. You will not incur storage costs unless you modify data on the clone.

  2. Match the instance count of the clone to the target cluster for a realistic time estimate.

  3. Perform the MVU on the clone and fully test for functional differences.

  4. Check if an upgrade is already scheduled by running describe-db-clusters and looking for PendingModifiedValues.EngineVersion. If you have modified the cluster and selected to apply it in the next maintenance window, the schedule will not be visible in the console but you can view it in the AWS CLI:

    aws docdb describe-db-clusters \
  --region us-east-1 \
  --db-cluster-identifier mydocdbcluster
    "PendingModifiedValues": {
    "EngineVersion": "5.0.0"
},

  5. If testing is successful, proceed with the upgrade on your production cluster.

During the 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.

The following events are generated during the upgrade:

  1. Database cluster engine major version upgrade started. Cluster remains online.

  2. Upgrade preparation in progress: Starting online upgrade prechecks.

  3. Upgrade preparation in progress: Completed online upgrade prechecks.

  4. Taking database cluster offline while the primary instance completes the patch/upgrade process.

  5. Upgrade preparation in progress: Starting offline upgrade prechecks.

  6. Upgrade preparation in progress: Completed offline upgrade prechecks.

  7. Upgrade in progress: Creating pre-upgrade snapshot [preupgrade-<cluster-name>-<version-from>-to-<version-to>-<timestamp>].

  8. Upgrade in progress: Cloning volume.

  9. Upgrade in progress: Upgrading writer.

  10. Upgrade in progress: Upgrading readers.

  11. Database cluster engine major version has been upgraded.

Events are visible in the console under the Events page:

Image: the Events navigation box showing a table of upgrade events.

From the AWS CLI, you can run aws docdb describe-events to monitor upgrade progress. To receive notifications automatically, use aws docdb create-event-subscription to subscribe to events and route them to Amazon SNS for email, push messages, or other delivery methods. For more information, see Subscribing to Amazon DocumentDB events.

aws docdb describe-events 
  --source-identifier mydocdbcluster 
  --source-type db-cluster

The command returns output similar to the following:

{
    "Events": [
        {
            "SourceIdentifier": "mydocdbcluster",
            "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 the upgrade

Warning

Immediately after the in-place major version upgrade, your Amazon DocumentDB cluster repopulates index metadata that the database engine uses to optimize query execution plans. Query performance returns to expected levels once this process completes. It typically finishes in a few minutes but can take up to two hours depending on the number of indexes on your cluster.

Do not reboot, failover, or scale up/down your writer instance during this time, as it may disrupt the index metadata recalculation. We recommend waiting until you observe expected query performance before making such changes.

Track progress via the following cluster events:

  • Post-upgrade cluster status: Index metadata refresh process started

  • Post-upgrade cluster status: Index metadata refresh process completed in X seconds

Contact AWS support if the index metadata refresh process hasn't completed within three hours, or if you continue to experience performance issues after the process completes.

  1. Take a manual snapshot of the upgraded cluster in case you need to restore to the post-upgrade state. The automatic snapshot process will resume as soon as the in-place major version upgrade completes.

  2. Tag clusters upgraded from 3.6. Add a tag to differentiate clusters upgraded from 3.6. (see Post-upgrade considerations for clusters upgraded from 3.6 or 4.0).

  3. Update your driver. To use new features (for example, collation, views, or Zstd compression in 8.0), upgrade to the corresponding MongoDB API version. For more information, see What's new in Amazon DocumentDB 8.0.

  4. Test thoroughly. Validate your application against the upgraded cluster.

What changes after upgrading from Amazon DocumentDB 5.0 to 8.0

After performing a major version upgrade from Amazon DocumentDB 5.0 to 8.0, the following features are enabled or changed:

  • Collation. Amazon DocumentDB 8.0 supports collation. After the upgrade, new collections and their indexes, and new indexes on existing collections, have collation enabled by default.

  • Text index. New text indexes are created using Text Index V2, which uses an updated text search parser for improved MongoDB compatibility. Existing text indexes are not affected.

  • Query planner version. If you did not have a custom parameter group, a new default parameter group is created for Amazon DocumentDB 8.0 with Planner Version 3 automatically selected. With query planner version 3, views are also available.

  • Compression. Amazon DocumentDB 8.0 supports dictionary-based document compression using the Zstd algorithm. After the upgrade, new collections are created with Zstd compression enabled by default. Existing collections from 5.0 retain their compression settings. To take advantage of Zstd compression on existing collections, you can modify their compression settings. For more information, see Dictionary-based compression.

  • Index rebuild. If you are upgrading from Amazon DocumentDB 5.0 to Amazon DocumentDB 8.0, no index rebuild is needed.

Note

For a full list of functional differences, see Amazon DocumentDB compatibility with MongoDB.

Post-upgrade considerations for clusters upgraded from 3.6 or 4.0

  • Index rebuild. An MVU retains original indexes. Amazon DocumentDB 5.0 has improved index maintenance and garbage collection, especially for low-cardinality indexes. After upgrading from 3.6 or 4.0, we recommend rebuilding your indexes to ensure optimal query performance (optional, involves additional I/O). See Index maintenance using reIndex.

  • Subdocument numeric comparison (3.6 only). Clusters upgraded from 3.6 inherit the 3.6 behavior where numeric types in subdocuments are not compared across types. For example, {a: {b: NumberLong(1)}} does not equal {a: {b: 1}} in 3.6, but they are equal in 4.0 and later. This behavior affects any clusters upgraded from 3.6.

Performing the upgrade

Using the AWS Management Console

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

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

    Image: the Clusters navigation box showing a list of existing cluster links and their corresponding instance links.

  3. In Cluster specifications, choose the target version (for example, 5.0.0 or 8.0.0) from the Engine version dropdown.

    Image: the Cluster specifications section of the Modify cluster dialog box showing the Cluster indentifier and Engine version fields.

  4. In Cluster options, select your cluster parameter group for the target engine version. You can use the default (for example, default.docdb5.0 or default.docdb8.0) or a custom parameter group you created.

    Image: the Cluster options section of the Modify cluster dialog box showing the Cluster parameter group field.

  5. Choose Continue, select your scheduling preference (apply immediately or next maintenance window), then choose Modify cluster.

    Image: the Modify cluster dialog box showing the summary and scheduling of modification for the selected cluster.

  6. Monitor the cluster status in the clusters table as it changes to upgrading:

    Image: the Clusters navigation box highlighting the Status column for the cluster being upgraded.
Using the AWS CLI

Use modify-db-cluster with the --allow-major-version-upgrade flag:

aws docdb modify-db-cluster \
  ‐‐db-cluster-identifier mydocdbcluster \
  ‐‐allow-major-version-upgrade \
  ‐‐engine-version 8.0.0 \
  ‐‐apply-immediately \
  ‐‐cluster-parameter-group mydocdbparametergroup \
  ‐‐region us-east-1

Replace each placeholder with your cluster's information.

Troubleshooting

  • Upgrade failure and rollback. If the upgrade fails, it automatically attempts a rollback. A successful rollback generates the event: "Database cluster is in a state that cannot be upgraded." Your cluster returns to its pre-upgrade state and you can continue using it. Contact AWS support to troubleshoot before re-attempting.

  • Post-upgrade performance. Temporary performance degradation and high CPU utilization may occur while the index metadata refresh runs. If degradation persists beyond 3 hours, contact AWS support.

For additional assistance, contact AWS Support.