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