better-sqlite3
SQLite driver using better-sqlite3
Installation
pnpm add better-sqlite3
VibORM supports better-sqlite3 12.11.1 or later in the 12.x series, and
13.0.3 or later in the 13.x series. These minimum versions include the SQLite
optimizer fixes needed for relation-filtered pagination.
Configuration
import { createClient } from "viborm/sqlite3";
const client = createClient({
dataDir: "./database.sqlite",
schema,
});
Options
| Option | Type | Description |
|---|---|---|
client |
Database |
Existing better-sqlite3 database |
dataDir |
string |
Path to SQLite file (:memory: for in-memory) |
options |
object |
Database 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 |
fileMustExist |
boolean |
Throw if file doesn’t exist |
timeout |
number |
Busy timeout in milliseconds (default 5000) |
verbose |
function |
Logging function |
In-Memory Database
import { createClient } from "viborm/sqlite3";
// Default is in-memory
const client = createClient({
schema,
});
Using Existing Database
import Database from "better-sqlite3";
import { createClient } from "viborm/sqlite3";
const db = new Database("./database.sqlite");
db.pragma("foreign_keys = ON");
const client = createClient({
client: db,
schema,
});
Supplied databases must already enforce foreign keys. VibORM checks the pragma
without changing caller state and leaves the database open on $disconnect().
The caller closes it with db.close(). Wrappers sharing one database serialize
transactions and base queries through the same connection queue.
Transactions
better-sqlite3 supports full transactions with savepoints for nested transactions — see Transactions. VibORM begins write transactions with BEGIN IMMEDIATE. An owned database keeps the busy timeout you pass as options.timeout, and uses 5 seconds when you pass none.
Features
- Synchronous API (fastest SQLite driver for Node.js)
- Full transaction support with savepoints
RETURNINGclause support (SQLite 3.35+)
GeoPoint storage tier
SQLite3 stores s.point() as checked canonical JSON text. Typed CRUD, exact
coordinate equality, inclusive ordinary/antimeridian bounds, nullability,
relations, transactions, and cache are supported. Polygon, distance,
_distance, and spatial indexes are refused before provider execution. See
GeoPoint.
Limitations
- SQLite dialect - no
LATERALjoins, limitedFULL OUTER JOIN - JSON columns return as strings and are parsed automatically
- Boolean values stored as integers (0/1)
- Node.js only (native module)
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.