class DatabaseCluster (construct)

Language	Type name
.NET	`Amazon.CDK.AWS.RDS.DatabaseCluster`
Java	`software.amazon.awscdk.services.rds.DatabaseCluster`
Python	`aws_cdk.aws_rds.DatabaseCluster`
TypeScript (source)	`@aws-cdk/aws-rds` » `DatabaseCluster`

Implements IConstruct, 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 rds.DatabaseCluster(this, 'Database', {
  engine: rds.DatabaseClusterEngine.AURORA,
  instanceProps: { vpc },
});

const proxy = new rds.DatabaseProxy(this, 'Proxy', {
  proxyTarget: rds.ProxyTarget.fromCluster(cluster),
  secrets: [cluster.secret!],
  vpc,
});

const role = new iam.Role(this, 'DBProxyRole', { assumedBy: new iam.AccountPrincipal(this.account) });
proxy.grantConnect(role, 'admin'); // Grant the role connection access to the DB Proxy for database user 'admin'.

Initializer

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

Parameters

scope Construct
id string
props DatabaseClusterProps

Construct Props

Name	Type	Description
engine	`IClusterEngine`	What kind of database to start.
instanceProps	`InstanceProps`	Settings for the individual instances that are launched.
backtrackWindow?	`Duration`	The number of seconds to set a cluster's target backtrack window to.
backup?	`BackupProps`	Backup settings.
cloudwatchLogsExports?	`string[]`	The list of log types that need to be enabled for exporting to CloudWatch Logs.
cloudwatchLogsRetention?	`RetentionDays`	The number of days log events are kept in CloudWatch Logs.
cloudwatchLogsRetentionRole?	`IRole`	The IAM role for the Lambda function associated with the custom resource that sets the retention policy.
clusterIdentifier?	`string`	An optional identifier for the cluster.
copyTagsToSnapshot?	`boolean`	Whether to copy tags to the snapshot when a snapshot is created.
credentials?	`Credentials`	Credentials for the administrative user.
defaultDatabaseName?	`string`	Name of a database which is automatically created inside the cluster.
deletionProtection?	`boolean`	Indicates whether the DB cluster should have deletion protection enabled.
iamAuthentication?	`boolean`	Whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts.
instanceIdentifierBase?	`string`	Base identifier for instances.
instances?	`number`	How many replicas/instances to create.
monitoringInterval?	`Duration`	The interval, in seconds, between points when Amazon RDS collects enhanced monitoring metrics for the DB instances.
monitoringRole?	`IRole`	Role that will be used to manage DB instances monitoring.
parameterGroup?	`IParameterGroup`	Additional parameters to pass to the database engine.
parameters?	`{ [string]: string }`	The parameters in the DBClusterParameterGroup to create automatically.
port?	`number`	What port to listen on.
preferredMaintenanceWindow?	`string`	A preferred maintenance window day/time range. Should be specified as a range ddd:hh24:mi-ddd:hh24:mi (24H Clock UTC).
removalPolicy?	`RemovalPolicy`	The removal policy to apply when the cluster and its instances are removed from the stack or replaced during an update.
s3ExportBuckets?	`IBucket[]`	S3 buckets that you want to load data into. This feature is only supported by the Aurora database engine.
s3ExportRole?	`IRole`	Role that will be associated with this DB cluster to enable S3 export.
s3ImportBuckets?	`IBucket[]`	S3 buckets that you want to load data from. This feature is only supported by the Aurora database engine.
s3ImportRole?	`IRole`	Role that will be associated with this DB cluster to enable S3 import.
storageEncrypted?	`boolean`	Whether to enable storage encryption.
storageEncryptionKey?	`IKey`	The KMS key for storage encryption.
subnetGroup?	`ISubnetGroup`	Existing subnet group for the cluster.

engine

Type: IClusterEngine

What kind of database to start.

instanceProps

Type: InstanceProps

Settings for the individual instances that are launched.

backtrackWindow?

Type: Duration (optional, default: 0 seconds (no backtrack))

The number of seconds to set a cluster's target backtrack window to.

This feature is only supported by the Aurora MySQL database engine and cannot be enabled on existing clusters.

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.

cloudwatchLogsExports?

Type: string[] (optional, default: no log exports)

The list of log types that need to be enabled for exporting to CloudWatch Logs.

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.

clusterIdentifier?

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

An optional identifier for the cluster.

copyTagsToSnapshot?

Type: boolean (optional, default: true)

Whether to copy tags to the snapshot when a snapshot is created.

credentials?

Type: Credentials (optional, default: A username of 'admin' (or 'postgres' for PostgreSQL) and SecretsManager-generated password)

Credentials for the administrative user.

defaultDatabaseName?

Type: string (optional, default: Database is not created in cluster.)

Name of a database which is automatically created inside the cluster.

deletionProtection?

Type: boolean (optional, default: true if removalPolicy is RETAIN, false otherwise)

Indicates whether the DB cluster should have deletion protection enabled.

iamAuthentication?

Type: boolean (optional, default: false)

Whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts.

instanceIdentifierBase?

Type: string (optional, default: clusterIdentifier is used with the word "Instance" appended. If clusterIdentifier 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: 2)

How many replicas/instances to create.

Has to be at least 1.

monitoringInterval?

Type: Duration (optional, default: no enhanced monitoring)

The interval, in seconds, between points when Amazon RDS collects enhanced monitoring metrics for the DB instances.

monitoringRole?

Type: IRole (optional, default: A role is automatically created for you)

Role that will be used to manage DB instances monitoring.

parameterGroup?

Type: IParameterGroup (optional, default: No parameter group.)

Additional parameters to pass to the database engine.

parameters?

Type: { [string]: string } (optional, default: None)

The parameters in the DBClusterParameterGroup to create automatically.

You can only specify parameterGroup or parameters but not both. You need to use a versioned engine to auto-generate a DBClusterParameterGroup.

port?

Type: number (optional, default: The default for the engine is used.)

What port to 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 preferred maintenance window day/time range. Should be specified as a range ddd:hh24:mi-ddd:hh24:mi (24H Clock UTC).

Example: 'Sun:23:45-Mon:00:15'

removalPolicy?

Type: RemovalPolicy (optional, default: RemovalPolicy.SNAPSHOT (remove the cluster and instances, but retain a snapshot of the data))

The removal policy to apply when the cluster and its instances are removed from the stack or replaced during an update.

s3ExportBuckets?

Type: IBucket[] (optional, default: None)

S3 buckets that you want to load data into. This feature is only supported by the Aurora database engine.

This property must not be used if s3ExportRole is used.

For MySQL:

s3ExportRole?

Type: IRole (optional, default: New role is created if s3ExportBuckets is set, no role is defined otherwise)

Role that will be associated with this DB cluster to enable S3 export.

This feature is only supported by the Aurora database engine.

This property must not be used if s3ExportBuckets is used.

For MySQL:

s3ImportBuckets?

Type: IBucket[] (optional, default: None)

S3 buckets that you want to load data from. This feature is only supported by the Aurora database engine.

This property must not be used if s3ImportRole is used.

For MySQL:

s3ImportRole?

Type: IRole (optional, default: New role is created if s3ImportBuckets is set, no role is defined otherwise)

Role that will be associated with this DB cluster to enable S3 import.

This feature is only supported by the Aurora database engine.

This property must not be used if s3ImportBuckets is used.

For MySQL:

storageEncrypted?

Type: boolean (optional, default: true if storageEncryptionKey is provided, false otherwise)

Whether to enable storage encryption.

storageEncryptionKey?

Type: IKey (optional, default: if storageEncrypted is true then the default master key, no key otherwise)

The KMS key for storage encryption.

If specified, {@link storageEncrypted} will be set to true.

subnetGroup?

Type: ISubnetGroup (optional, default: a new subnet group will be created.)

Existing subnet group for the cluster.

Properties

Name	Type	Description
clusterEndpoint	`Endpoint`	The endpoint to use for read/write operations.
clusterIdentifier	`string`	Identifier of the cluster.
clusterReadEndpoint	`Endpoint`	Endpoint to use for load-balanced read-only operations.
connections	`Connections`	Access to the network connections.
env	`ResourceEnvironment`	The environment this resource belongs to.
instanceEndpoints	`Endpoint[]`	Endpoints which address each individual replica.
instanceIdentifiers	`string[]`	Identifiers of the replicas.
multiUserRotationApplication	`SecretRotationApplication`	Application for multi user rotation to this cluster.
newCfnProps	`CfnDBClusterProps`
node	`ConstructNode`	The construct tree node associated with this construct.
securityGroups	`ISecurityGroup[]`
singleUserRotationApplication	`SecretRotationApplication`	Application for single user rotation of the master password to this cluster.
stack	`Stack`	The stack in which this resource is defined.
subnetGroup	`ISubnetGroup`
vpc	`IVpc`	The VPC network to place the cluster in.
engine?	`IClusterEngine`	The engine for this Cluster.
secret?	`ISecret`	The secret attached to this cluster.
vpcSubnets?	`SubnetSelection`	The cluster's subnets.

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.

connections

Type: Connections

Access to the network connections.

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.

multiUserRotationApplication

Type: SecretRotationApplication

Application for multi user rotation to this cluster.

newCfnProps

Type: CfnDBClusterProps

node

Type: ConstructNode

The construct tree node associated with this construct.

securityGroups

Type: ISecurityGroup[]

singleUserRotationApplication

Type: SecretRotationApplication

Application for single user rotation of the master password to this cluster.

stack

Type: Stack

The stack in which this resource is defined.

subnetGroup

Type: ISubnetGroup

vpc

Type: IVpc

The VPC network to place the cluster in.

engine?

Type: IClusterEngine (optional)

The engine for this Cluster.

Never undefined.

secret?

Type: ISecret (optional)

The secret attached to this cluster.

vpcSubnets?

Type: SubnetSelection (optional)

The cluster's subnets.

Methods

Name	Description
addProxy(id, options)	Add a new db proxy to this cluster.
addRotationMultiUser(id, options)	Adds the multi user rotation to this cluster.
addRotationSingleUser(options?)	Adds the single user rotation of the master password to this cluster.
applyRemovalPolicy(policy)	Apply the given removal policy to this resource.
asSecretAttachmentTarget()	Renders the secret attachment target specifications.
metric(metricName, props?)	Return the given named metric for this DBCluster.
metricCPUUtilization(props?)	The percentage of CPU utilization.
metricDatabaseConnections(props?)	The number of database connections in use.
metricDeadlocks(props?)	The average number of deadlocks in the database per second.
metricEngineUptime(props?)	The amount of time that the instance has been running, in seconds.
metricFreeLocalStorage(props?)	The amount of local storage available, in bytes.
metricFreeableMemory(props?)	The amount of available random access memory, in bytes.
metricNetworkReceiveThroughput(props?)	The amount of network throughput received from clients by each instance, in bytes per second.
metricNetworkThroughput(props?)	The amount of network throughput both received from and transmitted to clients by each instance, in bytes per second.
metricNetworkTransmitThroughput(props?)	The amount of network throughput sent to clients by each instance, in bytes per second.
metricSnapshotStorageUsed(props?)	The total amount of backup storage in bytes consumed by all Aurora snapshots outside its backup retention window.
metricTotalBackupStorageBilled(props?)	The total amount of backup storage in bytes for which you are billed.
metricVolumeBytesUsed(props?)	The amount of storage used by your Aurora DB instance, in bytes.
metricVolumeReadIOPs(props?)	The number of billed read I/O operations from a cluster volume, reported at 5-minute intervals.
metricVolumeWriteIOPs(props?)	The number of write disk I/O operations to the cluster volume, reported at 5-minute intervals.
toString()	Returns a string representation of this construct.
static fromDatabaseClusterAttributes(scope, id, attrs)	Import an existing DatabaseCluster from properties.

addProxy(id, options)

public addProxy(id: string, options: DatabaseProxyOptions): DatabaseProxy

Parameters

id string
options DatabaseProxyOptions

Returns

DatabaseProxy

Add a new db proxy to this cluster.

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(options?)

public addRotationSingleUser(options?: RotationSingleUserOptions): SecretRotation

Parameters

options RotationSingleUserOptions

Returns

SecretRotation

Adds the single user rotation of the master password 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.

metric(metricName, props?)

public metric(metricName: string, props?: MetricOptions): Metric

Parameters

metricName string
props MetricOptions

Returns

Metric

Return the given named metric for this DBCluster.

metricCPUUtilization(props?)

public metricCPUUtilization(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The percentage of CPU utilization.

Average over 5 minutes

metricDatabaseConnections(props?)

public metricDatabaseConnections(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The number of database connections in use.

Average over 5 minutes

metricDeadlocks(props?)

public metricDeadlocks(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The average number of deadlocks in the database per second.

Average over 5 minutes

metricEngineUptime(props?)

public metricEngineUptime(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of time that the instance has been running, in seconds.

Average over 5 minutes

metricFreeLocalStorage(props?)

public metricFreeLocalStorage(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of local storage available, in bytes.

Average over 5 minutes

metricFreeableMemory(props?)

public metricFreeableMemory(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of available random access memory, in bytes.

Average over 5 minutes

metricNetworkReceiveThroughput(props?)

public metricNetworkReceiveThroughput(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of network throughput received from clients by each instance, in bytes per second.

Average over 5 minutes

metricNetworkThroughput(props?)

public metricNetworkThroughput(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of network throughput both received from and transmitted to clients by each instance, in bytes per second.

Average over 5 minutes

metricNetworkTransmitThroughput(props?)

public metricNetworkTransmitThroughput(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of network throughput sent to clients by each instance, in bytes per second.

Average over 5 minutes

metricSnapshotStorageUsed(props?)

public metricSnapshotStorageUsed(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The total amount of backup storage in bytes consumed by all Aurora snapshots outside its backup retention window.

Average over 5 minutes

metricTotalBackupStorageBilled(props?)

public metricTotalBackupStorageBilled(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The total amount of backup storage in bytes for which you are billed.

Average over 5 minutes

metricVolumeBytesUsed(props?)

public metricVolumeBytesUsed(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The amount of storage used by your Aurora DB instance, in bytes.

Average over 5 minutes

metricVolumeReadIOPs(props?)

public metricVolumeReadIOPs(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The number of billed read I/O operations from a cluster volume, reported at 5-minute intervals.

Average over 5 minutes

metricVolumeWriteIOPs(props?)

public metricVolumeWriteIOPs(props?: MetricOptions): Metric

Parameters

props MetricOptions

Returns

Metric

The number of write disk I/O operations to the cluster volume, reported at 5-minute intervals.

Average over 5 minutes

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.