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

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
  • RETURNING clause 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 LATERAL joins, limited FULL 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.

Was this page helpful?