libSQL

libSQL is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.

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

Installation

Storage providers must be installed as separate packages:

npm

npm install @mastra/libsql@latest

pnpm

pnpm add @mastra/libsql@latest

Yarn

yarn add @mastra/libsql@latest

Bun

bun add @mastra/libsql@latest

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',
    }),
  }),
})

注意

File storage doesn't work with serverless platforms that have ephemeral file systems. For serverless deployments, use Turso or a different database engine.

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:',
})

注意

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

Embedded replica synced with a remote primary (for example Turso):

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

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.

syncUrl?:

string

URL of the remote primary database to sync from, enabling an embedded replica. Requires a local file: url.

syncInterval?:

number

Interval in seconds for automatic sync with the remote primary. Only applies when syncUrl is set.

Managed tables

The storage implementation creates the core storage tables automatically, including mastra_notifications for notification inbox records and delivery metadata.

LibSQLStore exposes notification storage through getStore('notifications').

Initialization

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
})

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

Observability

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

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