---
title: Bun SQLite
description: SQLite driver using Bun's built-in SQLite
---

## Requirements

- Bun runtime

## Configuration

```typescript
import { createClient } from "viborm/bun-sqlite";

const client = createClient({
  dataDir: "./database.sqlite",
  schema,
});
```

## Options

| Option | Type | Description |
|--------|------|-------------|
| `client` | `Database` | Existing Bun SQLite database |
| `dataDir` | `string` | Path to SQLite file (`:memory:` for in-memory) |
| `options` | `object` | SQLite options |

`createClient` refuses any other key with a `ClientInitializationError` that
names it: a database file is passed as `dataDir`, not `databaseUrl`.

### Options Object

| Option | Type | Description |
|--------|------|-------------|
| `readonly` | `boolean` | Open in read-only mode |
| `create` | `boolean` | Create file if it doesn't exist |
| `readwrite` | `boolean` | Open with read-write access |
| `strict` | `boolean` | Enable strict mode |
| `timeout` | `number` | Busy timeout in milliseconds (default 5000). A VibORM option: `bun:sqlite` has none, so VibORM applies it as `PRAGMA busy_timeout` |

### In-Memory Database

```typescript
import { createClient } from "viborm/bun-sqlite";

// Default is in-memory
const client = createClient({
  schema,
});
```

### Read-Only Mode

```typescript
import { createClient } from "viborm/bun-sqlite";

const client = createClient({
  dataDir: "./database.sqlite",
  options: { readonly: true },
  schema,
});
```

### Using an existing database

```typescript
import { Database } from "bun:sqlite";
import { createClient } from "viborm/bun-sqlite";

const database = new Database("./database.sqlite");
database.exec("PRAGMA foreign_keys = ON");
const client = createClient({ schema, client: database });
```

VibORM checks supplied foreign-key enforcement without changing it, and
`$disconnect()` leaves the supplied database open. Its owner calls
`database.close()`. Wrappers sharing one database use the same transaction
queue. Transactions begin with `BEGIN IMMEDIATE`; an owned database uses
`options.timeout` as its busy timeout, 5 seconds by default. Strings with
unpaired UTF-16 surrogates are refused before dispatch because Bun SQLite cannot
preserve them.

Typed statements are reused through the database's own `query()` cache: they
share its bounded size, are finalized when the database closes, and keep
Bun's `safeIntegers` mode (see below) if your code queries the same SQL text.
A database whose `prepare` was replaced or overridden sees every statement
instead.

## Large integers

SQLite's `INTEGER` is 64-bit, so a value past `2^53` cannot survive as a JS
number. Typed reads opt the statement into Bun's `safeIntegers` mode, so a
`s.bigInt()` field round-trips exactly — the same guarantee `sqlite3` and
`libsql` give:

```typescript
await client.measurement.create({
  data: { id: "m-1", views: 9_007_199_254_740_993n },
});

const row = await client.measurement.findUnique({ where: { id: "m-1" } });
row?.views; // 9007199254740993n — exact
```

`$queryRawUnsafe` bypasses the result parser and stays driver-native, so
INTEGER columns come back as plain (possibly rounded) numbers there. Read large
integers through a typed query, or through the tagged `` $queryRaw`...` ``.

Bun 1.1.14 or newer is required: on older builds the statement has no
`safeIntegers`, and viborm refuses the read with a `FeatureNotSupportedError`
rather than hand back a rounded value.

## GeoPoint storage tier

The real Bun runtime contract qualifies typed GeoPoint CRUD, equality,
inclusive bounds, callback and array transactions, nested and variant
relations, cache, extensions, and raw boundaries over the checked SQLite JSON
carrier. Polygon, distance, `_distance`, and spatial indexes are refused before
execution. See [GeoPoint](/docs/schema/scalars/point).

## Transactions

Bun SQLite supports full transactions with savepoints for nested transactions — see [Transactions](/docs/client/transactions).

## Limitations

- Only available in Bun runtime
- JSON columns are parsed automatically
- Boolean values stored as integers (0/1)
- Synchronous API internally (async wrapper)

Raw INTEGER results use `number` within JavaScript’s safe integer range and
`bigint` outside it. Safe Sql fragments, unsafe SQL, array transactions and
callback transactions share this rule; values are read losslessly once.
Typed model fields continue to use their declared scalar result domain.
