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-localThat 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 -sharedDbdocker-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 survivesdocker compose down. You can't combine-dbPathwith-inMemory.-sharedDbkeeps 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_REQUESTA 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:8000Browse 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 SQL Workbench, 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:
| Behavior | DynamoDB Local | AWS DynamoDB |
|---|---|---|
| Billing / RCU / WCU | Reports ConsumedCapacity, bills nothing | Metered per request |
| Throttling | Never | Yes, at table/index limits |
| TTL deletion timing | Expired items gone within seconds (measured) | Typically within a few days of expiry |
| DynamoDB Streams delivery | Simplified | Full stream semantics + Lambda wiring |
| Transactions across tables | Supported; never raises a transaction conflict | Can cancel with a TransactionConflict reason |
| Global Tables / PITR | Not available | Production 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
ProvisionedThroughputExceededExceptionorThrottlingException(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 withDYNAMODB_ERROR_PROBABILITY=0.2, which injectsProvisionedThroughputExceededExceptioninto 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 withThrottlingException, so check that your retry handler catches it as well asProvisionedThroughputExceededException. - 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
TransactionCanceledExceptionwith aTransactionConflictreason 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:
- CI setup: spin the container in CI, create tables in
beforeAll, tear down inafterAll. Keep fixtures small; marshal plain JSON through the DynamoDB JSON converter when tests paste attribute maps by hand. - Integration tests: exercise the same SDK client factory your app uses,
swapping only
endpointand credentials. Assert on item shape and conditional writes. Local returnsConsumedCapacityper request, so you can assert units per call; it can't tell you whether that rate would throttle. - 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
Querythe GSI, and check that your code tolerates the miss. Where read-after-write matters, read the base table withConsistentRead: trueinstead. - 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; theSQLiteExceptionis indocker 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.