Stockage DuckDB

DuckDB 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, 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, pour les domaines memory et workflows dans une configuration de stockage 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.

Installation

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

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é.

src/mastra/index.ts

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 :

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é :

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.

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

Configuration

DuckDBStore options

id?:

string

= 'duckdb'

Identifiant unique de cette instance de stockage.

path?:

string

= 'mastra.duckdb'

Chemin du fichier de base de données DuckDB. Utilisez :memory: pour une base de données éphémère en mémoire.

memoryLimit?:

string

= '2GB'

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.

threads?:

number

= un par cœur de processeur

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é.

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 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é :

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.

Voir aussi

• Présentation du stockage
• Stockage composite
• Stockage ClickHouse : backend d’observabilité pour la production
• Stockage vectoriel DuckDB : recherche vectorielle avec le même package
• Présentation de l’observabilité