Maintaining Amazon DocumentDB

Amazon DocumentDB periodically performs two kinds of maintenance:

Engine patches and OS updates use the same three lifecycle categories—optional, required, and forced—with the same notification and apply behavior for each category. Engine releases also have a fourth category: minor versions, which you upgrade to manually. The categories are:

Engine patches are released into a single category (optional, required, or forced) and stay there. OS updates progress: most start as optional and, if not applied, transition to required and eventually forced. The exact timing depends on the patch and is published in the AHD notification and the date fields returned by describe-pending-maintenance-actions (see Apply dates). The Amazon DocumentDB Release notes use these category names when announcing engine changes.

Applying any engine patch takes the cluster offline briefly. The rest of this topic walks through how maintenance windows work, how to find pending work, how to apply engine patches and minor versions, how OS updates work, and special handling for global clusters.

Engine version numbering

Amazon DocumentDB uses two separate version identifiers:

You can determine the engine version from the engine patch version's prefix, as shown in the following table.

To check the patch version your cluster is running, connect and run db.runCommand({getEngineVersion: 1}).

For the list of released engine patch versions and what each one contains, see Release notes.

Managing your Amazon DocumentDB maintenance windows

Every cluster and every instance has its own weekly 30-minute maintenance window—the period when scheduled modifications and software patching run. Most events complete within 30 minutes; larger ones can run longer.

If you don't choose a window when creating the resource, Amazon DocumentDB assigns one at random within an 8-hour daily block defined for the Region, on a randomly selected day. Choose windows that minimize impact to your application—evenings or weekends, for example.

For database engine upgrades, Amazon DocumentDB uses the cluster's window, not the windows of individual instances.

The following table shows the default time blocks per Region.

Changing your Amazon DocumentDB maintenance windows

Choose the lowest-traffic window you can, and adjust over time as your traffic patterns shift. The cluster or instance is unavailable during the window only if a system change—a scale-storage operation or an instance class change, for example—requires an outage, and only for as long as that change actually needs.

Notifications for Amazon DocumentDB engine patches

When a required engine patch becomes available in an AWS Region, every AWS account with an affected Amazon DocumentDB cluster in that Region receives a notification through the Health Dashboard (AHD) and through e-mail (sent to the AWS account's root user address). One notification is delivered per affected Amazon DocumentDB engine version. You can find them under Scheduled changes in the AHD. Each notification lists the patch availability timing, the auto-apply schedule, the affected clusters, and the release notes.

Notifications go out approximately two days before the auto-apply window opens. For example, a required patch released Monday at 00:00 UTC becomes eligible for auto-apply on Wednesday at 00:00 UTC. If your cluster's maintenance window is Wednesday at 12:00 UTC, the patch auto-applies that Wednesday—about 12 hours after the auto-apply window opens. If your maintenance window is Tuesday at 12:00 UTC, the patch waits a full week before auto-applying.

You have two options after receiving the notification: self-apply the patch before the auto-apply date, or wait for it to auto-apply during an upcoming maintenance window (the default). To self-apply, open the cluster's Maintenance & backups tab and look for the entry of type system-update.

Optional patches and new minor versions don't generate AHD or e-mail notifications. To track them, watch the Amazon DocumentDB Release notes.

Forced patches (the rarest category, reserved for the most critical security fixes) are also announced through AHD and e-mail. Unlike required patches, they apply outside your maintenance window, so the auto-apply timing example above does not apply.

Reacting to patch notifications programmatically

AWS Health integrates with Amazon EventBridge, which lets you build event-driven applications across more than 20 targets, including AWS Lambda and Amazon Simple Queue Service (SQS). To react to engine-patch availability programmatically, configure EventBridge against the AWS_DOCDB_DB_PATCH_UPGRADE_MAINTENANCE_SCHEDULED event. From there you can capture event data, raise additional events, send push notifications via the AWS Console Mobile Application, or take any other action you need.

If Amazon DocumentDB cancels a patch (rare), you receive an AHD notification and an e-mail about the cancellation. Use the AWS_DOCDB_DB_PATCH_UPGRADE_MAINTENANCE_CANCELLED event code with Amazon EventBridge to handle this case. For more about writing rules, see the Amazon EventBridge User Guide.

Viewing pending Amazon DocumentDB maintenance actions

Use the AWS Management Console or the AWS CLI to check what maintenance is pending for a cluster or instance.

Pending updates appear with the action type system-update, which covers both engine patches and OS updates.

When an update is pending, you can:

The maintenance window controls when pending operations start, not how long they take to complete.

Apply dates

Each pending maintenance action carries up to three apply dates. They appear in the AWS CLI output for describe-pending-maintenance-actions and indicate when the action will run. Fields are null for optional maintenance.

To defer a pending action, move your maintenance window to a later day before AutoAppliedAfterDate. Once AutoAppliedAfterDate passes, the action will auto-apply during the next maintenance window. Once ForcedApplyDate passes, no further deferral is possible. The exact deferral window varies per patch; the dates are published in the AHD notification and the AWS CLI output.

Amazon DocumentDB engine updates

When you've identified a pending engine patch, use one of the following procedures to apply or schedule it. You can run these procedures from either the AWS Management Console or the AWS CLI.

Read availability during patching

Amazon DocumentDB engine 5.0 and 8.0 preserve read availability during patching when the cluster has multiple instances. Amazon DocumentDB patches reader instances in a rolling fashion, in three groups, so the remaining readers continue serving traffic. The writer is briefly unavailable while it patches. To achieve zero read downtime, set your read preference so reads can fall back to the writer: secondaryPreferred or primaryPreferred work; primary or secondary alone may incur read downtime.

While readers are patching, overall cluster read throughput drops temporarily. To hold throughput steady, provision additional readers before the upgrade and remove them after it completes.

On engine 3.6 and 4.0, these read-availability features don't apply: an engine patch causes longer downtime that affects both reads and writes. To upgrade to a major version that does, see Amazon DocumentDB in-place major version upgrade.

Patch downtime length

Engine-patch downtime varies. The biggest factors are CPU utilization and memory pressure on the instance at the time of the patch, so right-sizing your instances matters. To minimize downtime, run the latest Amazon DocumentDB major engine version and spread instances across multiple Availability Zones.

Patch updates and replacements

Amazon DocumentDB monitors patches after release. In the rare case that an issue is identified, Amazon DocumentDB pauses the rollout while it prepares an updated version. When this happens, clusters that haven't yet received the patch no longer see it as an available maintenance action, and the corresponding scheduled-change notification in the Health Dashboard is withdrawn. Clusters already running the affected version continue to operate normally and require no action from you.

An updated patch follows shortly. When it becomes available in your Region, you receive a fresh notification through the Health Dashboard and e-mail, just as described in Notifications for Amazon DocumentDB engine patches.

Minor version upgrades

Amazon DocumentDB publishes minor versions on top of major version 5.0 and later (for example, 5.0.1). Minor versions are not published for major versions earlier than 5.0. Minor versions behave differently from required and optional engine patches:

Read more: Amazon DocumentDB minor version upgrade.

Amazon DocumentDB operating system updates

Instances occasionally need OS updates. Amazon DocumentDB updates the OS to improve performance and tighten security. OS updates leave the cluster engine version and instance class unchanged. Like engine patches, OS updates use the optional / required / forced lifecycle described at the top of this topic; unlike engine patches, an OS update can transition through these categories over time if you defer it. Apply OS updates as soon as they are available, and set your instance maintenance window to a time that fits your business.

To get an event when a new optional update arrives, subscribe to RDS-EVENT-0230 in the security patching event category. For details, see Subscribing to Amazon DocumentDB Event Subscriptions. After receiving a notification, you can self-apply the OS patch to each instance.

When patching a cluster, update reader instances first and the writer last. Avoid patching readers and the writer simultaneously—a failover during the patch can extend downtime. Maintenance on the primary instance triggers a failover, so run more than one instance per cluster to stay available. For details, see Amazon DocumentDB Failover.

OS updates are tied to specific engine versions and instance classes, so different instances become eligible at different times. When an instance is eligible, the update appears in the console; you can also see it via the AWS CLI describe-pending-maintenance-actions command or the DescribePendingMaintenanceActions API.

Use the AWS Management Console or AWS CLI to check whether an update is available.

User-initiated updates

Some changes you start yourself—for example, swapping an instance class for one with more or less memory, or changing the cluster's parameter group. Amazon DocumentDB treats these differently from updates it initiates. For details, see:

To list user-initiated changes that are still pending:

aws docdb describe-db-instances \
    --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'

aws docdb describe-db-instances ^
    --query 'DBInstances[*].[DBClusterIdentifier,DBInstanceIdentifier,PendingModifiedValues]'

[
    [
        "sample-cluster",
        "sample-cluster-instance",
        {
            "DBInstanceClass": "db.r5.xlarge"
        }
    ],
    [
        "sample-cluster",
        "sample-cluster-instance-2",
        {}
    ]
]

Global clusters patching

In a global cluster, each member cluster—primary and secondary—upgrades during its own maintenance window. When a required engine patch is available in every Region, you receive an AHD and e-mail notification. Optional patches and new minor versions don't generate notifications; check the Amazon DocumentDB Release notes for those.

If you self-apply, always patch secondaries first and the primary last. This order keeps failover and switchover available throughout the rollout.

If you take no action, the patch auto-applies during each cluster's next maintenance window: secondaries first, then the primary at its window once the secondaries are done.

Keep the primary and secondary DB clusters on the same version. Managed cross-Region failover only works on a global database when every cluster shares the same engine version and patch level. The same applies if you add a new secondary that uses a newer engine version than the primary—create new secondaries on the primary's version before joining them to the global database.

After a patch notification, upgrade primary and secondary to the latest version at your earliest opportunity to keep failover and switchover working. If a failover or switchover request is rejected, compare the engine patch versions across clusters; if they don't match, apply the available patch on the lagging clusters.