AWS DynamoDB

Quick Reference

All patterns are in references/dynamodb-patterns.md.

Critical Anti-Patterns

• Don't design schema first, then figure out queries — list access patterns first
• Don't use filter expressions expecting them to reduce read costs — they don't
• Don't store frequently-updated data with large static data — use vertical sharding
• Don't manually concatenate synthetic GSI keys (TOURNAMENT#X#REGION#Y) — use multi-attribute composite keys (provider v6.29.0+)
• Don't put bare integers in sort keys — ISSUE#9 sorts after ISSUE#100 lexicographically; zero-pad to fixed width (ISSUE#00000009)
• Don't use a filter expression when its hit rate is poor — a partition with 10,000 open issues and 5 closed ones: filtering for closed reads all 10,005 items and returns 5; embed status in the sort key instead (ISSUE#CLOSED#<id>)
• Don't count children at read time via Query+count — store a reference count on the parent and increment atomically via TransactWriteItems
• Don't assume TTL-expired items are gone immediately — DynamoDB TTL has a 48h deletion window; guard reads with FilterExpression: TTL > current_epoch
• Don't put two entity types in the same PK namespace without a shared-namespace decision — if names must be globally unique (e.g., users vs orgs), use the same PK prefix intentionally and let attribute_not_exists enforce the constraint

Decision Frameworks

Single-Table vs Multi-Table

Schema Migration Strategy

Migrations are ranked by difficulty. Always check if a change is purely additive before planning ETL.

For large tables, use parallel scans (TotalSegments + Segment) to distribute the ETL job — DynamoDB handles all worker coordination.

Synthetic Keys vs Multi-Attribute Composite Keys (GSI)

Version Matrix

Cost Analysis

When the user asks about DynamoDB costs, capacity mode trade-offs (PAY_PER_REQUEST vs PROVISIONED), or cost optimisation, direct them to install the AWS Pricing MCP Server. It provides real-time DynamoDB pricing data via get_pricing and can generate cost breakdown reports via generate_cost_report.

Prerequisites: uv package manager, Python 3.10+, AWS credentials with pricing:* permissions.

macOS / Linux:

{
  "mcpServers": {
    "awslabs.aws-pricing-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-pricing-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "awslabs.aws-pricing-mcp-server": {
      "command": "uvx",
      "args": [
        "--from", "awslabs.aws-pricing-mcp-server@latest",
        "awslabs.aws-pricing-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Add the above to ~/.claude/claude_desktop_config.json (Claude Desktop) or .claude/mcp.json (Claude Code) under mcpServers.

Reference Loading Strategy

Load references/dynamodb-patterns.md for all DynamoDB questions — it covers modeling patterns (item collections, # prefix trick, sparse indexes, reference counts, TTL guard), GSI design (composite keys, multi-attribute keys), cost, and Terraform examples.