Skip navigation links

Package software.amazon.awscdk.services.dynamodb

Amazon DynamoDB Construct Library

See: Description

Package software.amazon.awscdk.services.dynamodb Description

Amazon DynamoDB Construct Library

---

cfn-resources: Stable

cdk-constructs: Stable


Here is a minimal deployable DynamoDB table definition:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 
 Table table = new Table(this, "Table", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING())));
 

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:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object 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:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 
 Table table = new Table(this, "Table", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .billingMode(dynamodb.BillingMode.getPAY_PER_REQUEST()));
 

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

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.

 // Example automatically generated. See https://github.com/aws/jsii/issues/826
 IScalableTableAttribute readScaling = table.autoScaleReadCapacity(new EnableScalingProps().minCapacity(1).maxCapacity(50));
 
 readScaling.scaleOnUtilization(new UtilizationScalingProps()
         .targetUtilizationPercent(50));
 
 readScaling.scaleOnSchedule("ScaleUpInTheMorning", new ScalingSchedule()
         .schedule(appscaling.Schedule.cron(new CronOptions().hour("8").minute("0")))
         .minCapacity(20));
 
 readScaling.scaleOnSchedule("ScaleDownAtNight", new ScalingSchedule()
         .schedule(appscaling.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:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 
 Table globalTable = new Table(this, "Table", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .replicationRegions(asList("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:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object globalTable = Table.Builder.create(this, "Table")
         .partitionKey(Map.of("name", "id", "type", dynamodb.AttributeType.getSTRING()))
         .replicationRegions(asList("us-east-1", "us-east-2", "us-west-2"))
         .billingMode(BillingMode.getPROVISIONED())
         .build();
 
 globalTable.autoScaleWriteCapacity({
   minCapacity: 1,
   maxCapacity: 10,
 }).scaleOnUtilization(Map.of("targetUtilizationPercent", 75));
 

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

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object globalTable = Table.Builder.create(this, "Table")
         .partitionKey(Map.of("name", "id", "type", dynamodb.AttributeType.getSTRING()))
         .replicationRegions(asList("us-east-1", "us-east-2", "us-west-2"))
         .replicationTimeout(Duration.hours(2))
         .build();
 

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:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 
 Table table = new Table(stack, "MyTable", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .encryption(TableEncryption.getCUSTOMER_MANAGED()));
 
 // You can access the CMK that was added to the stack on your behalf by the Table construct via:
 Object tableEncryptionKey = table.getEncryptionKey();
 

You can also supply your own key:

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 import software.amazon.awscdk.services.kms.*;
 
 Key encryptionKey = new Key(stack, "Key", new KeyProps()
         .enableKeyRotation(true));
 Table table = new Table(stack, "MyTable", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .encryption(TableEncryption.getCUSTOMER_MANAGED())
         .encryptionKey(encryptionKey));
 

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

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 
 Table table = new Table(stack, "MyTable", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .encryption(TableEncryption.getAWS_MANAGED()));
 

Get schema of table or secondary indexes

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

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Object { partitionKey, sortKey } = table.schema();
 
 // In case you want to get schema details for any secondary index
 
 Object { partitionKey, sortKey } = table.schema(INDEX_NAME);
 

Kinesis Stream

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

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 import software.amazon.awscdk.services.kinesis.*;
 
 Stream stream = new Stream(this, "Stream");
 
 Table table = new Table(this, "Table", new TableProps()
         .partitionKey(new Attribute().name("id").type(dynamodb.AttributeType.getSTRING()))
         .kinesisStream(stream));
 
Skip navigation links