logoStacktape docs




DynamoDb tables

Overview and basic concepts

  • Amazon DynamoDB is a NoSQL key-value datastore with support for JSON documents.
  • It can deliver single-digit millisecond performance at large scale.
  • DynamoDB is serverless and fully managed. It's easy to set up, operate and scale. You don't have to worry about capacity scaling, hardware & VM provisioning, database setup, patching and more.
  • It's multi-active, replicated across multiple Availability Zones, durable and secure. It also supports in-memory caching.
  • DynamoDB doesn't have it's own query language. Instead, you can use aws-sdk to access the database.

When to use

Advantages

  • Performance at scale - DynamoDB supports some of the world’s largest scale applications by providing consistent, single-digit millisecond response times at any scale. You can build applications with virtually unlimited throughput and storage.
  • Auto-scalable - DynamoDb has a support for auto-scaling of both read/write capacity and storage.
  • IAM access - You can manage the access to your DynamoDb database with AWS Identity and Access management rules.
  • Connection-less - You don't have to worry about connection pool exhaustions.
  • Serverless - DynamoDb supports "pay-as-you-go" pricing. If there's no database load, it's essentially free.

Disadvantages

  • Relatively unmature - Not as mature as relational (SQL) databases. It has a signficantly less rich ecosystem.
  • Proprietary - DynamoDb is a properitary AWS database.
  • Not feature rich - DynamoDb is more of a data-store, not a fully-featured database such as Postgres or MongoDb. For a detailed comparison (even tho arguably slightly biased), refer to MongoDb comparsion.

Basic usage

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: id
type: string
myFunction:
type: function
properties:
packageConfig:
filePath: path/to/my/lambda.ts
environment:
- name: TABLE_NAME
value: $Param('myDynamoDbTable', 'DynamoDbTable::Name')
accessControl:
allowAccessTo:
- myDynamoTable

Lambda function connected to the DynamoDb table

import { DynamoDB } from '@aws-sdk/client-dynamodb';
const dynamoDb = new DynamoDB({});
export default async (event, context) => {
// Put item to the table
await dynamoDb.putItem({
Item: { id: { S: 'my_id_1' }, writeTimestamp: { S: new Date().toLocaleTimeString() } },
TableName: process.env.TABLE_NAME
});
// Get item from the table
const item = await dynamoDb.getItem({
Key: { id: { S: 'my_id_1' } },
TableName: process.env.TABLE_NAME
});
};

Lambda function written in typescript that accesses the DynamoDb table

Primary key

  • Primary key uniquely identifies each item in the table
  • Two different kinds of primary keys are supported:
    • simple primary key - you only specify partitionKey
    • composite primary key - you specify both partitionKey and sortKey
  • Primary key specification cannot be modified during updates (after the table is created).
  • The attribute must be top-level (not nested) field.
  • Each document saved to the table must contain the primary key attribute(s).
  • To learn more about primary keys, refet to AWS docs
partitionKey
Required

Specifies a single top-level attribute which must be included in each table item.

Type: DynamoDbKeyAttribute

  • In a table that has only partitionKey and no sortKey, no two items can have the same partitionKey.
  • Internally, DynamoDB uses the partitionKey's value as an input to an internal hash function. The output from the hash function determines the partition (physical location) where the item is stored.

sortKey

If specified, this attribute becomes part of the composite primary key together with partitionKey

Type: DynamoDbKeyAttribute

  • Using a sortKey in the primary key gives you additional flexibility when querying data.
  • In a table that has a partitionKey and a sortKey, it's possible for two items to have the same partitionKey value. However, those two items must have different sortKey values.
  • All items with the same partitionKey are stored together in the same partion in sorted order by sortKey value.

DynamoDbKeyAttribute  API reference
Parent API reference: DynamoDbTablePrimaryKey
name
Required

Name of the top-level attribute

Type: string

  • This attribute must be included in every item that is written to the table.

type
Required

Type of the key attribute

Type: string ENUM

Possible values: binarynumberstring

resources:
myDynamoTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: this_attribute_will_be_partition_key
type: string
sortKey:
name: this_attribute_will_be_sort_key
type: number

Example composite primary key.

Provisioned throughput

  • When you specify provisionedThroughput, the table will run in the provisioned mode and you need to specify read and write throughput for your table.
  • This can give you cost predictability and lower costs, but your table might not be able to handle an unpredictable load.
  • If provisionedThroughput is not configured, the table runs and is billed in an on-demand mode. This means you are only paying for what you use.
  • To learn more about differences between provisioned and on-demand modes, refer to AWS docs
DynamoDbProvisionedThroughput  API reference
Parent API reference: DynamoDbTable
readUnits
Required

Number of read units available every second

Type: number

  • Each read unit represent either:
    • one strongly consistent read
    • two eventually consistent reads
  • If exceeded, you receive a ThrottlingException.
  • The above applies for an item of up to 4 KB in size. If you need to read an item that is larger than 4 KB, additional read capacity units are consumed.

writeUnits
Required

Number of write units available every second

Type: number

  • One write unit represents one write per second for an item of up to 1 KB in size.
  • If exceeded, you receive a ThrottlingException.
  • If you need to write an item that is larger than 1 KB, additional write capacity units are consumed.

writeScaling

Auto scaling configuration for write units

Type: DynamoDbWriteScaling

  • Even in provisioned mode, you can configure throughput scaling based on load.
  • The table throughput scales up or down once the specified thresholds are met.
  • Compared to on-demand mode (default, if you don't specify provisionedThroughput), you have more control of how your table will scale and can save costs. However, your table might not be able to scale enough for an unpredictable load.
  • To learn more, refer to this detailed AWS article

readScaling

Auto scaling configuration for read units

Type: DynamoDbReadScaling

  • Even in provisioned mode, you can configure throughput scaling based on load.
  • The table throughput scales up or down once the specified thresholds are met.
  • Compared to on-demand mode (default, if you don't specify provisionedThroughput), you have more control of how your table will scale and can save costs. However, your table might not be able to scale enough for an unpredictable load.
  • To learn more, refer to this detailed AWS article

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: this_attribute_will_be_id
type: string
provisionedThroughput:
readUnits: 4
writeUnits: 4

Scaling

  • Even in provisioned mode, you can configure throughput scaling based on load.
  • The table throughput scales up or down once the specified thresholds are met.
  • Compared to on-demand mode (default, if you don't specify provisionedThroughput), you have more control of how your table will scale and can save costs. However, your table might not be able to scale enough for an unpredictable load.
  • To learn more, refer to this detailed AWS article

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: this_attribute_will_be_id
type: string
provisionedThroughput:
readUnits: 4
writeUnits: 4
readScaling:
minUnits: 4
maxUnits: 10
keepUtilizationUnder: 80

DynamoDbReadScaling  API reference
Parent API reference: DynamoDbProvisionedThroughput
minUnits
Required

Minimum number of provisioned read units (per second) available.

Type: number

  • Available read units will never scale down below this threshold

maxUnits
Required

Maximum number of provisioned read units (per second) table can scale up to

Type: number

  • Available read units will never scale up above the defined threshold

keepUtilizationUnder
Required

Percentual utilization threshold for scaling

Type: number

  • If the table's consumed read capacity exceeds your target utilization (or falls below the target) for a sustained amount of time, the provisioned capacity is increased (decreased).

DynamoDbWriteScaling  API reference
Parent API reference: DynamoDbProvisionedThroughput
minUnits
Required

Minimum number of provisioned write units (per second) available

Type: number

Available write units will never scale down below this threshold

maxUnits
Required

Maximum number of provisioned write units (per second) table can scale up to

Type: number

Available write units will never scale up above the defined threshold

keepUtilizationUnder
Required

Percentual utilization threshold for scaling

Type: number

  • If the table's consumed write capacity exceeds your target utilization (or falls below the target) for a sustained amount of time, the provisioned capacity is increased (decreased).

Point-in-time recovery

No description

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: this_attribute_will_be_id
type: string
enablePointInTimeRecovery: true

Item-change streaming

  • DynamoDb allows yout to stream item-level modifications in the table.
  • Item-change log is preserved for up to 24 hours.
  • Streams can be consumed by functions and batch jobs.
  • You must configure stream type. It determines what information is written to the stream for this table when the item in the table is modified. Allowed values are:
    • KEYS_ONLY - Only the key attributes of the modified item are written to the stream.
    • NEW_IMAGE - The entire item, as it appears after it was modified, is written to the stream.
    • OLD_IMAGE - The entire item, as it appeared before it was modified, is written to the stream.
    • NEW_AND_OLD_IMAGES - Both the new and the old item images of the item are written to the stream.

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: this_attribute_will_be_id
type: string
streamType: NEW_AND_OLD_IMAGES

Access control

  • DynamoDb uses AWS IAM (Identity and Access Management) to control who can access the table.
  • To interact with the DynamoDb table, your resources must have the sufficient permissions. You can give these permissions in 2 ways:

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: id
type: string
myFunction:
type: function
properties:
packageConfig:
filePath: path/to/my/lambda.ts
environment:
- name: TABLE_NAME
value: $Param('myDynamoDbTable', 'DynamoDbTable::Name')
accessControl:
allowAccessTo:
- myDynamoDbTable

resources:
myDynamoDbTable:
type: dynamo-db-table
properties:
primaryKey:
partitionKey:
name: id
type: string
myFunction:
type: function
properties:
packageConfig:
filePath: path/to/my/lambda.ts
environment:
- name: TABLE_NAME
value: $Param('myDynamoDbTable', 'DynamoDbTable::Name')
accessControl:
iamRoleStatements:
- Resource:
- $Param('myDynamoDbTable', 'Arn')
Effect: 'Allow'
Action:
- 'dynamodb:Get*'
- 'dynamodb:Query'
- 'dynamodb:Scan'
- 'dynamodb:Delete*'
- 'dynamodb:Update*'
- 'dynamodb:PutItem'

Pricing

You are charged for:

  • Read and Write operations:
    • PROVISIONED mode:
      • You configure how much read/write capacity table has at any moment:
      • WCU (write capaity unit) - $0.00065 - $0.000975 per WCU per hour
      • RCU (read capacity units - $0.00013 - $0.000195 per RCU per hour
      • To learn more, refer to AWS pricing page
    • ON DEMAND mode
      • Pay as you go
      • $1.25 - $1.875 per million write request units
      • $0.25- $0.375 per million read request units
      • To learn more, refer to AWS pricing page
  • Storage:
    • First 25 GB stored per month is free
    • $0.25 - $0.375 per GB-month thereafter
  • Continuous backup:
    • Applies when point-in-time-recovery is enabled
    • $0.20 -$0.30 per GB-month
  • Data transfer:
    • IN transfer: free
    • OUT to AWS services in the same region: free
    • OUT to internet: first 1 GB free, then $0.09 -$0.15 per GB

FREE TIER (eligible for first 12 months):

  • 25 GB of Storage
  • 25 provisioned Write Capacity Units (WCU)
  • 25 provisioned Read Capacity Units (RCU)
  • Enough to handle up to ~200M requests per month.

API Reference

DynamoDbTable  API reference
type
Required

No description

Type: string "dynamo-db-table"

properties.primaryKey
Required

Configures primary key for the table

Type: DynamoDbTablePrimaryKey

  • Primary key uniquely identifies each item in the table
  • Two different kinds of primary keys are supported:
    • simple primary key - you only specify partitionKey
    • composite primary key - you specify both partitionKey and sortKey
  • Primary key specification cannot be modified during updates (after the table is created).
  • The attribute must be top-level (not nested) field.
  • Each document saved to the table must contain the primary key attribute(s).
  • To learn more about primary keys, refet to AWS docs

properties.provisionedThroughput

Configures read and write throughput capabilities of the table

Type: DynamoDbProvisionedThroughput

  • When you specify provisionedThroughput, the table will run in the provisioned mode and you need to specify read and write throughput for your table.
  • This can give you cost predictability and lower costs, but your table might not be able to handle an unpredictable load.
  • If provisionedThroughput is not configured, the table runs and is billed in an on-demand mode. This means you are only paying for what you use.
  • To learn more about differences between provisioned and on-demand modes, refer to AWS docs

properties.enablePointInTimeRecovery

Enables continuous backups with point-in-time recovery capability.

Type: boolean

  • Point-in-time recovery enables you to restore table to any point in time during the last 35 days
  • The point-in-time recovery process always restores the data to a new table. You can restore data to the same table.
  • Enabling point-in-time recovery can result in additional charges. To learn more, refer to AWS DynamoDB pricing

properties.streamType

Enables streaming of table item changes and configures the stream type

Type: string ENUM

Possible values: KEYS_ONLYNEW_AND_OLD_IMAGESNEW_IMAGEOLD_IMAGE

  • Stream type determines what information is written to the stream for this table when the item in the table is modified.
  • Streams can be consumed by functions and batch jobs.
  • Allowed values are:
    • KEYS_ONLY - Only the key attributes of the modified item are written to the stream.
    • NEW_IMAGE - The entire item, as it appears after it was modified, is written to the stream.
    • OLD_IMAGE - The entire item, as it appeared before it was modified, is written to the stream.
    • NEW_AND_OLD_IMAGES - Both the new and the old item images of the item are written to the stream.

overrides

Overrides one or more properties of the specified child resource.

Type: Object

  • Child resouces are specified using their descriptive name (e.g. DbInstance or Events.0.HttpApiRoute).
  • To see all configurable child resources for given Stacktape resource, use stacktape stack-info --detailed command.
  • To see the list of properties that can be overriden, refer to AWS Cloudformation docs.