autobotAI

AWS DocumentDB Major Version Upgrade SOP

Purpose

This Standard Operating Procedure (SOP) outlines the process for upgrading an AWS DocumentDB cluster from version 4.0 to 5.0, including parameter group migration and configuration preservation.

Prerequisites

  • AWS CLI installed and configured with appropriate credentials
  • Necessary IAM permissions for DocumentDB operations
  • Access to the target DocumentDB cluster
  • Maintenance window scheduled (if not using --apply-immediately)

Procedure Overview

This SOP covers upgrading a DocumentDB cluster while preserving custom parameter configurations by creating a new parameter group compatible with the target version.

Step 1: List Available DocumentDB Clusters

Purpose: Identify the cluster to be upgraded.

bash
aws docdb describe-db-clusters \
  --query 'DBClusters[*].DBClusterIdentifier' \
  --output table

Expected Output: Table listing all DocumentDB cluster identifiers in your account.

Step 2: Verify Current Cluster Version and Status

Purpose: Confirm the current engine version and ensure the cluster is in a stable state before upgrade.

bash
aws docdb describe-db-clusters \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --query 'DBClusters[0].[EngineVersion, Status]' \
  --output table

Replace: <CLUSTER_IDENTIFIER> with your actual cluster identifier (e.g., autobotaidb-live-testqa-coupon-2-hd)

Expected Output: Current engine version and cluster status (should be "available")

Step 3: Export Current Parameter Group Configuration

Purpose: Backup current parameter settings for reference and migration.

bash
aws docdb describe-db-cluster-parameters \
  --db-cluster-parameter-group-name <CURRENT_PARAMETER_GROUP> \
  --query 'Parameters[*].[ParameterName, ParameterValue, ApplyMethod]' \
  --output text > docdb4-params.txt

Replace: <CURRENT_PARAMETER_GROUP> with your current parameter group name (e.g., autobotai-docdb-live-testqa-coupon-2)

Expected Output: A text file containing all parameters from the current parameter group.

Step 4: Create New Parameter Group for Target Version

Purpose: Create a parameter group compatible with DocumentDB 5.0.

bash
aws docdb create-db-cluster-parameter-group \
  --db-cluster-parameter-group-name <NEW_PARAMETER_GROUP> \
  --db-parameter-group-family docdb5.0 \
  --description "Copy of <CURRENT_PARAMETER_GROUP> for DocumentDB 5.0"

Replace:

  • <NEW_PARAMETER_GROUP> with your new parameter group name (e.g., autobotai-docdb5-live-testqa-coupon-2)
  • <CURRENT_PARAMETER_GROUP> with your current parameter group name

Expected Output: Confirmation of parameter group creation with details.

Step 5: Verify New Parameter Group Creation

Purpose: Confirm the new parameter group exists and has the correct family.

bash
aws docdb describe-db-cluster-parameter-groups \
  --query "DBClusterParameterGroups[?DBClusterParameterGroupName=='<NEW_PARAMETER_GROUP>'].[DBParameterGroupFamily,Description]" \
  --output table

Replace: <NEW_PARAMETER_GROUP> with your new parameter group name

Expected Output: Table showing docdb5.0 as the parameter group family.

Step 6: Copy Modifiable Parameters to New Parameter Group

Purpose: Transfer all custom parameter values from the old parameter group to the new one.

bash
for p in $(aws docdb describe-db-cluster-parameters \
  --db-cluster-parameter-group-name <CURRENT_PARAMETER_GROUP> \
  --query "Parameters[?IsModifiable==\`true\`].ParameterName" \
  --output text); do
  
  value=$(aws docdb describe-db-cluster-parameters \
    --db-cluster-parameter-group-name <CURRENT_PARAMETER_GROUP> \
    --query "Parameters[?ParameterName=='${p}'].ParameterValue" \
    --output text)
  
  aws docdb modify-db-cluster-parameter-group \
    --db-cluster-parameter-group-name <NEW_PARAMETER_GROUP> \
    --parameters "ParameterName=${p},ParameterValue=${value},ApplyMethod=immediate"
done

Replace:

  • <CURRENT_PARAMETER_GROUP> with your current parameter group name
  • <NEW_PARAMETER_GROUP> with your new parameter group name

Note: This loop may take several minutes depending on the number of parameters.

Expected Output: Multiple confirmation messages as each parameter is modified.

Step 7: Export New Parameter Group Configuration

Purpose: Verify parameter migration and create a backup of the new configuration.

bash
aws docdb describe-db-cluster-parameters \
  --db-cluster-parameter-group-name <NEW_PARAMETER_GROUP> \
  --query 'Parameters[*].[ParameterName, ParameterValue, ApplyMethod]' \
  --output text > docdb5-params.txt

Replace: <NEW_PARAMETER_GROUP> with your new parameter group name

Expected Output: A text file containing all parameters from the new parameter group.

Verification Step: Compare docdb4-params.txt and docdb5-params.txt to ensure modifiable parameters were copied correctly.

Step 8: Perform Major Version Upgrade

Purpose: Upgrade the DocumentDB cluster to version 5.0 with the new parameter group.

bash
aws docdb modify-db-cluster \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --engine-version 5.0.0 \
  --allow-major-version-upgrade \
  --db-cluster-parameter-group-name <NEW_PARAMETER_GROUP> \
  --apply-immediately

Replace:

  • <CLUSTER_IDENTIFIER> with your cluster identifier
  • <NEW_PARAMETER_GROUP> with your new parameter group name

Important Notes:

  • --allow-major-version-upgrade is required for major version changes
  • --apply-immediately applies changes immediately; remove this flag to apply during the next maintenance window
  • The upgrade process will cause downtime; plan accordingly

Expected Output: Confirmation that the cluster modification has been initiated.

Step 9: Monitor Upgrade Progress

Purpose: Track the upgrade status until completion.

bash
aws docdb describe-db-clusters \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --query 'DBClusters[0].[Status, EngineVersion]' \
  --output table

Expected Statuses:

  • upgrading - Upgrade in progress
  • available - Upgrade complete

Recommended: Run this command every 5-10 minutes until status returns to "available"

Step 10: Reboot DocumentDB Cluster

Purpose: Ensure the cluster loads the new engine binaries cleanly after the upgrade.

bash
aws docdb describe-db-instances \
  --query 'DBInstances[].DBInstanceIdentifier' \
  --output table

Use the Output from the Above mentioned command to Execute this command on each Instance Identifier:

bash
aws docdb reboot-db-instance \
  --db-instance-identifier <INSTANCE_IDENTIFIER>

Expected Statuses:

  • rebooting Reboot in progress
  • available Reboot complete

Recommended: Run this command every 5-10 minutes until status returns to "available"

bash
aws docdb describe-db-clusters \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --query 'DBClusters[0].[Status, EngineVersion]' \
  --output table

Post-Upgrade Verification

After the upgrade completes, perform the following checks:

  1. Verify Engine Version:

    bash
    aws docdb describe-db-clusters \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --query 'DBClusters[0].EngineVersion' \
  --output text

    Expected: 5.0.0

  2. Verify Parameter Group:

    bash
    aws docdb describe-db-clusters \
  --db-cluster-identifier <CLUSTER_IDENTIFIER> \
  --query 'DBClusters[0].DBClusterParameterGroup' \
  --output text

    Expected: Your new parameter group name

  3. Test Application Connectivity: Ensure applications can connect and function properly

  4. Review Application Logs: Check for any errors or warnings related to the database

Rollback Procedure

If issues occur after the upgrade:

  1. Create a snapshot (if not already done before upgrade)
  2. Restore from pre-upgrade snapshot to a new cluster
  3. Update application connection strings to point to the restored cluster

Note: DocumentDB does not support direct downgrade. Rollback requires restoration from a snapshot.

Best Practices

  • Create a manual snapshot before starting the upgrade
  • Test the upgrade in a non-production environment first
  • Schedule upgrades during low-traffic periods
  • Review AWS DocumentDB 5.0 release notes for breaking changes
  • Have a communication plan for stakeholders during the maintenance window
  • Keep backups of parameter configurations (docdb4-params.txt and docdb5-params.txt)
  • Document any custom application changes required for version 5.0 compatibility

Troubleshooting

Issue: Parameter modification fails

Solution: Verify parameter names are compatible with DocumentDB 5.0. Some parameters may have been deprecated or renamed.

Issue: Upgrade takes longer than expected

Solution: Large clusters or clusters with many instances may take 30+ minutes. Monitor status periodically.

Issue: Cluster status shows "incompatible-parameters"

Solution: Review and adjust incompatible parameters in the new parameter group before retrying the upgrade.

Issue: CloudFormation Fails After this with 'ParameterGroup Cannot Be Created, Already Exists' Error

Solution: Open DocumentDB, Open Cluster, Modify and Set the Parameter Group to Non Docdb5.0 Param Group and apply changes immediately. The Open Parameter Groups and Delete the 5.0 Parameter Group and retry the cloudformation.

Document Information

Last Updated: October 24, 2025
Version: 1.0
Owner: Database Operations Team
Review Frequency: Quarterly or when AWS releases new DocumentDB versions