Get DynamoDB Local up and running in 3 minutes with Docker
Published: 2020-02-25 04:49:43

---
title: Get DynamoDB Local up and running in 3 minutes with Docker
published: true
description: dynamodb, aws, nosql
tags: 
---

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._

# Table of Contents
1. [Advantages of using DynamoDB Local](#1)
2. [Setup](#2)
3. [GUI](#3)
4. [Creating tables and items from the command line](#4)
5. [Accessing DynamoDB Local from the SAM CLI](#5)

# 1. Advantages of using DynamoDB Local <a name="1"></a>
Using a local instance means you don't have to hit the actual DynamoDB tied to your AWS account, which in turn means:
1. Your production DB can be kept clean for actual production data
2. Your AWS costs will probably be cheaper
3. You don't need an internet connection (except for initial setup)

# 2. Setup <a name="2"></a>
## Prerequisites
- [Docker](https://docs.docker.com/docker-for-mac/install/)
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)

## Launch Docker image
From the command line:

```bash
$ 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](https://hub.docker.com/r/amazon/dynamodb-local/)

__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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html). 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 <a name="3"></a>
There's an unofficial but user-friendly GUI for DynamoDB Local, called [dynamodb-admin](https://github.com/aaronshaf/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
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/6mb686e07xtqieptyndv.png)

### See items inside a table
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/osndwi09754gbs4omms5.png)

# 4. Creating tables and items from the command line <a name="4"></a>
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
```bash
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](https://stackoverflow.com/a/48809570/11249670)).

Reference: [docs](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/create-table.html)

## Create item
```bash
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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.DataTypes.html).

Reference: [docs](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/put-item.html)

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  <a name="5"></a>
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:

```js
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](https://stackoverflow.com/q/48926260/11249670). 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 :)