# libSQL Storage

[libSQL](https://docs.turso.tech/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](https://mastra.ai/reference/vectors/libsql/llms.txt) which covers embeddings and vector search.

## Installation

Storage providers must be installed as separate packages:

```bash
npm install @mastra/libsql@latest
```

```bash
pnpm add @mastra/libsql@latest
```

```bash
yarn add @mastra/libsql@latest
```

```bash
bun add @mastra/libsql@latest
```

## Usage

```typescript
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:

```typescript
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](https://turso.tech) or a different database engine.

Production with remote database:

```typescript
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:

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

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

## 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.

## Initialization

When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/storage/overview/llms.txt):

```typescript
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:

```typescript
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](https://mastra.ai/docs/observability/tracing/exporters/default/llms.txt) for immediate visibility while debugging.

For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql/llms.txt) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite/llms.txt).