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

# libSQL 儲存空間

[libSQL](https://docs.turso.tech/libsql) 是與 SQLite 相容的開放原始碼資料庫，同時支援本機與遠端部署。它可用來儲存訊息歷程、Workflow snapshot、Trace 與評估分數。

對於語意回憶或傳統 RAG 等向量用途，請使用涵蓋 embedding 與向量搜尋的 [libSQL Vector](https://mastra.zisheng.pro/zh-TW/reference/vectors/libsql)。

## 安裝

儲存 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')` 提供通知儲存空間。

## 初始化

將 storage 傳入 Mastra 類別時，系統會自動呼叫 `init()` 以建立[核心 schema](https://mastra.zisheng.pro/zh-TW/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: '...' })
```

## 可觀測性

libSQL 支援可觀測性，非常適合本機開發。除錯時請使用 `realtime` [tracing strategy](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/mastra-storage)，以便立即查看資料。

若正式環境中的 Trace 量較高，請考慮使用 [PostgreSQL](https://mastra.zisheng.pro/zh-TW/reference/storage/postgresql)，或[透過複合儲存空間使用 ClickHouse](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)。