serverless-plugin-tables

This Serverless plugin makes adding tables to your service file easy.

Serverless License NPM Total Downloads NPM Version Build Status Coverage

Benefits

  • Less boilerplate
  • Common defaults
  • Integrates with existing resources
  • Handles deployment limits

Contents

Installation

Install the dependency:

yarn add -D serverless-plugin-tables

Add serverless-plugin-tables to your serverless.yml file:

plugins:
  - serverless-plugin-tables

Usage

Add a tables property the resources in your serverless.yml file and define tables by name according to the provider specs.

service: my-service
plugins:
  - serverless-plugin-tables
provider:
  ...
resources:
  tables:
    MyTable1:
      ...
    MyTable2:
      ...

Plugin options

The plugin can be configured by defining a custom tables object in your serverless.yml file. Database specific options should be defined as properties under their database type, like dynamo. See database specs for related options. Example options serverless.yml:

custom:
  tables:
    dynamo:
      deploymentBatchSize: 5

Providers

Common properties:

PropertyRequiredDefault ValueDescription
namefalseThe table keyThe name of the table
typefalseVaries by providerThe database type. Please refer to corresponding provider and database sections below.

AWS

Common properties:

PropertyRequiredDefault ValueDescription
resourceNamefalse'{pascalCase(tableName)}DynamoDbTable'The CloudFormation resource name. The default runs your table name through a pascal case transformation.
typefalse'dynamo'The database type. Please refer to corresponding database sections below.
templatefalsenullCustom CloudFormation template overrides. This allows you to implement features not covered, override the generated output, or do whatever other crazy stuff you have in mind 😀

Example

resources:
  tables:
    # Simple DynamoDB Table
    Music:
      partitionKey: Artist
      sortKey: SongTitle
      indexes:
        - name: GenreByTitleIndex
          partitionKey: Genre
          sortKey: AlbumTitle
    # Complex DynamoDB Table
    People:
      name: ${env:PEOPLE_TABLE_NAME}
      resourceName: FavoritePeopleDynamoTable
      type: dynamo
      partitionKey: personID
      sortKey: state
      readUnits: 5
      writeUnits: 5
      indexes:
        # Global Secondary Index
        - name: EmailIndex
          partitionKey: email
          projection: all
          readUnits: 2
          writeUnits: 2
        # Local Secondary Index
        - name: PersonByCreatedTimeIndex
          sortKey: 
            name: createdTime
            type: number
          projection: keys
          readUnits: 2
          writeUnits: 2
        # Local Secondary Index with projection
        - name: PersonByAgeIndex
          sortKey: 
            name: age
            type: number
          projection:
            - dob
            - firstName
            - lastName
          readUnits: 2
          writeUnits: 2
      streamType: newItem
      ttlKey: expirationTime
      encrypted: true
      pointInTimeRecovery: true
      tags:
        STAGE: test
        TEAM: backend      
      template: 
        # Override the computed CF template
        Properties: 
          ProvisionedThroughput:
            ReadCapacityUnits : 1

DynamoDB

Type: dynamo

Note that DynamoDB tables default to using on-demand billing mode.

Options

PropertyDefault ValueDescription
deploymentBatchSize10The deployment batch size. Do not exceed the AWS limits

Properties:

PropertyRequiredDescription
partitionKeytrueThe partition key. Refer to keys
sortKeyfalseThe sort key. Refer to keys
readUnitsfalse 1The provisioned read units. Setting this changes the table to provisioned billing mode.
writeUnitsfalse 1The provisioned write units. Setting this changes the table to provisioned billing mode.
indexesfalseList of secondary indexes
streamTypefalseThe stream type of the table. See Stream Types for valid values.
ttlKeyfalseThe Time To Live field
encryptedfalseEnable encryption
pointInTimeRecoveryfalseEnable Point-in-Time Recovery
tagsfalseKey-value pairs of resource tags

[1]: Both read and write units are required if one is defined

Keys:

Keys can be a string or an object. If a string is provided, then that will be the key name and it will be of data type string.

PropertyRequiredDescription
nametrueThe name of the key
typetrueThe data type of the key

Data Types:

Corresponds to DynamoDB Data Types

ValueDescription
stringString
numberNumber
binaryBinary
booleanBoolean
listList
mapMap
numberSetNumber Set
stringSetString Set
binarySetBinary Set
nullNull

Indexes:

Indexes can be Global or Local indexes. The difference being that Local indexes share the same partition key as the table. Therefore, to create a Local index, just omit the partitionKey field.

PropertyRequiredDescription
nametrueThe name of the index
partitionKeyfalse 2The partition key. Refer to keys
sortKeyfalse 2The sort key. Refer to keys
readUnitsfalse 3The provisioned read units
writeUnitsfalse 3The provisioned write units
projectionfalseThe projected fields. Possible values include:
all - [Default] The entire record
keys - Only keys
A list of fields

[2]: At least one key is required

[3]: Required if defined for the table

Stream Types:

Corresponds to DynamoDB Stream Types

ValueDescription
newItemEnable stream with new item/image only
oldItemEnable stream with old item/image only
bothEnable stream with new and old items
keysEnable stream with keys only

Others

If your provider or database isn't supported, open an issue to request it!