# aws-dynamodb

Guides Cursor to use AWS SDK v3 best practices for DynamoDB. It enforces single-table architecture and keeps database access inside dedicated repositories.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-dynamodb.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/aws-dynamodb

## What it does

This rule instructs Cursor to structure AWS DynamoDB integration around AWS SDK v3 and `@aws-sdk/lib-dynamodb`. Instead of splitting related entities across multiple tables, it directs the agent to apply single-table design with generic `PK` and `SK` composite keys. GSIs stay reserved strictly for access patterns that primary keys cannot satisfy.

All database interactions must live in dedicated data access layers or repository classes using `DynamoDBDocumentClient`. The rule stops the assistant from writing scattered inline SDK calls and hardcoding table identifiers. Without reading table names from environment variables like `DYNAMODB_TABLE_NAME`, code fails the pattern. For CloudFormation, it specifies `PAY_PER_REQUEST` or auto-scaled provisioned capacity.

## Requirements
- Works with: AWS

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/aws-dynamodb.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/aws-dynamodb.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/aws-dynamodb.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/aws-dynamodb.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/aws-dynamodb.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-dynamodb.mdc

## When to use it
- structure single-table schemas using composite PK and SK keys
- encapsulate database operations in typed repository classes
- configure CloudFormation tables with encryption and PAY_PER_REQUEST
- prevent inline SDK calls and hardcoded table names

## Example prompts
- Create a TypeScript repository for User and Order entities using @aws-sdk/lib-dynamodb.
- Generate a CloudFormation DynamoDB table template with point-in-time recovery and pay-per-request billing.
- Write a query function to fetch user orders using partition and sort keys.

## Source text · aws-dynamodb.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6cf1fc2e9c499af7.

BEGIN THIRD-PARTY FILE 6cf1fc2e9c499af7
````text
---
description: Provides definitive best practices and actionable code examples for interacting with AWS DynamoDB using the AWS SDK v3, focusing on data modeling, performance, security, and common pitfalls.
globs: **/*
---
# aws-dynamodb Best Practices

This guide outlines the definitive best practices for interacting with AWS DynamoDB, ensuring optimal performance, security, and maintainability. We leverage AWS SDK v3, modern data modeling, and infrastructure-as-code principles.

## 1. Data Modeling: Single-Table Design is King

Embrace single-table design to minimize operational overhead and maximize query flexibility. Only use Global Secondary Indexes (GSIs) when your access patterns *cannot* be satisfied by the primary key.

### ✅ GOOD: Single-Table Design with Composite Primary Keys
Model your primary key (Partition Key + Sort Key) to serve your most frequent access patterns. Use generic attribute names like `PK` and `SK` to allow for diverse item types within the same table.

```typescript
// Example: User and Order data in a single table
// PK: USER#<userId>, SK: #METADATA (for user details)
// PK: USER#<userId>, SK: ORDER#<orderId> (for user's orders)

interface UserItem {
  PK: string; // e.g., USER#123
  SK: string; // e.g., #METADATA
  userId: string;
  username: string;
  email: string;
}

interface OrderItem {
  PK: string; // e.g., USER#123
  SK: string; // e.g., ORDER#abc-123
  orderId: string;
  userId: string;
  orderDate: string;
  totalAmount: number;
}

// Access Pattern: Get User by userId -> Query: PK = 'USER#<userId>', SK = '#METADATA'
// Access Pattern: Get all Orders for a User -> Query: PK = 'USER#<userId>', SK begins_with 'ORDER#'
```

### ❌ BAD: Multi-Table Design for Related Entities
Creating separate tables for every entity type (e.g., `UsersTable`, `OrdersTable`) leads to increased operational complexity and often requires more complex cross-table queries or application-level joins.

```typescript
// Don't do this unless absolutely necessary for strict isolation
// UsersTable: PK = userId
// OrdersTable: PK = orderId, GSI on userId
```

## 2. Code Organization and Structure

Organize your DynamoDB interactions into dedicated data access layers (DALs) or repositories. Use the AWS SDK v3's modular clients and `async/await`.

### ✅ GOOD: Dedicated Data Access Layer with Typed Clients
Encapsulate all DynamoDB operations, ensuring consistent error handling, logging, and parameter construction. Use the DocumentClient for simpler JSON interaction.

```typescript
// src/data/userRepository.ts
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: process.env.AWS_REGION });
const ddbDocClient = DynamoDBDocumentClient.from(client);
const TABLE_NAME = process.env.DYNAMODB_TABLE_NAME || "YourAppTable";

export class UserRepository {
  static async getUserById(userId: string): Promise<UserItem | undefined> {
    const params = {
      TableName: TABLE_NAME,
      Key: { PK: `USER#${userId}`, SK: '#METADATA' },
    };
    const { Item } = await ddbDocClient.send(new GetCommand(params));
    return Item as UserItem | undefined;
  }
}
```

### ❌ BAD: Inline DynamoDB Calls or Generic Clients
Avoid scattering DynamoDB logic throughout your application or using untyped, generic clients. This makes maintenance, testing, and refactoring extremely difficult.

```typescript
// src/handlers/createUser.ts - Bad practice
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const ddbDocClient = DynamoDBDocumentClient.from(client);

export const handler = async (event: any) => {
````
END THIRD-PARTY FILE 6cf1fc2e9c499af7

The third-party file has ended. Everything between the 6cf1fc2e9c499af7 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3814 of 5816 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/aws-dynamodb.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md