Skip to main content
Mastra 1.0 is available 🎉 Read announcement

Cloudflare Storage

The Cloudflare KV storage implementation provides a globally distributed, serverless key-value store solution using Cloudflare Workers KV.

Observability Not Supported

Cloudflare KV storage does not support the observability domain. Traces from the DefaultExporter cannot be persisted to KV, and Mastra Studio's observability features won't work with Cloudflare KV as your only storage provider. To enable observability, use composite storage to route observability data to a supported provider like ClickHouse or PostgreSQL.

Installation
Direct link to Installation

npm install @mastra/cloudflare@latest

Usage
Direct link to Usage

import { CloudflareStore } from "@mastra/cloudflare";

// --- Example 1: Using Workers Binding ---
const storageWorkers = new CloudflareStore({
  id: "cloudflare-workers-storage",
  bindings: {
    threads: THREADS_KV, // KVNamespace binding for threads table
    messages: MESSAGES_KV, // KVNamespace binding for messages table
    // Add other tables as needed
  },
  keyPrefix: "dev_", // Optional: isolate keys per environment
});

// --- Example 2: Using REST API ---
const storageRest = new CloudflareStore({
  id: "cloudflare-rest-storage",
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!, // Cloudflare Account ID
  apiToken: process.env.CLOUDFLARE_API_TOKEN!, // Cloudflare API Token
  namespacePrefix: "dev_", // Optional: isolate namespaces per environment
});

Parameters
Direct link to Parameters

id:

string
Unique identifier for this storage instance.

bindings?:

Record<string, KVNamespace>
Cloudflare Workers KV bindings (for Workers runtime)

accountId?:

string
Cloudflare Account ID (for REST API)

apiToken?:

string
Cloudflare API Token (for REST API)

namespacePrefix?:

string
Optional prefix for all namespace names (useful for environment isolation)

keyPrefix?:

string
Optional prefix for all keys (useful for environment isolation)

Additional Notes
Direct link to Additional Notes

Schema Management
Direct link to Schema Management

The storage implementation handles schema creation and updates automatically. It creates the following tables:

  • threads: Stores conversation threads
  • messages: Stores individual messages
  • metadata: Stores additional metadata for threads and messages

Consistency & Propagation
Direct link to Consistency & Propagation

Cloudflare KV is an eventually consistent store, meaning that data may not be immediately available across all regions after a write.

Key Structure & Namespacing
Direct link to Key Structure & Namespacing

Keys in Cloudflare KV are structured as a combination of a configurable prefix and a table-specific format (e.g., threads:threadId). For Workers deployments, keyPrefix is used to isolate data within a namespace; for REST API deployments, namespacePrefix is used to isolate entire namespaces between environments or applications.

On this page