> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/studio/overview) ne fonctionnent pas si Cloudflare est votre seul Provider de stockage. Pour activer l'observabilité, utilisez un [stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite) afin d'acheminer les données d'observabilité vers un Provider pris en charge, tel que ClickHouse.

## Installation

**npm**:

```bash
npm install @mastra/cloudflare@latest
```

**pnpm**:

```bash
pnpm add @mastra/cloudflare@latest
```

**Yarn**:

```bash
yarn add @mastra/cloudflare@latest
```

**Bun**:

```bash
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

```typescript
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

```typescript
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 :

```typescript
// 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
```