Skip to content

Storage backends

Kinglet uses one engine for both modes: the libSQL client, which opens a local SQLite file by default or connects to a hosted Turso database with the same code. Schema and queries are defined once with Drizzle ORM; migrations live in apps/api/drizzle and are applied automatically on boot.

sqlite (default) — a single local file, zero config, zero services:

Terminal window
KINGLET_DB_PATH=/data/kinglet.db

WAL mode and the FTS5 trigram index are configured automatically.

Turso — point at your database; nothing else changes:

Terminal window
KINGLET_DB_PATH=libsql://your-db.turso.io
KINGLET_DB_AUTH_TOKEN=eyJ…

With KINGLET_STORAGE=auto (the default), a plain path uses the local file and libsql://, https://, wss://, or file: URLs use the libSQL transport.

Terminal window
docker run -d --name kinglet -p 8080:3000 \
-e KINGLET_DB_PATH=libsql://your-db.turso.io \
-e KINGLET_DB_AUTH_TOKEN=eyJ… \
-e KINGLET_ADMIN_EMAIL=you@example.com \
-e KINGLET_ADMIN_PASSWORD=change-me-please \
ghcr.io/rushlightlab/kinglet:latest
  • One Kinglet instance per database. Ingest assumes a single writer.
  • Every query is a network round trip. Keep ingest batched (the SDK does this by default); each enabled monitor’s count check costs one round trip per interval.
  • Backups are Turso’s job. Litestream applies to local SQLite files only.
  • Schema and migrations run automatically on first boot, same as a local file.

Schema changes are generated by Drizzle Kit and applied on boot. For local development:

Terminal window
pnpm --filter @kinglet/api db:generate # create a migration after schema edits

The generated SQL is reviewed and committed; the app runs it before serving.

When a single node stops being enough, a ClickHouse engine implementing the Storage interface is the graduation path for the event/query path — the API and UI won’t change.