How to Setting up DynamoDB Locally

2020/12/127 min read

AWS DynamoDB is a document database that provides single-digit millisecond performance, it is a serverless database, which means you can focus on use applications to access the 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 provided by DynamoDB. up to 25 GB storage, 25 write capacity units, and 25 read capacity units are free. Compare to MongoDB, depend on the MongoDB cloud provider it might be 500MB storage if you try to look for a free tier.

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

Download DynamoDB

Go to this link from AWS to download DynamoDB, the different region has 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 means your DynamoDB is able to run at your local with port 8000.

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

After download, the Dynamodb file to your local OS, cd to the folder, and run the following then it should start DynamoDB on your local. DynamoDB has a few ways to store the database file on your local, these are -sharedDb, -inMemory and -dbPath. Let's see what are the difference between these three.

Omit database file option

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

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

Use -sharedDb, will create a Dynamodb file shared-local-instance.db when starting the Dynamodb.

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

Now, there's another way to save Dynamodb file locally by use -dbPath {path} . For example, you have the following command, -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 at the test2 folder.

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

Use -inMemory, as the name show it will save the database file on the OS' memory but will destroy once stop the Dynamodb on your local.

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

So which is better? that'll depend on what your use for DynamoDB on your local, if you just want to test something quick you don't care where it store, then you can omit the file option or use -inMemory by destroying the file once you have done your task. Or you can use -dbPath to create a file path. e.g. dev or dev2 to store different DynamoDB files for a different environment.

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, cause you might have huge data to test on local before a move 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_b -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 background by append $ as follow. After this command, you type ctrl + c, you close the command but the DynamoDB will still run the background.

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

If you wish to switch to the foreground of the DynamoDB command, add fg to the DynamoDB start command. That will bring the to the foreground, then you can do ctrl + c to actual close if you wish to stop the DynamoDB on your local.

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

Use AWS CLI

Once the DynamoDB is ready, you can access DynamoDB via AWS CLI. You can try the list table, query, or update the table. However, before that, you will need to run aws configure to connect from your local OS to AWS service.

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

There are many ways to achieve this and one way you can do is, 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 at your command-line tool, type the user's AWS access key ID and secret access key, then from your local OS will use that user's credential to access to AWS service.

aws configure

Access to local DynamoDB

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

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

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

{
    "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, should see the output contains the table we just add.

{
    "TableNames": [
        "User"
    ]
}

AWS DynamoDB