Amazon DynamoDB is a serverless NoSQL key-value and document database that delivers single-digit millisecond performance at any scale. It's a fully managed, multi-active, durable database that is replicated across multiple Availability Zones.
Stacktape's DynamoDbTable resource provides a simple abstraction for provisioning and configuring Amazon DynamoDB tables.
When to use DynamoDB
Advantages
- Performance at scale: DynamoDB provides consistent, single-digit millisecond response times at any scale. You can build applications with virtually unlimited throughput and storage.
- Auto-scalable: DynamoDB supports auto-scaling of both read/write capacity and storage, so you don't have to worry about capacity planning.
- Fine-grained access control: You can manage access to your DynamoDB tables using IAM roles and policies.
- Connection-less: Your application connects to DynamoDB via an API, so you don't have to manage a connection pool.
- Pay-per-request pricing: DynamoDB has a "pay-as-you-go" pricing model. If there's no load on your database, it's essentially free.
Disadvantages
- Unfamiliar data modeling: If you're used to relational databases, DynamoDB's NoSQL data modeling can take some getting used to.
- Proprietary: DynamoDB is a proprietary AWS database, which can lead to vendor lock-in.
- Not as feature-rich as other databases: DynamoDB is more of a data store than a fully-featured database like Postgres or MongoDB. For a detailed comparison, refer to this MongoDB vs. DynamoDB article (which is arguably biased).
Basic Usage
The following example defines a simple DynamoDB table.
You can connect a Lambda function to the table to read and write data:
Primary Key
- Simple key: Just a
partitionKey(e.g.,userId). - Composite key:
partitionKey+sortKey(e.g.,userId+createdAt).
Cannot be changed after creation. Every item must include the primary key attribute(s).
Every item in a DynamoDB table is uniquely identified by a primary key. There are two types of primary keys:
- Partition key: A simple primary key, composed of one attribute. DynamoDB uses the partition key's value as input to an internal hash function. The output from the hash function determines the partition (physical storage internal to DynamoDB) in which the item will be stored.
- Partition key and sort key (composite primary key): All items with the same partition key value are stored together, in sorted order by the sort key value.
DynamoDbTablePrimaryKeyAPI referenceParent:DynamoDbTablepartitionKeyRequired
The main key attribute (e.g., userId, orderId). Must be unique if no sort key is used.
Type: DynamoDbAttribute
sortKey
Optional second key for composite keys. Enables range queries and multiple items per partition key.
Type: DynamoDbAttribute
E.g., partition key userId + sort key createdAt lets you query all items for a user sorted by date.
DynamoDbAttributeAPI referenceParent:DynamoDbTableGlobalSecondaryIndex or DynamoDbTablePrimaryKeynameRequired
Attribute name (e.g., userId, email, createdAt).
Type: string
typeRequired
Attribute data type: string, number, or binary.
Type: string ENUM
Possible values: binarynumberstring
This example shows a table with a composite primary key:
Provisioned Throughput
- On-demand (default, no config): Pay per read/write. Best for unpredictable or variable traffic.
- Provisioned: Set fixed read/write capacity. Cheaper at steady, predictable load. Can auto-scale.
DynamoDB has two capacity modes for processing reads and writes on your tables: on-demand and provisioned.
- On-demand: This is the default mode. You pay per request, which is suitable for unpredictable workloads.
- Provisioned: You specify the number of reads and writes per second that you require for your application. This is best for predictable traffic.
You can also configure auto-scaling for provisioned throughput to automatically adjust your table's capacity based on traffic.
DynamoDbProvisionedThroughputAPI referenceParent:DynamoDbTablereadUnitsRequired
Read capacity units per second. 1 unit = one 4 KB strongly consistent read (or two eventually consistent).
Type: number
Requests exceeding this limit get throttled. Use readScaling to auto-adjust.
writeUnitsRequired
Write capacity units per second. 1 unit = one 1 KB write.
Type: number
Requests exceeding this limit get throttled. Use writeScaling to auto-adjust.
writeScaling
Auto-scale write capacity based on actual usage. Scales up/down between min and max units.
Type: DynamoDbWriteScaling
readScaling
Auto-scale read capacity based on actual usage. Scales up/down between min and max units.
Type: DynamoDbReadScaling
Throughput Scaling
Auto-scale read capacity based on actual usage. Scales up/down between min and max units.
The following example shows how to configure auto-scaling for read and write capacity.
DynamoDbReadScalingAPI referenceParent:DynamoDbProvisionedThroughputminUnitsRequired
Minimum read units. Capacity never scales below this.
Type: number
maxUnitsRequired
Maximum read units. Capacity never scales above this.
Type: number
keepUtilizationUnderRequired
Target utilization percentage (e.g., 70). Scales up when usage exceeds this, down when it drops.
Type: number
DynamoDbWriteScalingAPI referenceParent:DynamoDbProvisionedThroughputminUnitsRequired
Minimum write units. Capacity never scales below this.
Type: number
maxUnitsRequired
Maximum write units. Capacity never scales above this.
Type: number
keepUtilizationUnderRequired
Target utilization percentage (e.g., 70). Scales up when usage exceeds this, down when it drops.
Type: number
Point-in-Time Recovery
Restores always create a new table. Adds ~20% to storage cost.
Point-in-time recovery (PITR) helps protect your tables from accidental write or delete operations. With PITR, you can restore that table to any point in time during the last 35 days.
Item-Change Streaming
You can capture a time-ordered sequence of item-level modifications in any DynamoDB table and store this information in a log for up to 24 hours. Applications can access this log and view the data items as they appeared before and after they were modified, in near-real time. This is called DynamoDB Streams.
Streams can be consumed by functions and batch jobs.
You must configure the stream type, which determines what information is written to the stream when an item in the table is modified. Allowed values are:
KEYS_ONLY: Only the key attributes of the modified item.NEW_IMAGE: The entire item as it appeared after it was modified.OLD_IMAGE: The entire item as it appeared before it was modified.NEW_AND_OLD_IMAGES: Both the new and the old images of the item.
Access Control
DynamoDB uses IAM to control who can access the table. To interact with a DynamoDB table, your compute resources must have sufficient permissions. You can grant these permissions in two ways:
- List the table in the
connectToarray of your compute resource. Stacktape will automatically grant the necessary permissions. - Configure
iamRoleStatementson your compute resource to define a custom policy.
Using connectTo is the recommended approach. Here's an example:
If you need more fine-grained control, you can use iamRoleStatements:
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 capacity 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
- PROVISIONED mode:
- 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.
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
AWS (physical) name of the table
- Usage:
$ResourceParam('<<resource-name>>', 'name')
Arn of the table
- Usage:
$ResourceParam('<<resource-name>>', 'arn')
Arn of DynamoDb stream (available only if
streamTypeis configured)- Usage:
$ResourceParam('<<resource-name>>', 'streamArn')
API Reference
DynamoDbTableAPI referencetypeRequired
Type: string "dynamo-db-table"
properties.primaryKeyRequired
The primary key that uniquely identifies each item.
Type: DynamoDbTablePrimaryKey
- Simple key: Just a
partitionKey(e.g.,userId). - Composite key:
partitionKey+sortKey(e.g.,userId+createdAt).
Cannot be changed after creation. Every item must include the primary key attribute(s).
properties.provisionedThroughput
Fixed-capacity mode with predictable pricing. Omit for on-demand (pay-per-request) mode.
Type: DynamoDbProvisionedThroughput
- On-demand (default, no config): Pay per read/write. Best for unpredictable or variable traffic.
- Provisioned: Set fixed read/write capacity. Cheaper at steady, predictable load. Can auto-scale.
properties.enablePointInTimeRecovery
Enable continuous backups with point-in-time recovery (restore to any second in the last 35 days).
Type: boolean
Restores always create a new table. Adds ~20% to storage cost.
properties.streamType
Stream item changes to trigger functions or batch jobs in real time.
Type: string ENUM
Possible values: KEYS_ONLYNEW_AND_OLD_IMAGESNEW_IMAGEOLD_IMAGE
KEYS_ONLY: Only key attributes of the changed item.NEW_IMAGE: The full item after the change.OLD_IMAGE: The full item before the change.NEW_AND_OLD_IMAGES: Both before and after — useful for change tracking and auditing.
properties.secondaryIndexes
Additional indexes for querying by attributes other than the primary key.
Type: Array of DynamoDbTableGlobalSecondaryIndex
Without indexes, you can only query by primary key. Add a secondary index to query by
any attribute (e.g., query orders by status or users by email).
properties.dev
Dev mode: runs locally in Docker by default. Set remote: true to use the deployed table.
Type: DevModeConfig
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true