Namespace Amazon.CDK.AWS.DynamoDB

Amazon DynamoDB Construct Library

---

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.

---

Here is a minimal deployable DynamoDB table definition:

var table = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING }
});

Importing existing tables

To import an existing table into your CDK application, use the Table.fromTableName, Table.fromTableArn or Table.fromTableAttributes factory method. This method accepts table name or table ARN which describes the properties of an already existing table:

User user;

var table = Table.FromTableArn(this, "ImportedTable", "arn:aws:dynamodb:us-east-1:111111111:table/my-table");
// now you can just call methods on the table
table.GrantReadWriteData(user);

If you intend to use the tableStreamArn (including indirectly, for example by creating an @aws-cdk/aws-lambda-event-source.DynamoEventSource on the imported table), you must use the Table.fromTableAttributes method and the tableStreamArn property must be populated.

Keys

When a table is defined, you must define it's schema using the partitionKey (required) and sortKey (optional) properties.

Billing Mode

DynamoDB supports two billing modes:

var table = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    BillingMode = BillingMode.PAY_PER_REQUEST
});

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.

Table Class

DynamoDB supports two table classes:

var table = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    TableClass = TableClass.STANDARD_INFREQUENT_ACCESS
});

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html

Configure AutoScaling for your table

You can have DynamoDB automatically raise and lower the read and write capacities of your table by setting up autoscaling. You can use this to either keep your tables at a desired utilization level, or by scaling up and down at pre-configured times of the day:

Auto-scaling is only relevant for tables with the billing mode, PROVISIONED.

var readScaling = table.AutoScaleReadCapacity(new EnableScalingProps { MinCapacity = 1, MaxCapacity = 50 });

readScaling.ScaleOnUtilization(new UtilizationScalingProps {
    TargetUtilizationPercent = 50
});

readScaling.ScaleOnSchedule("ScaleUpInTheMorning", new ScalingSchedule {
    Schedule = Schedule.Cron(new CronOptions { Hour = "8", Minute = "0" }),
    MinCapacity = 20
});

readScaling.ScaleOnSchedule("ScaleDownAtNight", new ScalingSchedule {
    Schedule = Schedule.Cron(new CronOptions { Hour = "20", Minute = "0" }),
    MaxCapacity = 20
});

Further reading: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/AutoScaling.html https://aws.amazon.com/blogs/database/how-to-use-aws-cloudformation-to-configure-auto-scaling-for-amazon-dynamodb-tables-and-indexes/

Amazon DynamoDB Global Tables

You can create DynamoDB Global Tables by setting the replicationRegions property on a Table:

var globalTable = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    ReplicationRegions = new [] { "us-east-1", "us-east-2", "us-west-2" }
});

When doing so, a CloudFormation Custom Resource will be added to the stack in order to create the replica tables in the selected regions.

The default billing mode for Global Tables is PAY_PER_REQUEST. If you want to use PROVISIONED, you have to make sure write auto-scaling is enabled for that Table:

var globalTable = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    ReplicationRegions = new [] { "us-east-1", "us-east-2", "us-west-2" },
    BillingMode = BillingMode.PROVISIONED
});

globalTable.AutoScaleWriteCapacity(new EnableScalingProps {
    MinCapacity = 1,
    MaxCapacity = 10
}).ScaleOnUtilization(new UtilizationScalingProps { TargetUtilizationPercent = 75 });

When adding a replica region for a large table, you might want to increase the timeout for the replication operation:

var globalTable = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    ReplicationRegions = new [] { "us-east-1", "us-east-2", "us-west-2" },
    ReplicationTimeout = Duration.Hours(2)
});

Encryption

All user data stored in Amazon DynamoDB is fully encrypted at rest. When creating a new table, you can choose to encrypt using the following customer master keys (CMK) to encrypt your table:

Creating a Table encrypted with a customer managed CMK:

var table = new Table(this, "MyTable", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    Encryption = TableEncryption.CUSTOMER_MANAGED
});

// You can access the CMK that was added to the stack on your behalf by the Table construct via:
var tableEncryptionKey = table.EncryptionKey;

You can also supply your own key:

using Amazon.CDK.AWS.KMS;


var encryptionKey = new Key(this, "Key", new KeyProps {
    EnableKeyRotation = true
});
var table = new Table(this, "MyTable", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    Encryption = TableEncryption.CUSTOMER_MANAGED,
    EncryptionKey = encryptionKey
});

In order to use the AWS managed CMK instead, change the code to:

var table = new Table(this, "MyTable", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    Encryption = TableEncryption.AWS_MANAGED
});

Get schema of table or secondary indexes

To get the partition key and sort key of the table or indexes you have configured:

Table table;

var schema = table.Schema();
var partitionKey = schema.PartitionKey;
var sortKey = schema.SortKey;

Kinesis Stream

A Kinesis Data Stream can be configured on the DynamoDB table to capture item-level changes.

using Amazon.CDK.AWS.Kinesis;


var stream = new Stream(this, "Stream");

var table = new Table(this, "Table", new TableProps {
    PartitionKey = new Attribute { Name = "id", Type = AttributeType.STRING },
    KinesisStream = stream
});

Classes

Attribute	Represents an attribute for describing the key schema for the table and indexes.
AttributeType	Data types for attributes within a table.
BillingMode	DynamoDB's Read/Write capacity modes.
CfnGlobalTable	A CloudFormation AWS::DynamoDB::GlobalTable.
CfnGlobalTable.AttributeDefinitionProperty	Represents an attribute for describing the key schema for the table and indexes.
CfnGlobalTable.CapacityAutoScalingSettingsProperty	Configures a scalable target and an autoscaling policy for a table or global secondary index's read or write capacity.
CfnGlobalTable.ContributorInsightsSpecificationProperty	Configures contributor insights settings for a replica or one of its indexes.
CfnGlobalTable.GlobalSecondaryIndexProperty	Allows you to specify a global secondary index for the global table.
CfnGlobalTable.KeySchemaProperty	Represents a single element of a key schema.
CfnGlobalTable.KinesisStreamSpecificationProperty	The Kinesis Data Streams configuration for the specified global table replica.
CfnGlobalTable.LocalSecondaryIndexProperty	Represents the properties of a local secondary index.
CfnGlobalTable.PointInTimeRecoverySpecificationProperty	Represents the settings used to enable point in time recovery.
CfnGlobalTable.ProjectionProperty	Represents attributes that are copied (projected) from the table into an index.
CfnGlobalTable.ReadProvisionedThroughputSettingsProperty	Allows you to specify the read capacity settings for a replica table or a replica global secondary index when the BillingMode is set to PROVISIONED .
CfnGlobalTable.ReplicaGlobalSecondaryIndexSpecificationProperty	Represents the properties of a global secondary index that can be set on a per-replica basis.
CfnGlobalTable.ReplicaSpecificationProperty	Defines settings specific to a single replica of a global table.
CfnGlobalTable.ReplicaSSESpecificationProperty	Allows you to specify a KMS key identifier to be used for server-side encryption.
CfnGlobalTable.SSESpecificationProperty	Represents the settings used to enable server-side encryption.
CfnGlobalTable.StreamSpecificationProperty	Represents the DynamoDB Streams configuration for a table in DynamoDB.
CfnGlobalTable.TargetTrackingScalingPolicyConfigurationProperty	Defines a target tracking scaling policy.
CfnGlobalTable.TimeToLiveSpecificationProperty	Represents the settings used to enable or disable Time to Live (TTL) for the specified table.
CfnGlobalTable.WriteProvisionedThroughputSettingsProperty	Specifies an auto scaling policy for write capacity.
CfnGlobalTableProps	Properties for defining a CfnGlobalTable.
CfnTable	A CloudFormation AWS::DynamoDB::Table.
CfnTable.AttributeDefinitionProperty	Represents an attribute for describing the key schema for the table and indexes.
CfnTable.ContributorInsightsSpecificationProperty	The settings used to enable or disable CloudWatch Contributor Insights.
CfnTable.CsvProperty	The options for imported source files in CSV format.
CfnTable.GlobalSecondaryIndexProperty	Represents the properties of a global secondary index.
CfnTable.ImportSourceSpecificationProperty	Specifies the properties of data being imported from the S3 bucket source to the table.
CfnTable.InputFormatOptionsProperty	The format options for the data that was imported into the target table.
CfnTable.KeySchemaProperty	Represents a single element of a key schema.
CfnTable.KinesisStreamSpecificationProperty	The Kinesis Data Streams configuration for the specified table.
CfnTable.LocalSecondaryIndexProperty	Represents the properties of a local secondary index.
CfnTable.PointInTimeRecoverySpecificationProperty	The settings used to enable point in time recovery.
CfnTable.ProjectionProperty	Represents attributes that are copied (projected) from the table into an index.
CfnTable.ProvisionedThroughputProperty	Throughput for the specified table, which consists of values for ReadCapacityUnits and WriteCapacityUnits .
CfnTable.S3BucketSourceProperty	The S3 bucket that is being imported from.
CfnTable.SSESpecificationProperty	Represents the settings used to enable server-side encryption.
CfnTable.StreamSpecificationProperty	Represents the DynamoDB Streams configuration for a table in DynamoDB.
CfnTable.TimeToLiveSpecificationProperty	Represents the settings used to enable or disable Time to Live (TTL) for the specified table.
CfnTableProps	Properties for defining a CfnTable.
EnableScalingProps	Properties for enabling DynamoDB capacity scaling.
GlobalSecondaryIndexProps	Properties for a global secondary index.
LocalSecondaryIndexProps	Properties for a local secondary index.
Operation	Supported DynamoDB table operations.
ProjectionType	The set of attributes that are projected into the index.
SchemaOptions	Represents the table schema attributes.
SecondaryIndexProps	Properties for a secondary index.
StreamViewType	When an item in the table is modified, StreamViewType determines what information is written to the stream for this table.
SystemErrorsForOperationsMetricOptions	Options for configuring a system errors metric that considers multiple operations.
Table	Provides a DynamoDB table.
TableAttributes	Reference to a dynamodb table.
TableClass	DynamoDB's table class.
TableEncryption	What kind of server-side encryption to apply to this table.
TableOptions	Properties of a DynamoDB Table.
TableProps	Properties for a DynamoDB Table.
UtilizationScalingProps	Properties for enabling DynamoDB utilization tracking.

Interfaces

CfnGlobalTable.IAttributeDefinitionProperty	Represents an attribute for describing the key schema for the table and indexes.
CfnGlobalTable.ICapacityAutoScalingSettingsProperty	Configures a scalable target and an autoscaling policy for a table or global secondary index's read or write capacity.
CfnGlobalTable.IContributorInsightsSpecificationProperty	Configures contributor insights settings for a replica or one of its indexes.
CfnGlobalTable.IGlobalSecondaryIndexProperty	Allows you to specify a global secondary index for the global table.
CfnGlobalTable.IKeySchemaProperty	Represents a single element of a key schema.
CfnGlobalTable.IKinesisStreamSpecificationProperty	The Kinesis Data Streams configuration for the specified global table replica.
CfnGlobalTable.ILocalSecondaryIndexProperty	Represents the properties of a local secondary index.
CfnGlobalTable.IPointInTimeRecoverySpecificationProperty	Represents the settings used to enable point in time recovery.
CfnGlobalTable.IProjectionProperty	Represents attributes that are copied (projected) from the table into an index.
CfnGlobalTable.IReadProvisionedThroughputSettingsProperty	Allows you to specify the read capacity settings for a replica table or a replica global secondary index when the BillingMode is set to PROVISIONED .
CfnGlobalTable.IReplicaGlobalSecondaryIndexSpecificationProperty	Represents the properties of a global secondary index that can be set on a per-replica basis.
CfnGlobalTable.IReplicaSpecificationProperty	Defines settings specific to a single replica of a global table.
CfnGlobalTable.IReplicaSSESpecificationProperty	Allows you to specify a KMS key identifier to be used for server-side encryption.
CfnGlobalTable.ISSESpecificationProperty	Represents the settings used to enable server-side encryption.
CfnGlobalTable.IStreamSpecificationProperty	Represents the DynamoDB Streams configuration for a table in DynamoDB.
CfnGlobalTable.ITargetTrackingScalingPolicyConfigurationProperty	Defines a target tracking scaling policy.
CfnGlobalTable.ITimeToLiveSpecificationProperty	Represents the settings used to enable or disable Time to Live (TTL) for the specified table.
CfnGlobalTable.IWriteProvisionedThroughputSettingsProperty	Specifies an auto scaling policy for write capacity.
CfnTable.IAttributeDefinitionProperty	Represents an attribute for describing the key schema for the table and indexes.
CfnTable.IContributorInsightsSpecificationProperty	The settings used to enable or disable CloudWatch Contributor Insights.
CfnTable.ICsvProperty	The options for imported source files in CSV format.
CfnTable.IGlobalSecondaryIndexProperty	Represents the properties of a global secondary index.
CfnTable.IImportSourceSpecificationProperty	Specifies the properties of data being imported from the S3 bucket source to the table.
CfnTable.IInputFormatOptionsProperty	The format options for the data that was imported into the target table.
CfnTable.IKeySchemaProperty	Represents a single element of a key schema.
CfnTable.IKinesisStreamSpecificationProperty	The Kinesis Data Streams configuration for the specified table.
CfnTable.ILocalSecondaryIndexProperty	Represents the properties of a local secondary index.
CfnTable.IPointInTimeRecoverySpecificationProperty	The settings used to enable point in time recovery.
CfnTable.IProjectionProperty	Represents attributes that are copied (projected) from the table into an index.
CfnTable.IProvisionedThroughputProperty	Throughput for the specified table, which consists of values for ReadCapacityUnits and WriteCapacityUnits .
CfnTable.IS3BucketSourceProperty	The S3 bucket that is being imported from.
CfnTable.ISSESpecificationProperty	Represents the settings used to enable server-side encryption.
CfnTable.IStreamSpecificationProperty	Represents the DynamoDB Streams configuration for a table in DynamoDB.
CfnTable.ITimeToLiveSpecificationProperty	Represents the settings used to enable or disable Time to Live (TTL) for the specified table.
IAttribute	Represents an attribute for describing the key schema for the table and indexes.
ICfnGlobalTableProps	Properties for defining a CfnGlobalTable.
ICfnTableProps	Properties for defining a CfnTable.
IEnableScalingProps	Properties for enabling DynamoDB capacity scaling.
IGlobalSecondaryIndexProps	Properties for a global secondary index.
ILocalSecondaryIndexProps	Properties for a local secondary index.
IScalableTableAttribute	Interface for scalable attributes.
ISchemaOptions	Represents the table schema attributes.
ISecondaryIndexProps	Properties for a secondary index.
ISystemErrorsForOperationsMetricOptions	Options for configuring a system errors metric that considers multiple operations.
ITable	An interface that represents a DynamoDB Table - either created with the CDK, or an existing one.
ITableAttributes	Reference to a dynamodb table.
ITableOptions	Properties of a DynamoDB Table.
ITableProps	Properties for a DynamoDB Table.
IUtilizationScalingProps	Properties for enabling DynamoDB utilization tracking.