@storyshelf/db-sqlite

@storyshelf/db-sqlite is the default database adapter for self-hosted StoryShelf. It uses node:sqlite (zero-dependency builtin) and Drizzle ORM, enables WAL mode, and stores the database in one local file.

Install

npm

npm i @storyshelf/db-sqlite

pnpm

pnpm add @storyshelf/db-sqlite

yarn

yarn add @storyshelf/db-sqlite

• npm package — install tarballs and version history.
• JSR package — TypeScript-first registry page.
• Public API reference — generated docs for every export; start here to learn the API. (The same reference is on JSR.)
• Source on GitHub — package directory on main.

Configure

import { createSqliteDatabase } from "@storyshelf/db-sqlite";
import { createShelfApp } from "@storyshelf/app";
import { createLocalStorage } from "@storyshelf/storage-local";

const database = createSqliteDatabase("./data/shelf.db");

const storage = createLocalStorage("./data");
const app = createShelfApp({ database, storage });
await app.lifecycle.setup();

createSqliteDatabase(path: string): DatabaseAdapter

Opens (or creates) a SQLite database at path and returns a DatabaseAdapter. The connection enables WAL journal mode and a 5s busy timeout. Schema migrations run inside the adapter's lifecycle.setup (via await app.lifecycle.setup()); teardown via lifecycle.teardown (idempotent).

The returned adapter implements every method of the DatabaseAdapter interface (insert, update, get, remove, list, count, all) plus metadata/lifecycle from the shared Adapter base.

When to use it

Use SQLite for a single-node deployment or local development. Pair it with local storage for the simplest self-hosted setup.

Presets (same schema, different driver)

Subpath	Driver	Install	When
@storyshelf/db-sqlite (root)	node:sqlite builtin	—	Default. Single-node VPS/Docker. Zero config.
@storyshelf/db-sqlite/turso	@libsql/client	npm install @libsql/client	Serverless (Turso cloud, Vercel, Lambda); file: URLs and embedded replicas work too.
@storyshelf/db-sqlite/better-sqlite3	better-sqlite3	npm install better-sqlite3	Native sync driver (needs allowBuilds for the postinstall).
@storyshelf/db-sqlite/bun-sqlite	bun:sqlite builtin	— (Bun only)	Bun runtime.
@storyshelf/db-sqlite/d1	D1 binding	— (Workers only)	Cloudflare Workers (env.DB). Hosts Storybooks only: it cannot back testing.runner.

import { createTursoDatabase } from "@storyshelf/db-sqlite/turso";

const database = createTursoDatabase({
  url: process.env["TURSO_DATABASE_URL"],
  authToken: process.env["TURSO_AUTH_TOKEN"],
});

All presets accept an injected client instead of connection options (the caller then owns teardown); all except D1 also accept plain connection options and throw on missing/invalid input. Driver peers are optional: consumers only install their backend's client.

Do not add any of drizzle-orm's peer packages as a direct dependency of a single workspace package — drizzle-orm resolves a distinct copy per unique peer set, which splits the shared Table/SQL types. Preset types that a peer would provide live in colocated *-ambient.d.ts files instead.

The former @storyshelf/db-turso package is retired — see docs/deprecated.md in the repo.