# Managing Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups"></a>

You can manage Amazon DocumentDB engine configuration by using parameters in a cluster parameter group. A *cluster parameter group* is a collection of Amazon DocumentDB configuration values that make it easier to manage the parameters of your Amazon DocumentDB clusters. Cluster parameter groups act as a container for engine configuration values that are applied to all instances in the cluster. 

This section describes how to create, view, and modify cluster parameter groups. It also shows how you can determine which cluster parameter group is associated with a given cluster.

**Topics**
+ [Describing cluster parameter groups](cluster_parameter_groups-describe.md)
+ [Creating cluster parameter groups](cluster_parameter_groups-create.md)
+ [Modifying cluster parameter groups](cluster_parameter_groups-modify.md)
+ [Modifying clusters to use customized cluster parameter groups](cluster_parameter_groups-modify_clusters.md)
+ [Copying cluster parameter groups](cluster_parameter_groups-copy.md)
+ [Resetting cluster parameter groups](cluster_parameter_groups-reset.md)
+ [Deleting cluster parameter groups](cluster_parameter_groups-delete.md)
+ [Cluster parameters reference](cluster_parameter_groups-list_of_parameters.md)

# Describing Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-describe"></a>

A `default` cluster parameter group is created automatically when you create the first Amazon DocumentDB cluster in new region or are using a new engine. Subsequent clusters, which are created in the same region and have the same engine version, are created with the `default` cluster parameter group.

**Topics**
+ [Describing the details of a cluster parameter group](#cluster_parameter_groups-describe_details)
+ [Determining a cluster's parameter group](#cluster_parameter_groups-determine)
+ [Determining clusters and instances associated with a cluster parameter group](#cluster_parameter_groups-count)

## Describing the details of an Amazon DocumentDB cluster parameter group
<a name="cluster_parameter_groups-describe_details"></a>

To describe the details of a given cluster parameter group, complete the following steps using the AWS Management Console or the AWS Command Line Interface (AWS CLI).

------
#### [ Using the AWS Management Console ]

****

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

1. In the navigation pane, choose **Parameter groups**.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. In the **Cluster parameter groups** pane, select the name of the parameter group that you want to see the details of.

1. The resulting page shows the parameter group's parameters, recent activity, and tags.
   + Under **Cluster parameters**, you can see the parameter's name, current value, allowed values, whether the parameter is modifiable, its apply type, data type, and description. You can modify individual parameters by selecting the parameter and then choosing **Edit** in the **Cluster parameters** section. For more information, see [Modifying Amazon DocumentDB cluster parameters](cluster_parameter_groups-parameters.md).
   + Under **Recent events**, you can see the most recent events for this parameter group. You can filter through these events using the search bar in this section. For more information, see [Managing Amazon DocumentDB events](managing-events.md).
   + Under **Tags**, you can see the tags that are on this cluster parameter group. You can add or remove tags by choosing **Edit** in the **Tags** section. For more information, see [Tagging Amazon DocumentDB resources](tagging.md).

------
#### [ Using the AWS CLI ]

You can use the `describe-db-cluster-parameter-groups` AWS CLI command to view the Amazon Resource Name (ARN), family, description, and name of a single cluster parameter group or all cluster parameter groups that you have for Amazon DocumentDB. You can also use the `describe-db-cluster-parameters` AWS CLI command to view the parameters and their details inside a single cluster parameter group.
+ **--describe-db-cluster-parameter-groups** — To see a listing of all your cluster parameter groups and their details.
  + **--db-cluster-parameter-group-name** — Optional. The name of the cluster parameter group that you want described. If this parameter is omitted, all cluster parameter groups are described.
+ **--describe-db-cluster-parameters** — To list all the parameters inside a parameter group and their values.
  + **--db-cluster-parameter-group name** — Required. The name of the cluster parameter group that you want described.

**Example**  
The following code lists up to 100 cluster parameter groups and their ARN, family, description, and name.  

```
aws docdb describe-db-cluster-parameter-groups
```
Output from this operation looks something like the following (JSON format).  

```
{
          "DBClusterParameterGroups": [
              {
                  "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:012345678912:cluster-pg:default.docdb4.0",
                  "DBParameterGroupFamily": "docdb4.0",
                  "Description": "Default cluster parameter group for docdb4.0",
                  "DBClusterParameterGroupName": "default.docdb4.0"
              },
              {
                  "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:012345678912:cluster-pg:sample-parameter-group",
                  "DBParameterGroupFamily": "docdb4.0",
                  "Description": "Custom docdb4.0 parameter group",
                  "DBClusterParameterGroupName": "sample-parameter-group"
              }
          ]
}
```

**Example**  
The following code lists the ARN, family, description, and name for `sample-parameter-group`.  
For Linux, macOS, or Unix:  

```
aws docdb describe-db-cluster-parameter-groups \
          --db-cluster-parameter-group-name sample-parameter-group
```
For Windows:  

```
aws docdb describe-db-cluster-parameter-groups ^
          --db-cluster-parameter-group-name sample-parameter-group
```
Output from this operation looks something like the following (JSON format).  

```
{
          "DBClusterParameterGroups": [
              {
                  "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:123456789012:cluster-pg:sample-parameter-group",
                  "Description": "Custom docdb4.0 parameter group",
                  "DBParameterGroupFamily": "docdb4.0",
                  "DBClusterParameterGroupName": "sample-parameter-group"
              }
          ]
}
```

**Example**  
The following code lists the values of the parameters in `sample-parameter-group`.  
For Linux, macOS, or Unix:  

```
aws docdb describe-db-cluster-parameters \
    --db-cluster-parameter-group-name sample-parameter-group
```
For Windows:  

```
aws docdb describe-db-cluster-parameters ^
    --db-cluster-parameter-group-name sample-parameter-group
```
Output from this operation looks something like the following (JSON format).  

```
{
   "Parameters": [
         {
            "ParameterName": "audit_logs",
            "ParameterValue": "disabled",
            "Description": "Enables auditing on cluster.",
            "Source": "system",
            "ApplyType": "dynamic",
            "DataType": "string",
            "AllowedValues": "enabled,disabled",
            "IsModifiable": true,
            "ApplyMethod": "pending-reboot"
         },
         {
            "ParameterName": "change_stream_log_retention_duration",
            "ParameterValue": "17777",
            "Description": "Duration of time in seconds that the change stream log is retained and can be consumed.",
            "Source": "user",
            "ApplyType": "dynamic",
            "DataType": "integer",
            "AllowedValues": "3600-86400",
            "IsModifiable": true,
            "ApplyMethod": "pending-reboot"
         }
   ]
}
```

------

## Determining an Amazon DocumentDB cluster's parameter group
<a name="cluster_parameter_groups-determine"></a>

To determine which parameter group is associated with a particular cluster, complete the following steps using the AWS Management Console or the AWS CLI. 

------
#### [ Using the AWS Management Console ]

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

1. In the left navigation pane, choose **Clusters**.

1. In the list of clusters, select the name of the cluster you are interested in.

1. The resulting page shows the details of the cluster that you selected. Scroll down to **Cluster details**. At the bottom of that section, locate the parameter group's name below **Cluster parameter group**.  
![\[Screenshot: Showing a cluster's parameter group.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-determine-parameter-group.png)

------
#### [ Using the AWS CLI ]

The following AWS CLI code determines which parameter group is governing the cluster `sample-cluster`.

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

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

```
[
       [
           "sample-cluster",
           "sample-parameter-group"
       ]
]
```

------

## Determining clusters and instances associated with a Amazon DocumentDB cluster parameter group
<a name="cluster_parameter_groups-count"></a>

To determine how many clusters and instances are associated with each parameter group, complete the following steps using the AWS CLI.

------
#### [ Using the AWS CLI ]

The following AWS CLI code determines how many clusters and instances are associated with `sample-parameter-group`.

For Linux, macOS, or Unix:

```
aws docdb describe-db-clusters \
      --query 'DBClusters[*].[DBClusterParameterGroup,DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]' \
      --output json | \
      jq -r 'group_by(.[0]) | map({
         parameter_group_name: .[0][0],
         total_clusters: length,
         total_instances: map(.[2] | length) | add // 0
      }) | .[]'
```

For Windows:

```
aws docdb describe-db-clusters ^
      --query 'DBClusters[*].[DBClusterParameterGroup,DBClusterIdentifier,DBClusterMembers[*].DBInstanceIdentifier]' ^
      --output json | ^
      jq -r 'group_by(.[0]) | map({
         parameter_group_name: .[0][0],
         total_clusters: length,
         total_instances: map(.[2] | length) | add // 0
      }) | .[]'
```

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

```
{
   "parameter_group_name": "sample-parameter-group",
   "total_clusters": 50,
   "total_instances": 150
}
```

------

# Creating Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-create"></a>

Default cluster parameter groups such as `default.docdb5.0`, `default.docdb4.0`, or `default.docdb3.6`, are created when you create a cluster with a new engine version and in a new region. Subsequent clusters created in this region and with the same engine version inherit the `default` cluster parameter group. Once created, the `default` parameter groups cannot be deleted or renamed. You can modify the engine behavior of cluster instances by creating a custom parameter group with preferred parameter values and attaching it to your Amazon DocumentDB cluster. 

The following procedure guides you through creating a custom cluster parameter group. You can then [modify the parameters within that parameter group](https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-modify.html).

**Note**  
After you create a cluster parameter group, you should wait at least 5 minutes before using that particular parameter group. This allows Amazon DocumentDB to fully complete the `create` action before the cluster parameter group is used for a new cluster. You can use the AWS Management Console or the `describe-db-cluster-parameter-groups` AWS CLI operation to verify that your cluster parameter group has been created. For more information, see [Describing Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-describe.md).

------
#### [ Using the AWS Management Console ]

**To create a cluster parameter group**

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

1. In the navigation pane, choose **Parameter groups**.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. In the **Cluster parameter groups** pane, choose **Create**.

1. In the **Create cluster parameter group** pane, enter the following:

   1. **New cluster parameter group name** — Enter a name for the cluster parameter group. For example, `sample-parameter-group`. Cluster parameter groups have the following naming constraints:
      + Length is [1–255] alphanumeric characters.
      + First character must be a letter.
      + Cannot end with a hyphen or contain two consecutive hyphens.

   1. **Family** — Choose a DocumentDB version you intend to use for your cluster.

   1. **Description** — Provide a description for this cluster parameter group.

1. To create the cluster parameter group, choose **Create**. To cancel the operation, choose **Cancel**.

1. After you choose **Create**, the following text appears at the top of the page to verify that your cluster parameter group has been successfully created:

   ```
   Successfully created cluster parameter group 'sample-parameter-group'.
   ```

------
#### [ Using the AWS CLI ]

To create a new cluster parameter group for Amazon DocumentDB 4.0 clusters, use the AWS CLI `create-db-cluster-parameter-group` operation with the following parameters:
+ **--db-cluster-parameter-group-name** — The name of the custom cluster parameter group. For example, `sample-parameter-group`.
+ **--db-cluster-parameter-group-family** — The cluster parameter group family that is used as the template for the custom cluster parameter group.
+ **--description** — The user-provided description for this cluster parameter group. The following example uses "`Custom docdb4.0 parameter group`".

For Linux, macOS, or Unix:

**Example**  

```
aws docdb create-db-cluster-parameter-group \
 --db-cluster-parameter-group-name sample-parameter-group \
 --db-parameter-group-family docdb5.0 \
 --description "Custom docdb5.0 parameter group"
```
For Windows:  

```
aws docdb create-db-cluster-parameter-group ^
 --db-cluster-parameter-group-name sample-parameter-group ^
 --db-parameter-group-family docdb5.0 ^
 --description "Custom docdb5.0 parameter group"
```
Output from this operation looks something like the following (JSON format).  

```
{
    "DBClusterParameterGroup": {
        "DBClusterParameterGroupName": "sample-parameter-group",
        "DBParameterGroupFamily": "docdb5.0",
        "Description": "Custom docdb4.0 parameter group",
        "DBClusterParameterGroupArn": "sample-parameter-group-arn"
    }
}
```

------

# Modifying Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-modify"></a>

This section explains how to modify a *custom* Amazon DocumentDB parameter group. In Amazon DocumentDB, you cannot modify a `default` cluster parameter group which is created when you first create a cluster with new engine version in a new region. If your Amazon DocumentDB cluster is using the default cluster parameter group and you want to modify a value in it, you must first [create a new parameter group](https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-create.html) or [copy an existing parameter group](https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-copy.html), modify it, and then apply the modified parameter group to your cluster.

Complete the following steps to modify a custom cluster parameter group. Modify actions could take a while to propagate. Please wait for the modified cluster paramater group to be available before attaching it to your cluster. You can use the AWS Management Console or the AWS CLI `describe-db-cluster-parameters` operation to verify that your cluster parameter group has been modified. For more information, see [Describing cluster parameter groups](cluster_parameter_groups-describe.md).

------
#### [ Using the AWS Management Console ]

Follow these steps to modify a custom Amazon DocumentDB parameter group. You can't modify a `default` parameter group. If you want to modify a value in the `default` parameter group, you can [copy the default cluster parameter group](https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-copy.html), modify it, and then apply the modified parameter group to your cluster. For more information about applying parameter groups to your cluster, see [Modifying an Amazon DocumentDB cluster](db-cluster-modify.md).

**To modify a custom cluster parameter group**

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

1. In the navigation pane on the left side of the console, choose **Parameter groups**. In the list of parameter groups, choose the name of the parameter group that you want to modify.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. For each parameter in the parameter group that you want to modify, do the following:

   1. Locate the parameter that you want to modify, and verify that it is modifiable by checking if it is listed as `true` under the **Modifiable** column.

   1. If it is modifiable, select the parameter and choose **Edit** from the top right of the console page.

   1. In the **Modify `<parameter-name>`** dialog box, make the changes that you want. Then choose **Modify cluster parameter**, or choose **Cancel** to discard the changes.

------
#### [ Using the AWS CLI ]

You can modify the `ParameterValue`, `Description`, or `ApplyMethod` of any modifiable parameter in a custom Amazon DocumentDB cluster parameter group using the AWS CLI. You can't make modifications directly to a default cluster parameter group.

To modify a custom cluster parameter group's parameters, use the `modify-db-cluster-parameter-group` operation with the following parameters.
+ **--db-cluster-parameter-group-name** — Required. The name of the cluster parameter group that you are modifying.
+ **--parameters** — Required. The parameters that you are modifying. For a list of the parameters that apply to all instances in an Amazon DocumentDB cluster, see the [Amazon DocumentDB cluster parameters reference](cluster_parameter_groups-list_of_parameters.md). Each parameter entry must include the following:
  + **ParameterName** — The name of the parameter that you are modifying.
  + **ParameterValue** — The new value for this parameter.
  + **ApplyMethod** — How you want changes to this parameter applied. Permitted values are `immediate` and `pending-reboot`.
**Note**  
Parameters with the `ApplyType` of `static` must have an `ApplyMethod` of `pending-reboot`.

**Example - Modifying a parameter's value**  
In this example, you list the parameter values of `sample-parameter-group` and modify the `tls` parameter. Then, after waiting 5 minutes, you again list the parameter values of `sample-parameter-group` to see the changed parameter values.  

1. List the parameters and their values of `sample-parameter-group`.

   For Linux, macOS, or Unix:

   ```
   aws docdb describe-db-cluster-parameters \
          --db-cluster-parameter-group-name sample-parameter-group
   ```

   For Windows:

   ```
   aws docdb describe-db-cluster-parameters ^
          --db-cluster-parameter-group-name sample-parameter-group
   ```

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

   ```
   {
          "Parameters": [
              {
                  "Source": "system",
                  "ApplyType": "static",
                  "AllowedValues": "disabled,enabled",
                  "ParameterValue": "enabled",
                  "ApplyMethod": "pending-reboot",
                  "DataType": "string",
                  "ParameterName": "tls",
                  "IsModifiable": true,
                  "Description": "Config to enable/disable TLS"
              },
              {
                  "Source": "user",
                  "ApplyType": "dynamic",
                  "AllowedValues": "disabled,enabled",
                  "ParameterValue": "enabled",
                  "ApplyMethod": "pending-reboot",
                  "DataType": "string",
                  "ParameterName": "ttl_monitor",
                  "IsModifiable": true,
                  "Description": "Enables TTL Monitoring"
              }
          ]
   }
   ```

1. Modify the `tls` parameter so that its value is `disabled` . 

   You can't modify the `ApplyMethod` because the `ApplyType` is `static`. 

   For Linux, macOS, or Unix:

   ```
   aws docdb modify-db-cluster-parameter-group \
          --db-cluster-parameter-group-name sample-parameter-group \
          --parameters "ParameterName"=tls,"ParameterValue"=disabled,"ApplyMethod"=pending-reboot
   ```

   For Windows:

   ```
   aws docdb modify-db-cluster-parameter-group ^
          --db-cluster-parameter-group-name sample-parameter-group ^
          --parameters "ParameterName"=tls,"ParameterValue"=disabled,"ApplyMethod"=pending-reboot
   ```

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

   ```
   {
          "DBClusterParameterGroupName": "sample-parameter-group"
      }
   ```

1. Wait at least 5 minutes.

1. List the parameter values of `sample-parameter-group` to verify that the `tls` parameter was modified.

   For Linux, macOS, or Unix:

   ```
   aws docdb describe-db-cluster-parameters \
          --db-cluster-parameter-group-name sample-parameter-group
   ```

   For Windows:

   ```
   aws docdb describe-db-cluster-parameters ^
          --db-cluster-parameter-group-name sample-parameter-group
   ```

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

   ```
   {
          "Parameters": [
              {
                  "ParameterValue": "false",
                  "ParameterName": "enable_audit_logs",
                  "ApplyType": "dynamic",
                  "DataType": "string",
                  "Description": "Enables auditing on cluster.",
                  "AllowedValues": "true,false",
                  "Source": "system",
                  "IsModifiable": true,
                  "ApplyMethod": "pending-reboot"
              },
              {
                  "ParameterValue": "disabled",
                  "ParameterName": "tls",
                  "ApplyType": "static",
                  "DataType": "string",
                  "Description": "Config to enable/disable TLS",
                  "AllowedValues": "disabled,enabled",
                  "Source": "system",
                  "IsModifiable": true,
                  "ApplyMethod": "pending-reboot"
              }
          ]
   }
   ```

------

# Modifying Amazon DocumentDB clusters to use custom cluster parameter groups
<a name="cluster_parameter_groups-modify_clusters"></a>

When you create an Amazon DocumentDB cluster, a `default.docdb4.0` parameter group is automatically created for that cluster. You can't modify the `default` cluster parameter group. Instead, you can modify your Amazon DocumentDB cluster to associate a new customized parameter group with it. 

This section explains how to modify an existing Amazon DocumentDB cluster to use a custom cluster parameter group using the AWS Management Console and the AWS Command Line Interface (AWS CLI). 

------
#### [ Using the AWS Management Console ]

**To modify an Amazon DocumentDB cluster to use a new, non-default cluster parameter group**

1. Before you begin, make sure you have created an Amazon DocumentDB cluster and a cluster parameter group. See [Creating an Amazon DocumentDB cluster](db-cluster-create.md) and [Creating Amazon DocumentDB cluster parameter groups](cluster_parameter_groups-create.md) for further instructions.

1. After creating your cluster parameter group, open the Amazon DocumentDB console at [https://console.aws.amazon.com/docdb](https://console.aws.amazon.com/docdb). In the navigation pane, choose **Clusters** to add your new parameter group to a cluster.

1. Choose the cluster that you want to associate your parameter group with. Choose **Actions**, and then choose **Modify** to modify your cluster.

1. Under **Cluster options**, choose the new parameter group that you want to associate your cluster with.

1. Choose **Continue** to view a summary of your modifications.

1. After verifying your changes, you can apply them immediately or during the next maintenance window under **Scheduling of modifications**.

1. Choose **Modify cluster** to update your cluster with your new parameter group.

------
#### [ Using the AWS CLI ]

Before you begin, make sure that you have created an Amazon DocumentDB cluster and a cluster parameter group. You can [create an Amazon DocumentDB cluster](https://docs.aws.amazon.com//documentdb/latest/developerguide/db-cluster-create.html) using the AWS CLI `create-db-cluster` operation. You can [create a cluster parameter group](https://docs.aws.amazon.com//documentdb/latest/developerguide/cluster_parameter_groups-create.html) using the AWS CLI `create-db-cluster-parameter-group` operation.

To add your new cluster parameter group to your cluster, use the AWS CLI `modify-db-cluster` operation with the following parameters.
+ **--db-cluster-identifier** — The name of your cluster (for example, `sample-cluster`).
+ **--db-cluster-parameter-group-name** — The name of the parameter group that you want to associate your cluster with (for example, `sample-parameter-group`).

**Example**  

```
aws docdb modify-db-cluster \
    --db-cluster-identifier sample-cluster \
    --db-cluster-parameter-group-name sample-parameter-group
```
Output from this operation looks something like the following (JSON format).  

```
"DBCluster": {
    "AvailabilityZones": [
            "us-west-2c",
            "us-west-2b",
            "us-west-2a"
    ],
    "BackupRetentionPeriod": 1,
    "DBClusterIdentifier": "sample-cluster",
    "DBClusterParameterGroup": "sample-parameter-group",
    "DBSubnetGroup": "default",
   ...
}
```

------

# Copying Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-copy"></a>

You can make a copy of a cluster parameter group in Amazon DocumentDB using the AWS Management Console or the AWS Command Line Interface (AWS CLI).

------
#### [ Using the AWS Management Console ]

The following procedure guides you through making a new cluster parameter group by making a copy of an existing cluster parameter group.

**To copy a cluster parameter group**

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

1. In the navigation pane, choose **Parameter groups**.

1. In the **Cluster parameter groups** pane, choose the name of the cluster parameter group that you want to copy.

1. Choose **Actions**, and then choose **Copy** to copy that parameter group.

1. Under **Copy options**, enter a name and description for the new cluster parameter group. Then choose **Copy** to save your changes.

------
#### [ Using the AWS CLI ]

To make a copy of a cluster parameter group, use the `copy-db-cluster-parameter-group` operation with the following parameters.
+ **--source-db-cluster-parameter-group-identifier** — Required. The name or Amazon Resource Name (ARN) of the cluster parameter group that you want to make a copy of.

  If the source and target cluster parameter groups are in the same AWS Region, the identifier can be either a name or an ARN.

  If the source and target cluster parameter groups are in different AWS Regions, the identifier must be an ARN.
+ **--target-db-cluster-parameter-group-identifier** — Required. The name or ARN of the cluster parameter group copy.

  Constraints:
  + Cannot be null, empty, or blank.
  + Must contain 1–255 letters, numbers, or hyphens.
  + First character must be a letter.
  + Cannot end with a hyphen or contain two consecutive hyphens.
+ **--target-db-cluster-parameter-group-description** — Required. A user-supplied description for the cluster parameter group copy.

**Example**  
The following code makes a copy of `sample-parameter-group`, naming the copy `sample-parameter-group-copy`.  
For Linux, macOS, or Unix:  

```
aws docdb copy-db-cluster-parameter-group \
    --source-db-cluster-parameter-group-identifier sample-parameter-group \
    --target-db-cluster-parameter-group-identifier sample-parameter-group-copy \
    --target-db-cluster-parameter-group-description "Copy of sample-parameter-group"
```
For Windows:  

```
aws docdb copy-db-cluster-parameter-group ^
    --source-db-cluster-parameter-group-identifier sample-parameter-group ^
    --target-db-cluster-parameter-group-identifier sample-parameter-group-copy ^
    --target-db-cluster-parameter-group-description "Copy of sample-parameter-group"
```
Output from this operation looks something like the following (JSON format).  

```
{
    "DBClusterParameterGroup": {
        "DBClusterParameterGroupArn": "arn:aws:rds:us-east-1:123456789012:cluster-pg:sample-parameter-group-copy",
        "DBClusterParameterGroupName": "sample-parameter-group-copy",
        "DBParameterGroupFamily": "docdb4.0",
        "Description": "Copy of sample-parameter-group"
    }
}
```

------

# Resetting Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-reset"></a>

You can reset some or all of an Amazon DocumentDB cluster parameter group's parameter values to their default values by using the AWS Management Console or the AWS Command Line Interface (AWS CLI) to reset the cluster parameter group.

------
#### [ Using the AWS Management Console ]

Follow these steps to reset some or all of a cluster parameter group's parameter values to their default values.

**To reset a cluster parameter group's parameter values**

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

1. In the navigation pane on the left side of the console, choose **Parameter groups**.

1. In the **Cluster parameter groups** pane, choose the name of the cluster parameter group that you want to reset.

1. Choose **Actions**, and then choose **Reset** to reset that parameter group.

1. On the resulting **Cluster parameter group reset confirmation** page, confirm that you want to reset all cluster parameters for that parameter group to their defaults. Then choose **Reset** to reset your parameter group. You can also choose **Cancel** to discard your changes.

------
#### [ Using the AWS CLI ]

To reset some or all of a cluster parameter group's parameter values to their default values, use the `reset-db-cluster-parameter-group` operation with the following parameters.
+ **--db-cluster-parameter-group-name** — Required. The name of the cluster parameter group to reset.
+ **--parameters** — Optional. A list of `ParameterName` and `ApplyMethod` in the cluster parameter group to reset to their default values. Static parameters must be set to `pending-reboot` to take effect on the next instance restart or `reboot-db-instance` request. You must call `reboot-db-instance` for every instance in your cluster that you want the updated static parameter to apply to.

  This parameter and `--reset-all-parameters` are mutually exclusive: you can use either one but not both.
+ **--reset-all-parameters** or **--no-reset-all-parameters** — Optional. Specifies whether to reset all parameters (`--reset-all-parameters` or only some of the parameters (`--no-reset-all-parameters`) to their default values. The `--reset-all-parameters` parameter and `--parameters` are mutually exclusive: you can use either one but not both.

  When you reset the entire group, dynamic parameters are updated immediately. Static parameters are set to `pending-reboot` to take effect on the next instance restart or `reboot-db-instance` request. You must call `reboot-db-instance` for every instance in your cluster that you want the updated static parameter applied to.

**Example**  
**Example 1: Resetting all parameters to their default values**  
The following code resets all parameters in the cluster parameter group `sample-parameter-group` their default values.
For Linux, macOS, or Unix:  

```
aws docdb reset-db-cluster-parameter-group \
       --db-cluster-parameter-group-name sample-parameter-group \
       --reset-all-parameters
```
For Windows:  

```
aws docdb reset-db-cluster-parameter-group ^
       --db-cluster-parameter-group-name sample-parameter-group ^
       --reset-all-parameters
```
**Example 2: Resetting specified parameters to their default values**  
The following code resets the `tls` parameter in the cluster parameter group `sample-parameter-group` to its default value.
For Linux, macOS, or Unix:  

```
aws docdb reset-db-cluster-parameter-group \
       --db-cluster-parameter-group-name sample-parameter-group \
       --no-reset-all-parameters \
       --parameters ParameterName=tls,ApplyMethod=pending-reboot
```
For Windows:  

```
aws docdb reset-db-cluster-parameter-group ^
       --db-cluster-parameter-group-name sample-parameter-group ^
       --no-reset-all-parameters ^
       --parameters ParameterName=tls,ApplyMethod=pending-reboot
```
Output from this operation looks something like the following (JSON format).  

```
{
       "DBClusterParameterGroupName": "sample-parameter-group"
   }
```
**Rebooting a cluster instance**  
Before a static parameter's value is changed, the cluster instance must be rebooted. Reboot each instance in your cluster that you want the updated static parameter to apply to.
For Linux, macOS, or Unix:  

```
aws docdb reboot-db-instance \
       --db-instance-identifier sample-cluster-instance
```
For Windows:  

```
aws docdb reboot-db-instance ^
       --db-instance-identifier sample-cluster-instance
```

------

# Deleting Amazon DocumentDB cluster parameter groups
<a name="cluster_parameter_groups-delete"></a>

You can delete a custom Amazon DocumentDB cluster parameter group using the AWS Management Console or the AWS Command Line Interface (AWS CLI). You can't delete the `default.docdb4.0` cluster parameter group.

------
#### [ Using the AWS Management Console ]

**To delete a cluster parameter group**

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

1. In the navigation pane, choose **Parameter groups**.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. In the **Parameter groups** pane, choose the radio button to the left of the cluster parameter group that you want to delete.

1. Choose **Actions**, and then choose **Delete**.

1. In the **Delete** confirmation pane, choose **Delete** to delete the cluster parameter group. To keep the cluster parameter group, choose **Cancel**.

------
#### [ Using the AWS CLI ]

To delete a cluster parameter group, use the `delete-db-cluster-parameter-group` operation with the following parameter.
+ **--db-cluster-parameter-group-name** — Required. The name of the cluster parameter group to delete. This must be an existing cluster parameter group. *You cannot delete the `default.docdb4.0` cluster parameter group. *

**Example - Deleting a cluster parameter group**  
The following example walks you through the three steps for deleting a cluster parameter group:  

1. Finding the name of the cluster parameter group that you want to delete.

1. Deleting the specified cluster parameter group.

1. Verifying that the cluster parameter group was deleted.
**1. Find the name of the cluster parameter group that you want to delete.**  
The following code lists the names of all cluster parameter groups.
For Linux, macOS, or Unix:  

```
aws docdb describe-db-cluster-parameter-groups \
       --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'
```
For Windows:  

```
aws docdb describe-db-cluster-parameter-groups ^
       --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'
```
The output of the preceding operation is a list the names of cluster parameter groups similar to the following (JSON format).  

```
[
       [
           "default.docdb4.0"
       ],
       [
           "sample-parameter-group"
       ],
       [
           "sample-parameter-group-copy"
       ]
   ]
```
**2. Delete a specific cluster parameter group.**  
The following code deletes the cluster parameter group `sample-parameter-group-copy`.
For Linux, macOS, or Unix:  

```
aws docdb delete-db-cluster-parameter-group \
       --db-cluster-parameter-group-name sample-parameter-group-copy
```
For Windows:  

```
aws docdb delete-db-cluster-parameter-group ^
       --db-cluster-parameter-group-name sample-parameter-group-copy
```
There is no output from this operation.  
**3. Verify that the specified cluster parameter group was deleted.**  
The following code lists the names of all remaining cluster parameter groups.
For Linux, macOS, or Unix:  

```
aws docdb describe-db-cluster-parameter-groups \
       --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'
```
For Windows:  

```
aws docdb describe-db-cluster-parameter-groups ^
       --query 'DBClusterParameterGroups[*].[DBClusterParameterGroupName]'
```
The output of the preceding operation is a list of cluster parameter groups similar to the following (JSON format). The cluster parameter group that you just deleted should not be in the list.  
Output from this operation looks something like the following (JSON format).  

```
[
       [
           "default.docdb4.0"
       ],
       [
           "sample-parameter-group"
       ]
   ]
```

------

# Amazon DocumentDB cluster parameters reference
<a name="cluster_parameter_groups-list_of_parameters"></a>

When you change a dynamic parameter and save the cluster parameter group, the change is applied immediately regardless of the *Apply immediately* setting. When you change a static parameter and save the cluster parameter group, the parameter change takes effect after you manually reboot the instance. You can reboot an instance using the Amazon DocumentDB console or by explicitly calling `reboot-db-instance`.

The following table shows the parameters that apply to all instances in an Amazon DocumentDB cluster. 


**Amazon DocumentDB cluster-level parameters**  

| Parameter | Default Value | Valid Values | Modifiable | Apply Type | Data Type | Description | 
| --- | --- | --- | --- | --- | --- | --- | 
| audit\$1logs | disabled | enabled, disabled, ddl, dml\$1read, dml\$1write, all, none | Yes | Dynamic | String | Defines whether Amazon CloudWatch audit logs are enabled. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| change\$1stream\$1log\$1retention\$1duration | 10800 | 3600-604800 | Yes | Dynamic | Integer | Defines the duration of time (in seconds) that the change stream log is retained and can be consumed.  | 
| default\$1collection\$1compression | disabled | enabled, disabled (Amazon DocumentDB 5.0) / zstd, lz4, none (Amazon DocumentDB8.0) | Yes | Dynamic | String | Defines the default compression setting for new collections in a cluster [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| profiler | disabled | enabled, disabled | Yes | Dynamic | String | Enables profiling for slow operations. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| profiler\$1sampling\$1rate | 1.0 | 0.0-1.0 | Yes | Dynamic | Float | Defines the sampling rate for logged operations. | 
| profiler\$1threshold\$1ms | 100 | 50-2147483646 | Yes | Dynamic | Integer | Defines the threshold for profiler. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| planner\$1version | 3.0 | 1.0, 2.0, 3.0 | Yes | Dynamic | Float | Defines the query planner version to use for queries.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| tls | enabled | enabled, disabled, fips-140-3, tls1.2\$1, tls1.3\$1 | Yes | Static | String | Defines whether Transport Layer Security (TLS) connections are required. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 
| ttl\$1monitor | enabled | enabled, disabled | Yes | Dynamic | String | Defines whether Time to Live (TTL) monitoring is enabled for the cluster. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/cluster_parameter_groups-list_of_parameters.html) | 

# Modifying Amazon DocumentDB cluster parameters
<a name="cluster_parameter_groups-parameters"></a>

In Amazon DocumentDB, *cluster parameter groups* consist of *parameters* that apply to all of the instances that you create in the cluster. For custom cluster parameter groups, you can modify a parameter value at any time or reset all the parameter values to their defaults for parameter groups that you create. This section describes how to view the parameters that make up an Amazon DocumentDB cluster parameter group and their values, and how you can change or update these values.

Parameters can be *dynamic* or *static*. When you change a dynamic parameter and save the cluster parameter group, the change is applied immediately regardless of the `Apply Immediately` setting. When you change a static parameter and save the cluster parameter group, the parameter change takes effect only after you manually reboot the instances.

## Viewing an Amazon DocumentDB cluster parameter group's parameters
<a name="cluster_parameter_groups-describe_details_parameters"></a>

You can see an Amazon DocumentDB cluster's parameters and their values using the AWS Management Console or AWS CLI.

------
#### [ Using the AWS Management Console ]

**To view the details of a cluster parameter group**

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

1. In the navigation pane, choose **Parameter groups**.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. In the **Parameter groups** pane, choose the name of the cluster parameter group that you want to see the details of.

1. The resulting page shows the following values for each parameter: the parameter's name, current value, allowed values, whether the parameter is modifiable, apply type, data type, and description.  
![\[Screenshot: Parameter names and values.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-determine-parameter-value.png)

------
#### [ Using the AWS CLI ]

To see a cluster's parameter group's parameters and their values, use the `describe-db-cluster-parameters` operation with the following parameters.
+ **--db-cluster-parameter-group-name** — Required. The name of the cluster parameter group for which you want a detailed parameter list.
+ **--source** — Optional. If supplied, returns only parameters for a specific source. Parameter sources can be `engine-default`, `system`, or `user`.

**Example**  
The following code lists the parameters and their values for the `custom3-6-param-grp` parameter group. For more information about the parameter group, omit the `--query` line. For information about all parameter groups, omit the `--db-cluster-parameter-group-name` line.  
For Linux, macOS, or Unix:  

```
aws docdb describe-db-cluster-parameters \
   --db-cluster-parameter-group-name custom3-6-param-grp \
   --query 'Parameters[*].[ParameterName,ParameterValue]'
```
For Windows:  

```
aws docdb describe-db-cluster-parameters ^
   --db-cluster-parameter-group-name custom3-6-param-grp ^
   --query 'Parameters[*].[ParameterName,ParameterValue]'
```
Output from this operation looks something like the following (JSON format).  

```
[
    [
        "audit_logs",
        "disabled"
    ],
    [
        "tls",
        "enabled"
    ],
    [
        "ttl_monitor",
        "enabled"
    ]
]
```

------

## Modifying an Amazon DocumentDB cluster parameter group's parameters
<a name="cluster_parameter_groups-modify_parameters"></a>

You can modify a parameter group's parameters using the AWS Management Console or AWS CLI.

------
#### [ Using the AWS Management Console ]

**To update the parameters of a cluster parameter group**

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

1. In the navigation pane, choose **Parameter groups**.
**Tip**  
If you don't see the navigation pane on the left side of your screen, choose the menu icon (![\[Hamburger menu icon with three horizontal lines.\]](http://docs.aws.amazon.com/documentdb/latest/developerguide/images/docdb-menu-icon.png)) in the upper-left corner of the page.

1. In the **Parameter groups** pane, choose the cluster parameter group that you want to update the parameters of.

1. The resulting page shows the parameters and their corresponding details for this cluster parameter group. Select a parameter to update.

1. On the top right of the page, choose **Edit** to change the value of the parameter. For more information about the types of cluster parameters, see [Amazon DocumentDB cluster parameters reference](cluster_parameter_groups-list_of_parameters.md).

1. Make your change, and then choose **Modify cluster parameter** to save the changes. To discard your changes, choose **Cancel**.

------
#### [ Using the AWS CLI ]

To modify a cluster parameter group's parameters, use the `modify-db-cluster-parameter-group` operation with the following parameters:
+ **--db-cluster-parameter-group-name** — Required. The name of the cluster parameter group that you are modifying.
+ **--parameters** — Required. The parameter or parameters that you are modifying. Each parameter entry must include the following:
  + **ParameterName** — The name of the parameter that you are modifying.
  + **ParameterValue** — The new value for this parameter.
  + **ApplyMethod** — How you want changes to this parameter applied. Permitted values are `immediate` and `pending-reboot`.
**Note**  
Parameters with the `ApplyType` of `static` must have an `ApplyMethod` of `pending-reboot`.

**To change the values of a cluster parameter group's parameters (AWS CLI)**

The following example changes the `tls` parameter.

1. **List the parameters and their values of `sample-parameter-group`**

   For Linux, macOS, or Unix:

   ```
   aws docdb describe-db-cluster-parameters \
       --db-cluster-parameter-group-name sample-parameter-group
   ```

   For Windows:

   ```
   aws docdb describe-db-cluster-parameters ^
       --db-cluster-parameter-group-name sample-parameter-group
   ```

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

   ```
   {
       "Parameters": [
           {
               "Source": "system",
               "ApplyType": "static",
               "AllowedValues": "disabled,enabled",
               "ParameterValue": "enabled",
               "ApplyMethod": "pending-reboot",
               "DataType": "string",
               "ParameterName": "tls",
               "IsModifiable": true,
               "Description": "Config to enable/disable TLS"
           },
           {
               "Source": "user",
               "ApplyType": "dynamic",
               "AllowedValues": "disabled,enabled",
               "ParameterValue": "enabled",
               "ApplyMethod": "pending-reboot",
               "DataType": "string",
               "ParameterName": "ttl_monitor",
               "IsModifiable": true,
               "Description": "Enables TTL Monitoring"
           }
       ]
   }
   ```

1. **Modify the `tls` parameter so that its value is `disabled`**. You can't modify the `ApplyMethod` because the `ApplyType` is `static`.

   For Linux, macOS, or Unix:

   ```
   aws docdb modify-db-cluster-parameter-group \
       --db-cluster-parameter-group-name sample-parameter-group \
       --parameters "ParameterName"=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"
   ```

   For Windows:

   ```
   aws docdb modify-db-cluster-parameter-group ^
       --db-cluster-parameter-group-name sample-parameter-group ^
       --parameters "ParameterName=tls,ParameterValue=disabled,ApplyMethod=pending-reboot"
   ```

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

   ```
   {
       "DBClusterParameterGroupName": "sample-parameter-group"
   }
   ```

1. **Wait at least 5 minutes.**

1. **List the parameter values of `sample-parameter-group`.**

   For Linux, macOS, or Unix:

   ```
   aws docdb describe-db-cluster-parameters \
       --db-cluster-parameter-group-name sample-parameter-group
   ```

   For Windows:

   ```
   aws docdb describe-db-cluster-parameters ^
       --db-cluster-parameter-group-name sample-parameter-group
   ```

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

   ```
   {
       "Parameters": [
           {
               "ParameterName": "audit_logs",
               "ParameterValue": "disabled",
               "Description": "Enables auditing on cluster.",
               "Source": "system",
               "ApplyType": "dynamic",
               "DataType": "string",
               "AllowedValues": "enabled,disabled",
               "IsModifiable": true,
               "ApplyMethod": "pending-reboot"
           },
           {
               "ParameterName": "tls",
               "ParameterValue": "disabled",
               "Description": "Config to enable/disable TLS",
               "Source": "user",
               "ApplyType": "static",
               "DataType": "string",
               "AllowedValues": "disabled,enabled",
               "IsModifiable": true,
               "ApplyMethod": "pending-reboot"
           }
       ]
   }
   ```

------