Get DynamoDB Local up and running in 3 minutes with Docker

While using DynamoDB for a side project, I was surprised to learn that there's a version you can run locally. I was doubly pleasantly surprised to find it useful and easy to set up! There's even a GUI available, so you don't have to do everything from the command line. Here is a quick guide for setup and usage.

Note: Guide is for MacOS.

Advantages of using DynamoDB Local
Setup
GUI
Creating tables and items from the command line
Accessing DynamoDB Local from the SAM CLI

1. Advantages of using DynamoDB Local

Using a local instance means you don't have to hit the actual DynamoDB tied to your AWS account, which in turn means:

Your production DB can be kept clean for actual production data
Your AWS costs will probably be cheaper
You don't need an internet connection (except for initial setup)

2. Setup

Prerequisites

Launch Docker image

From the command line:

$ docker run -p 8000:8000 amazon/dynamodb-local

# You should see something like this:
Initializing DynamoDB Local with the following configuration:
Port:   8000
InMemory:   true
DbPath: null
SharedDb:   false
shouldDelayTransientStatuses:   false
CorsParams: *

...And that's it! You can now create tables and put data inside!
Reference: docs

Gotchas

All data in the local database(s) are cleared every time the container is shut down. If you want the data to persist, it looks like you can use the sharedDB option. So far I've found it easy to simply create tables/data from the command line each time (I don't have much initial data).

GUI

There's an unofficial but user-friendly GUI for DynamoDB Local, called dynamodb-admin (check the link for more detailed instructions).

Install: npm install -g dynamodb-admin
Use:
1. Open a new terminal window, and execute dynamodb-admin
2. Go to localhost:8001

Using it is very straightforward so I won’t walk you through it here, but to give you an idea, here are what the screens look like.

Create a new item in a table

See items inside a table

4. Creating tables and items from the command line

If you're like me, and you want to create data by copy/pasting code in the command line instead of doing it manually from the GUI, here are some examples.

Create table

aws dynamodb create-table \
--endpoint-url http://localhost:8000 \
--table-name 'Beverages' \
--attribute-definitions AttributeName=Name,AttributeType=S \
--key-schema AttributeName=Name,KeyType=HASH \
--provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

Gotchas

Make sure the endpoint-url points to localhost:8000, or it will try to create a table in your actual (remote) DynamoDB.
Notice how I'm only creating the Name column, which is my primary key, and not the Pros or Cons columns. This is because the only options for AttributeType when creating a table are S/N/B (String, Number or Binary). You can create other types of columns later when you populate the table with data (further explanation).

Reference: docs

Create item

aws dynamodb put-item \
--endpoint-url http://localhost:8000 \
--table-name 'Beverages' \
--item '{
  "Name": {"S": "Green tea"},
  "Pros": {"SS": ["Delicious", "Supposedly healthy"]},
  "Cons": {"SS": ["Sometimes too bitter"]}
}'

Gotchas

SS here means “string set”, or in other words, an array of strings. You can read about the data types allowed for DynamoDB attributes here.

Reference: docs

You can also perform other actions using the CLI like deleting items or tables, but I’ll leave it here for now.

5. Accessing DynamoDB Local from the SAM CLI

If you’re not using the AWS SAM CLI, you can skip this section entirely. But if you are using the SAM CLI to develop an AWS lambda and want to access your local instance of DynamoDB from it (like me!), this is for you.
When you execute the lambda with a command like sam local invoke, you’ll want to configure the endpoint so it accesses the local instance. Here’s what you can do:

const AWS = require('aws-sdk')

// Use the local Docker endpoint if executed locally
if (process.env.AWS_SAM_LOCAL) {
  options.endpoint = 'http://docker.for.mac.localhost:8000'
}

const dynamo = new AWS.DynamoDB.DocumentClient(options)

If the configuration above doesn't work for you, or you want to know what's happening, check out this Stack Overflow thread. The accepted answer is for Linux, and it's more involved - you set up a local network to get SAM and DynamoDB to connect. But thankfully there is an easier solution for Mac, which is the code snippet I wrote above.

Thank you for reading! Please let me know if you have any tips to make DynamoDB Local even easier to use :)