# @aws-cdk/aws-docdb

> The CDK Construct Library for AWS::DocDB

Latest version **1.204.0** (published 2023-06-19) · Apache-2.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @aws-cdk/aws-docdb
pnpm add @aws-cdk/aws-docdb
yarn add @aws-cdk/aws-docdb
bun add @aws-cdk/aws-docdb
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.204.0 |
| Published | 2023-06-19 |
| First published | 2019-01-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 14.15.0 |
| Dependencies | 8 |
| Unpacked size | 719 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12900 |
| Author | Amazon Web Services |
| Maintainers | romainmuller, amzn-oss, rix0rrr, aws-cdk-team |
| Keywords | aws, cdk, constructs, AWS::DocDB, aws-docdb |

## Links

- npm: https://www.npmjs.com/package/@aws-cdk/aws-docdb
- Repository: https://github.com/aws/aws-cdk
- Issues: https://github.com/aws/aws-cdk/issues
- npm.io page: https://npm.io/package/@aws-cdk/aws-docdb

## Dependencies (8)

- [constructs](https://npm.io/package/constructs.md) ^3.3.69
- [@aws-cdk/core](https://npm.io/package/@aws-cdk/core.md) 1.204.0
- [@aws-cdk/aws-ec2](https://npm.io/package/@aws-cdk/aws-ec2.md) 1.204.0
- [@aws-cdk/aws-efs](https://npm.io/package/@aws-cdk/aws-efs.md) 1.204.0
- [@aws-cdk/aws-iam](https://npm.io/package/@aws-cdk/aws-iam.md) 1.204.0
- [@aws-cdk/aws-kms](https://npm.io/package/@aws-cdk/aws-kms.md) 1.204.0
- [@aws-cdk/aws-logs](https://npm.io/package/@aws-cdk/aws-logs.md) 1.204.0
- [@aws-cdk/aws-secretsmanager](https://npm.io/package/@aws-cdk/aws-secretsmanager.md) 1.204.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.204.0 (latest) — 2023-06-19
- 1.203.0 — 2023-05-31
- 1.202.0 — 2023-05-22
- 1.201.0 — 2023-05-10
- 1.200.0 — 2023-04-26
- 1.199.0 — 2023-04-20
- 1.198.1 — 2023-03-31
- 1.198.0 — 2023-03-22
- 1.197.0 — 2023-03-14
- 1.196.0 — 2023-03-08
- 1.195.0 — 2023-03-02
- 1.194.0 — 2023-02-21
- 1.193.0 — 2023-02-15
- 1.192.0 — 2023-02-09
- 1.191.0 — 2023-01-31
- … 251 more at https://npm.io/package/@aws-cdk/aws-docdb/versions

## README

# Amazon DocumentDB Construct Library
<!--BEGIN STABILITY BANNER-->

---

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1 has reached End-of-Support on 2023-06-01.
> This package is no longer being updated, and users should migrate to AWS CDK v2.
>
> For more information on how to migrate, see the [_Migrating to AWS CDK v2_ guide][doc].
>
> [doc]: https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html

---

<!--END STABILITY BANNER-->

## Starting a Clustered Database

To set up a clustered DocumentDB database, define a `DatabaseCluster`. You must
always launch a database in a VPC. Use the `vpcSubnets` attribute to control whether
your instances will be launched privately or publicly:

```ts
declare const vpc: ec2.Vpc;
const cluster = new docdb.DatabaseCluster(this, 'Database', {
  masterUser: {
    username: 'myuser', // NOTE: 'admin' is reserved by DocumentDB
    excludeCharacters: '\"@/:', // optional, defaults to the set "\"@/" and is also used for eventually created rotations
    secretName: '/myapp/mydocdb/masteruser', // optional, if you prefer to specify the secret name
  },
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
  vpcSubnets: {
    subnetType: ec2.SubnetType.PUBLIC,
  },
  vpc,
});
```

By default, the master password will be generated and stored in AWS Secrets Manager with auto-generated description.

Your cluster will be empty by default.

## Connecting

To control who can access the cluster, use the `.connections` attribute. DocumentDB databases have a default port, so
you don't need to specify the port:

```ts
declare const cluster: docdb.DatabaseCluster;
cluster.connections.allowDefaultPortFromAnyIpv4('Open to the world');
```

The endpoints to access your database cluster will be available as the `.clusterEndpoint` and `.clusterReadEndpoint`
attributes:

```ts
declare const cluster: docdb.DatabaseCluster;
const writeAddress = cluster.clusterEndpoint.socketAddress;   // "HOSTNAME:PORT"
```

If you have existing security groups you would like to add to the cluster, use the `addSecurityGroups` method. Security
groups added in this way will not be managed by the `Connections` object of the cluster.

```ts
declare const vpc: ec2.Vpc;
declare const cluster: docdb.DatabaseCluster;

const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
  vpc,
});
cluster.addSecurityGroups(securityGroup);
```

## Deletion protection

Deletion protection can be enabled on an Amazon DocumentDB cluster to prevent accidental deletion of the cluster:

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

## Rotating credentials

When the master password is generated and stored in AWS Secrets Manager, it can be rotated automatically:

```ts
declare const cluster: docdb.DatabaseCluster;
cluster.addRotationSingleUser(); // Will rotate automatically after 30 days
```

[example of setting up master password rotation for a cluster](test/integ.cluster-rotation.lit.ts)

The multi user rotation scheme is also available:

```ts
import * as secretsmanager from '@aws-cdk/aws-secretsmanager';

declare const myImportedSecret: secretsmanager.Secret;
declare const cluster: docdb.DatabaseCluster;

cluster.addRotationMultiUser('MyUser', {
  secret: myImportedSecret, // This secret must have the `masterarn` key
});
```

It's also possible to create user credentials together with the cluster and add rotation:

```ts
declare const cluster: docdb.DatabaseCluster;
const myUserSecret = new docdb.DatabaseSecret(this, 'MyUserSecret', {
  username: 'myuser',
  masterSecret: cluster.secret,
});
const myUserSecretAttached = myUserSecret.attach(cluster); // Adds DB connections information in the secret

cluster.addRotationMultiUser('MyUser', { // Add rotation using the multi user scheme
  secret: myUserSecretAttached, // This secret must have the `masterarn` key
});
```

**Note**: This user must be created manually in the database using the master credentials.
The rotation will start as soon as this user exists.

See also [@aws-cdk/aws-secretsmanager](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-secretsmanager/README.md) for credentials rotation of existing clusters.

## Audit and profiler Logs

Sending audit or profiler needs to be configured in two places:

1. Check / create the needed options in your ParameterGroup for [audit](https://docs.aws.amazon.com/documentdb/latest/developerguide/event-auditing.html#event-auditing-enabling-auditing) and
[profiler](https://docs.aws.amazon.com/documentdb/latest/developerguide/profiling.html#profiling.enable-profiling) logs.
2. Enable the corresponding option(s) when creating the `DatabaseCluster`:

```ts
import * as iam from '@aws-cdk/aws-iam';
import * as logs from'@aws-cdk/aws-logs';

declare const myLogsPublishingRole: iam.Role;
declare const vpc: ec2.Vpc;

const cluster = new docdb.DatabaseCluster(this, 'Database', {
  masterUser: {
    username: 'myuser',
  },
  instanceType: ec2.InstanceType.of(ec2.InstanceClass.R5, ec2.InstanceSize.LARGE),
  vpcSubnets: {
    subnetType: ec2.SubnetType.PUBLIC,
  },
  vpc,
  exportProfilerLogsToCloudWatch: true, // Enable sending profiler logs
  exportAuditLogsToCloudWatch: true, // Enable sending audit logs
  cloudWatchLogsRetention: logs.RetentionDays.THREE_MONTHS, // Optional - default is to never expire logs
  cloudWatchLogsRetentionRole: myLogsPublishingRole, // Optional - a role will be created if not provided
});
```

---
_Source: https://npm.io/package/@aws-cdk/aws-docdb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._