Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

Was this page helpful?