Amazon DocumentDB
Developer Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Deleting an Amazon DocumentDB Cluster

You can delete an Amazon DocumentDB cluster using the AWS Management Console or the AWS CLI.

Important

To delete a cluster, the cluster must be in the available state. You cannot delete a cluster that is stopped. If the cluster is stopped, first start the cluster, wait for the cluster to become available, and then delete the cluster. For more information, see Stopping and Starting an Amazon DocumentDB Cluster.

Deletion Protection

To protect your cluster from accidental deletion, you can enable deletion protection. Deletion protection is enabled by default when you create a cluster using the console. However, deletion protection is disabled by default if you create a cluster using the AWS CLI.

Amazon DocumentDB enforces deletion protection for a cluster whether you perform the delete operation using the console or the AWS CLI. If deletion protection enabled, you can't delete a cluster. To delete a cluster that has deletion projection enabled, you must first modify the cluster and disable deletion protection.

When using the console with deletion protection enabled on a cluster, you can't delete the cluster's last instance because doing so also deletes the cluster. You can delete the last instance of a deletion protected cluster using the AWS CLI. However, the cluster itself still exists, and your data is preserved. You can access the data by creating new instances for the cluster. For more information about enabling and disabling deletion protection, see:

Using the AWS Management Console

To delete a cluster using the AWS Management Console, deletion protection must be disabled.

To determine whether a cluster has deletion protection enabled

  1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. Choose the cluster's name, and scroll to the bottom of the Cluster details section. Locate Deletion protection. If deletion protection is enabled, modify the cluster to disable deletion protection. For information about modifying a cluster, see Modifying an Amazon DocumentDB Cluster.

    
                        Screenshot showing Amazon DocumentDB Cluster details, with Deletion protection
                           enabled.

    After Deletion protection is disabled, you are ready to delete the cluster.

To delete a cluster

  1. In the navigation pane, choose Clusters. Find the cluster that you want to delete, and choose the button to the left of the cluster name.

  2. Determine whether the cluster has any instances by checking the Instances column.

    
                        Screenshot showing list of cluster identifiers with instances column
                           highlighted.

    Before you can delete a cluster, you must delete all of its instances. For more information, see Deleting an Amazon DocumentDB Instance.

  3. Depending on whether your cluster has any instances, do one of the following steps.

    • If the cluster has no instances, choose Actions, and then choose Delete. Complete the Delete <cluster-name> dialog box, and then choose Delete.

    • If the cluster has one or more instances, do the following:

      1. In the navigation pane, choose Instances.

      2. Delete each of the cluster's instances. When you delete the last instance, the cluster is also deleted. For information about deleting instances, see Deleting an Amazon DocumentDB Instance.

It takes several minutes for the cluster to be deleted. To monitor the status of the cluster, see Monitoring a Cluster's Status in Amazon DocumentDB.

Using the AWS CLI

You cannot delete a cluster that has any instances associated with it. To determine which instances you need to delete, run the following command. To see a listing of all your instances grouped by cluster, omit the --db-cluster-identifier parameter.

To delete a cluster using the AWS CLI, first delete all the cluster's instances, then, if needed, disable deletion protection, and finally, delete the cluster. For instructions on deleting an instance, see Deleting an Amazon DocumentDB Instance.

First, delete all of the cluster's instances

To determine which instances you need to delete, run the following command. To see a listing of all your instances grouped by cluster, omit the --db-cluster-identifier parameter.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]'

Output from this operation looks something like the following (JSON format).

[ [ "sample-cluster", [ "sample-instance", "sample-instance2" ] ] ]

If the cluster you want to delete has any instances, delete them, then continue. For more information, see Deleting an Amazon DocumentDB Instance.

The following code deletes the instance sample-instance.

aws docdb delete-db-instance \ --db-instance-identifier sample-instance

Second, if currently enabled, disable deletion protection

Using the AWS CLI to delete all of a cluster's instances does not delete the cluster. You must also delete the cluster, but you can do this only if deletion protection is disabled.

To determine whether the cluster has deletion protection enabled, run the following command. To see the deletion protection status of all clusters, omit the --db-cluster-identifier parameter.

aws docdb describe-db-clusters \ --db-cluster-identifier sample-cluster \ --query 'DBClusters[*].[DBClusterIdentifier,DeletionProtection]'

Output from this operation looks something like the following (JSON format).

[ [ "sample-cluster", "enabled" ] ]

If the cluster has deletion protection enabled, modify the cluster and disable deletion protection. To disable deletion protection on the cluster, use the following code.

aws docdb modify-db-cluster \ --db-cluster-identifier sample-cluster \ --no-deletion-protection \ --apply-immediately

Finally, delete the cluster

After deletion protection is disabled, you are ready to delete the cluster. To delete a cluster, use the delete-db-cluster operation with the following parameters.

Parameters:

  • --db-cluster-identifier—Required. The identifier of the cluster that you want to delete.

  • --final-db-snapshot-identifier—Optional. If you want a final snapshot, you must include the --final-db-snapshot-identifier parameter with a name for the final snapshot. The naming constraints for the final snapshot are the same as for a cluster. You must include either --final-db-snapshot-identifier or --skip-final-snapshot.

    • Length is [1–63] letters, numbers, or hyphens.

    • First character must be a letter.

    • Cannot end with a hyphen or contain two consecutive hyphens.

    • Must be unique for all clusters (across Amazon RDS, Amazon Neptune, and Amazon DocumentDB) per AWS account, per Region.

  • --skip-final-snapshot—Optional. Use this parameter only if you don't want to take a final snapshot before deleting your cluster. The default setting is to take a final snapshot. You must include either --final-db-snapshot-identifier or --skip-final-snapshot.

The following code deletes the cluster sample-cluster using the AWS CLI. The operation fails if there are any instances associated with the cluster or if deletion protection is enabled.

For Linux, macOS, or Unix:

aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --final-db-snapshot-identifier sample-cluster-final-snapshot

For Windows:

aws docdb delete-db-cluster ^ --db-cluster-identifier sample-cluster ^ --final-db-snapshot-identifier sample-cluster-final-snapshot

To delete a cluster without taking a final snapshot, use the following command.

For Linux, macOS, or Unix:

aws docdb delete-db-cluster \ --db-cluster-identifier sample-cluster \ --skip-final-snapshot

For Windows:

aws docdb delete-db-cluster ^ --db-cluster-identifier sample-cluster ^ --skip-final-snapshot

The output of the delete-db-cluster operation is the cluster you are deleting.

It takes several minutes for the cluster to be deleted. To monitor the status of the cluster, see Monitoring a Cluster's Status.