Bun SQLite
SQLite driver using Bun's built-in SQLite
Requirements
- Bun runtime
Configuration
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
import { createClient } from "viborm/bun-sqlite";
// Default is in-memory
const client = createClient({
schema,
});
Read-Only Mode
import { createClient } from "viborm/bun-sqlite";
const client = createClient({
dataDir: "./database.sqlite",
options: { readonly: true },
schema,
});
Using an existing database
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:
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.
Transactions
Bun SQLite supports full transactions with savepoints for nested transactions — see 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.