How to Setting up DynamoDB Locally

2020/12/127 min read
bookmark this
Responsive image

Table of Contents

  1. Introduction
  2. Download DynamoDB
  3. JRE
  4. Start DynamoDB
  5. Run DynamoDB Command in Background
  6. Use AWS CLI
  7. Access Local DynamoDB
  8. Conclusion

Introduction

AWS DynamoDB is a document database that provides single-digit millisecond performance. It is a serverless database, which means you can focus on using applications to access DynamoDB and AWS will manage the server for you. It's also available in multiple AWS regions and has built-in Cache DAX.

Another good reason to use DynamoDB is the free tier it provides — up to 25 GB storage, 25 write capacity units, and 25 read capacity units are free. Compared to MongoDB, depending on the MongoDB cloud provider, it might be 500 MB of storage if you try to look for a free tier.

Now, in this blog I'll show how to set up DynamoDB locally, and also demonstrate a few simple commands to access local DynamoDB.

Download DynamoDB

Go to the following link from AWS to download DynamoDB. Each region has a different DynamoDB file, so choose the region you'll be using for DynamoDB. After unzipping the file, run the following command.

Link to Download DynamoDB

JRE

To start DynamoDB locally you'll need at least JRE version 8. You can use the following link as a reference to download JRE if you don't have it already.

Download JRE

Start DynamoDB

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

If you see the following, it means your DynamoDB is able to run locally on port 8000.

Initializing DynamoDB Local with the following configuration:
Port:	8000
InMemory:	false
DbPath:	null
SharedDb:	true
shouldDelayTransientStatuses:	false
CorsParams:	*

After downloading the DynamoDB file to your local OS, cd to the folder and run the command. It should start DynamoDB on your local machine. DynamoDB has a few ways to store the database file locally. These are -sharedDb, -inMemory, and -dbPath. Let's see what the differences are between these three.

Omit Database File Option

If you omit any option, DynamoDB will store the database file with your AWS access key ID and the region. For instance, you should see a DB file formatted as {your AWS access key ID}_{region}.db when running the following command. This file will change if you use a different AWS user by running aws configure.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar

Using -sharedDb will create a DynamoDB file called shared-local-instance.db when starting DynamoDB.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

Now, there's another way to save the DynamoDB file locally by using -dbPath {path}. For example, if you have the following command with -dbPath test2 (assume test2 is a folder), first make sure the folder exists. Then when you run the following command, you'll see the shared-local-instance.db file in the test2 folder.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -dbPath test2

Using -inMemory, as the name shows, will save the database file in the OS's memory but will destroy it once you stop DynamoDB locally.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -inMemory

So which is better? That depends on what you're using DynamoDB for locally. If you just want to test something quickly and you don't care where it's stored, then you can omit the file option or use -inMemory, which destroys the file once you're done with your task. Or you can use -dbPath to create a file path, e.g. dev or dev2, to store different DynamoDB files for different environments.

DynamoDB Port Option

By default, DynamoDB uses port 8000, but you can also change the port by using the following command. If for some reason you need to set up a different DynamoDB file with a different DynamoDB port, you can use -dbPath with -port, since you might have a large amount of data to test locally before moving to the AWS DynamoDB service.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb -port 8001

Furthermore, type help to get all the command options:

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -help

This is the output when running the -help option:

usage: java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar
            [-port ] [-inMemory] [-delayTransientStatuses]
            [-dbPath ][-sharedDb] [-cors ]
 -cors                       Enable CORS support for javascript against a
                            specific allow-list list the domains separated
                            by , use '*' for public access (default is
                            '*')
 -dbPath             Specify the location of your database file.
                            Default is the current directory.
 -delayTransientStatuses    When specified, DynamoDB Local will introduce
                            delays to hold various transient table and
                            index statuses so that it simulates actual
                            service more closely. Currently works only for
                            CREATING and DELETING online index statuses.
 -help                            Display DynamoDB Local usage and options.
 -inMemory                  When specified, DynamoDB Local will run in
                            memory.
 -optimizeDbBeforeStartup   Optimize the underlying backing store database
                            tables before starting up the server
 -port            Specify a port number. Default is 8000
 -sharedDb                  When specified, DynamoDB Local will use a
                            single database instead of separate databases
                            for each credential and region. As a result,
                            all clients will interact with the same set of
                            tables, regardless of their region and
                            credential configuration. (Useful for
                            interacting with Local through the JS Shell in
                            addition to other SDKs)

Run DynamoDB Command in Background

You can also run your DynamoDB command in the background by appending & as follows. After this command, if you type ctrl + c, you close the terminal but DynamoDB will still run in the background.

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar &

If you wish to switch to the foreground of the DynamoDB command, use fg with the DynamoDB start command. That will bring it to the foreground, then you can press ctrl + c to actually close it if you wish to stop DynamoDB locally.

fg java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar

Use AWS CLI

Once DynamoDB is ready, you can access it via AWS CLI. You can try listing tables, querying, or updating a table. However, before that, you will need to run aws configure to connect from your local OS to the AWS service.

Create a User at AWS Console

Create a user at the AWS console and make sure the user can access DynamoDB.

There are many ways to achieve this. One way is to create a group that has access to DynamoDB, then create a new user and assign the group to this user.

Once you run the following command in your command-line tool, type the user's AWS access key ID and secret access key. Then from your local OS, that user's credentials will be used to access the AWS service.

aws configure

Access Local DynamoDB

Now, you should be able to access local DynamoDB from AWS CLI. Let's try the following command, which will list all the tables.

aws dynamodb list-tables --endpoint-url http://localhost:8000

If you see the following output, it means you are able to access your local DynamoDB.

{
    "TableNames": []
}

Let's try more — create a table for local DynamoDB.

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

Now, if we run list-tables again, the output should contain the table we just added.

{
    "TableNames": [
        "User"
    ]
}

Conclusion

Setting up DynamoDB locally is a great way to develop and test your application without incurring AWS costs. You can use various storage options such as -sharedDb, -inMemory, or -dbPath depending on your development needs, and access the local instance through the AWS CLI or SDK.

AWS DynamoDB

More Blogs Like This