---
title: better-sqlite3
description: SQLite driver using better-sqlite3
---

## Installation

```bash
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

```typescript
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

```typescript
import { createClient } from "viborm/sqlite3";

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

### Using Existing Database

```typescript
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](/docs/client/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](/docs/schema/scalars/point).

## 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.
