DynamoDB with Serverless Framework - The Ultimate Guide

Why DynamoDB with Serverless Framework?

DynamoDB plays really well with Serverless Framework and AWS Lambda. Why? Both DynamoDB and AWS Lambda are serverless services meaning that both of them are billed based on your usage. Moreover, AWS enables a set of integrations between them including DynamoDB Streams which are consumable by Lambda functions. Both services can be deployed in a multi-region fashion, and you don't have to worry about managing, patching or maintaining either of these two.

If I've convinced you that both these services play nicely together, let me proceed with a tutorial on how to deploy a simple CRUD application using Serverless Framework with Node.js and Javascript.

Step 1 - Prerequisites

Make sure you have:

• AWS profile set up
• Node.js installed, preferably version > 10
• Serverless Framework

You should be able to run the following commands without any issues:

node -v # Checks Node.js version
aws sts get-caller-identity # Checks if your AWS profile is valid and setup correctly
serverless -v # Checks if you have Serverless Framework installed
node -v # Checks Node.js version
aws sts get-caller-identity # Checks if your AWS profile is valid and setup correctly
serverless -v # Checks if you have Serverless Framework installed

Step 2 - Create new Serverless Framework project

Serverless Framework provides a set of templates for a variety of platforms and languages. For this tutorial, we're going to use aws-nodejs template:

serverless create --template aws-nodejs --path my-new-serverless-project-with-dynamodb

cd my-new-serverless-project-with-dynamodb
serverless create --template aws-nodejs --path my-new-serverless-project-with-dynamodb

cd my-new-serverless-project-with-dynamodb

It should create the following file structure:

.
├── handler.js
└── serverless.yml
.
├── handler.js
└── serverless.yml

Step 3 - Provision necessary infrastructure

Go ahead and open serverless.yml file. This is the file that defines our cloud-native application. We need to add a DynamoDB Table definition here. You can either use our DynamoDB Table Designer tool or use following example table definition. Paste that at the end of serverless.yml file:

resources:
  Resources:
    myTable:
      Type: AWS::DynamoDB::Table
        Properties:
        TableName: myTable
        AttributeDefinitions:
          - AttributeName: name
            AttributeType: S
        KeySchema:
          - AttributeName: name
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1
resources:
  Resources:
    myTable:
      Type: AWS::DynamoDB::Table
        Properties:
        TableName: myTable
        AttributeDefinitions:
          - AttributeName: name
            AttributeType: S
        KeySchema:
          - AttributeName: name
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1

But, that's not all. We have our DynamoDB table, but we don't have:

• Reference to that table
• IAM permission to let Lambda query and mutate this table

The first one is fairly easy. Simply add following lines to the provider to supply table name as environment variable to all tables, or at function level to pass it just to one table.

environment:
  TABLE_NAME:
    Ref: myTable
environment:
  TABLE_NAME:
    Ref: myTable

Second one is a bit more complex. Since we want to follow the principle of least privilege and don't want to give the Lambda permission to manipulate all the DynamoDB tables but only this particular one. We need to use a combination of Fn::GetAtt intrinsic function and listing applicable IAM actions in iamRoleStatements block nested inside provider.

iamRoleStatements:
  - Effect: Allow
    Action:
      - dynamodb:DescribeTable
      - dynamodb:Query
      - dynamodb:Scan
      - dynamodb:GetItem
      - dynamodb:PutItem
      - dynamodb:UpdateItem
      - dynamodb:DeleteItem
    Resource:
      - "Fn::GetAtt": [myTable, Arn]
iamRoleStatements:
  - Effect: Allow
    Action:
      - dynamodb:DescribeTable
      - dynamodb:Query
      - dynamodb:Scan
      - dynamodb:GetItem
      - dynamodb:PutItem
      - dynamodb:UpdateItem
      - dynamodb:DeleteItem
    Resource:
      - "Fn::GetAtt": [myTable, Arn]

Step 4 - Application Code

Now, let's get to actual Lambda functions - our business logic. In this project, our API will have only three CRUD functionalities:

• Create Animal
• Get Animals
• Delete Animal

Go ahead, an open handler.js file, delete everything inside and include following require statement at the top:

const { DynamoDB } = require("aws-sdk")

const db = new DynamoDB.DocumentClient()
const TableName = process.env.TABLE_NAME
const { DynamoDB } = require("aws-sdk")

const db = new DynamoDB.DocumentClient()
const TableName = process.env.TABLE_NAME

Don't worry that you don't have aws-sdk installed locally. AWS-SDK is available in the AWS Lambda environment so you don't have to bundle it with your deployment artifact.

Create Function

In serverless.yml, add our createAnimal function definition. It will be invoked on POST animals request. You may also add other properties like memory or timeout.

functions:
  createAnimal:
    handler: handler.create
    events:
      - http:
          path: animals
          method: POST
functions:
  createAnimal:
    handler: handler.create
    events:
      - http:
          path: animals
          method: POST

In handler.js paste following lines of code.

module.exports.create = async (event) => {
  const newAnimal = {
    name: event.body.name,
    age: event.body.age,
    family: event.body.family,
  }

  await db
    .put({
      TableName,
      Item: newAnimal,
    })
    .promise()

  return { statusCode: 200, body: JSON.stringify(newAnimal) }
}
module.exports.create = async (event) => {
  const newAnimal = {
    name: event.body.name,
    age: event.body.age,
    family: event.body.family,
  }

  await db
    .put({
      TableName,
      Item: newAnimal,
    })
    .promise()

  return { statusCode: 200, body: JSON.stringify(newAnimal) }
}

It's pretty straightforward, we create newAnimal object based on parameters from the body of the POST request, save that to the database, and return the newly created entity with status code 200.

Get Many Function

The function responsible for returning a collection of our animals is pretty similar to the create one:

functions:
  getAnimals:
    handler: handler.list
    events:
      - http:
          path: animals
          method: GET
functions:
  getAnimals:
    handler: handler.list
    events:
      - http:
          path: animals
          method: GET

When it comes to the logic, it's quite simple. We're running a Scan operation against DynamoDB to get the list of our records.

module.exports.list = async (event) => {
  const animals = await db
    .scan({
      TableName,
    })
    .promise()

  return { statusCode: 200, body: JSON.stringify(animals) }
}
module.exports.list = async (event) => {
  const animals = await db
    .scan({
      TableName,
    })
    .promise()

  return { statusCode: 200, body: JSON.stringify(animals) }
}

Delete Function

Lastly, the delete function is also similar. The only difference here is that the path which includes :name variable, uses DELETE method.

functions:
  deleteAnimal:
    handler: handler.delete
    events:
      - http:
          path: animals/:name
          method: DELETE
          request:
            parameters:
              paths:
                name: true
functions:
  deleteAnimal:
    handler: handler.delete
    events:
      - http:
          path: animals/:name
          method: DELETE
          request:
            parameters:
              paths:
                name: true

Once again, the logic is quite simple. We delete an entity with key name which equals to our path parameter.

module.exports.delete = async (event) => {
  const animalToBeRemovedName = event.pathParameters.name

  await db
    .delete({
      TableName,
      Key: {
        name: animalToBeRemovedName,
      },
    })
    .promise()

  return { statusCode: 200 }
}
module.exports.delete = async (event) => {
  const animalToBeRemovedName = event.pathParameters.name

  await db
    .delete({
      TableName,
      Key: {
        name: animalToBeRemovedName,
      },
    })
    .promise()

  return { statusCode: 200 }
}

If you don't know how to create DynamoDB queries because its complicated syntax, use our DynamoDB Query Builder.

Step 5 - Deploy & Test

Deploying your project to the cloud is as easy as executing the following command:

serverless deploy
serverless deploy

It should output the URL of your endpoint. Copy it, and fire a request to check if it works correctly. If it does, then congrats! You've just deployed a production-ready, cloud-native API with Serverless Framework and DynamoDB!

Bonus - Our proven boilerplate

If you want to use something a bit more sophisitcated which follows many of the best practices, we've prepared a battle-tested Serverless Framework boilerplate for you.