clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview

Name	`clusters`
Type	Resource
Id	`aws.dsql.clusters`

Fields

The following fields are returned by SELECT queries:

get_cluster
list_clusters

Name	Datatype	Description
`arn`	`string`	The Amazon Resource Name of the cluster. (pattern: <code>arn:aws(-[^:]+)?:dsql:[a-z0-9-]{1,20}:[0-9]{12}:cluster/[a-z0-9]{26}</code>)
`creation_time`	`string (date-time)`	The time of when the cluster was created.
`deletion_protection_enabled`	`boolean`	Indicates whether deletion protection is enabled for a cluster.
`encryption_details`	`object`	The current encryption configuration details for the cluster.
`endpoint`	`string`	The connection endpoint for the cluster. (pattern: <code>[a-zA-Z0-9.-]+</code>)
`identifier`	`string`	The ID of the cluster. (pattern: <code>[a-z0-9]{26}</code>)
`multi_region_properties`	`object`	Defines the structure for multi-Region cluster configurations, containing the witness region and linked cluster settings.
`status`	`string`	The status of the retrieved cluster. (CREATING, ACTIVE, IDLE, INACTIVE, UPDATING, DELETING, DELETED, FAILED, PENDING_SETUP, PENDING_DELETE)
`tags`	`object`

Name	Datatype	Description
`arn`	`string`	The Amazon Resource Name of the cluster. (pattern: <code>arn:aws(-[^:]+)?:dsql:[a-z0-9-]{1,20}:[0-9]{12}:cluster/[a-z0-9]{26}</code>)
`identifier`	`string`	The ID of the cluster. (pattern: <code>[a-z0-9]{26}</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get_cluster`	`select`	`identifier`, `region`		Retrieves information about a cluster.
`list_clusters`	`select`	`region`	`max-results`, `next-token`	Retrieves information about a list of clusters.
`create_cluster`	`insert`	`region`		The CreateCluster API allows you to create both single-Region clusters and multi-Region clusters. With the addition of the multiRegionProperties parameter, you can create a cluster with witness Region support and establish peer relationships with clusters in other Regions during creation. Creating multi-Region clusters requires additional IAM permissions beyond those needed for single-Region clusters, as detailed in the Required permissions section below. Required permissions dsql:CreateCluster Required to create a cluster. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:TagResource Permission to add tags to a resource. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:PutMultiRegionProperties Permission to configure multi-Region properties for a cluster. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:AddPeerCluster When specifying multiRegionProperties.clusters, permission to add peer clusters. Resources: Local cluster: arn:aws:dsql:region:account-id:cluster/* Each peer cluster: exact ARN of each specified peer cluster dsql:PutWitnessRegion When specifying multiRegionProperties.witnessRegion, permission to set a witness Region. This permission is checked both in the cluster Region and in the witness Region. Resources: arn:aws:dsql:region:account-id:cluster/* Condition Keys: dsql:WitnessRegion (matching the specified witness region) The witness Region specified in multiRegionProperties.witnessRegion cannot be the same as the cluster's Region.
`update_cluster`	`update`	`identifier`, `region`		The UpdateCluster API allows you to modify both single-Region and multi-Region cluster configurations. With the multiRegionProperties parameter, you can add or modify witness Region support and manage peer relationships with clusters in other Regions. Note that updating multi-Region clusters requires additional IAM permissions beyond those needed for standard cluster updates, as detailed in the Permissions section. Required permissions dsql:UpdateCluster Permission to update a DSQL cluster. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:PutMultiRegionProperties Permission to configure multi-Region properties for a cluster. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:GetCluster Permission to retrieve cluster information. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:AddPeerCluster Permission to add peer clusters. Resources: Local cluster: arn:aws:dsql:region:account-id:cluster/cluster-id Each peer cluster: exact ARN of each specified peer cluster dsql:RemovePeerCluster Permission to remove peer clusters. When you list peer clusters in multiRegionProperties.clusters, you need this permission for each current peer cluster that your list omits. Resources: Each removed peer cluster: exact ARN of each removed peer cluster, in its own Region dsql:PutWitnessRegion Permission to set a witness Region. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id Condition Keys: dsql:WitnessRegion (matching the specified witness Region) This permission is checked both in the cluster Region and in the witness Region. The witness Region specified in multiRegionProperties.witnessRegion cannot be the same as the cluster's Region. When you list peer clusters in multiRegionProperties.clusters, you need dsql:AddPeerCluster for every peer cluster in your request. You need dsql:RemovePeerCluster only for the peer clusters that the update removes.
`delete_cluster`	`delete`	`identifier`, `region`	`client-token`	Deletes a cluster in Amazon Aurora DSQL.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`identifier`	`string`	The ID of the cluster to delete.
`region`	`string`	AWS region (default: us-east-1)
`client-token`	`string`	A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Idempotency ensures that an API request completes only once. With an idempotent request, if the original request completes successfully. The subsequent retries with the same client token return the result from the original successful request and they have no additional effect. If you don't specify a client token, the Amazon Web Services SDK automatically generates one.
`max-results`	`integer`	An optional parameter that specifies the maximum number of results to return. You can use nextToken to display the next page of results.
`next-token`	`string`	If your initial ListClusters operation returns a nextToken, you can include the returned nextToken in following ListClusters operations, which returns results in the next page.

`SELECT` examples

get_cluster
list_clusters

Retrieves information about a cluster.

SELECT
arn,
creation_time,
deletion_protection_enabled,
encryption_details,
endpoint,
identifier,
multi_region_properties,
status,
tags
FROM aws.dsql.clusters
WHERE identifier = '{{ identifier }}' -- required
AND region = '{{ region }}' -- required
;

Retrieves information about a list of clusters.

SELECT
arn,
identifier
FROM aws.dsql.clusters
WHERE region = '{{ region }}' -- required
AND `max-results` = '{{ max-results }}'
AND `next-token` = '{{ next-token }}'
;

`INSERT` examples

create_cluster
Manifest

The CreateCluster API allows you to create both single-Region clusters and multi-Region clusters. With the addition of the multiRegionProperties parameter, you can create a cluster with witness Region support and establish peer relationships with clusters in other Regions during creation. Creating multi-Region clusters requires additional IAM permissions beyond those needed for single-Region clusters, as detailed in the Required permissions section below. Required permissions dsql:CreateCluster Required to create a cluster. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:TagResource Permission to add tags to a resource. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:PutMultiRegionProperties Permission to configure multi-Region properties for a cluster. Resources: arn:aws:dsql:region:account-id:cluster/* dsql:AddPeerCluster When specifying multiRegionProperties.clusters, permission to add peer clusters. Resources: Local cluster: arn:aws:dsql:region:account-id:cluster/* Each peer cluster: exact ARN of each specified peer cluster dsql:PutWitnessRegion When specifying multiRegionProperties.witnessRegion, permission to set a witness Region. This permission is checked both in the cluster Region and in the witness Region. Resources: arn:aws:dsql:region:account-id:cluster/* Condition Keys: dsql:WitnessRegion (matching the specified witness region) The witness Region specified in multiRegionProperties.witnessRegion cannot be the same as the cluster's Region.

INSERT INTO aws.dsql.clusters (
deletionProtectionEnabled,
kmsEncryptionKey,
tags,
clientToken,
multiRegionProperties,
policy,
bypassPolicyLockoutSafetyCheck,
region
)
SELECT 
{{ deletionProtectionEnabled }},
'{{ kmsEncryptionKey }}',
'{{ tags }}',
'{{ clientToken }}',
'{{ multiRegionProperties }}',
'{{ policy }}',
{{ bypassPolicyLockoutSafetyCheck }},
'{{ region }}'
RETURNING
arn,
creation_time,
deletion_protection_enabled,
encryption_details,
endpoint,
identifier,
multi_region_properties,
status
;

# Description fields are for documentation purposes
- name: clusters
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the clusters resource.
  - name: deletionProtectionEnabled
    value: {{ deletionProtectionEnabled }}
    description: |
      Indicates whether deletion protection is enabled for a cluster.
  - name: kmsEncryptionKey
    value: "{{ kmsEncryptionKey }}"
  - name: tags
    value: "{{ tags }}"
    description: |
      Map of tags.
  - name: clientToken
    value: "{{ clientToken }}"
    description: |
      Idempotency token so a request is only processed once.
  - name: multiRegionProperties
    description: |
      Defines the structure for multi-Region cluster configurations, containing the witness region and linked cluster settings.
    value:
      witnessRegion: "{{ witnessRegion }}"
      clusters:
        - "{{ clusters }}"
  - name: policy
    value: "{{ policy }}"
    description: |
      A resource-based policy document in JSON format. Length constraints: Minimum length of 1. Maximum length of 20480 characters (approximately 20KB).
  - name: bypassPolicyLockoutSafetyCheck
    value: {{ bypassPolicyLockoutSafetyCheck }}

`UPDATE` examples

update_cluster

The UpdateCluster API allows you to modify both single-Region and multi-Region cluster configurations. With the multiRegionProperties parameter, you can add or modify witness Region support and manage peer relationships with clusters in other Regions. Note that updating multi-Region clusters requires additional IAM permissions beyond those needed for standard cluster updates, as detailed in the Permissions section. Required permissions dsql:UpdateCluster Permission to update a DSQL cluster. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:PutMultiRegionProperties Permission to configure multi-Region properties for a cluster. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:GetCluster Permission to retrieve cluster information. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id dsql:AddPeerCluster Permission to add peer clusters. Resources: Local cluster: arn:aws:dsql:region:account-id:cluster/cluster-id Each peer cluster: exact ARN of each specified peer cluster dsql:RemovePeerCluster Permission to remove peer clusters. When you list peer clusters in multiRegionProperties.clusters, you need this permission for each current peer cluster that your list omits. Resources: Each removed peer cluster: exact ARN of each removed peer cluster, in its own Region dsql:PutWitnessRegion Permission to set a witness Region. Resources: arn:aws:dsql:region:account-id:cluster/cluster-id Condition Keys: dsql:WitnessRegion (matching the specified witness Region) This permission is checked both in the cluster Region and in the witness Region. The witness Region specified in multiRegionProperties.witnessRegion cannot be the same as the cluster's Region. When you list peer clusters in multiRegionProperties.clusters, you need dsql:AddPeerCluster for every peer cluster in your request. You need dsql:RemovePeerCluster only for the peer clusters that the update removes.

UPDATE aws.dsql.clusters
SET 
deletionProtectionEnabled = {{ deletionProtectionEnabled }},
kmsEncryptionKey = '{{ kmsEncryptionKey }}',
clientToken = '{{ clientToken }}',
multiRegionProperties = '{{ multiRegionProperties }}'
WHERE 
identifier = '{{ identifier }}' --required
AND region = '{{ region }}' --required
RETURNING
arn,
creation_time,
identifier,
status;

`DELETE` examples

delete_cluster

Deletes a cluster in Amazon Aurora DSQL.

DELETE FROM aws.dsql.clusters
WHERE identifier = '{{ identifier }}' --required
AND region = '{{ region }}' --required
AND `client-token` = '{{ client-token }}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​