pxslip / serverless-plugin-tables

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

serverless-plugin-tables

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

Benefits

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

Contents

• Installation
• Usage
• Providers
  • AWS
    • DynamoDB
  • Others

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:

Property	Required	Default Value	Description
name	false	The table key	The name of the table
type	false	Varies by provider	The database type. Please refer to corresponding provider and database sections below.

AWS

Common properties:

Property	Required	Default Value	Description
resourceName	false	'{pascalCase(tableName)}DynamoDbTable'	The CloudFormation resource name. The default runs your table name through a pascal case transformation.
type	false	'dynamo'	The database type. Please refer to corresponding database sections below.
template	false	null	Custom 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

Property	Default Value	Description
deploymentBatchSize	10	The deployment batch size. Do not exceed the AWS limits

Properties:

Property	Required	Description
partitionKey	true	The partition key. Refer to keys
sortKey	false	The sort key. Refer to keys
readUnits	false 1	The provisioned read units. Setting this changes the table to provisioned billing mode.
writeUnits	false 1	The provisioned write units. Setting this changes the table to provisioned billing mode.
indexes	false	List of secondary indexes
streamType	false	The stream type of the table. See Stream Types for valid values.
ttlKey	false	The Time To Live field
encrypted	false	Enable encryption
pointInTimeRecovery	false	Enable Point-in-Time Recovery
tags	false	Key-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.

Property	Required	Description
name	true	The name of the key
type	true	The data type of the key

Data Types:

Corresponds to DynamoDB Data Types

Value	Description
string	String
number	Number
binary	Binary
boolean	Boolean
list	List
map	Map
numberSet	Number Set
stringSet	String Set
binarySet	Binary Set
null	Null

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.

Property	Required	Description
name	true	The name of the index
partitionKey	false 2	The partition key. Refer to keys
sortKey	false 2	The sort key. Refer to keys
readUnits	false 3	The provisioned read units
writeUnits	false 3	The provisioned write units
projection	false	The 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

Value	Description
newItem	Enable stream with new item/image only
oldItem	Enable stream with old item/image only
both	Enable stream with new and old items
keys	Enable stream with keys only

Others

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