aws-cdk-lib.aws_docdb.DatabaseCluster

class DatabaseCluster (construct)

LanguageType name
.NETAmazon.CDK.AWS.DocDB.DatabaseCluster
Gogithub.com/aws/aws-cdk-go/awscdk/v2/awsdocdb#DatabaseCluster
Javasoftware.amazon.awscdk.services.docdb.DatabaseCluster
Pythonaws_cdk.aws_docdb.DatabaseCluster
TypeScript (source)aws-cdk-lib » aws_docdb » DatabaseCluster

Implements IConstruct, IDependable, IResource, IDatabaseCluster, IConnectable, ISecretAttachmentTarget

Create a clustered database with a given number of instances.

Example

declare const vpc: ec2.Vpc;
const cluster = new docdb.DatabaseCluster(this, 'Database', {
  masterUser: {
    username: 'myuser',
  },
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.MEMORY5, ec2.InstanceSize.LARGE),
  vpcSubnets: {
    subnetType: ec2.SubnetType.PUBLIC,
  },
  vpc,
  deletionProtection: true, // Enable deletion protection.
});

Initializer

new DatabaseCluster(scope: Construct, id: string, props: DatabaseClusterProps)

Parameters

  • scope Construct
  • id string
  • props DatabaseClusterProps

Construct Props

NameTypeDescription
instanceTypeInstanceTypeWhat type of instance to start for the replicas.
masterUserLoginUsername and password for the administrative user.
vpcIVpcWhat subnets to run the DocumentDB instances in.
backup?BackupPropsBackup settings.
cloudWatchLogsRetention?RetentionDaysThe number of days log events are kept in CloudWatch Logs.
cloudWatchLogsRetentionRole?IRoleThe IAM role for the Lambda function associated with the custom resource that sets the retention policy.
dbClusterName?stringAn optional identifier for the cluster.
deletionProtection?booleanSpecifies whether this cluster can be deleted.
enablePerformanceInsights?booleanA value that indicates whether to enable Performance Insights for the instances in the DB Cluster.
engineVersion?stringWhat version of the database to start.
exportAuditLogsToCloudWatch?booleanWhether the audit logs should be exported to CloudWatch.
exportProfilerLogsToCloudWatch?booleanWhether the profiler logs should be exported to CloudWatch.
instanceIdentifierBase?stringBase identifier for instances.
instances?numberNumber of DocDB compute instances.
kmsKey?IKeyThe KMS key for storage encryption.
parameterGroup?IClusterParameterGroupThe DB parameter group to associate with the instance.
port?numberThe port the DocumentDB cluster will listen on.
preferredMaintenanceWindow?stringA weekly time range in which maintenance should preferably execute.
removalPolicy?RemovalPolicyThe removal policy to apply when the cluster and its instances are removed or replaced during a stack update, or when the stack is deleted.
securityGroup?ISecurityGroupSecurity group.
storageEncrypted?booleanWhether to enable storage encryption.
vpcSubnets?SubnetSelectionWhere to place the instances within the VPC.

instanceType

Type: InstanceType

What type of instance to start for the replicas.


masterUser

Type: Login

Username and password for the administrative user.


vpc

Type: IVpc

What subnets to run the DocumentDB instances in.

Must be at least 2 subnets in two different AZs.


backup?

Type: BackupProps (optional, default: Backup retention period for automated backups is 1 day. Backup preferred window is set to a 30-minute window selected at random from an 8-hour block of time for each AWS Region, occurring on a random day of the week.)

Backup settings.

See also: https://docs.aws.amazon.com/documentdb/latest/developerguide/backup-restore.db-cluster-snapshots.html#backup-restore.backup-window


cloudWatchLogsRetention?

Type: RetentionDays (optional, default: logs never expire)

The number of days log events are kept in CloudWatch Logs.

When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to Infinity.


cloudWatchLogsRetentionRole?

Type: IRole (optional, default: a new role is created.)

The IAM role for the Lambda function associated with the custom resource that sets the retention policy.


dbClusterName?

Type: string (optional, default: A name is automatically generated.)

An optional identifier for the cluster.


deletionProtection?

Type: boolean (optional, default: false)

Specifies whether this cluster can be deleted.

If deletionProtection is enabled, the cluster cannot be deleted unless it is modified and deletionProtection is disabled. deletionProtection protects clusters from being accidentally deleted.


enablePerformanceInsights?

Type: boolean (optional, default: false)

A value that indicates whether to enable Performance Insights for the instances in the DB Cluster.


engineVersion?

Type: string (optional, default: The default engine version.)

What version of the database to start.


exportAuditLogsToCloudWatch?

Type: boolean (optional, default: false)

Whether the audit logs should be exported to CloudWatch.

Note that you also have to configure the audit log export in the Cluster's Parameter Group.

See also: https://docs.aws.amazon.com/documentdb/latest/developerguide/event-auditing.html#event-auditing-enabling-auditing


exportProfilerLogsToCloudWatch?

Type: boolean (optional, default: false)

Whether the profiler logs should be exported to CloudWatch.

Note that you also have to configure the profiler log export in the Cluster's Parameter Group.

See also: https://docs.aws.amazon.com/documentdb/latest/developerguide/profiling.html#profiling.enable-profiling


instanceIdentifierBase?

Type: string (optional, default: dbClusterName is used with the word "Instance" appended. If dbClusterName is not provided, the identifier is automatically generated.)

Base identifier for instances.

Every replica is named by appending the replica number to this string, 1-based.


instances?

Type: number (optional, default: 1)

Number of DocDB compute instances.


kmsKey?

Type: IKey (optional, default: default master key.)

The KMS key for storage encryption.


parameterGroup?

Type: IClusterParameterGroup (optional, default: no parameter group)

The DB parameter group to associate with the instance.


port?

Type: number (optional, default: DatabaseCluster.DEFAULT_PORT)

The port the DocumentDB cluster will listen on.


preferredMaintenanceWindow?

Type: string (optional, default: 30-minute window selected at random from an 8-hour block of time for each AWS Region, occurring on a random day of the week.)

A weekly time range in which maintenance should preferably execute.

Must be at least 30 minutes long.

Example: 'tue:04:17-tue:04:47'

See also: https://docs.aws.amazon.com/documentdb/latest/developerguide/db-instance-maintain.html#maintenance-window


removalPolicy?

Type: RemovalPolicy (optional, default: Retain cluster.)

The removal policy to apply when the cluster and its instances are removed or replaced during a stack update, or when the stack is deleted.

This removal policy also applies to the implicit security group created for the cluster if one is not supplied as a parameter.


securityGroup?

Type: ISecurityGroup (optional, default: a new security group is created.)

Security group.


storageEncrypted?

Type: boolean (optional, default: true)

Whether to enable storage encryption.


vpcSubnets?

Type: SubnetSelection (optional, default: private subnets)

Where to place the instances within the VPC.

Properties

NameTypeDescription
clusterEndpointEndpointThe endpoint to use for read/write operations.
clusterIdentifierstringIdentifier of the cluster.
clusterReadEndpointEndpointEndpoint to use for load-balanced read-only operations.
clusterResourceIdentifierstringThe resource id for the cluster;
connectionsConnectionsThe connections object to implement IConnectable.
envResourceEnvironmentThe environment this resource belongs to.
instanceEndpointsEndpoint[]Endpoints which address each individual replica.
instanceIdentifiersstring[]Identifiers of the replicas.
nodeNodeThe tree node.
securityGroupIdstringSecurity group identifier of this database.
stackStackThe stack in which this resource is defined.
secret?ISecretThe secret attached to this cluster.
static DEFAULT_NUM_INSTANCESnumberThe default number of instances in the DocDB cluster if none are specified.
static DEFAULT_PORTnumberThe default port Document DB listens on.

clusterEndpoint

Type: Endpoint

The endpoint to use for read/write operations.


clusterIdentifier

Type: string

Identifier of the cluster.


clusterReadEndpoint

Type: Endpoint

Endpoint to use for load-balanced read-only operations.


clusterResourceIdentifier

Type: string

The resource id for the cluster;

for example: cluster-ABCD1234EFGH5678IJKL90MNOP. The cluster ID uniquely identifies the cluster and is used in things like IAM authentication policies.


connections

Type: Connections

The connections object to implement IConnectable.


env

Type: ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.


instanceEndpoints

Type: Endpoint[]

Endpoints which address each individual replica.


instanceIdentifiers

Type: string[]

Identifiers of the replicas.


node

Type: Node

The tree node.


securityGroupId

Type: string

Security group identifier of this database.


stack

Type: Stack

The stack in which this resource is defined.


secret?

Type: ISecret (optional)

The secret attached to this cluster.


static DEFAULT_NUM_INSTANCES

Type: number

The default number of instances in the DocDB cluster if none are specified.


static DEFAULT_PORT

Type: number

The default port Document DB listens on.

Methods

NameDescription
addRotationMultiUser(id, options)Adds the multi user rotation to this cluster.
addRotationSingleUser(automaticallyAfter?)Adds the single user rotation of the master password to this cluster.
addSecurityGroups(...securityGroups)Adds security groups to this cluster.
applyRemovalPolicy(policy)Apply the given removal policy to this resource.
asSecretAttachmentTarget()Renders the secret attachment target specifications.
toString()Returns a string representation of this construct.
static fromDatabaseClusterAttributes(scope, id, attrs)Import an existing DatabaseCluster from properties.

addRotationMultiUser(id, options)

public addRotationMultiUser(id: string, options: RotationMultiUserOptions): SecretRotation

Parameters

  • id string
  • options RotationMultiUserOptions

Returns

  • SecretRotation

Adds the multi user rotation to this cluster.


addRotationSingleUser(automaticallyAfter?)

public addRotationSingleUser(automaticallyAfter?: Duration): SecretRotation

Parameters

  • automaticallyAfter Duration — Specifies the number of days after the previous rotation before Secrets Manager triggers the next automatic rotation.

Returns

  • SecretRotation

Adds the single user rotation of the master password to this cluster.


addSecurityGroups(...securityGroups)

public addSecurityGroups(...securityGroups: ISecurityGroup[]): void

Parameters

  • securityGroups ISecurityGroup — The security groups to add.

Adds security groups to this cluster.


applyRemovalPolicy(policy)

public applyRemovalPolicy(policy: RemovalPolicy): void

Parameters

  • policy RemovalPolicy

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).


asSecretAttachmentTarget()

public asSecretAttachmentTarget(): SecretAttachmentTargetProps

Returns

  • SecretAttachmentTargetProps

Renders the secret attachment target specifications.


toString()

public toString(): string

Returns

  • string

Returns a string representation of this construct.


static fromDatabaseClusterAttributes(scope, id, attrs)

public static fromDatabaseClusterAttributes(scope: Construct, id: string, attrs: DatabaseClusterAttributes): IDatabaseCluster

Parameters

  • scope Construct
  • id string
  • attrs DatabaseClusterAttributes

Returns

  • IDatabaseCluster

Import an existing DatabaseCluster from properties.