DatabaseClusterProps

class aws_cdk.aws_rds.DatabaseClusterProps(*, engine, auto_minor_version_upgrade=None, backtrack_window=None, backup=None, cloudwatch_logs_exports=None, cloudwatch_logs_retention=None, cloudwatch_logs_retention_role=None, cluster_identifier=None, copy_tags_to_snapshot=None, credentials=None, default_database_name=None, deletion_protection=None, domain=None, domain_role=None, enable_data_api=None, enable_local_write_forwarding=None, enable_performance_insights=None, iam_authentication=None, instance_identifier_base=None, instance_props=None, instances=None, instance_update_behaviour=None, monitoring_interval=None, monitoring_role=None, network_type=None, parameter_group=None, parameters=None, performance_insight_encryption_key=None, performance_insight_retention=None, port=None, preferred_maintenance_window=None, readers=None, removal_policy=None, s3_export_buckets=None, s3_export_role=None, s3_import_buckets=None, s3_import_role=None, security_groups=None, serverless_v2_max_capacity=None, serverless_v2_min_capacity=None, storage_encrypted=None, storage_encryption_key=None, storage_type=None, subnet_group=None, vpc=None, vpc_subnets=None, writer=None)

Bases: object

Properties for a new database cluster.

Parameters:

engine (IClusterEngine) – What kind of database to start.
auto_minor_version_upgrade (Optional[bool]) – Specifies whether minor engine upgrades are applied automatically to the DB cluster during the maintenance window. Default: true
backtrack_window (Optional[Duration]) – 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. Default: 0 seconds (no backtrack)
backup (Union[BackupProps, Dict[str, Any], None]) – Backup settings. 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.
cloudwatch_logs_exports (Optional[Sequence[str]]) – The list of log types that need to be enabled for exporting to CloudWatch Logs. Default: - no log exports
cloudwatch_logs_retention (Optional[RetentionDays]) – 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. Default: - logs never expire
cloudwatch_logs_retention_role (Optional[IRole]) – The IAM role for the Lambda function associated with the custom resource that sets the retention policy. Default: - a new role is created.
cluster_identifier (Optional[str]) – An optional identifier for the cluster. Default: - A name is automatically generated.
copy_tags_to_snapshot (Optional[bool]) – Whether to copy tags to the snapshot when a snapshot is created. Default: - true
credentials (Optional[Credentials]) – Credentials for the administrative user. Default: - A username of ‘admin’ (or ‘postgres’ for PostgreSQL) and SecretsManager-generated password
default_database_name (Optional[str]) – Name of a database which is automatically created inside the cluster. Default: - Database is not created in cluster.
deletion_protection (Optional[bool]) – Indicates whether the DB cluster should have deletion protection enabled. Default: - true if removalPolicy is RETAIN, undefined otherwise, which will not enable deletion protection. To disable deletion protection after it has been enabled, you must explicitly set this value to false.
domain (Optional[str]) – Directory ID for associating the DB cluster with a specific Active Directory. Necessary for enabling Kerberos authentication. If specified, the DB cluster joins the given Active Directory, enabling Kerberos authentication. If not specified, the DB cluster will not be associated with any Active Directory, and Kerberos authentication will not be enabled. Default: - DB cluster is not associated with an Active Directory; Kerberos authentication is not enabled.
domain_role (Optional[IRole]) – The IAM role to be used when making API calls to the Directory Service. The role needs the AWS-managed policy AmazonRDSDirectoryServiceAccess or equivalent. Default: - If DatabaseClusterBaseProps.domain is specified, a role with the AmazonRDSDirectoryServiceAccess policy is automatically created.
enable_data_api (Optional[bool]) – Whether to enable the Data API for the cluster. Default: - false
enable_local_write_forwarding (Optional[bool]) – Whether read replicas can forward write operations to the writer DB instance in the DB cluster. This setting can only be enabled for Aurora MySQL 3.04 or higher, and for Aurora PostgreSQL 16.4 or higher (for version 16), 15.8 or higher (for version 15), and 14.13 or higher (for version 14). Default: false
enable_performance_insights (Optional[bool]) – Whether to enable Performance Insights for the DB cluster. Default: - false, unless performanceInsightRetention or performanceInsightEncryptionKey is set.
iam_authentication (Optional[bool]) – Whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts. Default: false
instance_identifier_base (Optional[str]) – Base identifier for instances. Every replica is named by appending the replica number to this string, 1-based. Default: - clusterIdentifier is used with the word “Instance” appended. If clusterIdentifier is not provided, the identifier is automatically generated.
instance_props (Union[InstanceProps, Dict[str, Any], None]) – (deprecated) Settings for the individual instances that are launched.
instances (Union[int, float, None]) – (deprecated) How many replicas/instances to create. Has to be at least 1. Default: 2
instance_update_behaviour (Optional[InstanceUpdateBehaviour]) – The ordering of updates for instances. Default: InstanceUpdateBehaviour.BULK
monitoring_interval (Optional[Duration]) – The interval, in seconds, between points when Amazon RDS collects enhanced monitoring metrics for the DB instances. Default: no enhanced monitoring
monitoring_role (Optional[IRole]) – Role that will be used to manage DB instances monitoring. Default: - A role is automatically created for you
network_type (Optional[NetworkType]) – The network type of the DB instance. Default: - IPV4
parameter_group (Optional[IParameterGroup]) – Additional parameters to pass to the database engine. Default: - No parameter group.
parameters (Optional[Mapping[str, str]]) – 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. Default: - None
performance_insight_encryption_key (Optional[IKey]) – The AWS KMS key for encryption of Performance Insights data. Default: - default master key
performance_insight_retention (Optional[PerformanceInsightRetention]) – The amount of time, in days, to retain Performance Insights data. Default: 7
port (Union[int, float, None]) – What port to listen on. Default: - The default for the engine is used.
preferred_maintenance_window (Optional[str]) – 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’ 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.
readers (Optional[Sequence[IClusterInstance]]) – A list of instances to create as cluster reader instances. Default: - no readers are created. The cluster will have a single writer/reader
removal_policy (Optional[RemovalPolicy]) – The removal policy to apply when the cluster and its instances are removed from the stack or replaced during an update. Default: - RemovalPolicy.SNAPSHOT (remove the cluster and instances, but retain a snapshot of the data)
s3_export_buckets (Optional[Sequence[IBucket]]) – 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: Default: - None
s3_export_role (Optional[IRole]) – 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. To use this property with Aurora PostgreSQL, it must be configured with the S3 export feature enabled when creating the DatabaseClusterEngine For MySQL: Default: - New role is created if s3ExportBuckets is set, no role is defined otherwise
s3_import_buckets (Optional[Sequence[IBucket]]) – 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: Default: - None
s3_import_role (Optional[IRole]) – 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. To use this property with Aurora PostgreSQL, it must be configured with the S3 import feature enabled when creating the DatabaseClusterEngine For MySQL: Default: - New role is created if s3ImportBuckets is set, no role is defined otherwise
security_groups (Optional[Sequence[ISecurityGroup]]) – Security group. Default: a new security group is created.
serverless_v2_max_capacity (Union[int, float, None]) – The maximum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster. You can specify ACU values in half-step increments, such as 40, 40.5, 41, and so on. The largest value that you can use is 256. The maximum capacity must be higher than 0.5 ACUs. Default: 2
serverless_v2_min_capacity (Union[int, float, None]) – The minimum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster. You can specify ACU values in half-step increments, such as 8, 8.5, 9, and so on. The smallest value that you can use is 0.5. Default: 0.5
storage_encrypted (Optional[bool]) – Whether to enable storage encryption. Default: - true if storageEncryptionKey is provided, false otherwise
storage_encryption_key (Optional[IKey]) – The KMS key for storage encryption. If specified, storageEncrypted will be set to true. Default: - if storageEncrypted is true then the default master key, no key otherwise
storage_type (Optional[DBClusterStorageType]) – The storage type to be associated with the DB cluster. Default: - DBClusterStorageType.AURORA_IOPT1
subnet_group (Optional[ISubnetGroup]) – Existing subnet group for the cluster. Default: - a new subnet group will be created.
vpc (Optional[IVpc]) – What subnets to run the RDS instances in. Must be at least 2 subnets in two different AZs.
vpc_subnets (Union[SubnetSelection, Dict[str, Any], None]) – Where to place the instances within the VPC. Default: - the Vpc default strategy if not specified.
writer (Optional[IClusterInstance]) – The instance to use for the cluster writer. Default: required if instanceProps is not provided

ExampleMetadata:

infused

Example:

# vpc: ec2.Vpc

cluster = rds.DatabaseCluster(self, "Database",
    engine=rds.DatabaseClusterEngine.aurora_mysql(version=rds.AuroraMysqlEngineVersion.VER_3_01_0),
    writer=rds.ClusterInstance.provisioned("writer",
        instance_type=ec2.InstanceType.of(ec2.InstanceClass.R6G, ec2.InstanceSize.XLARGE4)
    ),
    serverless_v2_min_capacity=6.5,
    serverless_v2_max_capacity=64,
    readers=[
        # will be put in promotion tier 1 and will scale with the writer
        rds.ClusterInstance.serverless_v2("reader1", scale_with_writer=True),
        # will be put in promotion tier 2 and will not scale with the writer
        rds.ClusterInstance.serverless_v2("reader2")
    ],
    vpc=vpc
)

Attributes

auto_minor_version_upgrade

Specifies whether minor engine upgrades are applied automatically to the DB cluster during the maintenance window.

Default:: true

backtrack_window

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.

Default:: 0 seconds (no backtrack)
See:: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Managing.Backtrack.html

backup

Backup settings.

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.

See:: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithAutomatedBackups.html#USER_WorkingWithAutomatedBackups.BackupWindow

cloudwatch_logs_exports

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

Default:

no log exports

cloudwatch_logs_retention

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.

Default:

logs never expire

cloudwatch_logs_retention_role

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

Default:

a new role is created.

cluster_identifier

An optional identifier for the cluster.

Default:

A name is automatically generated.

copy_tags_to_snapshot

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

Default:

true

credentials

Credentials for the administrative user.

Default:

A username of ‘admin’ (or ‘postgres’ for PostgreSQL) and SecretsManager-generated password

default_database_name

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

Default:

Database is not created in cluster.

deletion_protection

Indicates whether the DB cluster should have deletion protection enabled.

Default:

true if removalPolicy is RETAIN, undefined otherwise, which will not enable deletion protection.

To disable deletion protection after it has been enabled, you must explicitly set this value to false.

domain

Directory ID for associating the DB cluster with a specific Active Directory.

Necessary for enabling Kerberos authentication. If specified, the DB cluster joins the given Active Directory, enabling Kerberos authentication. If not specified, the DB cluster will not be associated with any Active Directory, and Kerberos authentication will not be enabled.

Default:

DB cluster is not associated with an Active Directory; Kerberos authentication is not enabled.

domain_role

The IAM role to be used when making API calls to the Directory Service.

The role needs the AWS-managed policy AmazonRDSDirectoryServiceAccess or equivalent.

Default:

If DatabaseClusterBaseProps.domain is specified, a role with the AmazonRDSDirectoryServiceAccess policy is automatically created.

enable_data_api

Whether to enable the Data API for the cluster.

Default:

false

enable_local_write_forwarding

Whether read replicas can forward write operations to the writer DB instance in the DB cluster.

This setting can only be enabled for Aurora MySQL 3.04 or higher, and for Aurora PostgreSQL 16.4 or higher (for version 16), 15.8 or higher (for version 15), and 14.13 or higher (for version 14).

Default:: false
See:: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-postgresql-write-forwarding.html

enable_performance_insights

Whether to enable Performance Insights for the DB cluster.

Default:

false, unless performanceInsightRetention or performanceInsightEncryptionKey is set.

engine: What kind of database to start.

iam_authentication

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

Default:: false

instance_identifier_base

Base identifier for instances.

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

Default:

clusterIdentifier is used with the word “Instance” appended.

If clusterIdentifier is not provided, the identifier is automatically generated.

instance_props

(deprecated) Settings for the individual instances that are launched.

Deprecated:

use writer and readers instead

Stability:

deprecated

instance_update_behaviour

The ordering of updates for instances.

Default:: InstanceUpdateBehaviour.BULK

instances

(deprecated) How many replicas/instances to create.

Has to be at least 1.

Default:

2

Deprecated:

use writer and readers instead

Stability:

deprecated

monitoring_interval

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

Default:: no enhanced monitoring

monitoring_role

Role that will be used to manage DB instances monitoring.

Default:

A role is automatically created for you

network_type

The network type of the DB instance.

Default:

IPV4

parameter_group

Additional parameters to pass to the database engine.

Default:

No parameter group.

parameters

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.

Default:

None

performance_insight_encryption_key

The AWS KMS key for encryption of Performance Insights data.

Default:

default master key

performance_insight_retention

The amount of time, in days, to retain Performance Insights data.

Default:: 7

port

What port to listen on.

Default:

The default for the engine is used.

preferred_maintenance_window

mi-ddd:hh24:mi (24H Clock UTC).

Example: ‘Sun:23:45-Mon:00:15’

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.

See:: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Concepts.DBMaintenance
Type:: A preferred maintenance window day/time range. Should be specified as a range ddd
Type:: hh24

readers

A list of instances to create as cluster reader instances.

Default:

no readers are created. The cluster will have a single writer/reader

removal_policy

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

Default:

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

s3_export_buckets

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:

Default:

None

See:

https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/postgresql-s3-export.html

s3_export_role

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. To use this property with Aurora PostgreSQL, it must be configured with the S3 export feature enabled when creating the DatabaseClusterEngine For MySQL:

Default:

New role is created if s3ExportBuckets is set, no role is defined otherwise

See:

https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/postgresql-s3-export.html

s3_import_buckets

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:

Default:

None

See:

https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Migrating.html

s3_import_role

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. To use this property with Aurora PostgreSQL, it must be configured with the S3 import feature enabled when creating the DatabaseClusterEngine For MySQL:

Default:

New role is created if s3ImportBuckets is set, no role is defined otherwise

See:

https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Migrating.html

security_groups

Security group.

Default:: a new security group is created.

serverless_v2_max_capacity

The maximum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster.

You can specify ACU values in half-step increments, such as 40, 40.5, 41, and so on. The largest value that you can use is 256.

The maximum capacity must be higher than 0.5 ACUs.

Default:: 2
See:: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.setting-capacity.html#aurora-serverless-v2.max_capacity_considerations

serverless_v2_min_capacity

The minimum number of Aurora capacity units (ACUs) for a DB instance in an Aurora Serverless v2 cluster.

You can specify ACU values in half-step increments, such as 8, 8.5, 9, and so on. The smallest value that you can use is 0.5.

Default:: 0.5
See:: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.setting-capacity.html#aurora-serverless-v2.max_capacity_considerations

storage_encrypted

Whether to enable storage encryption.

Default:

true if storageEncryptionKey is provided, false otherwise

storage_encryption_key

The KMS key for storage encryption.

If specified, storageEncrypted will be set to true.

Default:

if storageEncrypted is true then the default master key, no key otherwise

storage_type

The storage type to be associated with the DB cluster.

Default:

DBClusterStorageType.AURORA_IOPT1

subnet_group

Existing subnet group for the cluster.

Default:

a new subnet group will be created.

vpc

What subnets to run the RDS instances in.

Must be at least 2 subnets in two different AZs.

vpc_subnets

Where to place the instances within the VPC.

Default:

the Vpc default strategy if not specified.

writer

The instance to use for the cluster writer.

Default:: required if instanceProps is not provided