AWS DynamoDB Best Practices

Opinionated conventions for designing and operating DynamoDB tables at scale. For SDK/API usage or infrastructure-as-code definitions, consult the relevant AWS SDK or Terraform documentation instead.

NoSQL Design Mindset

DynamoDB is not a relational database — schema follows queries, not the other way around. Identify all access patterns before creating tables. Denormalize and duplicate data to avoid cross-table lookups.

See references/nosql-design-principles.md for access-pattern-first design, RDBMS migration thinking, and when to use single vs multiple tables.

Key and Index Design

Partition key — high cardinality, uniform distribution

Sort key — encode hierarchy broadest to most specific

PK: USER#alice    SK: PROFILE         ← user metadata
PK: USER#alice    SK: ORDER#2024-001  ← order (query begins_with(SK, "ORDER#"))
PK: USER#alice    SK: ADDR#home       ← address

GSI vs LSI

Default to GSI. Use LSI only when all three apply: you need strongly consistent reads on an alternate sort key, item collection stays under 10 GB, and you can define the index at table creation.

Query vs Scan

Always design for Query. Scan costs RCU proportional to total table size — filters reduce results but not capacity consumed. If you need Scan for a regular access pattern, redesign your keys or add a GSI.

See references/key-and-index-design.md for sharding strategies, GSI overloading, sparse indexes, projection strategy, and parallel scan guidelines.

Data Modeling Patterns

One-to-many — denormalize into parent partition

PK          | SK              | data
ORDER#1     | ORDER#1         | {customer, total, date}
ORDER#1     | ITEM#1          | {product, qty, price}
ORDER#1     | ITEM#2          | {product, qty, price}

One Query on PK = ORDER#1 returns the order with all its items.

Many-to-many — adjacency list pattern

Store bidirectional edges as items. A GSI with SK as partition key enables reverse lookups without maintaining duplicate edge items.

Large items (400 KB limit)

See references/data-modeling-patterns.md for adjacency list examples, time series table-per-period strategy, and trade-offs.

Concurrency Control

Individual writes are atomic. Locking is only needed for read-modify-write cycles:

See references/concurrency-control.md for retry strategies, transaction design considerations, and global tables concurrency caveats.

Global Tables

Global tables replicate data across regions for low-latency global access (99.999% availability).

Write modes are application-level routing (write-to-any, write-to-one, write-to-your-region) — DynamoDB itself always accepts writes in any replica.

See references/global-tables.md for MREC vs MRSC design implications, write mode selection, and operational guidance.

Common Mistakes

Reference Files

• references/nosql-design-principles.md — Access-pattern-first design, RDBMS vs NoSQL mindset, when to denormalize, when to use multiple tables
• references/key-and-index-design.md — Partition key evaluation, write sharding, sort key patterns, GSI vs LSI, projections, sparse indexes, GSI overloading, query vs scan optimization
• references/data-modeling-patterns.md — Adjacency lists, time series, large items, vertical partitioning, S3 offload
• references/concurrency-control.md — Optimistic/pessimistic locking, transactions, DynamoDB Lock Client, global tables concurrency
• references/global-tables.md — MREC vs MRSC, write modes, request routing, monitoring, cost model