# @storyshelf/db-sqlite

> The zero-configuration SQLite database adapter for single-node StoryShelf deployments.

Source: https://storyshelf.js.org/packages/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

```sh
npm i @storyshelf/db-sqlite
```

[![JSR](https://jsr.io/badges/@storyshelf/db-sqlite)](https://jsr.io/@storyshelf/db-sqlite) [![JSR Score](https://jsr.io/badges/@storyshelf/db-sqlite/score)](https://jsr.io/@storyshelf/db-sqlite)

- [npm package](https://www.npmjs.com/package/@storyshelf/db-sqlite) — install tarballs and version history.
- [JSR package](https://jsr.io/@storyshelf/db-sqlite) — TypeScript-first registry page.
- [Public API reference](https://storyshelf.js.org/reference/db-sqlite/) — generated docs for every export; start here to learn the API. (The same reference is on [JSR](https://jsr.io/@storyshelf/db-sqlite/doc).)
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/db-sqlite) — package directory on `main`.

## Configure

```ts
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](../storage-local/) 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`. |

```ts
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.