DynamoDB + AWS CDK - The Ultimate Guide w/ Examples

Why DynamoDB with AWS CDK?

AWS CDK (Cloud Development Kit) is an open-source software development framework provided by AWS. It simplifies the cloud-based application development process and supports many programming languages, including Java, JavaScript, TypeScript, Python, and C#.

AWS CDK provides separate libraries in all the above languages for DynamoDB. You can use those libraries to create and manage DynamoDB tables easily. In addition, it allows configuring billing models, scaling options, global tables, encryption, and many other DynamoDB features with minimum effort. So, let's see how we can use AWS CDK with DynamoDB.

Prerequisites

In this article, I will be using AWS CDK for TypeScript to demonstrate examples.

So, make sure you have:

• AWS profile set up
• Node.js installed
• TypeScript installed

You should be able to run the following commands without any issues:

node -v # Checks Node.js version
aws sts get-caller-identity # Checks the validity of AWS profile and setup
node -v # Checks Node.js version
aws sts get-caller-identity # Checks the validity of AWS profile and setup

Step 1 - Initializing a New Project with AWS CDK

Since we are using TypeScript for the demonstration, we need to install AWS CDK for JavaScript/TypeScript using NPM. You can either install the complete AWS CDK or only install the AWS CDK for the DynamoDB client.

npm i -g aws-cdk // Complete JavaScript AWS CDK
npm i @aws-cdk/aws-dynamodb // AWS JavaScript CDK for DynamoDB
npm i -g aws-cdk // Complete JavaScript AWS CDK
npm i @aws-cdk/aws-dynamodb // AWS JavaScript CDK for DynamoDB

After installation, you can create a new project using AWS CDK as below:

mkdir aws-cdk-dynamodb
cd aws-cdk-dynamodb
cdk init sample-app --language=typescript
mkdir aws-cdk-dynamodb
cd aws-cdk-dynamodb
cdk init sample-app --language=typescript

To get started, AWS CDK provides 3 templates named app, lib, and sample-app. The above command generates a project using the sample-app template.

Once the project is initialized, you will find a file named aws-cdk-dynamodb-stack.ts in the lib folder. By default, it will look like the below:

import { Duration, Stack, StackProps } from 'aws-cdk-lib';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as subs from 'aws-cdk-lib/aws-sns-subscriptions';
import * as sqs from 'aws-cdk-lib/aws-sqs';
import { Construct } from 'constructs';

export class AwsCdkDynamodbStack extends Stack {
 constructor(scope: Construct, id: string, props?: StackProps) {
  super(scope, id, props);

  const queue = new sqs.Queue(this, 'AwsCdkDynamodbQueue', {
   visibilityTimeout: Duration.seconds(300)
  });

  const topic = new sns.Topic(this, 'AwsCdkDynamodbTopic');

  topic.addSubscription(new subs.SqsSubscription(queue));
 }
}
import { Duration, Stack, StackProps } from 'aws-cdk-lib';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as subs from 'aws-cdk-lib/aws-sns-subscriptions';
import * as sqs from 'aws-cdk-lib/aws-sqs';
import { Construct } from 'constructs';

export class AwsCdkDynamodbStack extends Stack {
 constructor(scope: Construct, id: string, props?: StackProps) {
  super(scope, id, props);

  const queue = new sqs.Queue(this, 'AwsCdkDynamodbQueue', {
   visibilityTimeout: Duration.seconds(300)
  });

  const topic = new sns.Topic(this, 'AwsCdkDynamodbTopic');

  topic.addSubscription(new subs.SqsSubscription(queue));
 }
}

Since we are focusing on DynamoDB, you can remove all the code related to SNS and SQS and clear the file for the next steps.

Step 2 - Creating a New DynamoDB Table using AWS CDK

With AWS CDK, you can easily create a DynamoDB table by only passing 2 properties: partitionKey and billingMode.

import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';

export class AwsCdkDynamodbStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Table', { 
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, 
    });
  }
}
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';

export class AwsCdkDynamodbStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Table', { 
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, 
    });
  }
}

DynamoDB provides 2 billing modes, and the Pay Per Request mode has been selected in the above example. If you wish to use Provisioned mode, you can simply change the billingMode property to dynamodb.BillingMode.PROVISIONED. 

In addition, you can configure read and write capacities, sort key, table class, local secondary index, and point in time recovery when creating a DynamoDB table using AWS CDK. However, it is not mandatory to configure all these properties.

import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';

export class AwsCdkDynamodbStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Table', { 
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
      billingMode: dynamodb.BillingMode.PROVISIONED, 
      readCapacity: 20,
      writeCapacity: 20,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      sortKey: {name: 'createdAt', type: dynamodb.AttributeType.NUMBER},
      pointInTimeRecovery: true,
      tableClass: dynamodb.TableClass.STANDARD_INFREQUENT_ACCESS,
    });

     table.addLocalSecondaryIndex({
       indexName: 'statusIndex',
       sortKey: {name: 'status', type: dynamodb.AttributeType.STRING},
       projectionType: dynamodb.ProjectionType.ALL
    });
  }
}
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import { Duration, Stack, StackProps } from 'aws-cdk-lib';

export class AwsCdkDynamodbStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new dynamodb.Table(this, 'Table', { 
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
      billingMode: dynamodb.BillingMode.PROVISIONED, 
      readCapacity: 20,
      writeCapacity: 20,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      sortKey: {name: 'createdAt', type: dynamodb.AttributeType.NUMBER},
      pointInTimeRecovery: true,
      tableClass: dynamodb.TableClass.STANDARD_INFREQUENT_ACCESS,
    });

     table.addLocalSecondaryIndex({
       indexName: 'statusIndex',
       sortKey: {name: 'status', type: dynamodb.AttributeType.STRING},
       projectionType: dynamodb.ProjectionType.ALL
    });
  }
}

Similarly, you can easily use tools like Dynobase to create DynamoDB tables with few clicks. Learn More.

Step 3 - Auto Scaling Configurations

If you choose Provisioned billing mode for your table, you must manually configure your table's read and write capacity units. With AWS CDK, you can easily create scale-up or scale-down events for specific times of the day.

const readScaling = table.autoScaleReadCapacity({ minCapacity: 5, maxCapacity: 100 }); 

// Utilization based scaling
readScaling.scaleOnUtilization({ targetUtilizationPercent: 100, }); 

// Time based scaling
readScaling.scaleOnSchedule('ScaleUpAtsix', { 
  schedule: appscaling.Schedule.cron({ hour: '6', minute: '0' }), 
  minCapacity: 75, 
});
const readScaling = table.autoScaleReadCapacity({ minCapacity: 5, maxCapacity: 100 }); 

// Utilization based scaling
readScaling.scaleOnUtilization({ targetUtilizationPercent: 100, }); 

// Time based scaling
readScaling.scaleOnSchedule('ScaleUpAtsix', { 
  schedule: appscaling.Schedule.cron({ hour: '6', minute: '0' }), 
  minCapacity: 75, 
});

Step 4 - Creating Global Tables using AWS CDK

DynamoDB Global Tables play a vital role in disaster recovery. With AWS CDK, you can easily configure Global Tables. The below code examples shows the minimum configuration you need to create Global Tables in 3 different regions.

const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
});
const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
});

By default, Global Tables will have Pay Per Request billing mode. But, if you need, you can change it to the Provisioned mode by including the billingMode: dynamodb.BillingMode.PROVISIONED property in the table definition.

const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
  billingMode: dynamodb.BillingMode.PROVISIONED,
});
const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
  billingMode: dynamodb.BillingMode.PROVISIONED,
});

In addition, default Global Tables will have a default replication timeout period of 30 minutes. However, if you have a large-scale table, it is advised to increase the timeout duration using replicationTimeout property.

const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
  billingMode: dynamodb.BillingMode.PROVISIONED,
  replicationTimeout: Duration.hours(3),
});
const globalTable = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING }, 
  replicationRegions: ['us-east-1', 'us-east-2', 'us-west-1'], 
  billingMode: dynamodb.BillingMode.PROVISIONED,
  replicationTimeout: Duration.hours(3),
});

Step 5 - DynamoDB Table Encryption using AWS CDK

As we all know, DynamoDB supports encryption at rest. When creating a table, you can select AWS-owned CMK, AWS-managed CMK or Customer-managed CMK as the encryption option. By default, AWS DynamoDB tables are encrypted with a master key owned by AWS.

The below examples show how to encrypt your DynamoDB tables with Customer managed and AWS manages CMKs using AWS CDK.

Customer-managed CMK

const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
});

// CMK can be accessed using table.encryptionKey
const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
});

// CMK can be accessed using table.encryptionKey

You can also create your own encryption key using AWS KMS and pass it to the table definition as shown below:

import * as kms from '@aws-cdk/aws-kms';

const encryptionKey = new kms.Key(this, 'Key', {
  enableKeyRotation: true,
});

const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
  encryptionKey, 
});
import * as kms from '@aws-cdk/aws-kms';

const encryptionKey = new kms.Key(this, 'Key', {
  enableKeyRotation: true,
});

const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED,
  encryptionKey, 
});

AWS-managed CMK

const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.AWS_MANAGED,
});
const table = new dynamodb.Table(this, 'MyTable', {
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  encryption: dynamodb.TableEncryption.AWS_MANAGED,
});

Step 6 - Kinesis Stream using AWS CDK

You can also configure AWS Kinesis Stream on your DynamoDB table using AWS CDK. It can be used to capture item-level changes in the DynamoDB tables.

import * as kinesis from 'aws-cdk-lib/aws-kinesis'; 

const stream = new kinesis.Stream(this, 'Stream'); 

const table = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  kinesisStream: stream, 
});
import * as kinesis from 'aws-cdk-lib/aws-kinesis'; 

const stream = new kinesis.Stream(this, 'Stream'); 

const table = new dynamodb.Table(this, 'Table', { 
  partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
  kinesisStream: stream, 
});

Step 7 - Deploying

As the final step, you need to deploy all the changes in your project using cdk deploy command. It will take some time to provision the resources in your AWS account, and you will be able to monitor them in the AWS management console.