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 recordkeys - Only keysA 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!