provectus/aws-dynamodb-best-practices

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

| Partition key | Verdict | Why | |---|---|---| | user_id (UUID) | Excellent | Very high cardinality, uniform traffic | | tenant_id | Needs sharding | Skewed — large tenants dominate | | status (active/inactive) | Bad | Very low cardinality, heavily skewed | | date (YYYY-MM-DD) | Bad for writes | All writes hit "today" |

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)

| Strategy | When to use | |---|---| | Compression (gzip) | Large attributes you don't filter on (stored as Binary) | | Vertical partitioning | Split into METADATA / BODY / COMMENTS sort keys — query only what you need | | S3 offload | Anything over ~100 KB — store pointer in DynamoDB |

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:

| Scenario | Approach | |---|---| | Low-contention read-modify-write | Optimistic locking — version attribute + ConditionExpression | | Multi-item atomic operations | TransactWriteItems (up to 100 items / 4 MB, costs 2x WCU) | | Long-running exclusive operations | DynamoDB Lock Client (heartbeat-based distributed locks) | | Cross-region writes (MREC) | Design to avoid conflicts — partition by region |

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).

| Need | Choose | |---|---| | Low-latency global writes, tolerate eventual consistency | MREC — async replication, last-writer-wins | | Strong consistency globally, zero RPO | MRSC — sync replication, exactly 3 regions, no transactions/TTL | | Conditional writes or transactions | MREC with write-to-one-region mode |

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

| Mistake | Fix | |---|---| | Designing schema before access patterns | List all queries first, then design keys | | Low-cardinality partition key | Composite key or write sharding | | Using Scan for regular access patterns | Redesign keys or add a GSI | | Filter expressions to reduce reads | Filters don't reduce RCU — use key conditions | | Storing large lists in one attribute | Individual items with sort key prefixes | | ALL projection on write-heavy GSI | KEYS_ONLY or INCLUDE to reduce write amplification | | Optimistic locking across regions (MREC) | Last-writer-wins silently resolves — partition writes by region | | Transactions for bulk ingestion | Use BatchWriteItem instead |

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