Skip to main content
DynamoDB storage provides serverless, fully managed NoSQL storage for Mastra with automatic scaling and pay-per-request pricing.

​
Installation

npm install @mastra/dynamodb

​
Configuration

1

Import DynamoDBStore

import { DynamoDBStore } from '@mastra/dynamodb';
2

Create storage instance

const storage = new DynamoDBStore({
  id: 'my-storage',
  region: process.env.AWS_REGION!,
});
3

Configure Mastra

import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  storage,
});

​
Configuration Options

​
id
string
required
Unique identifier for the storage instance
​
region
string
required
AWS region (e.g., us-east-1, eu-west-1)
​
credentials
object
AWS credentials (optional if using IAM roles or environment variables)
{
  accessKeyId: string,
  secretAccessKey: string
}
​
tablePrefix
string
default:"mastra"
Prefix for DynamoDB table names
​
endpoint
string
Custom endpoint URL (for DynamoDB Local or custom deployments)
​
disableInit
boolean
default:false
Disable automatic table creation

​
Usage Examples

​
AWS Credentials from Environment

import { DynamoDBStore } from '@mastra/dynamodb';
import { Mastra } from '@mastra/core';

// AWS SDK will automatically use:
// - AWS_ACCESS_KEY_ID
// - AWS_SECRET_ACCESS_KEY
// - AWS_REGION
const storage = new DynamoDBStore({
  id: 'storage',
  region: process.env.AWS_REGION!,
});

const mastra = new Mastra({
  storage,
});

​
Explicit Credentials

const storage = new DynamoDBStore({
  id: 'storage',
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

// No credentials needed when running on EC2, ECS, or Lambda
// with proper IAM role attached
const storage = new DynamoDBStore({
  id: 'storage',
  region: process.env.AWS_REGION!,
});

​
DynamoDB Local (Development)

const storage = new DynamoDBStore({
  id: 'dev-storage',
  region: 'local',
  endpoint: 'http://localhost:8000',
});

​
Custom Table Prefix

const storage = new DynamoDBStore({
  id: 'storage',
  region: process.env.AWS_REGION!,
  tablePrefix: 'prod-mastra',
});
// Creates tables like: prod-mastra-memory, prod-mastra-workflows, etc.

​
Access Storage Domains

const storage = new DynamoDBStore({
  id: 'storage',
  region: process.env.AWS_REGION!,
});

// Access memory domain
const memory = await storage.getStore('memory');
await memory?.saveThread({ thread });

// Access workflows domain
const workflows = await storage.getStore('workflows');
await workflows?.persistWorkflowSnapshot({
  workflowName: 'my-workflow',
  runId: 'run-123',
  snapshot,
});

​
Storage Domains

DynamoDB storage supports these Mastra domains:
  • memory - Thread-based conversation persistence
  • workflows - Workflow execution snapshots
  • observability - Telemetry and logging
  • agents - Agent configurations

​
IAM Policy Requirements

Minimum IAM permissions required: 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:CreateTable",
        "dynamodb:DescribeTable",
        "dynamodb:PutItem",
        "dynamodb:GetItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:BatchGetItem",
        "dynamodb:BatchWriteItem"
      ],
      "Resource": "arn:aws:dynamodb:*:*:table/mastra-*"
    }
  ]
}

​
Cost Optimization

​
On-Demand Billing

DynamoDB storage uses on-demand billing mode by default for predictable costs: 
const storage = new DynamoDBStore({
  id: 'storage',
  region: process.env.AWS_REGION!,
});

​
Provisioned Capacity

For predictable workloads, configure provisioned capacity in AWS Console or via IaC.

​
DynamoDB Local for Testing

​
Start DynamoDB Local

docker run -p 8000:8000 amazon/dynamodb-local

​
Configure Storage

const storage = new DynamoDBStore({
  id: 'test-storage',
  region: 'local',
  endpoint: 'http://localhost:8000',
});

​
Best Practices

Use IAM Roles

Prefer IAM roles over hardcoded credentials for security.

Table Prefixes

Use table prefixes to separate environments:
tablePrefix: `${process.env.STAGE}-mastra`

On-Demand Billing

Start with on-demand billing and switch to provisioned capacity if you have predictable traffic.

Point-in-Time Recovery

Enable PITR in AWS Console for production tables.

​
Monitoring

​
CloudWatch Metrics

Monitor these DynamoDB metrics:
  • ConsumedReadCapacityUnits
  • ConsumedWriteCapacityUnits
  • ThrottledRequests
  • SystemErrors

​
Enable X-Ray Tracing

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { captureDynamoDBv3Client } from 'aws-xray-sdk';

const client = new DynamoDBClient({ region: 'us-east-1' });
captureDynamoDBv3Client(client);

PostgreSQL Storage

SQL alternative with relational features

MongoDB Storage

NoSQL alternative with flexible schema

DynamoDB Docs

Official AWS DynamoDB documentation

ElectroDB

DynamoDB ORM used by Mastra

Build docs developers (and LLMs) love

Get started for freeTalk to us