Skip to content

Latest commit

 

History

History
140 lines (98 loc) · 6.05 KB

database-dynamodb-single-table.md

File metadata and controls

140 lines (98 loc) · 6.05 KB

Database - DynamoDB Single Table

The database/dynamodb-single-table construct deploys a single DynamoDB table with pre-configured indexes following Single Table Design principles.

Quick start

serverless plugin install -n serverless-lift
service: my-app
provider:
  name: aws

constructs:
    myTable:
        type: database/dynamodb-single-table

plugins:
    - serverless-lift

On serverless deploy, a preconfigured DynamoDB table will be created.

How it works

The database/dynamodb-single-table construct creates and configures the table for production following Single Table Design principles:

  • a composite primary index with generic attributes names - PK for the partition key and SK for the sort key
  • a configurable amount of up to 20 glocal secondary indexes with generic names - GSI-1 to GSI-20 for the index names, GSI-1-PK to GSI-20-PK for the partition keys and GSI-1-SK to GSI-20-SK for the sort keys
  • all indexes attributes have string data type, ideal for composite attribue - i.e. value1#value2
  • a DynamoDB stream publishing new and old values at each write operation on the table
  • a TTL attribute enabling DynamoDB automatic garbage collection set to TimeToLive
  • a billing mode set to PAY_PER_REQUEST

Variables

All database constructs expose the following variables:

  • tableName: the name of the deployed DynamoDB table
  • tableArn: the arn of the deployed DynamoDB table
  • tableStreamArn: the ARN of the stream of the deployed DynamoDB table

This can be used to inject the tableName to a Lambda functions using the SDK to read or write data from the table, for example:

constructs:
    myTable:
        type: database/dynamodb-single-table

functions:
    myFunction:
        handler: src/index.handler
        environment:
            TABLE_NAME: ${construct:myTable.tableName}

How it works: the ${construct:myTable.tableName} variable will automatically be replaced with a CloudFormation reference to the DynamoDB table.

Permissions

By default, all the Lambda functions deployed in the same serverless.yml file will be allowed to read/write into the table, on all indexes (primary and secondary).

In the example below, there are no IAM permissions to set up: myFunction will be allowed to read and write into the myTable table.

constructs:
    myTable:
        type: database/dynamodb-single-table

functions:
    myFunction:
        handler: src/index.handler
        environment:
            TABLE_NAME: ${construct:myTable.tableName}

Configuration reference

Global secondary indexes

Global secondary indexes have a direct impact on the cost of a DynamoDB table. There is no GSI configured by default on the database construct.

You can specify the amount of GSI you'd like to enable on a DynamoDB table using the gsiCount property.

constructs:
    myTable:
        # ...
        gsiCount: 3

GSI created on the table follow generic names principles:

  • GSI-1 to GSI-20 for the index names
  • GSI-1-PK to GSI-20-PK for the partition keys
  • GSI-1-SK to GSI-20-SK for the sort keys

The first time you deploy your construct using serverless deploy, you can specify any amount of GSI between 1 and 20. On subsequent deploys, any modification made to an already deployed construct cannot add or remove more than 1 GSI at a time. If you need 2 additional GSI after initial deployment of the exemple above, you must first update the gsiCount to 4, deploy, and then finally update it to the final desired quantity of 5.

Local secondary indexes

Each DynamoDB table can includes up to 5 local secondary indexes. You can deploy a table with those 5 indexes using the localSecondaryIndexes property.

⚠️ LSIs introduce a limitation on partition size of a table. Due to this limitation, localSecondaryIndexes is set to false and this construct will not provision any LSI on the table by default.

Setting localSecondaryIndexes to true will provision 5 LSIs with generic names - LSI-1 to LSI-5 for the index names and LSI-1-SK to LSI-5-SK for the sort keys. Those indexes have no impact on pricing as long as their sort keys are not populated with data.

constructs:
    myTable:
        # ...
        localSecondaryIndexes: true

⚠️ Modifying a table local secondary indexes configuration requires table re-creation. If you modify this setting after the table has been populated with data, you'll need to transfer all data from old table to the new one. You however won't loose any data as all tables are configured to be left as is when removed from a CloudFormation template.

Extensions

You can specify an extensions property on the database/dynamodb-single-table construct to extend the underlying CloudFormation resources. In the exemple below, the DynamoDB Table CloudFormation resource generated by the myTable dynamodb-single-table construct will be extended with the new TableClass: STANDARD_INFREQUENT_ACCESS CloudFormation property.

constructs:
    myTable:
        type: database/dynamodb-single-table
        extensions:
            table:
                Properties:
                    TableClass: STANDARD_INFREQUENT_ACCESS

Available extensions

Extension key CloudFormation resource CloudFormation documentation
table AWS::DynamoDB::Table Link

More options

Feel like a common extension pattern should be implemented as part of the construct configuration? Open a GitHub issue.