Class CfnDBCluster
A CloudFormation AWS::RDS::DBCluster
.
Inherited Members
Namespace: Amazon.CDK.AWS.RDS
Assembly: Amazon.CDK.AWS.RDS.dll
Syntax (csharp)
public class CfnDBCluster : CfnResource, IConstruct, IConstruct, IDependable, IInspectable
Syntax (vb)
Public Class CfnDBCluster
Inherits CfnResource
Implements IConstruct, IConstruct, IDependable, IInspectable
Remarks
The AWS::RDS::DBCluster
resource creates an Amazon Aurora DB cluster. For more information, see Managing an Amazon Aurora DB Cluster in the Amazon Aurora User Guide .
You can only create this resource in AWS Regions where Amazon Aurora is supported.
This topic covers the resource for Amazon Aurora DB clusters. For the documentation on the resource for Amazon RDS DB instances, see AWS::RDS::DBInstance .
Updating DB clusters
When properties labeled " Update requires: Replacement " are updated, AWS CloudFormation first creates a replacement DB cluster, then changes references from other dependent resources to point to the replacement DB cluster, and finally deletes the old DB cluster.
We highly recommend that you take a snapshot of the database before updating the stack. If you don't, you lose the data when AWS CloudFormation replaces your DB cluster. To preserve your data, perform the following procedure:
After you restore a DB cluster with a SnapshotIdentifier
property, you must specify the same SnapshotIdentifier
property for any future updates to the DB cluster. When you specify this property for an update, the DB cluster is not restored from the DB cluster snapshot again, and the data in the database is not changed. However, if you don't specify the SnapshotIdentifier
property, an empty DB cluster is created, and the original DB cluster is deleted. If you specify a property that is different from the previous snapshot restore property, a new DB cluster is restored from the specified SnapshotIdentifier
property, and the original DB cluster is deleted.
Currently, when you are updating the stack for an Aurora Serverless DB cluster, you can't include changes to any other properties when you specify one of the following properties: PreferredBackupWindow
, PreferredMaintenanceWindow
, and Port
. This limitation doesn't apply to provisioned DB clusters.
For more information about updating other properties of this resource, see ModifyDBCluster
. For more information about updating stacks, see AWS CloudFormation Stacks Updates .
Deleting DB clusters
The default DeletionPolicy
for AWS::RDS::DBCluster
resources is Snapshot
. For more information about how AWS CloudFormation deletes resources, see DeletionPolicy Attribute .
CloudformationResource: AWS::RDS::DBCluster
Link: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbcluster.html
ExampleMetadata: fixture=_generated
Examples
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
using Amazon.CDK.AWS.RDS;
CfnDBCluster cfnDBCluster = new CfnDBCluster(this, "MyCfnDBCluster", new CfnDBClusterProps {
Engine = "engine",
// the properties below are optional
AssociatedRoles = new [] { new DBClusterRoleProperty {
RoleArn = "roleArn",
// the properties below are optional
FeatureName = "featureName"
} },
AvailabilityZones = new [] { "availabilityZones" },
BacktrackWindow = 123,
BackupRetentionPeriod = 123,
CopyTagsToSnapshot = false,
DatabaseName = "databaseName",
DbClusterIdentifier = "dbClusterIdentifier",
DbClusterParameterGroupName = "dbClusterParameterGroupName",
DbSubnetGroupName = "dbSubnetGroupName",
DeletionProtection = false,
EnableCloudwatchLogsExports = new [] { "enableCloudwatchLogsExports" },
EnableHttpEndpoint = false,
EnableIamDatabaseAuthentication = false,
EngineMode = "engineMode",
EngineVersion = "engineVersion",
GlobalClusterIdentifier = "globalClusterIdentifier",
KmsKeyId = "kmsKeyId",
MasterUsername = "masterUsername",
MasterUserPassword = "masterUserPassword",
Port = 123,
PreferredBackupWindow = "preferredBackupWindow",
PreferredMaintenanceWindow = "preferredMaintenanceWindow",
ReplicationSourceIdentifier = "replicationSourceIdentifier",
RestoreType = "restoreType",
ScalingConfiguration = new ScalingConfigurationProperty {
AutoPause = false,
MaxCapacity = 123,
MinCapacity = 123,
SecondsUntilAutoPause = 123
},
SnapshotIdentifier = "snapshotIdentifier",
SourceDbClusterIdentifier = "sourceDbClusterIdentifier",
SourceRegion = "sourceRegion",
StorageEncrypted = false,
Tags = new [] { new CfnTag {
Key = "key",
Value = "value"
} },
UseLatestRestorableTime = false,
VpcSecurityGroupIds = new [] { "vpcSecurityGroupIds" }
});
Synopsis
Constructors
CfnDBCluster(Construct, String, ICfnDBClusterProps) | Create a new |
CfnDBCluster(ByRefValue) | Used by jsii to construct an instance of this class from a Javascript-owned object reference |
CfnDBCluster(DeputyBase.DeputyProps) | Used by jsii to construct an instance of this class from DeputyProps |
Properties
AssociatedRoles | Provides a list of the AWS Identity and Access Management (IAM) roles that are associated with the DB cluster. |
AttrEndpointAddress | The connection endpoint for the DB cluster. |
AttrEndpointPort | The port number that will accept connections on this DB cluster. |
AttrReadEndpointAddress | The reader endpoint for the DB cluster. |
AvailabilityZones | A list of Availability Zones (AZs) where instances in the DB cluster can be created. |
BacktrackWindow | The target backtrack window, in seconds. To disable backtracking, set this value to 0. |
BackupRetentionPeriod | The number of days for which automated backups are retained. |
CFN_RESOURCE_TYPE_NAME | The CloudFormation resource type name for this resource class. |
CfnProperties | |
CopyTagsToSnapshot | A value that indicates whether to copy all tags from the DB cluster to snapshots of the DB cluster. |
DatabaseName | The name of your database. |
DbClusterIdentifier | The DB cluster identifier. This parameter is stored as a lowercase string. |
DbClusterParameterGroupName | The name of the DB cluster parameter group to associate with this DB cluster. |
DbSubnetGroupName | A DB subnet group that you want to associate with this DB cluster. |
DeletionProtection | A value that indicates whether the DB cluster has deletion protection enabled. |
EnableCloudwatchLogsExports | The list of log types that need to be enabled for exporting to CloudWatch Logs. |
EnableHttpEndpoint | A value that indicates whether to enable the HTTP endpoint for an Aurora Serverless DB cluster. |
EnableIamDatabaseAuthentication | A value that indicates whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts. |
Engine | The name of the database engine to be used for this DB cluster. |
EngineMode | The DB engine mode of the DB cluster, either |
EngineVersion | The version number of the database engine to use. |
GlobalClusterIdentifier | If you are configuring an Aurora global database cluster and want your Aurora DB cluster to be a secondary member in the global database cluster, specify the global cluster ID of the global database cluster. |
KmsKeyId | The Amazon Resource Name (ARN) of the AWS KMS key that is used to encrypt the database instances in the DB cluster, such as |
MasterUsername | The name of the master user for the DB cluster. |
MasterUserPassword | The master password for the DB instance. |
Port | The port number on which the DB instances in the DB cluster accept connections. |
PreferredBackupWindow | The daily time range during which automated backups are created. |
PreferredMaintenanceWindow | The weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC). |
ReplicationSourceIdentifier | The Amazon Resource Name (ARN) of the source DB instance or DB cluster if this DB cluster is created as a read replica. |
RestoreType | The type of restore to be performed. You can specify one of the following values:. |
ScalingConfiguration | The |
SnapshotIdentifier | The identifier for the DB snapshot or DB cluster snapshot to restore from. |
SourceDbClusterIdentifier | When restoring a DB cluster to a point in time, the identifier of the source DB cluster from which to restore. |
SourceRegion | The AWS Region which contains the source DB cluster when replicating a DB cluster. |
StorageEncrypted | Indicates whether the DB cluster is encrypted. |
Tags | Tags to assign to the DB cluster. |
UseLatestRestorableTime | A value that indicates whether to restore the DB cluster to the latest restorable backup time. |
VpcSecurityGroupIds | A list of EC2 VPC security groups to associate with this DB cluster. |
Methods
Inspect(TreeInspector) | Examines the CloudFormation resource and discloses attributes. |
RenderProperties(IDictionary<String, Object>) |
Constructors
CfnDBCluster(Construct, String, ICfnDBClusterProps)
Create a new AWS::RDS::DBCluster
.
public CfnDBCluster(Construct scope, string id, ICfnDBClusterProps props)
Parameters
- scope Construct
- scope in which this resource is defined.
- id System.String
- scoped id of the resource.
- props ICfnDBClusterProps
- resource properties.
CfnDBCluster(ByRefValue)
Used by jsii to construct an instance of this class from a Javascript-owned object reference
protected CfnDBCluster(ByRefValue reference)
Parameters
- reference Amazon.JSII.Runtime.Deputy.ByRefValue
The Javascript-owned object reference
CfnDBCluster(DeputyBase.DeputyProps)
Used by jsii to construct an instance of this class from DeputyProps
protected CfnDBCluster(DeputyBase.DeputyProps props)
Parameters
- props Amazon.JSII.Runtime.Deputy.DeputyBase.DeputyProps
The deputy props
Properties
AssociatedRoles
Provides a list of the AWS Identity and Access Management (IAM) roles that are associated with the DB cluster.
public virtual object AssociatedRoles { get; set; }
Property Value
System.Object
Remarks
IAM roles that are associated with a DB cluster grant permission for the DB cluster to access other Amazon Web Services on your behalf.
AttrEndpointAddress
The connection endpoint for the DB cluster.
public virtual string AttrEndpointAddress { get; }
Property Value
System.String
Remarks
For example: mystack-mydbcluster-123456789012.us-east-2.rds.amazonaws.com
CloudformationAttribute: Endpoint.Address
AttrEndpointPort
The port number that will accept connections on this DB cluster.
public virtual string AttrEndpointPort { get; }
Property Value
System.String
Remarks
For example: 3306
CloudformationAttribute: Endpoint.Port
AttrReadEndpointAddress
The reader endpoint for the DB cluster.
public virtual string AttrReadEndpointAddress { get; }
Property Value
System.String
Remarks
For example: mystack-mydbcluster-ro-123456789012.us-east-2.rds.amazonaws.com
CloudformationAttribute: ReadEndpoint.Address
AvailabilityZones
A list of Availability Zones (AZs) where instances in the DB cluster can be created.
public virtual string[] AvailabilityZones { get; set; }
Property Value
System.String[]
Remarks
For information on AWS Regions and Availability Zones, see Choosing the Regions and Availability Zones in the Amazon Aurora User Guide .
BacktrackWindow
The target backtrack window, in seconds. To disable backtracking, set this value to 0.
public virtual Nullable<double> BacktrackWindow { get; set; }
Property Value
System.Nullable<System.Double>
Remarks
Currently, Backtrack is only supported for Aurora MySQL DB clusters.
Default: 0
Constraints:
BackupRetentionPeriod
The number of days for which automated backups are retained.
public virtual Nullable<double> BackupRetentionPeriod { get; set; }
Property Value
System.Nullable<System.Double>
Remarks
CFN_RESOURCE_TYPE_NAME
The CloudFormation resource type name for this resource class.
public static string CFN_RESOURCE_TYPE_NAME { get; }
Property Value
System.String
CfnProperties
protected override IDictionary<string, object> CfnProperties { get; }
Property Value
System.Collections.Generic.IDictionary<System.String, System.Object>
Overrides
CopyTagsToSnapshot
A value that indicates whether to copy all tags from the DB cluster to snapshots of the DB cluster.
public virtual object CopyTagsToSnapshot { get; set; }
Property Value
System.Object
Remarks
The default is not to copy them.
DatabaseName
The name of your database.
public virtual string DatabaseName { get; set; }
Property Value
System.String
Remarks
If you don't provide a name, then Amazon RDS won't create a database in this DB cluster. For naming constraints, see Naming Constraints in the Amazon Aurora User Guide .
DbClusterIdentifier
The DB cluster identifier. This parameter is stored as a lowercase string.
public virtual string DbClusterIdentifier { get; set; }
Property Value
System.String
Remarks
Constraints:
Example: my-cluster1
DbClusterParameterGroupName
The name of the DB cluster parameter group to associate with this DB cluster.
public virtual string DbClusterParameterGroupName { get; set; }
Property Value
System.String
Remarks
If you apply a parameter group to an existing DB cluster, then its DB instances might need to reboot. This can result in an outage while the DB instances are rebooting.
If you apply a change to parameter group associated with a stopped DB cluster, then the update stack waits until the DB cluster is started.
To list all of the available DB cluster parameter group names, use the following command:
aws rds describe-db-cluster-parameter-groups --query "DBClusterParameterGroups[].DBClusterParameterGroupName" --output text
DbSubnetGroupName
A DB subnet group that you want to associate with this DB cluster.
public virtual string DbSubnetGroupName { get; set; }
Property Value
System.String
Remarks
If you are restoring a DB cluster to a point in time with RestoreType
set to copy-on-write
, and don't specify a DB subnet group name, then the DB cluster is restored with a default DB subnet group.
DeletionProtection
A value that indicates whether the DB cluster has deletion protection enabled.
public virtual object DeletionProtection { get; set; }
Property Value
System.Object
Remarks
The database can't be deleted when deletion protection is enabled. By default, deletion protection is disabled.
EnableCloudwatchLogsExports
The list of log types that need to be enabled for exporting to CloudWatch Logs.
public virtual string[] EnableCloudwatchLogsExports { get; set; }
Property Value
System.String[]
Remarks
The values in the list depend on the DB engine being used. For more information, see Publishing Database Logs to Amazon CloudWatch Logs in the Amazon Aurora User Guide .
Aurora MySQL
Valid values: audit
, error
, general
, slowquery
Aurora PostgreSQL
Valid values: postgresql
EnableHttpEndpoint
A value that indicates whether to enable the HTTP endpoint for an Aurora Serverless DB cluster.
public virtual object EnableHttpEndpoint { get; set; }
Property Value
System.Object
Remarks
By default, the HTTP endpoint is disabled.
When enabled, the HTTP endpoint provides a connectionless web service API for running SQL queries on the Aurora Serverless DB cluster. You can also query your database from inside the RDS console with the query editor.
For more information, see Using the Data API for Aurora Serverless in the Amazon Aurora User Guide .
EnableIamDatabaseAuthentication
A value that indicates whether to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts.
public virtual object EnableIamDatabaseAuthentication { get; set; }
Property Value
System.Object
Remarks
By default, mapping is disabled.
For more information, see IAM Database Authentication in the Amazon Aurora User Guide.
Engine
The name of the database engine to be used for this DB cluster.
public virtual string Engine { get; set; }
Property Value
System.String
Remarks
Valid Values: aurora
(for MySQL 5.6-compatible Aurora), aurora-mysql
(for MySQL 5.7-compatible Aurora), and aurora-postgresql
EngineMode
The DB engine mode of the DB cluster, either provisioned
, serverless
, parallelquery
, global
, or multimaster
.
public virtual string EngineMode { get; set; }
Property Value
System.String
Remarks
The serverless
engine mode only supports Aurora Serverless v1. Currently, AWS CloudFormation doesn't support Aurora Serverless v2.
The parallelquery
engine mode isn't required for Aurora MySQL version 1.23 and higher 1.x versions, and version 2.09 and higher 2.x versions.
The global
engine mode isn't required for Aurora MySQL version 1.22 and higher 1.x versions, and global
engine mode isn't required for any 2.x versions.
The multimaster
engine mode only applies for DB clusters created with Aurora MySQL version 5.6.10a.
For Aurora PostgreSQL, the global
engine mode isn't required, and both the parallelquery
and the multimaster
engine modes currently aren't supported.
Limitations and requirements apply to some DB engine modes. For more information, see the following sections in the Amazon Aurora User Guide :
EngineVersion
The version number of the database engine to use.
public virtual string EngineVersion { get; set; }
Property Value
System.String
Remarks
To list all of the available engine versions for aurora
(for MySQL 5.6-compatible Aurora), use the following command:
aws rds describe-db-engine-versions --engine aurora --query "DBEngineVersions[].EngineVersion"
To list all of the available engine versions for aurora-mysql
(for MySQL 5.7-compatible Aurora), use the following command:
aws rds describe-db-engine-versions --engine aurora-mysql --query "DBEngineVersions[].EngineVersion"
To list all of the available engine versions for aurora-postgresql
, use the following command:
aws rds describe-db-engine-versions --engine aurora-postgresql --query "DBEngineVersions[].EngineVersion"
GlobalClusterIdentifier
If you are configuring an Aurora global database cluster and want your Aurora DB cluster to be a secondary member in the global database cluster, specify the global cluster ID of the global database cluster.
public virtual string GlobalClusterIdentifier { get; set; }
Property Value
System.String
Remarks
To define the primary database cluster of the global cluster, use the AWS::RDS::GlobalCluster resource.
If you aren't configuring a global database cluster, don't specify this property.
To remove the DB cluster from a global database cluster, specify an empty value for the GlobalClusterIdentifier
property.
For information about Aurora global databases, see Working with Amazon Aurora Global Databases in the Amazon Aurora User Guide .
KmsKeyId
The Amazon Resource Name (ARN) of the AWS KMS key that is used to encrypt the database instances in the DB cluster, such as arn:aws:kms:us-east-1:012345678910:key/abcd1234-a123-456a-a12b-a123b4cd56ef
.
public virtual string KmsKeyId { get; set; }
Property Value
System.String
Remarks
If you enable the StorageEncrypted
property but don't specify this property, the default KMS key is used. If you specify this property, you must set the StorageEncrypted
property to true
.
If you specify the SnapshotIdentifier
property, the StorageEncrypted
property value is inherited from the snapshot, and if the DB cluster is encrypted, the specified KmsKeyId
property is used.
MasterUsername
The name of the master user for the DB cluster.
public virtual string MasterUsername { get; set; }
Property Value
System.String
Remarks
If you specify the SourceDBClusterIdentifier
, SnapshotIdentifier
, or GlobalClusterIdentifier
property, don't specify this property. The value is inherited from the source DB cluster, the snapshot, or the primary DB cluster for the global database cluster, respectively.
MasterUserPassword
The master password for the DB instance.
public virtual string MasterUserPassword { get; set; }
Property Value
System.String
Remarks
If you specify the SourceDBClusterIdentifier
, SnapshotIdentifier
, or GlobalClusterIdentifier
property, don't specify this property. The value is inherited from the source DB cluster, the snapshot, or the primary DB cluster for the global database cluster, respectively.
Port
The port number on which the DB instances in the DB cluster accept connections.
public virtual Nullable<double> Port { get; set; }
Property Value
System.Nullable<System.Double>
Remarks
Default:
The <code>No interruption</code> on update behavior only applies to DB clusters. If you are updating a DB instance, see <a href="https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-rds-database-instance.html#cfn-rds-dbinstance-port">Port</a> for the AWS::RDS::DBInstance resource.
PreferredBackupWindow
The daily time range during which automated backups are created.
public virtual string PreferredBackupWindow { get; set; }
Property Value
System.String
Remarks
PreferredMaintenanceWindow
The weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).
public virtual string PreferredMaintenanceWindow { get; set; }
Property Value
System.String
Remarks
Format: ddd:hh24:mi-ddd:hh24:mi
The default is 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. To see the time blocks available, see Adjusting the Preferred DB Cluster Maintenance Window in the Amazon Aurora User Guide.
Valid Days: Mon, Tue, Wed, Thu, Fri, Sat, Sun.
Constraints: Minimum 30-minute window.
ReplicationSourceIdentifier
The Amazon Resource Name (ARN) of the source DB instance or DB cluster if this DB cluster is created as a read replica.
public virtual string ReplicationSourceIdentifier { get; set; }
Property Value
System.String
Remarks
RestoreType
The type of restore to be performed. You can specify one of the following values:.
public virtual string RestoreType { get; set; }
Property Value
System.String
Remarks
Constraints: You can't specify copy-on-write
if the engine version of the source DB cluster is earlier than 1.11.
If you don't specify a RestoreType
value, then the new DB cluster is restored as a full copy of the source DB cluster.
ScalingConfiguration
The ScalingConfiguration
property type specifies the scaling configuration of an Aurora Serverless DB cluster.
public virtual object ScalingConfiguration { get; set; }
Property Value
System.Object
Remarks
Currently, AWS CloudFormation only supports Aurora Serverless v1. AWS CloudFormation doesn't support Aurora Serverless v2.
SnapshotIdentifier
The identifier for the DB snapshot or DB cluster snapshot to restore from.
public virtual string SnapshotIdentifier { get; set; }
Property Value
System.String
Remarks
You can use either the name or the Amazon Resource Name (ARN) to specify a DB cluster snapshot. However, you can use only the ARN to specify a DB snapshot.
After you restore a DB cluster with a SnapshotIdentifier
property, you must specify the same SnapshotIdentifier
property for any future updates to the DB cluster. When you specify this property for an update, the DB cluster is not restored from the snapshot again, and the data in the database is not changed. However, if you don't specify the SnapshotIdentifier
property, an empty DB cluster is created, and the original DB cluster is deleted. If you specify a property that is different from the previous snapshot restore property, a new DB cluster is restored from the specified SnapshotIdentifier
property, and the original DB cluster is deleted.
If you specify the SnapshotIdentifier
property to restore a DB cluster (as opposed to specifying it for DB cluster updates), then don't specify the following properties:
Constraints:
SourceDbClusterIdentifier
When restoring a DB cluster to a point in time, the identifier of the source DB cluster from which to restore.
public virtual string SourceDbClusterIdentifier { get; set; }
Property Value
System.String
Remarks
SourceRegion
The AWS Region which contains the source DB cluster when replicating a DB cluster.
public virtual string SourceRegion { get; set; }
Property Value
System.String
Remarks
For example, us-east-1
.
StorageEncrypted
Indicates whether the DB cluster is encrypted.
public virtual object StorageEncrypted { get; set; }
Property Value
System.Object
Remarks
If you specify the KmsKeyId
property, then you must enable encryption.
If you specify the SourceDBClusterIdentifier
property, don't specify this property. The value is inherited from the source DB cluster, and if the DB cluster is encrypted, the specified KmsKeyId
property is used.
If you specify the SnapshotIdentifier
and the specified snapshot is encrypted, don't specify this property. The value is inherited from the snapshot, and the specified KmsKeyId
property is used.
If you specify the SnapshotIdentifier
and the specified snapshot isn't encrypted, you can use this property to specify that the restored DB cluster is encrypted. Specify the KmsKeyId
property for the KMS key to use for encryption. If you don't want the restored DB cluster to be encrypted, then don't set this property or set it to false
.
Tags
Tags to assign to the DB cluster.
public virtual TagManager Tags { get; }
Property Value
Remarks
UseLatestRestorableTime
A value that indicates whether to restore the DB cluster to the latest restorable backup time.
public virtual object UseLatestRestorableTime { get; set; }
Property Value
System.Object
Remarks
By default, the DB cluster is not restored to the latest restorable backup time.
VpcSecurityGroupIds
A list of EC2 VPC security groups to associate with this DB cluster.
public virtual string[] VpcSecurityGroupIds { get; set; }
Property Value
System.String[]
Remarks
If you plan to update the resource, don't specify VPC security groups in a shared VPC.
Methods
Inspect(TreeInspector)
Examines the CloudFormation resource and discloses attributes.
public virtual void Inspect(TreeInspector inspector)
Parameters
- inspector TreeInspector
- tree inspector to collect and process attributes.
RenderProperties(IDictionary<String, Object>)
protected override IDictionary<string, object> RenderProperties(IDictionary<string, object> props)
Parameters
- props System.Collections.Generic.IDictionary<System.String, System.Object>
Returns
System.Collections.Generic.IDictionary<System.String, System.Object>