Deleting an Amazon DocumentDB cluster
You can delete an Amazon DocumentDB cluster using the AWS Management Console or the AWS CLI. To delete a cluster, the cluster must be in the available state and must not have any instances associated with it. 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 is enabled, you can't delete a cluster. To
delete a cluster that has deletion protection 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:
-
Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.
-
In the navigation pane, choose Clusters.
If you don't see the navigation pane on the left side of your screen, choose the menu icon
()
in the upper-left corner of the page.
-
Note that in the Clusters navigation box, the column Cluster Identifier shows both clusters and instances. Instances are listed underneath clusters, similar to the screenshot below.
-
Choose the cluster's name, and select the
Configuration tab. In 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.
After Deletion protection is disabled,
you are ready to delete the cluster.
To delete a cluster:
-
In the navigation pane, choose Clusters.
-
Determine whether the cluster has any instances by
checking the Instances column. Before
you can delete a cluster, you must delete all of its
instances. For more information, see Deleting an Amazon DocumentDB instance.
-
Depending on whether your cluster has any instances, do
one of the following steps.
-
If the cluster has no instances, select the
button to the left of the cluster name and choose
Actions. From the dropdown menu,
choose Delete. Complete the
Delete <cluster-name> dialog
box, and then choose Delete.
If the cluster has one or more instances, do the
following:
-
In the navigation pane, choose
Instances.
-
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 an Amazon DocumentDB cluster's status.
- Using the AWS CLI
-
You cannot delete a cluster that has any instances associated
with it. To determine which instances are associated with your
cluster, run the describe-db-clusters
command and
delete all of the cluster's instances. Then, if needed, disable
deletion protection on your cluster, and finally, delete the
cluster.
-
First, delete all of the cluster's
instances.
To determine which instances you need to delete, run the
following command.
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-1",
"sample-instance-2"
]
]
]
If the cluster you want to delete has any instances,
delete them as shown below.
aws docdb delete-db-instance \
--db-instance-identifier sample-instance
-
Second, 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 your
Amazon DocumentDB 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.
[
[
"sample-cluster",
"true"
]
]
If the cluster has deletion protection enabled, modify
the cluster and disable deletion protection. To disable
deletion protection on the cluster, run the following command.
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.
-
--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 this
parameter with a name for the final snapshot. You must
include either --final-db-snapshot-identifier
or --skip-final-snapshot
.
Naming constraints:
-
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 AWS CLI code deletes the cluster sample-cluster
with a final snapshot. 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
The following AWS CLI code deletes the cluster
sample-cluster
without taking a final snapshot.
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.