How to run DynamoDB Local and Offline — Complete Guide

Imagine you’re traveling by plane to a different city, and the deadline for your DynamoDB-powered project is really tight. Obviously, during flight, there’s no internet, but you just had one of these «Aha!» moments. You want to rush into the implementation, but there’s one problem:

Since DynamoDB is fully managed NoSQL database, you cannot access it when you’re offline. Bummer.

This didn’t happened to me just once. Until recently, when I discovered I can run DynamoDB offline and locally on my computer, without AWS Cloud. In some scenarios, it makes developing and testing applications without accessing DynamoDB easier. In this guide, I’ll show you how you can do that too. There are a few ways to do this; let’s run through them below:

Different ways to setup DynamoDB locally

• Docker
• Docker Compose (The recommended way 🚀)
• Java
• Serverless Framework
• LocalStack
• With AWS Amplify mock

Using Offline DynamoDB Local

Once you started DynamoDB offline, you might also be wondering — How do I connect to it?

Troubleshooting

Using Docker

This is my favorite way because it does not require Java installed. In this setup, DynamoDB is running in an isolated container on the port of your choice. Another good thing about this solution is that it works the same across all the operating systems and can be easily added to your Docker Compose setup.

Make sure you have Docker installed. If you don’t have Docker yet, you can get it here.

Open terminal and type:

And that’s pretty much it.

Your DynamoDB local instance is now running on port 8000. If you want to connect to this container using SDK or CLI, don’t forget to change the endpoint parameter in the configuration. Otherwise, you’ll keep trying to connect to the AWS network.

Using Docker Compose

A bit better way to run DynamoDB locally is to use Docker Compose. Using this approach, you can configure persistent volumes, network and resources much easier without adding parameters to the docker run command. Moreover, a YAML file is easier to maintain and share as a file inside repo.

1. Create a file called docker-compose.yml and paste following code:

1. Run docker-compose up -d . You can skip -d flag if you don’t want to run in in the «detached» mode.

Using Java

In this setup, we’re running Java binary in our system without any containerization. It’s a bit more complicated

First, make sure you have Java Runtime Environment (JRE) version 6.x or newer already installed. It’s required to run DynamoDB locally.

Then, extract the archive and copy its contents to a location of your choice.

Lastly, open terminal in the location where you’ve extracted files in step 3 and enter the following command:

DynamoDB is now running on port 8000 . If you want to change it, use -port flag.

Similar to the Docker setup, you need to change the endpoint parameter in the configuration.

Running out of memory

If you’re going to use DynamoDB really heavily, it’s possible that the allocated amount of memory for your JVM might not be enough. In a case like that, use a combination of Xms and Xmx flags to adjust the amount of RAM. For example:

This will start your local DynamoDB instance with 256 MB of memory and allow the process to use up to 2048 MB of memory.

With Serverless Framework

Using DynamoDB with Serverless Framework is a pretty popular combination. DDB in a case like this one is perfect for running offline integration tests or just running local replica of the AWS environment for development purposes. Here’s how:

1. Open serverless.yml file and add the following entry to the plugins section:

1. Now, run the following command to let the plugin setup everything for us, including downloading DynamoDB Local:

If you don’t have DynamoDB tables defined in your serverless.yml file, do it now.

Finally, start DynamoDB Local and migrate by running this command:

Using LocalStack

LocalStack is a project aiming to mock most of the AWS resources locally. Once again, in my opinion, using Localstack is much easier with Docker. Running DynamoDB local with it look like this:

This will run a container exposing three ports:

• 4572 running S3
• 4569 running DynamoDB
• 8080 running Localstack’s status dashboard

Similar to the previous approaches, if we want to use our offline services, we need to set the endpoint parameter of SDK or CLI to http://localhost:4569 . If you don’t want to set the endpoint setting explicitly when using CLI with each command, alternatively, you can use awscli-local.

With AWS Amplify mock

This method is only useful when you’re working with Amplify-powered projects.

One of the AWS Amplify toolchain options is to mock some of the cloud functionality locally. In our case, when working with an Amplify-powered API, you can run command amplify mock api and it will not only mock your API, but also the DynamoDB which is used as a persistence layer for this interface. Under the hood, it will simply spin a Java process with a copy of Java-based local DynamoDB.

The database will be ran with following parameters:

• Port: 62224
• Region: us-fake-1
• AWS Access Key ID: fake

Connecting to DynamoDB Local using SDK

All you need to do, is to tell the DynamoDB or DocumentClient to use the local endpoint in the constructor.

Dynamodb local on windows

Support for running DynamoDB Local in tests.

Add the following to your project/plugins.sbt file:

sbt 0.13.6+ is supported, 0.13.5 should work with the right bintray resolvers

To use DynamoDB Local in your project you can call start-dynamodb-local and stop-dynamodb-local directly in sbt .

To have DynamoDB Local automatically start and stop around your tests

To download the DynamoDB Local jar to a specific location («dynamodb-local» is the default)

To use a specific version («latest» is the default DynamoDB version to download and run)

If the «latest» version is being used, specify how old the downloaded copy should be before attempting a new download (default is 2 days)

To specify a port other than the default 8000

To override the default JVM heap size (specified in MB)

The default for the DynamoDB Local instance is to run in «in-memory» mode. To use a persistent file based mode you need to set both the data path & turn off in-memory. The plugin will fail to overwrite an existing db file at this path.

The default for DynamoDB Local instance is to use a separate file for each credential and region. To allow all all DynamoDB clients to interact with the same set of tables regardless of their region and credentials enable «shared db» mode.

The default on stop is to cleanup any data directory if specified. This can be changed using

Debugging db Contents

Configure your app to persist to disk:

Once you have completed some operation involving dynamo, you can inspect the contents with sqlite3. Example:

By default this plugin lives entirely in the Global scope. However, different settings for different scopes is possible. For instance, you can add the plugin to the Test scope using

You can then adjust the settings within the Test scope using

and you can execute the plugin tasks within the Test scope using

Similarly, you can have the plugin automatically start and stop around your tests using

This work is based on the Maven Plugin for DynamoDB.

Dynamodb local on windows

The DynamoDB setup only includes the access of your AWS account through which the DynamoDB GUI console can be accessed. However, a local installation can also be done for the same purpose.

Creating AWS account:

1. Visit the following website:- https://aws.amazon.com/dynamodb/
2. Click on the “ Get Started with Amazon DynamoDB” button, or the “Create an AWS Account” button.
3. Fill in the required information for account creation.
4. Choose the plan that best suits you and you are good to go.

After the above steps, you can sign in to the AWS console and then navigate to the DynamoDB console.

Local installation:

AWS (Amazon Web Service) provides a version of DynamoDB for local installations. Applications can be created in this type of setup without any web connection. It also significantly diminishes provisioned throughput, data storage, and transfer fees by allowing a local database.

Deployment of applications created on local installation can be done by making small changes to it for AWS use.

To set up DynamoDB locally follow the below steps:

• Download DynamoDB .tar file specific to your area using one of the following link:- https://s3.ap-south-1.amazonaws.com/dynamodb-local-mumbai/dynamodb_local_latest.tar.gz
• After you download the archive, extract the contents , and copy the extracted directory to a location of your choice.
• To start DynamoDB on your computer, open a command prompt window, navigate to the directory where you extracted DynamoDBLocal.jar , and enter the following command.

• Before you can access DynamoDB programmatically or through the AWS Command Line Interface (AWS CLI), you must configure your credentials to enable authorization for your applications. Downloadable DynamoDB requires any credentials to work, as shown in the following example.

• Start writing applications. To access DynamoDB running locally with the AWS CLI(Command Line Interface), use the –endpoint-url parameter. For example, use the following command to list DynamoDB tables.

Now your local installation is all set and you can start building your application.

Working Environment:

Programming languages like Ruby, Java, Python, C#, Erlang, PHP, and Perl are supported by DynamoDB. A JavaScript shell can also be used as a GUI console for DynamoDB.

At the deployment stage , you will need to make changes to your code. The changes depend on code language and a few other factors. The primary change consists of altering the endpoint from a local point to an AWS region. Other changes are based on requirement centric analysis of your application.

Difference between local and web-based setup:

The key difference between the local setup and web-based setup of DynamoDB are listed below:

• Tables are created instantaneously in local setup but the services provided by AWS consume more time.
• Generally, the local installation ignores throughput.
• The process of deletion is instantaneous in the local setup.
• Alteration of data is quicker as compared to the web-based setup due to absence of the network overhead.

Attention reader! Don’t stop learning now. Get hold of all the important DSA concepts with the DSA Self Paced Course at a student-friendly price and become industry ready.

How to launch local DynamoDB programmatically?

I am able to launch a local DynamoDB server from bash through this command:

Is there not a pure-java way to start the server in one’s code? I don’t mean a java callout to the shell through the Process object but a way such that when I run my app, the server starts, and when my app is killed, the server is killed.

I can live with an embedded database if such a mode exists, though something that reflects server consistency semantics would be ideal.

/.gradle/caches. – Piyush Jajoo Jul 11 ’15 at 12:19

2 Answers 2

EDIT: September 23rd 2015

There was an announcement on Aug 3, 2015 that now adds the ability to have an embedded DynamoDB local running in the same process. You can add a Maven test dependency and use one of the ways below to run it.

And here is an example taken from the awslabs/aws-dynamodb-examples Github repository:

Old answer

Like you said, there is currently no built-in way from DynamoDBLocal or the SDK to do this right now. It would be nice if there was an embedded DynamoDBLocal that you could start up in the same process.

Here is a simple workaround/solution using java.lang.Process to start it up and shut it down programmatically in case others are interested.

Documentation for DynamoDBLocal can be found here and here are the current definition of the arguments:

• -inMemory — Run in memory, no file dump
• -port 4000 — Communicate using port 4000.
• -sharedDb — Use a single database file, instead of separate files for each credential and region

Note that this is using the most recent version of DynamoDBLocal as of August 5th, 2015.

Dynamodb local on windows

This Plugin Requires

• serverless@^1
• Java Runtime Engine (JRE) version 6.x or newer

• Install DynamoDB Local
• Start DynamoDB Local with all the parameters supported (e.g port, inMemory, sharedDb)
• Table Creation for DynamoDB Local

npm install —save serverless-dynamodb-local

Then in serverless.yml add following entry to the plugins array: serverless-dynamodb-local

Using the Plugin

Install DynamoDB Local sls dynamodb install

Add DynamoDB Resource definitions to your Serverless configuration, as defined here: https://serverless.com/framework/docs/providers/aws/guide/resources/#configuration

Start DynamoDB Local and migrate (DynamoDB will process incoming requests until you stop it. To stop DynamoDB, type Ctrl+C in the command prompt window). Make sure above command is executed before this. sls dynamodb start —migrate

Note: Read the detailed section for more information on advanced options and configurations. Open a browser and go to the url http://localhost:8000/shell to access the web shell for dynamodb local.

Install: sls dynamodb install

To remove the installed dynamodb local, run: sls dynamodb remove Note: This is useful if the sls dynamodb install failed in between to completely remove and install a new copy of DynamoDB local.

Start: sls dynamodb start

All CLI options are optional:

All the above options can be added to serverless.yml to set default configuration: e.g.

Migrations: sls dynamodb migrate

In serverless.yml add following to execute all the migration upon DynamoDB Local Start

AWS::DynamoDB::Table Resource Template for serverless.yml

Note: DynamoDB local doesn’t support TTL specification, therefore plugin will simply ignore ttl configuration from Cloudformation template.

Seeding: sls dynamodb seed

In serverless.yml seeding categories are defined under dynamodb.seed .

If dynamodb.start.seed is true, then seeding is performed after table migrations.

If you wish to use raw AWS AttributeValues to specify your seed data instead of Javascript types then simply change the variable of any such json files from sources: to rawsources: .

If seed config is set to true, your configuration will be seeded automatically on startup. You can also put the seed to false to prevent initial seeding to use manual seeding via cli.

Using DynamoDB Local in your code

You need to add the following parameters to the AWS NODE SDK dynamodb constructor

e.g. for dynamodb document client sdk

e.g. for dynamodb document client sdk

Using with serverless-offline plugin

When using this plugin with serverless-offline, it is difficult to use above syntax since the code should use DynamoDB Local for development, and use DynamoDB Online after provisioning in AWS. Therefore we suggest you to use serverless-dynamodb-client plugin in your code.

The serverless dynamodb start command can be triggered automatically when using serverless-offline plugin. Please note that you still need to install DynamoDB Local first.

Add both plugins to your serverless.yml file:

Make sure that serverless-dynamodb-local is above serverless-offline so it will be loaded earlier.

Now your local DynamoDB database will be automatically started before running serverless offline .

Using with serverless-offline and serverless-webpack plugin

Run serverless offline start . In comparison with serverless offline , the start command will fire an init and a end lifecycle hook which is needed for serverless-offline and serverless-dynamodb-local to switch off both ressources.