serverless-components/aws-dynamodb

⚡ Easily provision AWS DynamoDB tables using Serverless Components.

Click Here for Version 1.0

AWS DynamoDB Component ⎯⎯⎯ The easiest way to deploy & manage AWS DynamoDB tables, powered by Serverless Components.

• Minimal Configuration - With built-in sane defaults.
• Fast Deployments - Create & update tables in seconds.
• Team Collaboration - Share your table outputs with your team's components.
• Easy Management - Easily manage and monitor your tables with the Serverless Dashboard.

Check out the Serverless Fullstack Application for a ready-to-use boilerplate and overall great example of how to use this Component.

1. Install
2. Initialize
3. Deploy
4. Configure
5. Develop
6. Monitor
7. Remove

 

1. Install

To get started with component, install the latest version of the Serverless Framework:

$ npm install -g serverless

After installation, make sure you connect your AWS account by setting a provider in the org setting page on the Serverless Dashboard.

2. Initialize

The easiest way to start using the aws-dynamodb component is by initializing the aws-dynamodb-starter template. Just run this command:

$ serverless init aws-dynamodb-starter
$ cd aws-dynamodb-starter

3. Deploy

Once you have the directory set up, you're now ready to deploy. Just run the following command from within the directory containing the serverless.yml file:

$ serverless deploy

Your first deployment might take a little while, but subsequent deployment would just take few seconds. For more information on what's going on during deployment, you could specify the --debug flag, which would view deployment logs in realtime:

$ serverless deploy --debug

4. Configure

The aws-dynamodb component requires minimal configuration with built-in sane defaults. Here's a complete reference of the serverless.yml file for the aws-dynamodb component:

component: aws-dynamodb          # (required) name of the component. In that case, it's aws-dynamodb.
name: my-table                   # (required) name of your instance.
org: serverlessinc               # (optional) serverless dashboard org. default is the first org you created during signup.
app: myApp                       # (optional) serverless dashboard app. default is the same as the name property.
stage: dev                       # (optional) serverless dashboard stage. default is dev.

inputs:
  name: my-table
  attributeDefinitions:
    - AttributeName: id
      AttributeType: S
    - AttributeName: attribute1
      AttributeType: N
  keySchema:
    - AttributeName: id
      KeyType: HASH
    - AttributeName: attribute1
      KeyType: RANGE
  localSecondaryIndexes:
    - IndexName: 'myLocalSecondaryIndex'
      KeySchema:
        - AttributeName: id
          KeyType: HASH
        - AttributeName: attribute2
          KeyType: RANGE
      Projection:
        ProjectionType: 'KEYS_ONLY'
  globalSecondaryIndexes:
    - IndexName: 'myGlobalSecondaryIndex'
      KeySchema:
        - AttributeName: attribute2
          KeyType: HASH
      Projection:
        ProjectionType: 'ALL'
  region: us-east-1

Once you've chosen your configuration, run serverless deploy again (or simply just serverless) to deploy your changes. Please keep in mind that localSecondaryIndexes cannot be updated after first deployment. This is an AWS limitation. Also note that this component exclusively uses the Pay Per Request pricing, which scales on demand like any serverless offering.

5. Develop

Instead of having to run serverless deploy everytime you make changes you wanna test, you could enable dev mode, which allows the CLI to watch for changes in your configuration file, and deploy instantly on save.

To enable dev mode, just run the following command:

$ serverless dev

6. Monitor

Anytime you need to know more about your running aws-dynamodb instance, you can run the following command to view the most critical info.

$ serverless info

This is especially helpful when you want to know the outputs of your instances so that you can reference them in another instance. It also shows you the status of your instance, when it was last deployed, and how many times it was deployed. You will also see a url where you'll be able to view more info about your instance on the Serverless Dashboard.

To digg even deeper, you can pass the --debug flag to view the state of your component instance in case the deployment failed for any reason.

$ serverless info --debug

7. Remove

If you wanna tear down your entire aws-dynamodb infrastructure that was created during deployment, just run the following command in the directory containing the serverless.yml file.

$ serverless remove

The aws-dynamodb component will then use all the data it needs from the built-in state storage system to delete only the relavent cloud resources that it created. Just like deployment, you could also specify a --debug flag for realtime logs from the website component running in the cloud.

$ serverless remove --debug

aws-dynamodb's Issues

Support for Tagging

This is 1 of 2 features I believe would open this component up to wider use, particularly in shared AWS accounts. Is anyone currently working on adding this - before I give it a shot mysaelf?

Prefix resourceId with a name for the table name

Having the table name generated makes sense to avoid errors and collisions but it might make it hard to find and work with dynamo tables in the aws console. What about prefixing the resourceId name with a string from the inputs:

class AwsDynamoDb extends Component {
  async default(inputs = {}) {
    this.context.status('Deploying')
    const config = mergeDeepRight(defaults, inputs)

    const generatedName = inputs.name + this.context.resourceId()
    config.name = this.state.name || generatedName

Can't define attribute of type BOOL

inputs:
  name: ${name}-${stage}
  attributeDefinitions:
    - AttributeName: mobileNumber
      AttributeType: S
    - AttributeName: orderId
      AttributeType: S
    - AttributeName: isSettle
      AttributeType: BOOL

1 validation error detected: Value 'BOOL' at 'attributeDefinitions.3.member.attributeType' failed to satisfy constraint: Member must satisfy enum value set: [B, N, S]

Support for setting SSE

This is 1 of 2 features I believe would open this component up to wider use, particularly in shared AWS accounts. Is anyone currently working on adding this - before I give it a shot mysaelf?

Global Secondary Index Support

Global secondary indexes seems is very important. Here is an idea how it could be supported:

myTable:
  component: '@serverless/aws-dynamodb'
  inputs:
    name: nameOfTable # optional
    attributeDefinitions:
      - AttributeName: id
        AttributeType: S
    keySchema:
      - AttributeName: id
        KeyType: HASH
    region: us-east-1
    globalSecondaryIndexes:
      - IndexName: nameOfGSIndex
      - KeySchema:
         - AttributeName: id
            KeyType: HASH

Dynamo Stream Support

Would it make sense to support streams in this component, or add that functionality with another? For example, we could add streams to the createTable method in utils.js:

async function createTable({ dynamodb, name, attributeDefinitions, keySchema, isStreamActive }) {
  const res = await dynamodb
    .createTable({
      TableName: name,
      AttributeDefinitions: attributeDefinitions,
      KeySchema: keySchema,
      BillingMode: 'PAY_PER_REQUEST',
      StreamSpecification: {
        StreamEnabled: isStreamActive,
        StreamViewType: NEW_IMAGE 
      }
    })
    .promise()
  return res.TableDescription.TableArn
}

TypeError: childComponentInstance.init is not a function

Hi, I'm trying to add a database (dynamodb) into my serverless file, however I get this error:

 error:
  TypeError: childComponentInstance.init is not a function
    at Template.load (/usr/local/lib/node_modules/serverless/node_modules/@serverless/core/src/Component.js:116:34)
    at async fn (/usr/local/lib/node_modules/serverless/node_modules/@serverless/template/utils.js:272:25)
    at async Promise.all (index 1)
    at async executeGraph (/usr/local/lib/node_modules/serverless/node_modules/@serverless/template/utils.js:294:3)
    at async Template.default (/usr/local/lib/node_modules/serverless/node_modules/@serverless/template/serverless.js:67:38)
    at async Object.runComponents (/usr/local/lib/node_modules/serverless/node_modules/@serverless/cli/src/index.js:220:17)

  47s › Template › TypeError: childComponentInstance.init is not a function

Do you have any ideas on how I can add a dynamodb table via serverless?

I've used @serverless/aws-dynamodb and that works fine, however I wanted to use the latest serverless component.

Here are some details regarding my serverless versions:

serverless --version

Framework Core: 1.74.1
Plugin: 3.6.15
SDK: 2.3.1
Components: 2.31.10

Serverless file:

App:
  component: "@sls-next/[email protected]"
  inputs:
    roleArn: xxxx
    domain: "xxxxx" # sub-domain defaults to www
    cloudfront:
      distributionId: xxxxx
      defaults:
        forward:
          cookies: "none"

database:
  component: aws-dynamodb          # (required) name of the component. In that case, it's aws-dynamodb.
  name: app-db                   # (required) name of your instance.

  inputs:
    name: app-db
    attributeDefinitions:
      - AttributeName: id
        AttributeType: S
      - AttributeName: attribute1
        AttributeType: N
    keySchema:
      - AttributeName: id
        KeyType: HASH
      - AttributeName: attribute1
        KeyType: RANGE
    localSecondaryIndexes:
      - IndexName: 'myLocalSecondaryIndex'
        KeySchema:
          - AttributeName: id
            KeyType: HASH
          - AttributeName: attribute2
            KeyType: RANGE
        Projection:
          ProjectionType: 'KEYS_ONLY'
    globalSecondaryIndexes:
      - IndexName: 'myGlobalSecondaryIndex'
        KeySchema:
          - AttributeName: attribute2
            KeyType: HASH
        Projection:
          ProjectionType: 'ALL'
    region: us-east-1

Many thanks :)

multiple tables?

Do we need a different component for every table?

UnhandledPromiseRejectionWarning

(node:16576) UnhandledPromiseRejectionWarning: Error: Unexpected Serverless Platform Streaming Error: WebSocket was closed before the connection was established
at WebSocket.self.connection.onerror (/usr/local/lib/node_modules/serverless/node_modules/@serverless/platform-client/src/Connection.js:106:13)
at WebSocket.onError (/usr/local/lib/node_modules/serverless/node_modules/ws/lib/event-target.js:140:16)
at WebSocket.emit (events.js:400:28)
at abortHandshake (/usr/local/lib/node_modules/serverless/node_modules/ws/lib/websocket.js:896:15)
at WebSocket.close (/usr/local/lib/node_modules/serverless/node_modules/ws/lib/websocket.js:272:14)
at Connection.disconnect (/usr/local/lib/node_modules/serverless/node_modules/@serverless/platform-client/src/Connection.js:165:23)
at ServerlessSDK.disconnect (/usr/local/lib/node_modules/serverless/node_modules/@serverless/platform-client/src/index.js:1539:23)
at Object.module.exports [as run] (/usr/local/lib/node_modules/serverless/node_modules/@serverless/components/src/cli/commands/run.js:194:9)
at processTicksAndRejections (internal/process/task_queues.js:95:5)
at async Object.module.exports (/usr/local/lib/node_modules/serverless/node_modules/@serverless/components/src/cli/index.js:197:7)
(Use node --trace-warnings ... to show where the warning was created)
(node:16576) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag --unhandled-rejections=strict (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)
(node:16576) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

 Operating System:          linux
 Node Version:              14.18.3
 Framework Version:         2.71.0
 Plugin Version:            5.5.3
 SDK Version:               4.3.0
 Components Version:        3.18.1

I'm using [email protected]. I got this error log after successful deployment.

Add support for setting "Encryption Type" and "Point-in-time recovery"

It would be great to get support to be able to set the following settings.

• Point-in-time recovery
• Encryption Type

Apologies if i missed them in the docs or code

Dynamodb local support

This component be able to be used with dynamodb local. This could be accomplished by implementing a method on the component: describeTable, that would output the cloudformation used to create the table. This could then be used as input to a script that would create the table within the local dynamodb.

Questions:

1. If one uses a yml file with many instances of this component, how could this be run for each instance.

Add support for TTL setting

the passwordless component could use the TTL setting to clean up expired codes. Check here for more details:
https://github.com/serverless-components/passwordless/issues/4