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 |
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 |
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 |
CfnTable | A CloudFormation |
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 |
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 |
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 |
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 |
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 |
ICfnTableProps | Properties for defining a |
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. |