Modifying an Amazon DocumentDB Cluster

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

Using the AWS Management Console

Use the following procedure to modify a specific Amazon DocumentDB cluster using the console.

To modify an Amazon DocumentDB cluster

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

  2. In the navigation pane, choose Clusters.

    Tip

    If you don’t see the navigation pane on the left side of your screen, choose the menu icon (Modifying a Cluster - 图1) in the upper-left corner of the page.

  3. Specify the cluster that you want to modify by choosing the button to the left of the cluster’s name.

  4. Choose Actions, and then choose Modify.

  5. In the Modify Cluster: <cluster-name> pane, make the changes that you want. You can make changes in the following areas:

    • Cluster specifications—The cluster’s name, security groups, and password.

    • Cluster options—The cluster’s port and parameter group.

    • Backup—The cluster’s backup retention period and backup window.

    • Log exports—Enable or disable exporting audit or profiler logs.

    • Maintenance—Set the cluster’s maintenance window.

    • Deletion protection—Enable or disable deletion protection on the cluster. Deletion protection is enabled by default.

  6. When you’re finished, choose Continue to view a summary of your changes.

  7. If you are satisfied with your changes, you can choose Modify cluster to modify your cluster. Alternatively, you can choose Back or Cancel to edit or cancel your changes, respectively.

It takes a few minutes for your changes to be applied. You can use the cluster only when its status is available. You can monitor the cluster’s status using the console or AWS CLI. For more information, see Monitoring an Amazon DocumentDB Cluster’s Status.

Using the AWS CLI

Use the modify-db-cluster operation to modify the specified cluster using the AWS CLI. For more information, see ModifyDBCluster in the Amazon DocumentDB API Reference.

Parameters

  • --db-cluster-identifier—Required. The identifier of the Amazon DocumentDB cluster that you are going to modify.

  • --backup-retention-period—Optional. The number of days for which automated backups are retained. Valid values are 1–35.

  • --db-cluster-parameter-group-name—Optional. The name of the cluster parameter group to use for the cluster.

  • --master-user-password—Optional. The new password for the master database user.

    Password constraints:

    • Length is [8—100] printable ASCII characters.

    • Can use any printable ASCII characters except for the following:

      • / (forward slash)

      • " (double quotation mark)

      • @ (at symbol)

  • --new-db-cluster-identifier—Optional. The new cluster identifier for the cluster when renaming a cluster. This value is stored as a lowercase string.

    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.

  • --preferred-backup-window—Optional. The daily time range during which automated backups are created, in Universal Coordinated Time (UTC).

    • Format: hh24:mm-hh24:mm

  • --preferred-maintenance-window—Optional. The weekly time range during which system maintenance can occur, in UTC.

    • Format: ddd:hh24:mm-ddd:hh24:mm

    • Valid days: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.

  • --deletion-protection or --no-deletion-protection—Optional. Whether deletion protection should be enabled on this cluster. Deletion protection prevents a cluster from being accidentally deleted until the cluster is modified to disable deletion protection. For more information, see Deleting an Amazon DocumentDB Cluster.

  • --apply-immediately or --no-apply-immediately—Use --apply-immediately to make the change immediately. Use --no-apply-immediately to make the change during your cluster’s next maintenance window.

The following code changes the backup retention period for the cluster sample-cluster.

For Linux, macOS, or Unix:

  1. aws docdb modify-db-cluster \
  2.        --db-cluster-identifier sample-cluster \
  3.        --apply-immediately \
  4.        --backup-retention-period 7

For Windows:

  1. aws docdb modify-db-cluster ^
  2.        --db-cluster-identifier sample-cluster ^
  3.        --apply-immediately ^
  4.        --backup-retention-period 7

Output from this operation looks something like the following.

  1. {
  2.     "DBCluster": {
  3.         "BackupRetentionPeriod": 7,
  4.         "DbClusterResourceId": "cluster-VDP53QEWST7YHM36TTXOPJT5YE",
  5.         "Status": "available",
  6.         "DBClusterMembers": [
  7.             {
  8.                 "PromotionTier": 1,
  9.                 "DBClusterParameterGroupStatus": "in-sync",
  10.                 "DBInstanceIdentifier": "sample-cluster-instance",
  11.                 "IsClusterWriter": true
  12.             }
  13.         ],
  14.         "ReadReplicaIdentifiers": [],
  15.         "AvailabilityZones": [
  16.             "us-east-1b",
  17.             "us-east-1c",
  18.             "us-east-1a"
  19.         ],
  20.         "ReaderEndpoint": "sample-cluster.cluster-ro-ctevjxdlur57.us-east-1.rds.amazonaws.com",
  21.         "DBClusterArn": "arn:aws:rds:us-east-1:123456789012:cluster:sample-cluster",
  22.         "PreferredMaintenanceWindow": "sat:09:51-sat:10:21",
  23.         "EarliestRestorableTime": "2018-06-17T00:06:19.374Z",
  24.         "StorageEncrypted": false,
  25.         "MultiAZ": false,
  26.         "AssociatedRoles": [],
  27.         "MasterUsername": "<your-master-user-name>",
  28.         "DBClusterIdentifier": "sample-cluster",
  29.         "VpcSecurityGroups": [
  30.             {
  31.                 "Status": "active",
  32.                 "VpcSecurityGroupId": "sg-77186e0d"
  33.             }
  34.         ],
  35.         "HostedZoneId": "Z2SUY0A1719RZT",
  36.         "LatestRestorableTime": "2018-06-18T21:17:05.737Z",
  37.         "AllocatedStorage": 1,
  38.         "Port": 27017,
  39.         "Engine": "docdb",
  40.         "DBClusterParameterGroup": "default.docdb3.4",
  41.         "Endpoint": "sample-cluster.cluster-ctevjxdlur57.us-east-1.rds.amazonaws.com",
  42.         "DBSubnetGroup": "default",
  43.         "PreferredBackupWindow": "00:00-00:30",
  44.         "EngineVersion": "3.4",
  45.         "ClusterCreateTime": "2018-06-06T19:25:47.991Z",
  46.         "IAMDatabaseAuthenticationEnabled": false
  47.     }
  48. }

It takes a few minutes for your changes to be applied. You can use the cluster only when its status is available. You can monitor the cluster’s status using the console or AWS CLI. For more information, see Monitoring an Amazon DocumentDB Cluster’s Status.