跳至主要內容

libSQL 儲存空間

libSQL 是與 SQLite 相容的開放原始碼資料庫，同時支援本機與遠端部署。它可用來儲存訊息歷程、Workflow snapshot、Trace 與評估分數。

對於語意回憶或傳統 RAG 等向量用途，請使用涵蓋 embedding 與向量搜尋的 libSQL Vector。

安裝
「安裝」的直接連結

儲存 Provider 必須以獨立套件安裝：

npm install @mastra/libsql@latest

使用方式
「使用方式」的直接連結

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 層級的檔案儲存空間：

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 或其他資料庫引擎。

在正式環境使用遠端資料庫：

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

進行本機開發與測試時，可以將資料儲存在記憶體中：

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：

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()：

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，以便立即查看資料。

若正式環境中的 Trace 量較高，請考慮使用 PostgreSQL，或透過複合儲存空間使用 ClickHouse。

On this page