SQLiteStateStore

Automatic Engine Detection

SQLiteStateStore automatically detects available SQLite engines in this order:

1. Bun SQLite (bun:sqlite) - Built into Bun runtime
2. libSQL (@libsql/client) - Turso-compatible SQLite

Explicit Engine Selection

Force a specific SQLite engine:

Bun SQLite

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "bun",
    filename: ".alchemy/state.sqlite"
  })
});

libSQL

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "libsql",
    url: "file:.alchemy/state.sqlite"
  })
});

Custom Database Location

Change the database file location:

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    filename: "./data/my-app-state.db"
  })
});

Environment Variable Configuration

Use environment variables for flexible configuration:

.env

ALCHEMY_STATE_FILE=./data/production-state.sqlite

// alchemy.run.ts - automatically uses ALCHEMY_STATE_FILE
const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope)
});

Engine-Specific Options

Configure engine-specific options:

Bun SQLite

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "bun",
    readonly: false,
    create: true,
    safeIntegers: true,
    strict: true
  })
});

libSQL

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "libsql",
    url: "libsql://my-db.turso.io",
    authToken: process.env.TURSO_AUTH_TOKEN,
    syncUrl: "file:./local-replica.db"
  })
});

Development vs Production

Use different configurations for different environments:

const isDev = process.env.NODE_ENV === "development";

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    filename: isDev
      ? ".alchemy/dev-state.sqlite"
      : "/var/lib/myapp/prod-state.sqlite",
  })
});

Per-Stage Databases

Use separate databases for different deployment stages:

const stage = process.env.STAGE ?? "dev";

const app = await alchemy("my-app", {
  stage,
  stateStore: (scope) => new SQLiteStateStore(scope, {
    filename: `.alchemy/state-${stage}.sqlite`,
  })
});

Turso Database

Connect to a remote Turso database:

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "libsql",
    url: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN
  })
});

Local Replica with Sync

Use a local replica that syncs with remote:

const app = await alchemy("my-app", {
  stateStore: (scope) => new SQLiteStateStore(scope, {
    engine: "libsql",
    url: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
    syncUrl: "file:./local-replica.db",
    syncInterval: 60 // Sync every 60 seconds
  })
});

Engine Performance

• Bun SQLite: Fastest for Bun runtime, zero additional dependencies
• libSQL: Best for remote/distributed scenarios, async API

Peer Dependencies

The SQLiteStateStore requires drizzle-orm as a peer dependency. Additionally, if you are using the libsql engine (default for Node.js), you will need to install @libsql/client as a peer dependency.

If you see dependency errors:

[SQLiteStateStore] Missing `@libsql/client` peer dependency. Please `npm install @libsql/client`.

Install the required packages:

npm install drizzle-orm @libsql/client

Permission Errors

Ensure the directory is writable:

mkdir -p .alchemy
chmod 755 .alchemy