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

# libSQL 儲存

[libSQL](https://docs.turso.tech/libsql) 是一個開源、兼容 SQLite 的數據庫，支援本機及遙距部署。它可用於儲存訊息記錄、Workflow 快照、Trace 和 Evals 分數。

如要處理語義回憶或傳統 RAG 等向量用途，請使用 [libSQL Vector](https://mastra.zisheng.pro/zh-HK/reference/vectors/libsql)，當中涵蓋 embedding 和向量搜尋。

## 安裝

儲存 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 數據庫的驗證 token。

## 受管理的資料表

儲存實作會自動建立核心儲存資料表，包括用於通知收件箱記錄和傳送 metadata 的 `mastra_notifications`。

`LibSQLStore` 透過 `getStore('notifications')` 提供通知儲存。

## 初始化

當你將儲存傳入 Mastra class 時，系統會自動呼叫 `init()` 以建立[核心 schema](https://mastra.zisheng.pro/zh-HK/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 而直接使用儲存，請明確呼叫 `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: '...' })
```

## 可觀測性

libSQL 支援可觀測性，而且非常適合本機開發。偵錯時請使用 `realtime` [追蹤策略](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/mastra-storage)，即時查看結果。

如果生產環境的 Trace 數量較多，可考慮使用 [PostgreSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/postgresql) 或[透過複合儲存使用 ClickHouse](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)。