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

# Stockage DuckDB

[DuckDB](https://duckdb.org/) est une base de données analytique embarquée, exécutée dans le processus. Le package `@mastra/duckdb` fournit un stockage d’observabilité fondé sur OLAP pour le développement local. Il permet de gérer les Traces, logs, métriques, scores et retours sans exécuter de service externe.

Pour la recherche vectorielle, consultez la [référence du stockage vectoriel DuckDB](https://mastra.zisheng.pro/fr/reference/vectors/duckdb), qui correspond à une API distincte dans le même package.

## Quand utiliser DuckDB

DuckDB est adapté au développement local de fonctionnalités d’observabilité. Comme il est embarqué et fondé sur un fichier, il ne nécessite aucun serveur et démarre instantanément. Il prend en charge les mêmes signaux d’observabilité que ClickHouse, ce qui permet de tester les tableaux de bord et l’exploration des Traces avant le déploiement sur un backend de production.

DuckDB n’implémente actuellement que le domaine `observability`. Associez-le à un autre adaptateur de stockage, tel que [LibSQL](https://mastra.zisheng.pro/fr/reference/storage/libsql), pour les domaines `memory` et `workflows` dans une configuration de [stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite).

> **Attention:** DuckDB est destiné au développement et n’est pas recommandé en production. Il s’exécute dans le processus, conserve les données dans un unique fichier local et ne fonctionne pas sur les plateformes dotées de systèmes de fichiers éphémères, telles que Railway, Fly.io, Render, Heroku ou les conteneurs serverless. Pour l’observabilité en production, utilisez [ClickHouse](https://mastra.zisheng.pro/fr/reference/storage/clickhouse).

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
bun add @mastra/duckdb@latest
```

## Utilisation

### Comme domaine d’observabilité d’un stockage composite

Il s’agit de la configuration standard pour le développement local. LibSQL gère les autres domaines et DuckDB gère l’observabilité.

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: new DuckDBStore().observability,
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

L’accesseur `.observability` renvoie directement le stockage du domaine d’observabilité. La forme générique équivalente utilise `getStore()`, qui fonctionne avec tout adaptateur de stockage de type composite :

```typescript
const observability = await new DuckDBStore().getStore('observability')
```

### Utilisation autonome

Lorsque vous avez uniquement besoin du stockage d’observabilité en dehors du composite `Mastra`, instanciez directement `DuckDBStore` et accédez au domaine d’observabilité :

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
const observability = duckdb.observability

await observability.init()
```

### Base de données en mémoire

Transmettez `:memory:` pour utiliser une instance DuckDB éphémère. Les données sont perdues à l’arrêt du processus, ce qui convient aux tests unitaires et aux scripts de courte durée.

```typescript
const duckdb = new DuckDBStore({ path: ':memory:' })
```

## Configuration

### `DuckDBStore` options

**id** (`string`): Identifiant unique de cette instance de stockage. (Default: `'duckdb'`)

**path** (`string`): Chemin du fichier de base de données DuckDB. Utilisez :memory: pour une base de données éphémère en mémoire. (Default: `'mastra.duckdb'`)

**memoryLimit** (`string`): Quantité maximale de mémoire que DuckDB peut utiliser, par exemple '2GB' ou '512MB'. Pour les bases de données fondées sur un fichier, les opérations qui dépassent cette quantité utilisent le disque. Augmentez cette valeur pour les charges de travail analytiques dédiées. (Default: `'2GB'`)

**threads** (`number`): Nombre de threads que DuckDB peut utiliser. Réduisez cette valeur pour éviter que les requêtes ne monopolisent tous les cœurs d’un serveur d’applications partagé. (Default: `un par cœur de processeur`)

### Types de bas niveau

`@mastra/duckdb` exporte également `DuckDBConnection`, qui permet de partager une même base de données sous-jacente entre plusieurs instances de stockage Mastra, ainsi que le type `DuckDBStorageConfig` correspondant. La plupart des applications n’ont pas besoin de les utiliser directement.

## Domaines pris en charge

DuckDB implémente actuellement un seul domaine de stockage :

| Domaine         | Pris en charge |
| --------------- | -------------- |
| `observability` | Oui            |
| `memory`        | Non            |
| `workflows`     | Non            |
| `scores`        | Non            |
| `agents`        | Non            |

Pour obtenir une solution de stockage complète, combinez `DuckDBStore` avec un adaptateur qui couvre les domaines manquants, le plus souvent [LibSQL](https://mastra.zisheng.pro/fr/reference/storage/libsql) pour le développement local.

## Initialisation

Lorsqu’il est transmis à `Mastra` par l’intermédiaire de `MastraCompositeStore`, le domaine d’observabilité s’initialise à la première utilisation. Pour exécuter explicitement l’initialisation en dehors de `Mastra`, appelez `init()` sur le stockage d’observabilité :

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
await duckdb.observability.init()
```

## Stratégie d’observabilité

DuckDB prend en charge la stratégie `event-sourced` utilisée par `MastraStorageExporter`, qui met les spans en mémoire tampon et écrit par lots les événements terminés. Cette approche convient à un trafic de développement. Pour les charges de travail de production à volume élevé, consultez la page sur [la prise en charge des Providers de stockage par `MastraStorageExporter`](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/mastra-storage).

## Voir aussi

- [Présentation du stockage](https://mastra.zisheng.pro/fr/reference/storage/overview)
- [Stockage composite](https://mastra.zisheng.pro/fr/reference/storage/composite)
- [Stockage ClickHouse](https://mastra.zisheng.pro/fr/reference/storage/clickhouse) : backend d’observabilité pour la production
- [Stockage vectoriel DuckDB](https://mastra.zisheng.pro/fr/reference/vectors/duckdb) : recherche vectorielle avec le même package
- [Présentation de l’observabilité](https://mastra.zisheng.pro/fr/docs/observability/overview)