dynobase-icon
Dynobase

Run DynamoDB in LocalStack with Docker Compose

Rafal Wilinski

Written by Rafal Wilinski

Published: November 20th, 2026

Developing against DynamoDB Local? Dynobase connects to DynamoDB Local, LocalStack and DynamoDB in Docker, so you can browse and edit local tables in a GUI. Dynobase for DynamoDB Local

Run DynamoDB in LocalStack by starting its Docker container with a LocalStack auth token and pointing your AWS CLI or SDK at http://localhost:4566. LocalStack emulates multiple AWS services on your machine, so you can test a DynamoDB write and the Lambda function it triggers without deploying to AWS. The current image uses LocalStack's own Rust-based DynamoDB and Streams emulator by default. LocalStack installation · DynamoDB service coverage

Does LocalStack run DynamoDB Local internally?

Older versions used AWS's downloadable DynamoDB Local as their backend. The 2026.09.0 release, published October 2, 2026, made LocalStack's Rust-based engine the default on every plan. The deprecated DynamoDB Local backend is still available on paid plans via PROVIDER_OVERRIDE_DYNAMODB=legacy_pro. Requests go to the LocalStack gateway whichever backend is selected. Check the service coverage for the APIs you need before relying on a local test. LocalStack configuration · DynamoDB service coverage

LocalStack licensing and auth tokens in November 2026

On March 23, 2026, release 2026.03.0 consolidated the Community and Pro distributions. From that release onward, localstack/localstack and localstack/localstack-pro publish the same image, and startup requires a valid LocalStack auth token. Your token determines the features you can use. Older Community tags remain available as historical releases and miss subsequent fixes. March 2026 release announcement · Community migration notice · Auth token documentation

LocalStack lists Hobby as free for non-commercial use and Base, Ultimate and Enterprise as commercial subscriptions as of March 23, 2026. A verified GitHub Education student account can qualify for Student, and open-source projects can apply for sponsorship. The plan matrix lists DynamoDB, Streams, Lambda and CI testing on Hobby, subject to the non-commercial terms. Local state persistence is included on Base, Ultimate, Enterprise and Student. LocalStack plan matrix · LocalStack support plans

Use a personal Developer Token locally and a workspace CI Auth Token in automated pipelines. Pass either to the emulator as LOCALSTACK_AUTH_TOKEN. The AWS API clients below sign requests separately with the dummy values test and test. LocalStack auth tokens · LocalStack AWS credentials

Start LocalStack DynamoDB with Docker Compose

Save the following as compose.yaml in a demo directory. It pins the image to 2026.10.0, publishes the gateway on the host loopback address, and mounts the Docker socket so LocalStack can start Lambda runtime containers. You can omit the socket mount for DynamoDB-only development. LocalStack 2026.10.0 release · LocalStack Compose installation

Export LOCALSTACK_AUTH_TOKEN from your local secrets store or set it in an untracked .env file next to compose.yaml. Start Docker, then run docker compose up -d. Inspect startup with docker compose logs localstack if the API does not respond yet. The host endpoint is http://localhost:4566. If your application is another service in the same Compose project, use http://localstack:4566 so the hostname resolves to the LocalStack container. LocalStack networking

Connect with AWS CLI v2 or awslocal

Open a dedicated shell for the demo. Use the same region and credentials throughout so the CLI and both SDKs see the same tables. The function keeps the endpoint explicit on every request. AWS CLI endpoint configuration · LocalStack CLI configuration

For existing scripts that use awslocal, install the wrapper into a virtual environment alongside the already installed AWS CLI v2. LocalStack now deprecates awslocal in favor of lstk aws, and the older wrapper still works for these DynamoDB commands. LocalStack wrapper documentation

Create a table, put an item, query and scan

Create an on-demand Orders table with string keys customerId and orderId. Enable NEW_IMAGE so the same table works for the Lambda example below. Run this on a fresh instance, or use the startup hook later in the guide to create the table automatically. AWS CLI DynamoDB examples

Query targets a partition key and can narrow results by sort key. Scan reads across the table or index, so use it to inspect a small test table and use Query for customer order lookups. Both AWS APIs return paginated results. The AWS CLI paginates by default. In SDK code, use LastEvaluatedKey to continue when you need every result. To inspect the table visually, see the local DynamoDB GUI setup. AWS Query guide · AWS Scan guide · AWS CLI pagination

AWS SDK for JavaScript v3

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb with npm in your demo directory. Save this as orders.mjs and run node orders.mjs. The document client converts native JavaScript values to and from DynamoDB attribute values. AWS JavaScript DynamoDB guide

Python with boto3

If you skipped the awslocal example, create a virtual environment with python3 -m venv .venv. Install boto3 with .venv/bin/pip install boto3, save this as orders.py, and run .venv/bin/python orders.py. The low-level boto3 client uses DynamoDB's typed attribute values, just like the CLI command above. Boto3 session and endpoint reference If Python reports No module named boto3, check the interpreter running the script.

Persist DynamoDB data between restarts

If your plan includes local persistence, export ORDERS_PERSISTENCE=1 before starting the container and writing data. That sets PERSISTENCE=1 inside the container, and the named volume keeps /var/lib/localstack across container replacement. The default backend stores persistent DynamoDB state in the volume's state/dynamodb/ddb.sqlite file. Leave DYNAMODB_IN_MEMORY off. LocalStack persistence · DynamoDB storage

To verify persistence, start with that setting, create the table, write an order, then run docker compose restart localstack. Rerun the query after startup and check the order is still present. Keep the same Compose project and volume if you recreate the container. docker compose down -v deletes the named volume. On Hobby, use a startup hook to rebuild your test schema each time. Docker Compose down · LocalStack plans

Trigger a local Lambda from DynamoDB Streams

LocalStack supports DynamoDB Streams as a Lambda event source. Lambda polls the stream and hands a batch of records to the function. The example uses the stream on Orders and the Docker socket mount from the Compose file. See the DynamoDB Streams guide for stream view types and record structure. LocalStack Streams walkthrough · AWS Lambda event source mapping

Save this handler as orders_audit.py. It logs the keys for each change and the new image when one is present. AWS tutorial for processing DynamoDB records with Lambda

Package the handler, create an execution role, and attach the AWS-managed policy for reading stream records and writing function logs. Use the ARN returned by DescribeTable to wire up the trigger. TRIM_HORIZON starts at the oldest available record, so the first order may appear in the logs alongside the new test write. AWS Lambda execution role policy · AWS Lambda supported runtimes

Look for order-101 with aws_local logs tail /aws/lambda/orders-audit --since 10m. If the log group is missing immediately after the write, give the mapping time to start and poll, then rerun the command. Use aws_local lambda list-event-source-mappings --function-name orders-audit to check the mapping state. AWS Lambda function logs

Create tables on startup with a ready hook

Mount a Python script in LocalStack's ready.d directory to create the same schema on each clean start. The hook catches ResourceInUseException so restarting with a persisted Orders table preserves it. LocalStack initialization hooks · AWS CreateTable reference

Add the following line under services.localstack.volumes in compose.yaml, then run chmod +x init-orders.py and docker compose up -d. Check http://localhost:4566/_localstack/init/ready and look for the script's SUCCESSFUL state before running tests. LocalStack init hook status

If your project already manages tables as infrastructure as code, run the existing Terraform apply or CDK deploy after LocalStack is ready. The older tflocal and cdklocal wrappers are deprecated. LocalStack documents lstk terraform and lstk cdk as their replacements. LocalStack Terraform setup · LocalStack CDK setup

LocalStack vs. DynamoDB Local vs. a real AWS dev account

OptionFidelityFeaturesCostCI use
LocalStackEmulates AWS APIs with documented coverage and behavioral gapsDynamoDB, Streams, local Lambda event source mappings, persistence on eligible plansFree Hobby for non-commercial use, paid commercial plansTest supported cross-service flows using a CI Auth Token
DynamoDB LocalAWS's downloadable emulator. It ignores provisioned throughput and runs without table partitioningDynamoDB APIs and local Streams support. Lambda execution needs a separate runtimeFree downloadTest data access and schema with a disposable database
AWS dev accountRuns actual AWS services under the account's IAM policies and quotasManaged DynamoDB, Streams, Lambda and AWS operational featuresAWS service pricing appliesTest deployed IAM, event delivery and managed-service behavior

Use DynamoDB Local for table and query tests, LocalStack for supported workflows spanning services, and a real AWS account for checks that depend on managed-service behavior. AWS DynamoDB Local limitations · AWS DynamoDB Local downloads · AWS DynamoDB pricing · LocalStack service coverage

Run a DynamoDB smoke test in GitHub Actions

Save this workflow as .github/workflows/localstack-dynamodb.yml and add a workspace CI Auth Token to repository secrets as LOCALSTACK_AUTH_TOKEN. The Ubuntu job maps the service container's gateway to localhost, waits for a DynamoDB API response, writes a row, and verifies it with a query. The standard Ubuntu runner supplies the AWS CLI. LocalStack GitHub Actions guide · GitHub Actions service containers

Common LocalStack DynamoDB problems

SymptomWhat to check
Connection refused or timeoutCheck docker compose ps and docker compose logs localstack. Confirm port 4566 is published. From a peer Compose service, use the service hostname.
LocalStack exits on startupCheck for a missing LOCALSTACK_AUTH_TOKEN, an expired license or a license that has yet to be assigned.
ResourceNotFoundExceptionCheck the endpoint, region and credentials with aws_local dynamodb list-tables. If using a ready hook, check the hook status.
Table data disappearsCheck the plan's persistence entitlement, PERSISTENCE=1, the named volume and the DYNAMODB_IN_MEMORY setting.
Lambda receives no recordsCheck the Docker socket mount, LatestStreamArn, event source mapping state and function logs. Put a fresh item to produce another stream record.

For a step-by-step diagnosis, see LocalStack DynamoDB not working. LocalStack auth troubleshooting · LocalStack endpoint networking · LocalStack Lambda support

Frequently Asked Questions

What is the LocalStack DynamoDB endpoint?

Use http://localhost:4566 from the host. From another service in the same Compose project, use http://localstack:4566 when the Compose service is named localstack.

Does LocalStack still run DynamoDB Local internally?

Since release 2026.09.0, LocalStack defaults to its own Rust-based DynamoDB and Streams emulator on every plan. DynamoDB Local is available as a deprecated legacy provider on paid plans.

Can I run the current LocalStack image without an auth token?

The unified image has required a valid LocalStack auth token since release 2026.03.0 on March 23, 2026. The free, non-commercial Hobby plan also requires a token.

Can I keep LocalStack DynamoDB data after restarting Docker?

On a plan with local persistence, enable PERSISTENCE=1 and mount a volume at /var/lib/localstack. Keep the volume and leave DynamoDB in-memory mode disabled.

Can LocalStack trigger Lambda from DynamoDB Streams?

Yes. Enable the table stream, create a Lambda function and configure an event source mapping with the table's stream ARN. Mount the Docker socket so LocalStack can launch the Lambda runtime.

Dynobase is a Professional GUI Client for DynamoDB

Start your 7-day free trial today

Product Features

Download
/
Changelog
/
Pricing
/
Member Portal
/
Privacy
/
EULA
/
Twitter
© 2026 Dynobase