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

# libSQL 存储

[libSQL](https://docs.turso.tech/libsql) 是一款开源且兼容 SQLite 的数据库，支持本地和远程部署。它可用于存储消息历史、Workflow 快照、Trace 和 eval 分数。

对于 semantic recall 或传统 RAG 等向量功能，请使用涵盖 embeddings 和向量搜索的 [libSQL Vector](https://mastra.zisheng.pro/reference/vectors/libsql)。

## 安装

Storage Provider 必须作为独立包安装：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 使用方法

```typescript
import { LibSQLStore } from '@mastra/libsql'
import { Mastra } from '@mastra/core'

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'libsql-storage',
    url: 'file:./storage.db',
  }),
})
```

Agent 级别的文件存储：

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'

export const agent = new Agent({
  id: 'example-agent',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'libsql-storage',
      url: 'file:./agent.db',
    }),
  }),
})
```

> **注意:** 文件存储无法在具有临时文件系统的 serverless 平台上运行。对于 serverless 部署，请使用 [Turso](https://turso.tech) 或其他数据库引擎。

使用远程数据库进行生产：

```typescript
storage: new LibSQLStore({
  id: 'libsql-storage',
  url: 'libsql://your-db-name.aws-ap-northeast-1.turso.io',
  authToken: process.env.TURSO_AUTH_TOKEN,
})
```

对于本地开发和测试，可以将数据存储在内存中：

```typescript
storage: new LibSQLStore({
  id: 'libsql-storage',
  url: ':memory:',
})
```

> **注意:** 进程变更时，内存存储会重置。仅适用于开发。

## 选项

**url** (`string`): 数据库 URL。内存数据库使用 :memory:，文件数据库使用 file:filename.db，远程存储使用 libSQL 连接字符串（例如 libsql://your-database.turso.io）。

**authToken** (`string`): 远程 libSQL 数据库的身份验证令牌。

## 托管表

该存储实现会自动创建核心存储表，其中包括用于通知收件箱记录和投递元数据的 `mastra_notifications`。

`LibSQLStore` 通过 `getStore('notifications')` 暴露通知存储。

## 初始化

将 storage 传递给 Mastra class 时，会自动调用 `init()` 来创建[核心 schema](https://mastra.zisheng.pro/reference/storage/overview)：

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: 'file:./storage.db',
})

const mastra = new Mastra({
  storage, // init() called automatically
})
```

如果不通过 Mastra 而直接使用 storage，请显式调用 `init()`：

```typescript
import { LibSQLStore } from '@mastra/libsql'

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: 'file:./storage.db',
})

await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })
```

## Observability

libSQL 支持 observability，非常适合本地开发。调试期间若要立即看到数据，请使用 `realtime` [tracing strategy](https://mastra.zisheng.pro/docs/observability/integrations/exporters/mastra-storage)。

对于 Trace 量更高的生产环境，请考虑使用 [PostgreSQL](https://mastra.zisheng.pro/reference/storage/postgresql) 或[通过组合存储使用 ClickHouse](https://mastra.zisheng.pro/reference/storage/composite)。