DynamoDB Database Integration

This database integration allows you to store user specific data in a DynamoDB table.

Introduction

DynamoDB is the NoSQL database service by Amazon Web Services (AWS). Many Jovo apps that are hosted on AWS Lambda rely on DynamoDB to persist user data.

If you use AWS for your deployment, we recommend FileDb for local development and DynamoDB for deployed versions. Learn more about staging here.

You can also find an example on GitHub.

Installation

You can install the plugin like this:

$ npm install @jovotech/db-dynamodb

Add it as plugin to any stage you like, e.g. app.prod.ts:

import { DynamoDb } from '@jovotech/db-dynamodb';

// ...

app.configure({
  plugins: [
    new DynamoDb({
      table: {
        name: '<YOUR_TABLE_NAME>',
      },
    }),
    // ...
  ],
});

For the plugin to work, you need to at least add a table name to the configuration. The configuration section then provides a detailed overview of all options.

Once the configuration is done, the DynamoDB database integration will create a DynamoDB table on the first read/write attempt. This might take some seconds and could lead to the app returning an error during the first request. The second request should then work as expected.

The rest of this section provides an introduction to the steps you need to take depending on where you host your Jovo app:

For Apps Hosted on AWS

If you host your app on AWS Lambda and want to use a DynamoDB table in the same region, you only need to add a table name to get started:

new DynamoDb({
  table: {
    name: '<YOUR_TABLE_NAME>',
  }
}),

For Apps Hosted Outside AWS

If you want to use DynamoDB from outside AWS Lambda, you need to set it up for programmatic access. Learn more in the official guide by Amazon: Setting Up DynamoDB (Web Service).

You can then add the necessary keys using the libraryConfig property:

new DynamoDb({
  table: {
    name: '<YOUR_TABLE_NAME>',
  },
  libraryConfig: {
    dynamoDbClient: {
      region: 'us-east-1',
      credentials: {
        accessKeyId: 'myAccessKeyId',
        secretAccessKey: 'mySecretAccessKey',
      },
    },
  }
}),

Configuration

The following configurations can be added:

new DynamoDb({
  table: { /* ... */ },
  libraryConfig: { /* ... */ },
  storedElements: { /* ... */ },
}),

table

The table property includes configuration for the creation of the DynamoDB table:

new DynamoDb({
  table: {
    // Required properties
    name: '<YOUR_TABLE_NAME>',

    // Optional properties (with default values)
    createTableOnInit: true, // Creates a table if one does not already exist
    primaryKeyColumn: 'userId',
    readCapacityUnits: 2, // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ProvisionedThroughput.html
    writeCapacityUnits: 2, // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ProvisionedThroughput.html
  },
  // ...
}),

libraryConfig

The libraryConfig property can be used to pass configurations to the AWS DynamoDB SDK that is used by this integration.

Currently, it includes options for the DynamoDbClient and marshall:

new DynamoDb({
  libraryConfig: {
    dynamoDbClient: { /* ... */ },
    marshall: { /* ... */ },
  },
  // ...
}),

For example, you can add credentials like this:

new DynamoDb({
  libraryConfig: {
    dynamoDbClient: {
      region: 'us-east-1',
      credentials: {
        accessKeyId: 'myAccessKeyId',
        secretAccessKey: 'mySecretAccessKey',
      },
    },
    // ...
  }
}),

marshall includes the following default values:

new DynamoDb({
  libraryConfig: {
    marshall: {
      removeUndefinedValues: true,
      convertClassInstanceToMap: true,
    },
  },
  // ...
}),

Permissions

The DynamoDB integration needs the following permissions. Learn more in the official AWS docs.

  • dynamodb:CreateTable
  • dynamodb:DescribeTable
  • dynamodb:Query
  • dynamodb:Scan
  • dynamodb:GetItem
  • dynamodb:PutItem
  • dynamodb:UpdateItem
  • dynamodb:DeleteItem

You can find all permissions for the Serverless CLI in this example jovo.project.js file.