SQLite Setup

@frontmcp/storage-sqlite provides a local storage backend for FrontMCP using SQLite. It replaces Redis for single-process deployments where you need persistence without managing external infrastructure.

Zero Infrastructure

No Redis or external database needed — just a local file

Persistent Sessions

Sessions, elicitation state, and SSE events survive restarts

Optional Encryption

AES-256-GCM at-rest encryption via HKDF-SHA256

WAL Mode

Write-Ahead Logging enabled by default for better read concurrency

When to Use SQLite

Use Case	SQLite	Redis
Local-only / single-process	Recommended	Overkill
Unix socket deployments	Recommended	Not needed
Background daemons	Recommended	Not needed
Multi-instance production	Not supported	Required
Pub/Sub (resource subscriptions)	EventEmitter (single process)	Required for distributed
Edge / serverless	Not supported	Required

SQLite is ideal for local-only deployments — Unix socket servers, CLI tools, and background daemons. For multi-instance production or serverless, use Redis or Vercel KV instead.

Installation

npm install @frontmcp/storage-sqlite better-sqlite3
# or
yarn add @frontmcp/storage-sqlite better-sqlite3

better-sqlite3 is a native module and requires a C++ compiler. On most systems this is already available. If you run into build issues, see the better-sqlite3 troubleshooting guide.

Quick Start

With Unix Socket (Recommended)

The simplest way to use SQLite is via the sqlite option on FrontMcpInstance.runUnixSocket():

import { FrontMcpInstance } from '@frontmcp/sdk';
import { serverConfig } from './config';

const handle = await FrontMcpInstance.runUnixSocket({
  ...serverConfig,
  socketPath: '/tmp/my-app.sock',
  sqlite: {
    path: '~/.frontmcp/data/my-app.sqlite',
  },
});

Or via the CLI:

frontmcp socket ./src/main.ts --db ~/.frontmcp/data/my-app.sqlite

With @FrontMcp Decorator

import 'reflect-metadata';
import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  http: { port: 3001 },
  sqlite: {
    path: './data/my-app.sqlite',
  },
})
export default class Server {}

Configuration Options

Option	Type	Default	Description
`path`	`string`	required	Path to the `.sqlite` database file
`encryption.secret`	`string`	—	Secret key for AES-256-GCM encryption via HKDF-SHA256
`walMode`	`boolean`	`true`	Enable WAL mode for better read concurrency
`busyTimeoutMs`	`number`	`5000`	How long a connection waits for a lock held by another process before failing with `SQLITE_BUSY`
`ttlCleanupIntervalMs`	`number`	`60000`	Interval in ms for purging expired keys

The database location can also be supplied through the FRONTMCP_SQLITE_PATH environment variable (used by frontmcp start --db, frontmcp socket --db and the generated installer). It overrides sqlite.path; other sqlite options are kept.

Encryption

Enable at-rest encryption to protect stored session data. Keys are stored in plaintext (needed for lookups); only values are encrypted.

sqlite: {
  path: './data/my-app.sqlite',
  encryption: {
    secret: process.env.FRONTMCP_ENCRYPTION_SECRET!,
  },
}

The encryption pipeline:

Your secret is run through HKDF-SHA256 to derive a 256-bit key
Each value is encrypted with AES-256-GCM using a random 96-bit IV
Stored format: base64url(iv):base64url(tag):base64url(ciphertext)

If you lose the encryption secret, stored data becomes unrecoverable. Store the secret securely (environment variable, secrets manager) and keep a backup.

Store Types

@frontmcp/storage-sqlite provides three specialized stores, all built on a common SqliteKvStore:

Session Store

Stores MCP session data with TTL support.

import { SqliteSessionStore } from '@frontmcp/storage-sqlite';

const sessions = new SqliteSessionStore({
  path: './data/app.sqlite',
  keyPrefix: 'mcp:session:',   // default
  defaultTtlMs: 3600000,       // 1 hour (default)
});

await sessions.set('session-123', { user: { sub: 'user-1' } });
const data = await sessions.get('session-123');

Event Store

Stores SSE events for resumability with max event limits and TTL-based eviction.

import { SqliteEventStore } from '@frontmcp/storage-sqlite';

const events = new SqliteEventStore({
  path: './data/app.sqlite',
  maxEvents: 10000,    // default
  ttlMs: 300000,       // 5 minutes (default)
});

const eventId = await events.storeEvent('stream-1', { type: 'update' });

Elicitation Store

Stores pending elicitation requests with EventEmitter-based single-process pub/sub.

import { SqliteElicitationStore } from '@frontmcp/storage-sqlite';

const elicitation = new SqliteElicitationStore({
  path: './data/app.sqlite',
  keyPrefix: 'mcp:elicit:',   // default
});

Comparison: SQLite vs Redis vs Vercel KV

Feature	SQLite	Redis	Vercel KV
Infrastructure	Local file	Server or managed service	Vercel-managed
Setup	`npm install`	Docker / cloud setup	Dashboard toggle
Multi-instance	Single process only	Full support	Full support
Pub/Sub	EventEmitter (local)	Native Redis pub/sub	Not supported
Encryption	Built-in AES-256-GCM	TLS in transit	TLS in transit
Edge Compatible	No	No	Yes
Latency	~0ms (local file I/O)	~1-5ms (TCP)	~5-15ms (REST)
Best For	Local daemons, CLI tools	Production servers	Vercel deployments

Troubleshooting

Error: Cannot find module 'better-sqlite3'

Cause: The better-sqlite3 native module is not installed.Solution:

npm install better-sqlite3

If you’re using yarn with PnP, you may need to add it as a dependency (not devDependency).

SQLITE_CANTOPEN: unable to open database file

Cause: The parent directory is created for you, so this means the path itself cannot be opened: no permission to create the directory, a path that points at a directory or a file that is not a database, or a read-only file system.Solution: Check the permissions and that path names a file. Serverless targets with a read-only file system need a writable path such as /tmp, or a different store.

Database is locked

Cause: Multiple processes are trying to write to the same SQLite file simultaneously.Solution: The store sets busy_timeout (5 s by default) before it enables WAL and creates tables, and retries SQLITE_BUSY during startup, so two processes starting on the same file wait for each other. If a writer holds the lock longer than that, raise busyTimeoutMs. SQLite still allows one writer at a time: for many writer processes, use Redis.

Encryption errors after changing the secret

Cause: Existing data was encrypted with a different secret.Solution: Reading a value written under another secret throws SqliteDecryptionError (code SQLITE_DECRYPTION_FAILED) with a message that names the secret as the likely cause. Restore the original secret or delete the database file and let the server create a fresh one. There is no migration path between encryption keys.

Unix Socket

Run FrontMCP as a persistent local server over Unix sockets

Redis Setup

Configure Redis for multi-instance production deployments

Vercel KV

Edge-compatible storage for Vercel deployments

Runtime Modes

Compare SDK, Server, and Handler deployment modes

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Zero Infrastructure

Persistent Sessions

Optional Encryption

WAL Mode

When to Use SQLite

Installation

Quick Start

With Unix Socket (Recommended)

With @FrontMcp Decorator

Configuration Options

Encryption

Store Types

Session Store

Event Store

Elicitation Store

Comparison: SQLite vs Redis vs Vercel KV

Troubleshooting

Unix Socket

Redis Setup

Vercel KV

Runtime Modes

Zero Infrastructure

Persistent Sessions

Optional Encryption

WAL Mode

​When to Use SQLite

​Installation

​Quick Start

​With Unix Socket (Recommended)

​With @FrontMcp Decorator

​Configuration Options

​Encryption

​Store Types

​Session Store

​Event Store

​Elicitation Store

​Comparison: SQLite vs Redis vs Vercel KV

​Troubleshooting

​Related Documentation

Unix Socket

Redis Setup

Vercel KV

Runtime Modes

When to Use SQLite

Installation

Quick Start

With Unix Socket (Recommended)

With @FrontMcp Decorator

Configuration Options

Encryption

Store Types

Session Store

Event Store

Elicitation Store

Comparison: SQLite vs Redis vs Vercel KV

Troubleshooting

Related Documentation