# zidane/session/sqlite

> A SQLite-backed session store for Bun.

Import: `import { … } from 'zidane/session/sqlite'`. Source: [src/session/sqlite.ts](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts).

Use `createSqliteStore` when sessions must survive a restart. It writes each turn as it completes, in SQLite's write-ahead-log (WAL) mode, so a crash keeps history up to the last finished turn. It needs Bun (`bun:sqlite`), so it has its own subpath. See [Sessions](https://zidane.si/docs/sessions.md).

```ts
import { createSession } from 'zidane/session'
import { createSqliteStore } from 'zidane/session/sqlite'

const store = createSqliteStore({ path: './sessions.db' })
const session = await createSession({ store })
await session.save()
console.log(session.id)
```

## Functions

### `createSqliteStore`

Function.

Creates a [`SessionStore`](https://zidane.si/docs/reference/session.md#SessionStore) backed by a SQLite file through `bun:sqlite`. Corruption errors are rethrown with the file path and a recovery recipe.

```ts
function createSqliteStore(options: SqliteStoreOptions): SessionStore
```

**Parameters**

- `options` (`SqliteStoreOptions`): Database path.

**Returns** `SessionStore`

**Example**

```ts
import { createSession } from 'zidane/session'
import { createSqliteStore } from 'zidane/session/sqlite'

const store = createSqliteStore({ path: './sessions.db' })
const session = await createSession({ store })
```

Source: [src/session/sqlite.ts:210](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts#L210)

### `createTuiStore`

Function.

Convenience: open a SQLite store at `dbPath`, creating its parent
directory if it doesn't yet exist. Meant as the `store` factory of
`resolveConfig`, for example `store: paths => createTuiStore(paths.db)`.

Lives here (and not in `zidane/chat`) so the renderer-agnostic
`zidane/chat` entry stays free of `bun:sqlite` — non-Bun consumers
can import `zidane/chat` without pulling in the Bun-only binding.

```ts
function createTuiStore(dbPath: string): SessionStore
```

**Parameters**

- `dbPath` (`string`): Path of the SQLite database file. The parent directory is created when missing.

**Returns** `SessionStore`

Source: [src/session/sqlite.ts:262](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts#L262)

### `describeCorruptDb`

Function.

Re-wrap a corruption error with the file path and a recovery recipe.
The bare SQLite string ("database disk image is malformed") tells the
user nothing about WHICH file or what to do; every host (TUI, daemon,
headless) surfaces this message instead. Non-corruption errors pass
through untouched.

Deliberately no auto-repair / quarantine: the file is the only copy of
the user's history and `.recover` salvages most of it. Never touch it.

```ts
function describeCorruptDb(err: unknown, dbPath: string): unknown
```

**Parameters**

- `err` (`unknown`): Error thrown by a SQLite operation.
- `dbPath` (`string`): Path of the database file, named in the message.

**Returns** `unknown`

Source: [src/session/sqlite.ts:181](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts#L181)

### `isCorruptDbError`

Function.

True when `err` is SQLite reporting a damaged file (`SQLITE_CORRUPT`,
`SQLITE_NOTADB`). Matched on the message because bun:sqlite's error
class exposes the code inconsistently across versions.

```ts
function isCorruptDbError(err: unknown): boolean
```

**Parameters**

- `err` (`unknown`): Error thrown by a SQLite operation.

**Returns** `boolean`

Source: [src/session/sqlite.ts:164](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts#L164)

## Interfaces

### `SqliteStoreOptions`

Interface.

Options for [`createSqliteStore`](https://zidane.si/docs/reference/session-sqlite.md#createSqliteStore).

```ts
interface SqliteStoreOptions
```

**Properties**

- `path` (`string`): Path to the SQLite database file

Source: [src/session/sqlite.ts:153](https://github.com/Tahul/zidane/blob/main/src/session/sqlite.ts#L153)