DynamoDB with AWS SAM: Tables, Policies and Local Testing

AWS SAM can create DynamoDB tables with AWS::Serverless::SimpleTable or the full AWS::DynamoDB::Table resource. Use SimpleTable for a single-attribute primary key; use Table when you need a sort key, indexes, TTL, deletion protection or other detailed settings. SAM policy templates connect your Lambda execution roles to the table, while the SAM CLI builds and tests the application.

Why use SAM with DynamoDB?

SAM extends CloudFormation with shorter declarations for Lambda functions, APIs and event sources. Deployment still runs through CloudFormation, so you can review changes, retain database resources and use ordinary AWS resources in the same template. SAM is infrastructure tooling, not a database service or an application authorization layer.

The example keeps the original book API: create a book, list books and delete a book. It uses Node.js 24, ES modules and SDK v3. AWS SDK for JavaScript v2 reached end of support on September 8, 2025, and old nodejs12.x examples should not be deployed.

Serverless Framework provides another YAML workflow, while AWS CDK synthesizes infrastructure from code. SAM is a practical choice when your team wants CloudFormation templates plus AWS-maintained local Lambda tooling.

Step 1: prepare the project

Install AWS CLI v2, SAM CLI, Docker and a supported Node.js release. Use an AWS profile for deployment:

export AWS_PROFILE=development
aws sts get-caller-identity
node --version
sam --version
sam init
export AWS_PROFILE=development
aws sts get-caller-identity
node --version
sam --version
sam init

Choose an AWS Quick Start Node.js project with the nodejs24.x runtime and ZIP packaging. Wizard menu numbers can change, so select by the displayed runtime name. For the files below, use a books directory beside template.yaml and initialize its runtime dependencies:

mkdir -p books
cd books
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
cd ..
mkdir -p books
cd books
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
cd ..

Remove or replace the sample Hello World resource in the generated template. The handler below is books/app.mjs; .mjs makes it an ES module without relying on the package's type field. Keep the dependency lock file and build with a current SAM CLI that supports the selected runtime.

SimpleTable versus AWS::DynamoDB::Table

A valid SimpleTable declaration uses a PrimaryKey object, not PrimaryKey: name:

BooksTable:
  Type: AWS::Serverless::SimpleTable
  DeletionPolicy: Retain
  UpdateReplacePolicy: Retain
  Properties:
    PrimaryKey:
      Name: name
      Type: String
    PointInTimeRecoverySpecification:
      PointInTimeRecoveryEnabled: true
      RecoveryPeriodInDays: 14
BooksTable:
  Type: AWS::Serverless::SimpleTable
  DeletionPolicy: Retain
  UpdateReplacePolicy: Retain
  Properties:
    PrimaryKey:
      Name: name
      Type: String
    PointInTimeRecoverySpecification:
      PointInTimeRecoveryEnabled: true
      RecoveryPeriodInDays: 14

Insert that under Resources in a SAM template. Without ProvisionedThroughput, SimpleTable generates on-demand billing. Its default key is a String named id if PrimaryKey is omitted. It supports PITR, encryption settings, tags and a table name, but it is intentionally narrower than the full resource. See the SimpleTable reference.

SAM templates can contain all these CloudFormation resources. Choosing the full Table does not prevent you from using SAM functions or policy templates alongside it.

Step 2: define the table and functions

Use this complete template.yaml for the walkthrough. It chooses the full Table to enable deletion protection:

AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Books API with DynamoDB

Globals:
  Function:
    Runtime: nodejs24.x
    Timeout: 10
    Environment:
      Variables:
        TABLE_NAME: !Ref BooksTable
        DYNAMODB_ENDPOINT: ""

Resources:
  BooksTable:
    Type: AWS::DynamoDB::Table
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      DeletionProtectionEnabled: true
      AttributeDefinitions:
        - AttributeName: name
          AttributeType: S
      KeySchema:
        - AttributeName: name
          KeyType: HASH
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true
        RecoveryPeriodInDays: 14

  CreateBookFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.create
      Policies:
        - Statement:
            - Effect: Allow
              Action: dynamodb:PutItem
              Resource: !GetAtt BooksTable.Arn
      Events:
        CreateBook:
          Type: Api
          Properties:
            Path: /books
            Method: post

  ListBooksFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.list
      Policies:
        - DynamoDBReadPolicy:
            TableName: !Ref BooksTable
      Events:
        ListBooks:
          Type: Api
          Properties:
            Path: /books
            Method: get

  DeleteBookFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.remove
      Policies:
        - Statement:
            - Effect: Allow
              Action: dynamodb:DeleteItem
              Resource: !GetAtt BooksTable.Arn
      Events:
        DeleteBook:
          Type: Api
          Properties:
            Path: /books/{name}
            Method: delete

Outputs:
  TableName:
    Value: !Ref BooksTable
  ApiUrl:
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/Prod/books"
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: Books API with DynamoDB

Globals:
  Function:
    Runtime: nodejs24.x
    Timeout: 10
    Environment:
      Variables:
        TABLE_NAME: !Ref BooksTable
        DYNAMODB_ENDPOINT: ""

Resources:
  BooksTable:
    Type: AWS::DynamoDB::Table
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Properties:
      BillingMode: PAY_PER_REQUEST
      DeletionProtectionEnabled: true
      AttributeDefinitions:
        - AttributeName: name
          AttributeType: S
      KeySchema:
        - AttributeName: name
          KeyType: HASH
      PointInTimeRecoverySpecification:
        PointInTimeRecoveryEnabled: true
        RecoveryPeriodInDays: 14

  CreateBookFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.create
      Policies:
        - Statement:
            - Effect: Allow
              Action: dynamodb:PutItem
              Resource: !GetAtt BooksTable.Arn
      Events:
        CreateBook:
          Type: Api
          Properties:
            Path: /books
            Method: post

  ListBooksFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.list
      Policies:
        - DynamoDBReadPolicy:
            TableName: !Ref BooksTable
      Events:
        ListBooks:
          Type: Api
          Properties:
            Path: /books
            Method: get

  DeleteBookFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: books/
      Handler: app.remove
      Policies:
        - Statement:
            - Effect: Allow
              Action: dynamodb:DeleteItem
              Resource: !GetAtt BooksTable.Arn
      Events:
        DeleteBook:
          Type: Api
          Properties:
            Path: /books/{name}
            Method: delete

Outputs:
  TableName:
    Value: !Ref BooksTable
  ApiUrl:
    Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/Prod/books"

SAM generates the REST API referenced by ServerlessRestApi from the Api events. Each function gets a separate execution role unless you supply one. The globals supply the same table name to all functions; permissions are configured separately.

When to use DynamoDBCrudPolicy

For a function that genuinely needs several table operations, SAM provides this shorthand inside the function's Properties:

Policies:
  - DynamoDBCrudPolicy:
      TableName: !Ref BooksTable
Policies:
  - DynamoDBCrudPolicy:
      TableName: !Ref BooksTable

It grants a group of data operations on the named table and its indexes. Pass the table name, not its ARN, because SAM constructs ARNs from the placeholder. It does not create the table or give the caller access to the HTTP API. The policy template list shows the exact generated actions.

Use DynamoDBReadPolicy for read-only functions, DynamoDBWritePolicy when the broader write group is appropriate, or an inline policy for one action as above. DynamoDBStreamReadPolicy concerns stream access, which is separate from table reads. If you supply an existing function Role, SAM does not add its Policies entries to that role; manage the role's policies yourself.

Step 3: implement create, list and delete

Start books/app.mjs with a shared SDK v3 client:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient, PutCommand, ScanCommand, DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const endpoint = process.env.DYNAMODB_ENDPOINT
const db = DynamoDBDocumentClient.from(new DynamoDBClient(endpoint ? {
  endpoint,
  region: "us-east-1",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
} : {}))
const TableName = process.env.TABLE_NAME
const json = (statusCode, value) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(value),
})
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import {
  DynamoDBDocumentClient, PutCommand, ScanCommand, DeleteCommand,
} from "@aws-sdk/lib-dynamodb"

const endpoint = process.env.DYNAMODB_ENDPOINT
const db = DynamoDBDocumentClient.from(new DynamoDBClient(endpoint ? {
  endpoint,
  region: "us-east-1",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
} : {}))
const TableName = process.env.TABLE_NAME
const json = (statusCode, value) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(value),
})

The local endpoint override uses dummy credentials; when it is empty in AWS, the SDK uses the Lambda execution role. Bundle the SDK packages rather than depending on the runtime's installed version.

Create a book

export const create = async (event) => {
  let body
  try {
    const raw = event.isBase64Encoded
      ? Buffer.from(event.body, "base64").toString("utf8")
      : event.body
    body = JSON.parse(raw)
  } catch {
    return json(400, { message: "Body must be JSON" })
  }
  if (typeof body?.name !== "string" || !body.name.trim() ||
      typeof body.author !== "string" || !Number.isInteger(body.pages) || body.pages < 1) {
    return json(400, { message: "name, author and a positive integer pages are required" })
  }
  const book = { name: body.name, author: body.author, pages: body.pages }
  try {
    await db.send(new PutCommand({
      TableName,
      Item: book,
      ConditionExpression: "attribute_not_exists(#name)",
      ExpressionAttributeNames: { "#name": "name" },
    }))
    return json(201, book)
  } catch (error) {
    if (error.name === "ConditionalCheckFailedException") {
      return json(409, { message: "Book already exists" })
    }
    throw error
  }
}
export const create = async (event) => {
  let body
  try {
    const raw = event.isBase64Encoded
      ? Buffer.from(event.body, "base64").toString("utf8")
      : event.body
    body = JSON.parse(raw)
  } catch {
    return json(400, { message: "Body must be JSON" })
  }
  if (typeof body?.name !== "string" || !body.name.trim() ||
      typeof body.author !== "string" || !Number.isInteger(body.pages) || body.pages < 1) {
    return json(400, { message: "name, author and a positive integer pages are required" })
  }
  const book = { name: body.name, author: body.author, pages: body.pages }
  try {
    await db.send(new PutCommand({
      TableName,
      Item: book,
      ConditionExpression: "attribute_not_exists(#name)",
      ExpressionAttributeNames: { "#name": "name" },
    }))
    return json(201, book)
  } catch (error) {
    if (error.name === "ConditionalCheckFailedException") {
      return json(409, { message: "Book already exists" })
    }
    throw error
  }
}

API Gateway sends event.body as a string, so parse it before accessing fields. The condition rejects an existing title rather than replacing it. A real catalog usually needs a stable ID because different books can share a title; the name key is retained here to keep the demonstration simple.

List a page of books

export const list = async (event) => {
  let ExclusiveStartKey
  const token = event.queryStringParameters?.nextToken
  if (token) {
    try {
      const key = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
      if (typeof key?.name !== "string" || !key.name) throw new Error("Invalid key")
      ExclusiveStartKey = { name: key.name }
    } catch {
      return json(400, { message: "Invalid nextToken" })
    }
  }
  const result = await db.send(new ScanCommand({ TableName, Limit: 100, ExclusiveStartKey }))
  return json(200, {
    items: result.Items ?? [],
    nextToken: result.LastEvaluatedKey
      ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
      : null,
  })
}
export const list = async (event) => {
  let ExclusiveStartKey
  const token = event.queryStringParameters?.nextToken
  if (token) {
    try {
      const key = JSON.parse(Buffer.from(token, "base64url").toString("utf8"))
      if (typeof key?.name !== "string" || !key.name) throw new Error("Invalid key")
      ExclusiveStartKey = { name: key.name }
    } catch {
      return json(400, { message: "Invalid nextToken" })
    }
  }
  const result = await db.send(new ScanCommand({ TableName, Limit: 100, ExclusiveStartKey }))
  return json(200, {
    items: result.Items ?? [],
    nextToken: result.LastEvaluatedKey
      ? Buffer.from(JSON.stringify(result.LastEvaluatedKey)).toString("base64url")
      : null,
  })
}

A Scan returns a page, not the entire database. Continue until the token is null. Limit controls evaluated items; filters can leave a short or empty page with another token. For a large catalog, model a Query access pattern instead of repeatedly scanning all books.

Delete a book

export const remove = async (event) => {
  const name = event.pathParameters?.name
  if (typeof name !== "string" || !name) return json(400, { message: "name is required" })
  await db.send(new DeleteCommand({ TableName, Key: { name } }))
  return { statusCode: 204, body: "" }
}
export const remove = async (event) => {
  const name = event.pathParameters?.name
  if (typeof name !== "string" || !name) return json(400, { message: "name is required" })
  await db.send(new DeleteCommand({ TableName, Key: { name } }))
  return { statusCode: 204, body: "" }
}

Use URL encoding for book names in request paths. DeleteItem is successful even when the item is already absent. Add a condition if your API needs a distinct not-found response.

Step 4: test SAM locally with DynamoDB Local

sam local runs Lambda code in Docker but does not create the DynamoDB table from your template. Run DynamoDB Local on a shared Docker network and create the table explicitly:

docker network create sam-local
docker run --rm -d --name dynamodb-local --network sam-local \
  -p 127.0.0.1:8000:8000 amazon/dynamodb-local:3.3.2 \
  -jar DynamoDBLocal.jar -sharedDb -inMemory
AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local AWS_SESSION_TOKEN= \
  aws dynamodb create-table --endpoint-url http://127.0.0.1:8000 --region us-east-1 \
  --table-name books-local \
  --attribute-definitions AttributeName=name,AttributeType=S \
  --key-schema AttributeName=name,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST
docker network create sam-local
docker run --rm -d --name dynamodb-local --network sam-local \
  -p 127.0.0.1:8000:8000 amazon/dynamodb-local:3.3.2 \
  -jar DynamoDBLocal.jar -sharedDb -inMemory
AWS_ACCESS_KEY_ID=local AWS_SECRET_ACCESS_KEY=local AWS_SESSION_TOKEN= \
  aws dynamodb create-table --endpoint-url http://127.0.0.1:8000 --region us-east-1 \
  --table-name books-local \
  --attribute-definitions AttributeName=name,AttributeType=S \
  --key-schema AttributeName=name,KeyType=HASH \
  --billing-mode PAY_PER_REQUEST

Create env.local.json:

{
  "Parameters": {
    "TABLE_NAME": "books-local",
    "DYNAMODB_ENDPOINT": "http://dynamodb-local:8000"
  }
}
{
  "Parameters": {
    "TABLE_NAME": "books-local",
    "DYNAMODB_ENDPOINT": "http://dynamodb-local:8000"
  }
}

The host CLI reaches the published localhost port. The SAM Lambda container reaches the other container by its network name, dynamodb-local; localhost inside the Lambda container would refer to itself.

sam validate --lint
sam build
sam local start-api --docker-network sam-local --env-vars env.local.json
sam validate --lint
sam build
sam local start-api --docker-network sam-local --env-vars env.local.json

Call http://127.0.0.1:3000/books with a JSON POST body, then GET and DELETE requests. For one function invocation, write an API event to event.json and run:

sam local invoke CreateBookFunction --event event.json \
  --docker-network sam-local --env-vars env.local.json
sam local invoke CreateBookFunction --event event.json \
  --docker-network sam-local --env-vars env.local.json

An example event is {"body":"{\"name\":\"DynamoDB Notes\",\"author\":\"Sam\",\"pages\":120}"}. The local invocation documentation explains environment overrides and event files.

This database is in memory and disappears when the container stops. For persistent Compose storage and more SDK configurations, see running DynamoDB locally. Local tests do not validate IAM, PITR, replication or real throughput limits.

Step 5: deploy and operate the API

sam build
sam deploy --guided
sam build
sam deploy --guided

Review the account, Region, generated IAM roles and change set. Keep the local endpoint override out of deployment configuration. The guided deployment can save non-secret settings in samconfig.toml; use separate stack names and configurations for development and production.

The example exposes unauthenticated demonstration routes. Before using real data, configure API authorization, enforce item ownership, validate field lengths and handle application errors consistently. Confirm both successful requests and denied requests in AWS; a local success cannot demonstrate the execution role's permissions.

Monitor API and Lambda errors plus DynamoDB throttles. Enable appropriate alarms, test backup restoration, and document how the application switches to a restored table. PITR restores into a new table and supports a 1-to-35-day recovery window; shortening it does not reduce the price.

Indexes, Streams and safe cleanup

Use AWS::DynamoDB::Table for GSIs or LSIs and declare their keys alongside the table keys. Secondary indexes store projected data and add storage and write costs; they do not give free alternative queries. GSIs can be added later, while LSIs must be defined at table creation.

For event-driven processing, enable DynamoDB Streams and attach a SAM DynamoDB event source to a subscriber function. A table's stream permissions differ from its CRUD permissions. Consumers must handle duplicate delivery; see the Streams guide for retry and failure handling.

sam delete removes the stack, but the Retain policies in this template preserve the table. Deletion protection also blocks direct deletion until explicitly disabled. Retained tables continue to incur charges. If the database has a longer lifecycle than the API, manage it in a dedicated CloudFormation stack and pass its name and ARN to the application stack.