DEV Community

Anna Aitchison
Anna Aitchison

Posted on

How to Run AWS DynamoDB Locally

Running a DynamoDB instance locally is great for testing or just messing around without incurring any cost - it's works exactly the same as the DynamoDB in the cloud All you need to do is to create a local instance and add an endpoint (JS), or endpoint_url (Python) option pointing to it when creating a DynamoDB object in the AWS SDK, or a --endpoint-url option when using the CLI.

Step 1 - Creating your Local Instance

The easiest method is via the DynamoDB Docker image. The process for this varies slightly depending on how you're testing your code though and what you're making.

If you're using AWS SAM Local

At the time I was first trying to do this, I was building a serverless API with AWS SAM using AWS SAM local for testing, which would do a complete API Gateway in a container so I needed the SAM container and the DynamoDB container to talk to each other over the network. I found a Docker compose file which sets up the network and container in rynop's answer on StackOverflow. Here's my version of that:

version: '3.5'

    container_name: local-dynamodb
    image: amazon/dynamodb-local
      - local-dynamodb
      - '8000:8000'
      - dynamodata:/home/dynamodblocal
    working_dir: /home/dynamodblocal
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath .'

    name: local-dynamodb

  dynamodata: {}
Enter fullscreen mode Exit fullscreen mode

To run this, save it in a file called docker-compose.yml and run

docker-compose up -d dynamo

Once this is setup, you can run commands something like the ones below in your project folder and get the DynamoDB and SAM containers talking to each other. To detect that you're running in this environment, you can check for the AWS_SAM_LOCAL environment variable inside your lambda code. To connect to the DB, use http://dynamo:8000 as the endpoint URL.

sam build --use-container
sam local start-api --docker-network local-dynamodb --skip-pull-image --profile default --parameter-overrides 'ParameterKey=StageName,ParameterValue=local'
Enter fullscreen mode Exit fullscreen mode

If you're using something else

If you're running your code in a container, you'll need to do something similar to the above. Otherwise, you can do it that way (the container will be accessible on http://localhost:8000) but it's probably easier to run the below command:

docker run --rm -d  -p 8000:8000/tcp amazon/dynamodb-local:latest
Enter fullscreen mode Exit fullscreen mode

This runs the latest version of the DynamoDB container with port 8000 forwarded to localhost. So, the endpoint URL that needs to be set is http://localhost:8000.

2. - Create the Table

To create a table, simply create a JSON file with the below contents (tweaked as necessary for your environment), then use the AWS CLI command below to create that table.

    "TableName": "testTable",
    "KeySchema": [
      { "AttributeName": "id", "KeyType": "HASH" }
    "AttributeDefinitions": [
      { "AttributeName": "id", "AttributeType": "N" }
    "ProvisionedThroughput": {
      "ReadCapacityUnits": 2,
      "WriteCapacityUnits": 2
Enter fullscreen mode Exit fullscreen mode
aws dynamodb create-table --cli-input-json file://local-db-create.json --endpoint-url http://localhost:8000
Enter fullscreen mode Exit fullscreen mode

Top comments (0)