Upstash Storage

The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.

warning

Important: When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a fixed pricing plan for predictable costs. See Upstash pricing for details and GitHub issue #5850 for context.

Installation

npm install @mastra/upstash@latest

Usage

import { UpstashStore } from "@mastra/upstash";

const storage = new UpstashStore({
  url: process.env.UPSTASH_URL,
  token: process.env.UPSTASH_TOKEN,
});

Parameters

url:

string

Upstash Redis URL

token:

string

Upstash Redis authentication token

prefix?:

string

= mastra:

Key prefix for all stored items

Additional Notes

Key Structure

The Upstash storage implementation uses a key-value structure:

• Thread keys: {prefix}thread:{threadId}
• Message keys: {prefix}message:{messageId}
• Metadata keys: {prefix}metadata:{entityId}

Serverless Benefits

Upstash storage is particularly well-suited for serverless deployments:

• No connection management needed
• Pay-per-request pricing
• Global replication options
• Edge-compatible

Data Persistence

Upstash provides:

• Automatic data persistence
• Point-in-time recovery
• Cross-region replication options

Performance Considerations

For optimal performance:

• Use appropriate key prefixes to organize data
• Monitor Redis memory usage
• Consider data expiration policies if needed