Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท SDKs and Local Development

Local Development and Testing

Develop and test DynamoDB code offline with DynamoDB Local in Docker, an endpoint override, fakes and repositories, table setup in tests and what Local cannot do.

You do not need an AWS account to write DynamoDB code. DynamoDB Local is a downloadable version of the service (a Java application, also distributed as a Docker image) that implements the same API on your machine. Your code talks to http://localhost:8000 instead of the AWS endpoint. This makes tests fast, free and repeatable.

This lesson covers running DynamoDB Local, pointing SDKs at it, structuring tests, and the limits you must remember. The commands are read-only examples (DynamoDB Local cannot run in your browser); the runnable examples are Python stand-ins that demonstrate the testing structure.

Running DynamoDB Local

With Docker:

Terminal
docker run --rm -p 8000:8000 amazon/dynamodb-local
# keep data between restarts, stored in a mounted folder
docker run --rm -p 8000:8000 -v "$PWD/ddb-data:/home/dynamodblocal/data" \
  amazon/dynamodb-local -jar DynamoDBLocal.jar -sharedDb -dbPath /home/dynamodblocal/data

Useful flags: -inMemory (data vanishes on exit, perfect for tests), -sharedDb (one database file for all credentials and Regions), -port 8001. A docker compose service is a convenient way to share it with your team.

Point tools at it with an endpoint override. Use dummy credentials, since Local does not validate them (but the SDK still needs some):

Terminal
export AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local AWS_REGION=eu-west-1
aws dynamodb list-tables --endpoint-url http://localhost:8000
Python
import boto3
ddb = boto3.resource("dynamodb", endpoint_url="http://localhost:8000", region_name="eu-west-1")
JavaScript
const client = new DynamoDBClient({ region: "eu-west-1", endpoint: "http://localhost:8000",
  credentials: { accessKeyId: "local", secretAccessKey: "local" } });

Other options: LocalStack emulates many AWS services (including DynamoDB and Streams) in one container, moto mocks AWS calls inside Python tests, and NoSQL Workbench for DynamoDB gives a visual data modeler that can connect to Local.

Ways to test without AWS

DynamoDB Local Real API on localhost:8000
moto / LocalStack Mock many AWS services
Fakes In-memory repository for unit tests
Real AWS test table Final integration check

Use several layers, not just one.

1 / 2

Structure code so it can be tested

Put all DynamoDB calls behind a small repository (a class with methods like get_order, list_orders, save_order). Business logic depends on the repository, not on boto3. Then:

  • Unit tests pass a fake in-memory repository: instant, no Docker.
  • Integration tests run the real repository against DynamoDB Local to verify key conditions, expressions, pagination and index queries.
Python Business logic tested with a fake repository

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The fake covers the logic. Whether the real repository's condition expression behaves the same is what the integration tests with DynamoDB Local are for.

Integration tests against DynamoDB Local

A typical pytest fixture (read-only here):

Python
import boto3, pytest, uuid

@pytest.fixture
def table():
    ddb = boto3.resource("dynamodb", endpoint_url="http://localhost:8000", region_name="eu-west-1",
                         aws_access_key_id="x", aws_secret_access_key="x")
    t = ddb.create_table(
        TableName=f"test-{uuid.uuid4().hex[:8]}",          # unique name per test
        KeySchema=[{"AttributeName": "PK", "KeyType": "HASH"}, {"AttributeName": "SK", "KeyType": "RANGE"}],
        AttributeDefinitions=[{"AttributeName": "PK", "AttributeType": "S"}, {"AttributeName": "SK", "AttributeType": "S"}],
        BillingMode="PAY_PER_REQUEST",
    )
    t.wait_until_exists()
    yield t
    t.delete()

Tips:

  1. Create tables from the same definition as production (the infrastructure template, see IaC and IAM), so indexes match.
  2. Use a unique table name or key prefix per test to avoid interference; keep tests independent.
  3. Test access patterns, not just CRUD: seed items, then run each query from your pattern list (access patterns) and assert order, pagination and index contents.
  4. Test failure paths: failed conditions, transactions that cancel, throttling handled with a stubbed client.
  5. Run a handful of end-to-end tests against a real AWS table in a test account in CI to catch what Local cannot.
Python Test an access pattern: order and pagination

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What DynamoDB Local does not do

DynamoDB Local is faithful for the data plane but is not the real service:

  • It does not enforce provisioned throughput or burst, so you will not see throttling.
  • Latency and partition behaviour (hot keys, sharding) are not simulated.
  • Features like IAM authorization, backups/PITR, global tables replication, TTL timing, encryption and some limits can differ or be missing. Check the current documentation for the supported list.
  • Streams are supported by Local but without the exact scaling and retention behaviour; verify Lambda triggers in AWS.
  • Eventual consistency is not reproduced: everything reads as strongly consistent, so bugs that depend on lag stay hidden (see consistency models).

Treat Local as a correctness tool for keys, expressions and logic, and use load tests on a real table for capacity and hot-key questions.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you point an SDK or the CLI at DynamoDB Local?

    The API is the same. Only the endpoint changes, and the SDK needs some credentials even though Local does not check them.
  2. 2. Which is NOT reproduced by DynamoDB Local?

    Local does not enforce capacity, so throttling and hot-partition problems appear only on the real service.
  3. 3. Why put DynamoDB calls behind a repository class?

    A repository interface lets unit tests avoid the database while integration tests check the real implementation.
  4. 4. What is a good way to isolate tests that share one DynamoDB Local?

    Unique table names or prefixes keep tests independent so they can run in any order or in parallel.

Summary

  • DynamoDB Local (Docker) implements the DynamoDB API on localhost:8000; override the endpoint to use it.
  • LocalStack and moto are alternatives that mock more AWS services.
  • Hide DynamoDB behind a repository: fakes for unit tests, DynamoDB Local for integration tests of access patterns.
  • Create test tables from the production definition and isolate each test.
  • Local does not model throttling, eventual consistency or IAM, so verify those on real AWS.

Next: Infrastructure as Code and IAM