# DatabaseCluster

Create a clustered database with a given number of instances.

Extends: Construct › Resource › DatabaseCluster
Implements: IResource, IDatabaseCluster, IConnectable, ISecretAttachmentTarget, IEnvironmentAware, IDBClusterRef, IConstruct, IDependable

- CloudFormation: [`AWS::DocDB::DBCluster`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-docdb-dbcluster.html)
- L1 type: [`CfnDBCluster`](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.CfnDBCluster.html)
- Source: [`aws-docdb/lib/cluster.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-docdb/lib/cluster.ts#L419)
- Type last changed: v2.235.0 · 15 Jan 2026

## Example

```ts
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

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

## Construct Props

- `backup`: [BackupProps](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.BackupProps.html) — 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.

- `caCertificate`: [CaCertificate](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.CaCertificate.html) — The identifier of the CA certificate used for the instances.

  **Default:** DocumentDB will choose a certificate authority

  Specifying or updating this property triggers a reboot.

- `cloudWatchLogsRetention`: [RetentionDays](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.RetentionDays.html) — The number of days log events are kept in CloudWatch Logs.

  **Default:** logs never expire

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

- `cloudWatchLogsRetentionRole`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — The IAM role for the Lambda function associated with the custom resource that sets the retention policy.

  **Default:** a new role is created.

- `copyTagsToSnapshot`: boolean = false — Whether to copy tags to the snapshot when a snapshot is created.

- `dbClusterName`: string — An optional identifier for the cluster.

  **Default:** A name is automatically generated.

- `deletionProtection`: boolean = 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`: boolean = false — A value that indicates whether to enable Performance Insights for the instances in the DB Cluster.

- `engineVersion`: string — What version of the database to start.

  **Default:** the latest major version

- `exportAuditLogsToCloudWatch`: boolean = 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.

- `exportProfilerLogsToCloudWatch`: boolean = 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.

- `instanceIdentifierBase`: string — Base identifier for instances.

  **Default:** `dbClusterName` is used with the word "Instance" appended. If `dbClusterName` is not provided, the identifier is automatically generated.

  Every replica is named by appending the replica number to this string, 1-based.
  Only applicable for provisioned clusters.

- `instanceMaintenanceWindow`: string — The weekly time range during which system maintenance can occur on the cluster's instances.

  **Default:** 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.

  The cluster-level `preferredMaintenanceWindow` applies to cluster-wide maintenance events; this prop
  applies to each auto-created instance independently. To use the same window for both, set this prop
  to the same value as `preferredMaintenanceWindow`.

  Format: `ddd:hh24:mi-ddd:hh24:mi`. Must be at least 30 minutes long.
  Example: 'sat:09:00-sat:09:30'

  Only applicable to provisioned clusters; has no effect on serverless clusters because they do not
  create instances.

- `instanceRemovalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) — The removal policy to apply to the cluster's instances.

  **Default:** `RemovalPolicy.DESTROY` when `removalPolicy` is set to `SNAPSHOT`, `removalPolicy` otherwise.

  Cannot be set to `SNAPSHOT`.

- `instances`: number = 1 — Number of DocDB compute instances.

- `instanceType`: [InstanceType](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.InstanceType.html) = None — What type of instance to start for the replicas.

  Required for provisioned clusters, not applicable for serverless clusters.

- `kmsKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — The KMS key for storage encryption.

  **Default:** default master key.

- `manageMasterUserPassword`: boolean = false — Specifies whether to manage the master user password with AWS Secrets Manager.

  When set to true, Amazon DocumentDB will automatically generate and manage the master user password in AWS Secrets Manager.
  This provides enhanced security and automatic password rotation capabilities.

  Constraint: You can't manage the master user password with AWS Secrets Manager if `masterUser.password` is specified.

  The `secret` property of the cluster is not set when using this option. See the
  module README for how to access the managed secret.

- `masterUser`: [Login](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.Login.html) (required) — Username and password for the administrative user.

- `masterUserSecretKmsKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — The AWS KMS key to encrypt a secret that is automatically generated and managed in AWS Secrets Manager.

  **Default:** default AWS managed key `aws/secretsmanager`

  This setting is valid only if the master user password is managed by Amazon DocumentDB in AWS Secrets Manager
  for the DB cluster (i.e. when `manageMasterUserPassword` is true).
  If you don't specify this property, then the `aws/secretsmanager` KMS key is used to encrypt the secret.

- `parameterGroup`: [IDBClusterParameterGroupRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_docdb.IDBClusterParameterGroupRef.html) — The DB parameter group to associate with the instance.

  **Default:** no parameter group

- `port`: number = DatabaseCluster.DEFAULT_PORT — The port the DocumentDB cluster will listen on.

- `preferredMaintenanceWindow`: string — A weekly time range in which maintenance should preferably execute.

  **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.

  Must be at least 30 minutes long.

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

- `removalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) — 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.

  **Default:** Retain cluster.

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

  When set to `SNAPSHOT`, the removal policy for the instances and the security group
  will default to `DESTROY` as those resources do not support the policy.

  Use the `instanceRemovalPolicy` and `securityGroupRemovalPolicy` to change the behavior.

- `securityGroup`: [ISecurityGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.ISecurityGroup.html) — Security group.

  **Default:** a new security group is created.

- `securityGroupRemovalPolicy`: [RemovalPolicy](/cdk/api/v2/docs/aws-cdk-lib.RemovalPolicy.html) — The removal policy to apply to the cluster's security group.

  **Default:** `RemovalPolicy.DESTROY` when `removalPolicy` is set to `SNAPSHOT`, `removalPolicy` otherwise.

  Cannot be set to `SNAPSHOT`.

- `serverlessV2ScalingConfiguration`: [ServerlessV2ScalingConfiguration](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.ServerlessV2ScalingConfiguration.html) = None — ServerlessV2 scaling configuration.

  When specified, the cluster will be created as a serverless cluster.

- `storageEncrypted`: boolean = true — Whether to enable storage encryption.

- `storageType`: [StorageType](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.StorageType.html) = StorageType.STANDARD — The storage type of the DocDB cluster.

  I/O-optimized storage is supported starting with engine version 5.0.0.

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) (required) — What subnets to run the DocumentDB instances in.

  Must be at least 2 subnets in two different AZs.

- `vpcSubnets`: [SubnetSelection](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetSelection.html) — Where to place the instances within the VPC.

  **Default:** private subnets

## Properties

- `clusterEndpoint`: [Endpoint](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.Endpoint.html) — The endpoint to use for read/write operations.

- `clusterIdentifier`: string — Identifier of the cluster.

- `clusterReadEndpoint`: [Endpoint](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.Endpoint.html) — Endpoint to use for load-balanced read-only operations.

- `clusterResourceIdentifier`: 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`: [Connections](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Connections.html) — The connections object to implement IConnectable.

- `dbClusterRef`: [DBClusterReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_docdb.DBClusterReference.html) — A reference to this cluster.

- `DEFAULT_NUM_INSTANCES`: number (static) — The default number of instances in the DocDB cluster if none are specified.

- `DEFAULT_PORT`: number (static) — The default port Document DB listens on.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `instanceEndpoints`: [Endpoint](/cdk/api/v2/docs/aws-cdk-lib.aws_docdb.Endpoint.html)[] — Endpoints which address each individual replica.

- `instanceIdentifiers`: string[] — Identifiers of the replicas.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `secret`: [ISecret](/cdk/api/v2/docs/aws-cdk-lib.aws_secretsmanager.ISecret.html) — The secret attached to this cluster.

- `securityGroupId`: string — Security group identifier of this database.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) — The stack in which this resource is defined.

## Methods

- `addRotationMultiUser(id: string, options: RotationMultiUserOptions): SecretRotation` — Adds the multi user rotation to this cluster.

- `addRotationSingleUser(automaticallyAfter?: Duration): SecretRotation` — Adds the single user rotation of the master password to this cluster.

  **Parameters**

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

- `addSecurityGroups(...securityGroups: ISecurityGroup[]): void` — Adds security groups to this cluster.

  **Parameters**

  - `securityGroups` — The security groups to add.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — 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(): SecretAttachmentTargetProps` — Renders the secret attachment target specifications.

- `fromDatabaseClusterAttributes(scope: Construct, id: string, attrs: DatabaseClusterAttributes): IDatabaseCluster` (static) — Import an existing DatabaseCluster from properties.

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.