LibSQL Storage

The LibSQL storage implementation provides a SQLite-compatible storage solution that can run both in-memory and as a persistent database.

Installation

npm install @mastra/libsql@latest

Usage

import { LibSQLStore } from "@mastra/libsql";

// File database (development)
const storage = new LibSQLStore({
  url: "file:./storage.db",
});

// Persistent database (production)
const storage = new LibSQLStore({
  url: process.env.DATABASE_URL,
});

Parameters

url:

string

Database URL. Use ':memory:' for in-memory database, 'file:filename.db' for a file database, or any LibSQL-compatible connection string for persistent storage.

authToken?:

string

Authentication token for remote LibSQL databases.

Additional Notes

In-Memory vs Persistent Storage

The file configuration (file:storage.db) is useful for:

• Development and testing
• Temporary storage
• Quick prototyping

For production use cases, use a persistent database URL: libsql://your-database.turso.io

Schema Management

The storage implementation handles schema creation and updates automatically. It creates the following tables:

• mastra_workflow_snapshot: Stores workflow state and execution data
• mastra_evals: Stores evaluation results and metadata
• mastra_threads: Stores conversation threads
• mastra_messages: Stores individual messages
• mastra_traces: Stores telemetry and tracing data
• mastra_scorers: Stores scoring and evaluation data
• mastra_resources: Stores resource working memory data

Initialization

When you pass storage to the Mastra class, init() is called automatically before any storage operation:

import { Mastra } from "@mastra/core";
import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  url: "file:./storage.db",
});

const mastra = new Mastra({
  storage, // init() is called automatically
});

If you're using storage directly without Mastra, you must call init() explicitly to create the tables:

import { LibSQLStore } from "@mastra/libsql";

const storage = new LibSQLStore({
  url: "file:./storage.db",
});

// Required when using storage directly
await storage.init();

// Now you can use the storage
await storage.getThread({ threadId: "..." });

warning

If init() is not called, tables won't be created and storage operations will fail silently or throw errors.