DynamoDB

This page contains information about using DynamoDB service supported in Handel. This service provisions a DynamoDB table for use by other AWS services.

Service Limitations

No Update Support

This service intentionally does not support updates. Once a table is created, certain updates to the table will cause a new one to be created and the old one deleted. In an effort to avoid unwanted data loss, we don’t update this service automatically.

Parameters

Parameter Type Required Default Description
type string Yes   This must always be dynamodb for this service type.
table_name string No ‘<app name>-<environment>-<service name>-dynamodb’ Sets the name of the Dynamod table to be created.
partition_key PartitionKey Yes   The ParitionKey element details how you want your partition key specified.
sort_key SortKey No None The SortKey element details how you want your sort key specified. Unlike partition_key, sort_key is not required.
provisioned_throughput ProvisionedThroughput No 1 for read and write The ProvisionedThroughput element details how much provisioned IOPS you want on your table for reads and writes.
ttl_attribute string No None Configures the attribute to use for DynamoDB TTL and auto-expiration.
local_indexes LocalIndexes No   You can configure local secondary indexes for fast queries on a different sort key within the same partition key.
stream_view_type string No   When present, the stream view type element indicates that a dynamodb stream will be used and specifies what information is written to the stream. Options are KEYS_ONLY, NEW_IMAGE, OLD_IMAGE and NEW_AND_OLD_IMAGES.
global_indexes GlobalIndexes No   You can configure global secondary indexes for fast queries on other partition and sort keys in addition to the ones on your table.
tags Resource Tags No   Any tags you want to apply to your Dynamo Table

PartitionKey

The PartitionKey element tells how to configure your partition key in DynamoDB. It has the following schema:

partition_key:
  name: <key_name>
  type: <String|Number>

SortKey

The SortKey element tells how to configure your sort key in DynamoDB. It has the following schema:

sort_key:
  name: <key_name>
  type: <String|Number>

ProvisionedThroughput

The ProvisionedThroughput element tells many IOPS to provision for your table for reads and writes. It has the following schema:

provisioned_throughput:
  read_capacity_units: <number or range> # Required
  write_capacity_units: <number or range> # Required
  read_target_utilization: <percentage> # Default: 70 (if autoscaling is enabled)
  write_target_utilization: <percentage> # Default: 70 (if autoscaling is enabled)

Autoscaling Throughput

If a range (ex: 1-10) is provided to read_capacity_units or write_capacity_units, an autoscaling rule will be created with the min and max values from the range and target utilization as specified by read_target_utilization and write_target_utilization.

The following configuration will cause the read capacity to be automatically scaled between 10 and 100, with a target usage of 50%. The write capacity will scale between 1-10, with a target usage of 70% (the default).

provisioned_throughput:
  read_capacity_units: 10-100
  write_capacity_units: 1-10
  read_target_utilization: 50

LocalIndexes

The LocalIndexes element allows you to configure local secondary indexes on your table for alternate query methods. It has the following schema:

local_indexes:
- name: <string> # Required
  sort_key: # Required
    name: <string>
    type: <String|Number>
  attributes_to_copy: # Required
  - <string>

GlobalIndexes

The GlobalIndexes element allows you to configure global secondary indexes on your table for alternate query methods. It allows you to specify a different partition key than the main table. It has the following schema:

global_indexes:
- name: <string> # Required
  partition_key: # Required
    name: <string>
    type: <String|Number>
  sort_key: # Optional
    name: <string>
    type: <String|Number>
  attributes_to_copy: # Optional. If not specified, will default to ALL
  - <string>
  provisioned_throughput: # Optional
    read_capacity_units: <number or range> # Required
    write_capacity_units: <number or range> # Required
    read_target_utilization: <percentage> # Default: Matches table config
    write_target_utilization: <percentage> # Default: Matches table config

The provisioned throughput configuration for Global Secondary Indexes matches that for the table. If the provisioned throughput is not configured for the index, the table’s configuration will be used, including any autoscaling configuration.

Warning

Be aware that using Global Secondary Indexes can greatly increase your cost. When you use global indexes, you are effectively creating a new table. This will increase your cost by the amount required for storage and allocated IOPS for the global index.

Example Handel File

version: 1

name: my-ecs-app

environments:
  dev:
    webapp:
      type: dynamodb
      partition_key: # Required, NOT updateable
        name: MyPartionKey
        type: String
      sort_key:
        name: MySortKey
        type: Number
      provisioned_throughput:
        read_capacity_units: 1-20 #Autoscale reads, but not writes
        write_capacity_units: 6
      tags:
        name: my-dynamodb-tag

Depending on this service

The DynamoDB service outputs the following environment variables:

Environment Variable Description
<SERVICE_NAME>_TABLE_NAME The name of the created DynamoDB table
<SERVICE_NAME>_TABLE_ARN The ARN of the created DynamoDB table

See Environment Variable Names for information about how the service name is included in the environment variable name.

DynamoDB Streams

A DynamoDB Stream sends an event to a lambda function when data in the table changes. To configure a stream, include the stream_view_type element in your handel file and declare your lambda function as an event_consumer with the following syntax:

event_consumers:
- service_name: <string> # Required.  The service name of the lambda function
  batch_size: <number> # Optional.  Default: 100

BatchSize

The largest number of records that AWS Lambda will retrieve from your event source at the time of invoking your function. Your function receives an event with all the retrieved records. The default is 100 records.

Events produced by this service

The DynamoDB service currently produces events for the following services types:

  • Lambda

Events consumed by this service

The DynamoDB service does not consume events from other Handel services.