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

# DuckDB 存储

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

对于向量搜索，请参阅 [DuckDB vector store 参考](https://mastra.zisheng.pro/reference/vectors/duckdb)，它是同一包中独立的 API。

## 何时使用 DuckDB

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

DuckDB 当前仅实现 `observability` 域。在[组合存储](https://mastra.zisheng.pro/reference/storage/composite)设置中，将它与其他 storage adapter（如 [LibSQL](https://mastra.zisheng.pro/reference/storage/libsql)）搭配使用，以支持 `memory` 和 `workflows`。

> **注意:** DuckDB 用于开发，不建议用于生产。它在进程内运行、持久化到单个本地文件，且无法在具有临时文件系统的平台（如 Railway、Fly.io、Render、Heroku 或 serverless 容器）上运行。生产环境的 observability 请使用 [ClickHouse](https://mastra.zisheng.pro/reference/storage/clickhouse)。

## 安装

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

## 使用方法

### 在组合存储中作为 observability 域

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

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

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

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

### 独立使用

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

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

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

await observability.init()
```

### 内存数据库

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

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

## 配置

### `DuckDBStore` 选项

**id** (`string`): 此 storage 实例的唯一标识符。 (Default: `'duckdb'`)

**path** (`string`): DuckDB 数据库文件的路径。使用 :memory: 创建临时内存数据库。 (Default: `'mastra.duckdb'`)

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

**threads** (`number`): DuckDB 可使用的线程数。可降低此值，避免查询占用共享应用服务器的所有 CPU 核心。 (Default: `每个 CPU 核心一个`)

### 底层类型

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

## 支持的域

DuckDB 当前实现一个 storage 域：

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

如需完整存储方案，请将 `DuckDBStore` 与覆盖缺失域的 adapter 组合使用（本地开发最常用的是 [LibSQL](https://mastra.zisheng.pro/reference/storage/libsql)）。

## 初始化

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

```typescript
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 支持](https://mastra.zisheng.pro/docs/observability/integrations/exporters/mastra-storage)。

## 相关内容

- [存储概览](https://mastra.zisheng.pro/reference/storage/overview)
- [组合存储](https://mastra.zisheng.pro/reference/storage/composite)
- [ClickHouse 存储](https://mastra.zisheng.pro/reference/storage/clickhouse)：生产环境 observability 后端
- [DuckDB vector store](https://mastra.zisheng.pro/reference/vectors/duckdb)：使用同一包进行向量搜索
- [Observability 概览](https://mastra.zisheng.pro/docs/observability/overview)