Skip to main content
LibSQL is a SQLite-compatible database that powers Turso. It provides both local file-based storage and cloud-hosted databases with edge replication.

​
Installation

npm install @mastra/libsql

​
Configuration

LibSQLStore supports both local file-based databases and remote Turso databases.

​
Local File Database

1

Import LibSQLStore

import { LibSQLStore } from '@mastra/libsql';
2

Create storage instance

const storage = new LibSQLStore({
  id: 'my-storage',
  url: 'file:./dev.db',
});
3

Configure Mastra

import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  storage,
});

​
Remote Turso Database

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

const storage = new LibSQLStore({
  id: 'turso-storage',
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

​
In-Memory Database

For testing purposes: 
const storage = new LibSQLStore({
  id: 'test-storage',
  url: 'file::memory:',
});

​
Configuration Options

​
id
string
required
Unique identifier for the storage instance
​
url
string
required
Database URL. Can be:
  • file:./path/to/db.db - Local file database
  • file::memory: - In-memory database
  • libsql://your-db.turso.io - Remote Turso database
​
authToken
string
Authentication token for remote Turso databases
​
maxRetries
number
default:5
Maximum retries for write operations on SQLITE_BUSY errors
​
initialBackoffMs
number
default:100
Initial backoff time in milliseconds for retries (doubles with each retry)
​
disableInit
boolean
default:false
Disable automatic table initialization. Useful for CI/CD pipelines where you want to control when migrations run

​
Usage Examples

​
Access Storage Domains

const storage = new LibSQLStore({
  id: 'my-storage',
  url: 'file:./dev.db',
});

// Access memory domain
const memory = await storage.getStore('memory');
await memory?.saveThread({ thread });

// Access workflows domain
const workflows = await storage.getStore('workflows');
await workflows?.persistWorkflowSnapshot({ 
  workflowName: 'my-workflow',
  runId: 'run-123',
  snapshot 
});

​
Environment-Based Configuration

const storage = new LibSQLStore({
  id: 'storage',
  url: process.env.NODE_ENV === 'production'
    ? process.env.TURSO_URL!
    : 'file:./dev.db',
  authToken: process.env.NODE_ENV === 'production'
    ? process.env.TURSO_AUTH_TOKEN
    : undefined,
});

​
Manual Migration Control

// In CI/CD script with admin credentials
const storage = new LibSQLStore({
  id: 'storage',
  url: process.env.DATABASE_URL!,
  authToken: process.env.ADMIN_TOKEN!,
  disableInit: false,
});
await storage.init(); // Explicitly run migrations

// In runtime with limited credentials
const storage = new LibSQLStore({
  id: 'storage',
  url: process.env.DATABASE_URL!,
  authToken: process.env.RUNTIME_TOKEN!,
  disableInit: true, // Skip auto-init
});

​
Vector Store Support

LibSQL also provides vector storage capabilities: 
import { LibSQLVector } from '@mastra/libsql';

const vectorStore = new LibSQLVector({
  id: 'vectors',
  url: 'file:./vectors.db',
});

const mastra = new Mastra({
  vectors: {
    embeddings: vectorStore,
  },
});
See Vector Store documentation for more details.

​
Storage Domains

LibSQL storage supports all Mastra storage domains:
  • memory - Thread-based conversation persistence
  • workflows - Workflow execution snapshots
  • observability - Telemetry and logging
  • agents - Agent configurations
  • datasets - Training and evaluation datasets
  • experiments - Evaluation experiment results
  • promptBlocks - Reusable prompt templates
  • scorerDefinitions - Evaluation scorer configurations
  • mcpClients - MCP client configurations
  • mcpServers - MCP server configurations
  • workspaces - Workspace metadata
  • skills - Agent skill definitions
  • blobs - Binary large object storage

​
Performance Considerations

​
WAL Mode

LibSQL automatically enables WAL (Write-Ahead Logging) mode for file-based databases to improve concurrency: 
// This is handled automatically
PRAGMA journal_mode=WAL;
PRAGMA busy_timeout = 5000;

​
Retry Strategy

Write operations automatically retry on SQLITE_BUSY errors with exponential backoff: 
const storage = new LibSQLStore({
  id: 'storage',
  url: 'file:./db.db',
  maxRetries: 10, // Increase for high-concurrency scenarios
  initialBackoffMs: 50, // Start with shorter backoff
});

​
Best Practices

Local Development

Use file-based databases for local development:
url: 'file:./dev.db'

Production Deployment

Use Turso for production with edge replication:
url: process.env.TURSO_URL!,
authToken: process.env.TURSO_AUTH_TOKEN!

Testing

Use in-memory databases for tests:
url: 'file::memory:'

PostgreSQL Storage

Alternative SQL storage with advanced features

MongoDB Storage

Document-based NoSQL storage

Turso Documentation

Official Turso database documentation

LibSQL GitHub

LibSQL open-source repository

Build docs developers (and LLMs) love

Get started for freeTalk to us