DuckDB 存储

DuckDB 是一款嵌入式进程内分析型数据库。@mastra/duckdb 包提供由 OLAP 支持的 observability 存储，适用于本地开发，可存储 Trace、日志、指标、分数和反馈，无需运行外部服务。

对于向量搜索，请参阅 DuckDB vector store 参考，它是同一包中独立的 API。

何时使用 DuckDB

用于 observability 功能的本地开发。DuckDB 是嵌入式且基于文件的，无需服务器并能立即启动。它支持与 ClickHouse 相同的 observability 信号，因此适合在部署到生产后端前测试仪表板和 Trace 探索。

DuckDB 当前仅实现 observability 域。在组合存储设置中，将它与其他 storage adapter（如 LibSQL）搭配使用，以支持 memory 和 workflows。

注意

DuckDB 用于开发，不建议用于生产。它在进程内运行、持久化到单个本地文件，且无法在具有临时文件系统的平台（如 Railway、Fly.io、Render、Heroku 或 serverless 容器）上运行。生产环境的 observability 请使用 ClickHouse。

安装

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

使用方法

在组合存储中作为 observability 域

这是标准的本地开发设置。LibSQL 处理其他域，DuckDB 处理 observability。

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()],
      },
    },
  }),
})

.observability accessor 直接返回 observability 域存储。等效的通用形式使用 getStore()，适用于任何组合风格的 storage adapter：

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

独立使用

当仅在 Mastra composite 外部需要 observability 存储时，直接实例化 DuckDBStore 并访问 observability 域：

import { DuckDBStore } from '@mastra/duckdb'

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

await observability.init()

内存数据库

传递 :memory: 以使用临时 DuckDB 实例。进程退出时数据会丢失，适合单元测试和短生命周期脚本。

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

配置

DuckDBStore 选项

id?:

string

= 'duckdb'

此 storage 实例的唯一标识符。

path?:

string

= 'mastra.duckdb'

DuckDB 数据库文件的路径。使用 :memory: 创建临时内存数据库。

memoryLimit?:

string

= '2GB'

DuckDB 可使用的最大内存，例如 '2GB' 或 '512MB'。对于基于文件的数据库，超出内存大小的操作会写入磁盘。可为专用分析工作负载提高此值。

threads?:

number

= 每个 CPU 核心一个

DuckDB 可使用的线程数。可降低此值，避免查询占用共享应用服务器的所有 CPU 核心。

底层类型

@mastra/duckdb 还导出 DuckDBConnection，用于在多个 Mastra storage 实例之间共享单个底层数据库，以及相应的 DuckDBStorageConfig 类型。大多数应用无需直接使用它们。

支持的域

DuckDB 当前实现一个 storage 域：

域	支持情况
observability	是
memory	否
workflows	否
scores	否
agents	否

如需完整存储方案，请将 DuckDBStore 与覆盖缺失域的 adapter 组合使用（本地开发最常用的是 LibSQL）。

初始化

通过 MastraCompositeStore 将 DuckDB 传递给 Mastra 时，observability 域会在首次使用时自行初始化。若要在 Mastra 外部显式初始化，请在 observability store 上调用 init()：

import { DuckDBStore } from '@mastra/duckdb'

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

Observability strategy

DuckDB 支持 MastraStorageExporter 使用的 event-sourced strategy，它会在内存中缓冲 span，并批量写入已完成的事件。这适合开发规模的流量。对于高流量生产工作负载，请参阅 MastraStorageExporter storage provider 支持。

相关内容

• 存储概览
• 组合存储
• ClickHouse 存储：生产环境 observability 后端
• DuckDB vector store：使用同一包进行向量搜索
• Observability 概览