Stockage Cloudflare

Mastra fournit deux implémentations de stockage Cloudflare :

• Cloudflare KV (CloudflareKVStorage) : stockage clé-valeur distribué à l'échelle mondiale et offrant une cohérence à terme
• Cloudflare Durable Objects (CloudflareDOStorage) : stockage à cohérence forte, fondé sur SQLite et utilisant Durable Objects

Observabilité non prise en charge

Le stockage Cloudflare ne prend pas en charge le domaine de l'observabilité. Les Traces de MastraStorageExporter ne peuvent pas être conservées et les fonctionnalités d'observabilité du Studio ne fonctionnent pas si Cloudflare est votre seul Provider de stockage. Pour activer l'observabilité, utilisez un stockage composite afin d'acheminer les données d'observabilité vers un Provider pris en charge, tel que ClickHouse.

Installation

npm

npm install @mastra/cloudflare@latest

pnpm

pnpm add @mastra/cloudflare@latest

Yarn

yarn add @mastra/cloudflare@latest

Bun

bun add @mastra/cloudflare@latest

Stockage Cloudflare KV

L'implémentation de stockage KV fournit une solution de stockage clé-valeur distribuée à l'échelle mondiale et sans serveur au moyen de Cloudflare Workers KV.

Utilisation

import { CloudflareKVStorage } from '@mastra/cloudflare/kv'

// --- Example 1: Using Workers Binding ---
const storageWorkers = new CloudflareKVStorage({
  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 CloudflareKVStorage({
  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
})

Paramètres

id:

string

Identifiant unique de cette instance de stockage.

bindings?:

Record<string, KVNamespace>

Bindings Cloudflare Workers KV (pour l'environnement d'exécution Workers)

accountId?:

string

Identifiant du compte Cloudflare (pour l'API REST)

apiToken?:

string

Token d'API Cloudflare (pour l'API REST)

namespacePrefix?:

string

Préfixe facultatif pour tous les noms d'espaces de noms (utile pour isoler les environnements)

keyPrefix?:

string

Préfixe facultatif pour toutes les clés (utile pour isoler les environnements)

Remarques supplémentaires

Gestion du schéma

L'implémentation de stockage gère automatiquement la création et la mise à jour du schéma. Elle crée les tables suivantes :

• threads : stocke les threads de conversation
• messages : stocke les messages individuels
• metadata : stocke les métadonnées supplémentaires des threads et des messages

Cohérence et propagation

Cloudflare KV est un stockage à cohérence à terme. Après une écriture, les données peuvent donc ne pas être immédiatement disponibles dans toutes les régions.

Structure des clés et espaces de noms

Les clés de Cloudflare KV combinent un préfixe configurable et un format propre à la table (par exemple, threads:threadId). Pour les déploiements Workers, keyPrefix permet d'isoler les données dans un espace de noms ; pour les déploiements avec l'API REST, namespacePrefix permet d'isoler des espaces de noms entiers entre les environnements ou les applications.

Stockage Cloudflare Durable Objects

L'implémentation de stockage Durable Objects fournit un stockage à cohérence forte fondé sur SQLite au moyen de Cloudflare Durable Objects. Elle est idéale pour les applications qui nécessitent une cohérence transactionnelle et des fonctionnalités de requête SQL.

Utilisation

import { DurableObject } from 'cloudflare:workers'
import { CloudflareDOStorage } from '@mastra/cloudflare/do'

class AgentDurableObject extends DurableObject<Env> {
  private storage: CloudflareDOStorage

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
    this.storage = new CloudflareDOStorage({
      sql: ctx.storage.sql,
      tablePrefix: 'mastra_', // Optional: prefix for table names
    })
  }

  async run() {
    const memory = await this.storage.getStore('memory')
    await memory?.saveThread({
      thread: { id: 'thread-1', resourceId: 'user-1', title: 'Chat', metadata: {} },
    })
  }
}

Paramètres

sql:

SqlStorage

Instance SqlStorage issue de Durable Objects ctx.storage.sql

tablePrefix?:

string

Préfixe facultatif des noms de tables (seuls les lettres, les chiffres et les traits de soulignement sont autorisés)

disableInit?:

boolean

Lorsque la valeur est true, la création automatique des tables et les migrations sont désactivées. Utile pour les pipelines CI/CD dans lesquels les migrations s'exécutent séparément.

Cohérence forte

Contrairement à KV, Durable Objects offre des garanties de cohérence forte. Toutes les lectures et écritures au sein d'un Durable Object sont sérialisées, ce qui le rend particulièrement adapté aux Agents rapides qui s'exécutent longtemps.

Fonctionnalités SQL

Le stockage Durable Objects utilise SQLite en interne, ce qui permet des requêtes, un filtrage et une pagination efficaces impossibles avec un stockage clé-valeur.

Gestion du schéma

Les deux implémentations de stockage gèrent automatiquement la création et la mise à jour du schéma. Elles créent les tables suivantes :

• threads : stocke les threads de conversation
• messages : stocke les messages individuels
• workflow_snapshot : stocke l'état d'exécution du Workflow

Alias obsolètes

Pour assurer la rétrocompatibilité, les alias suivants sont disponibles :

// These are deprecated - use CloudflareKVStorage and CloudflareDOStorage instead
import { CloudflareStore } from '@mastra/cloudflare/kv' // alias for CloudflareKVStorage
import { DOStore } from '@mastra/cloudflare/do' // alias for CloudflareDOStorage