Skip to content

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

License

Notifications You must be signed in to change notification settings

chris-feist/serverless-plugin-tables

Repository files navigation

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:

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!

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published