DynamoDB Database Integration

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

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.

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:

• On AWS (e.g. Lambda)
• Outside 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>',
  }
}),

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',
      },
    },
  }
}),

The following configurations can be added:

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

• table: Configuration for the table that is going to be created by the plugin. Learn more below.
• libraryConfig: Any configuration for the AWS DynamoDb SDK can be passed here. Learn more below.
• storedElements: What should be stored in the database. Learn more in the database integration documentation.

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
    billingMode: 'PROVISIONED', // https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html
  },
  // ...
}),

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,
    },
  },
  // ...
}),

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.