Skip to content

SYSTEM Cited by 1 source

DynamoDB Local

What it is

DynamoDB Local is AWS's downloadable emulator of Amazon DynamoDB — a Java-based server that implements the DynamoDB API surface (Query, Scan, PutItem, GetItem, UpdateItem, DeleteItem, BatchGet/Write, Streams, Transactions) and persists to a local SQLite-backed file. Intended for local development + automated testing against the same wire protocol the real service speaks, without network calls to AWS.

Role in this wiki — CRUD tests at local-emulation speed

Named by the AWS Architecture Blog's agentic-AI-development essay as the data-store instance of the patterns/local-emulation-first pattern:

"For data persistence, Amazon DynamoDB Local allows the agent to test create, read, update, and delete (CRUD) operations against a local database that mirrors the DynamoDB API." (Source: sources/2026-03-26-aws-architecting-for-agentic-ai-development-on-aws)

The value proposition is the cheapest tier that can falsify a DynamoDB-facing code change for an AI agent: same SDK, same API shape, same query / index semantics, no AWS round trip, no IAM, no billed capacity. Iteration time collapses from "deploy-to-cloud + wait" to "subprocess start + test."

What it does and doesn't mirror

Mirrors (close enough that most application code is unchanged):

  • Item model, attribute types, primary keys, secondary indexes.
  • Query / Scan with condition / filter expressions.
  • Conditional writes, optimistic concurrency via ConditionExpression.
  • Transactions (TransactGetItems, TransactWriteItems).
  • Streams API surface (events generated on table mutations).

Does not mirror (structural reasons:

  • Provisioned/on-demand capacity + throttling. No throughput control; there's no way to exercise the ProvisionedThroughputExceededException path locally without injection.
  • Partition-level hot-key behaviour. Real DynamoDB partitions by key and has per-partition throughput ceilings; local is one SQLite file.
  • Global Tables / multi-region replication. Not emulated.
  • Adaptive capacity / autoscaling. Not emulated.
  • Performance profile. p50/p99 latency bear no resemblance to production — local is typically faster; under real production concurrency local will be slower and different.
  • DAX accelerator cache. Not emulated.
  • IAM policy evaluation. Emulator is open by default.

Relation to the concepts/agentic-development feedback-loop ladder

DynamoDB Local sits at tier 1 (local emulation, seconds per iteration) alongside systems/aws-sam and AWS Glue Docker images:

Path Emulator When it suffices
Lambda + API Gateway systems/aws-sam sam local request-response handler logic
DynamoDB DynamoDB Local (this page) CRUD + query semantics + conditional writes
Containers ECS/Fargate docker run same image container behaviour
Glue jobs Glue Docker images PySpark / ETL transformation logic

When local insufficiency bites (throttling, hot-key, DAX, multi-AZ consistency) escalate to patterns/hybrid-cloud-testing then to patterns/ephemeral-preview-environments.

Caveats

  • Emulator drift is the known gotcha. Behaviour-equivalent for the documented API surface; performance, throttling, and multi-region paths are not. Real tests eventually need a hybrid-cloud tier against a minimal real DynamoDB table.
  • Single-process only. No cross-instance concurrency testing in meaningful shape — it's a SQLite-backed single process.
  • Patch cadence lags the real service. New DynamoDB features typically ship to the managed service before DynamoDB Local — the emulator is an approximation of yesterday's DynamoDB.

Seen in

Last updated · 200 distilled / 1,178 read