Beginner7 min read

How to Run DynamoDB Local with Docker

DynamoDB Local is AWS's downloadable emulation of DynamoDB in a single process: same API, no AWS account, no network, no per-request bill. Use it for local development and integration tests, then point the same code at the cloud in production.

It ignores provisioned throughput and never throttles, so load and limit tests belong on a real table (what Local does not emulate says how to test those).

How do I run DynamoDB Local with Docker?

Run docker run -p 8000:8000 amazon/dynamodb-local to start the official image, which exposes the DynamoDB engine on http://localhost:8000. Point your AWS SDK or CLI at that endpoint with any dummy credentials, then create tables and run requests exactly as you would against the cloud.

The image runs in memory by default. Use -dbPath on a mounted volume to keep data across restarts, and -sharedDb so every client and GUI sees the same tables.

Start the container

docker run -p 8000:8000 amazon/dynamodb-local

That exposes the engine on http://localhost:8000, in memory. To keep one shared database for every client, replace the image's default command:

docker run -p 8000:8000 amazon/dynamodb-local -jar DynamoDBLocal.jar -inMemory -sharedDb

docker-compose

Most projects pin it in docker-compose.yml so the whole team gets the same endpoint:

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

The image runs as the non-root dynamodblocal user, which can't open a database file inside the root-owned named volume. Without user: root you hit SQLiteException [14] unable to open database file and every call hangs.

Persistence

The image's default command runs -jar DynamoDBLocal.jar -inMemory, so every table vanishes when the container stops. The compose file above replaces that command:

  • -dbPath /data + a mounted volume writes the database file to disk, so data survives docker compose down. You can't combine -dbPath with -inMemory.
  • -sharedDb keeps every client on one database file. Without it, each access-key/region pair gets its own isolated database, even in memory; the connection guide covers the details.

Point the SDK at it

Only the endpoint changes; credentials can be any alphanumeric dummy values:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

Without -sharedDb, these values pick the database: another tool sees this client's tables only if it uses key x and region local too.

Create a table

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

A single-table PK/SK schema like this is a good default. When you load fixtures, convert plain JSON to the wire format with the DynamoDB-JSON converter.

Verify the container is up and the table landed:

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

Browse it with a GUI

CLI calls get tedious fast. The usual options are the open-source dynamodb-admin web UI (how it compares) or a desktop client. DynoTable connects with an Offline profile on any localhost port and signs with its own throwaway key, so start Local with -sharedDb (as the compose file does) to see your app's tables.

You then browse, query with the , and edit local tables with the same UI you use for cloud tables. The setup is in connecting to DynamoDB Local & LocalStack.

What Local does not emulate

Treat Local as an API compatibility layer. It ignores provisioned throughput, never returns ProvisionedThroughputExceededException, and does not model on-demand burst behavior. A load test against Local tells you nothing about partition limits or adaptive capacity in AWS.

For the requests that answer at once, we sent the same calls to DynamoDB Local 3.3.2 and to DynamoDB and compared every response. Most error messages differ, so assert on error names. Three lines of AWS's own list of differences no longer hold.

Other gaps show up in integration tests if you do not plan for them:

BehaviorDynamoDB LocalAWS DynamoDB
Billing / RCU / WCUReports ConsumedCapacity, bills nothingMetered per request
ThrottlingNeverYes, at table/index limits
TTL deletion timingExpired items gone within seconds (measured)Typically within a few days of expiry
DynamoDB Streams deliverySimplifiedFull stream semantics + Lambda wiring
Transactions across tablesSupported; never raises a transaction conflictCan cancel with a TransactionConflict reason
Global Tables / PITRNot availableProduction features

What to do for each gap:

  • Throttling and retries. To exercise your retry path, stub the client in a unit test so a call throws ProvisionedThroughputExceededException or ThrottlingException (this tests your handling; to exercise the SDK's built-in retries, give the client a custom request handler that returns a 400 with that error code). Or start LocalStack with DYNAMODB_ERROR_PROBABILITY=0.2, which injects ProvisionedThroughputExceededException into that share of DynamoDB responses (LocalStack configuration). LocalStack needs a LocalStack account and auth token to start; its free Hobby plan is for non-commercial use.
  • Real throttling. Use a disposable on-demand cloud table with a low maximum throughput: aws dynamodb update-table --table-name T --on-demand-throughput MaxReadRequestUnits=1,MaxWriteRequestUnits=1. AWS applies it best-effort, so burst capacity can absorb a short spike; run the load long enough to see the errors. Requests over the maximum fail with ThrottlingException, so check that your retry handler catches it as well as ProvisionedThroughputExceededException.
  • TTL. Don't assert deletion timing in any environment. Filter expired items in reads (FilterExpression: "#exp > :now"), as AWS recommends, and assert that each item carries the right TTL attribute.
  • Transaction conflicts. Local never raises them, so mock a TransactionCanceledException with a TransactionConflict reason in your client to test that handling.
  • Stream fan-out. Wire the stream to a Lambda on a cloud table, or on LocalStack (auth token required).

A practical local workflow

A common setup wires Local into three layers:

  1. CI setup: spin the container in CI, create tables in beforeAll, tear down in afterAll. Keep fixtures small; marshal plain JSON through the DynamoDB JSON converter when tests paste attribute maps by hand.
  2. Integration tests: exercise the same SDK client factory your app uses, swapping only endpoint and credentials. Assert on item shape and conditional writes. Local returns ConsumedCapacity per request, so you can assert units per call; it can't tell you whether that rate would throttle.
  3. Manual exploration: connect DynoTable with an Offline profile (Local started with -sharedDb), stage edits, and run PartiQL or key-condition queries before you deploy schema changes.

When you outgrow a single process (multiple services, S3 triggers, or IAM-style routing), graduate to LocalStack or a dev account. Local stays the fastest loop for "does my access pattern compile?"

Seed data without hand-marshalling

Loading ten fixture items from a JSON file is faster when you do not tag every value yourself. Paste the array into the DynamoDB JSON converter, copy the marshaled output, and batch-write with BatchWriteItem against --endpoint-url http://localhost:8000. For update-heavy fixtures, assemble the UpdateExpression in the DynamoDB expression builder and paste the generated attribute maps into your test harness.

DynoTable's item editor performs the same marshaling on commit, which helps when a test failure leaves you staring at raw {"S":...} blobs in the CLI.

When to leave Local

Ship to a real table when you need any of the following measured on AWS itself:

  • Capacity planning: a 1 KB item read 1,000 times per second costs 500 read request units per second on on-demand (0.5 each, eventually consistent). Local reports the same per-request units but bills nothing and never throttles. Model the bill with the pricing calculator using sizes from the item-size calculator.
  • Index propagation lag: GSI reads are eventually consistent in production; Local returns index rows quickly enough that stale-read bugs hide until deploy. Against a cloud table, write an item and immediately Query the GSI, and check that your code tolerates the miss. Where read-after-write matters, read the base table with ConsistentRead: true instead.
  • Cross-account IAM: resource-scoped roles and condition keys only exist in the cloud.

Keep Local for fast feedback on schema and expression syntax; validate cost and consistency assumptions against a staging table before production traffic.

Pitfalls worth scripting around

  • Forgotten -sharedDb: each access-key/region pair gets an isolated database, so CI, your laptop and your GUI each see different tables.
  • Root-owned volume without user: root: Local can't open its database file and every request hangs; the SQLiteException is in docker logs. Add the compose override from the section above.
  • Assuming Streams parity: stream-enabled Lambdas need a cloud or LocalStack target; Local alone will not exercise fan-out.
  • Empty-string keys: allowed on non-key attributes since 2020, still rejected on keys; validate fixtures the same way you would in AWS.

Download DynoTable, start Local with -sharedDb (the compose file above does), add an Offline profile on port 8000, and browse your local tables with the same grid, filter builder, and SQL Workbench you use in production, with zero AWS spend on the loop.

By Dmitriy · Updated