Skip to main content

libSQL 存储

🌐 libSQL Storage

libSQL 是一个开源、兼容 SQLite 的数据库，支持本地和远程部署。它可用于存储消息历史、工作流快照、跟踪信息和评估分数。

对于语义召回或传统RAG等向量，使用 libSQL Vector，它涵盖了嵌入和向量搜索。

🌐 For vectors like semantic recall or traditional RAG, use libSQL Vector which covers embeddings and vector search.

安装
Direct link to 安装

🌐 Installation

存储提供程序必须作为独立的包安装：

🌐 Storage providers must be installed as separate packages:

npm install @mastra/libsql@latest

用法
Direct link to 用法

🌐 Usage

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-level file storage:

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",
    }),
  }),
});
warning

文件存储无法在具有临时文件系统的无服务器平台上使用。对于无服务器部署，请使用 Turso 或其他数据库引擎。

使用远程数据库的生产环境：

🌐 Production with remote database:

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

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

🌐 For local development and testing, you can store data in memory:

storage: new LibSQLStore({
  id: 'libsql-storage',
  url: ":memory:",
})
warning

In-memory storage resets when the process changes. Only suitable for development.

选项
Direct link to 选项

🌐 Options

url:

string
Database URL. Use `:memory:` for in-memory database, `file:filename.db` for a file database, or a libSQL connection string (e.g., `libsql://your-database.turso.io`) for remote storage.

authToken?:

string
Authentication token for remote libSQL databases.

初始化
Direct link to 初始化

🌐 Initialization

当你将存储传递给 Mastra 类时，init() 会自动被调用来创建核心模式：

🌐 When you pass storage to the Mastra class, init() is called automatically to create the core 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，请显式调用 init()：

🌐 If using storage directly without Mastra, call init() explicitly:

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: "..." });

可观测性
Direct link to 可观测性

🌐 Observability

libSQL 支持可观测性，非常适合本地开发。在调试时使用 realtime 追踪策略 可以立即获得可见性。

🌐 libSQL supports observability and is ideal for local development. Use the realtime tracing strategy for immediate visibility while debugging.

对于追踪量较高的生产环境，可以考虑使用 PostgreSQL 或通过复合存储使用 ClickHouse。

🌐 For production environments with higher trace volumes, consider using PostgreSQL or ClickHouse via composite storage.

目录