LibSQL (Turso)
SQLite driver for Turso and libSQL
Installation
pnpm add @libsql/client
Configuration
import { createClient } from "viborm/libsql";
const client = createClient({
databaseUrl: process.env.TURSO_DATABASE_URL,
authToken: process.env.TURSO_AUTH_TOKEN,
schema,
});
Options
| Option | Type | Description |
|---|---|---|
client |
Client |
Existing libSQL client |
databaseUrl |
string |
Database URL (Turso cloud or local file) |
dataDir |
string |
Local file path (alternative to databaseUrl) |
authToken |
string |
Authentication token for Turso |
options |
Config |
Additional libSQL configuration |
createClient refuses any other key with a ClientInitializationError that
names it.
Local Development
import { createClient } from "viborm/libsql";
// In-memory database (default)
const client = createClient({
schema,
});
// Local file with dataDir
const client = createClient({
dataDir: "./local.db",
schema,
});
// Or with databaseUrl
const client = createClient({
databaseUrl: "file:./local.db",
schema,
});
Turso Cloud
import { createClient } from "viborm/libsql";
const client = createClient({
databaseUrl: "libsql://your-database.turso.io",
authToken: process.env.TURSO_AUTH_TOKEN,
schema,
});
Using an existing client
import { createClient as createTransport } from "@libsql/client";
import { createClient } from "viborm/libsql";
const transport = createTransport({
url: "file:./local.db",
intMode: "bigint",
timeout: 5000,
});
const client = createClient({ schema, client: transport });
Typed queries read BigInt and Decimal columns as text, so they stay exact
with intMode: "number" or "bigint", and a supplied client sends no setup
statement; "string" mode is not supported for typed reads. Raw rows keep the
client’s own carrier: in libSQL’s default number mode, a raw read of an integer
beyond 2^53 fails, so prefer bigint mode.
$disconnect() leaves the supplied transport open; its owner calls
transport.close(). Owned transports use bigint mode and a 5-second local busy
timeout. Strings containing NUL bytes are refused before dispatch because the
local provider truncates them.
Transactions
LibSQL supports transactions with savepoints for nested transactions — see Transactions. Callback transactions use the provider’s dedicated write transaction; standalone typed and raw statements keep native provider execution.
V1 qualification covers local libSQL 0.18 rollback and supplied-client ownership,
and actual HTTP/Hrana rollback with @libsql/client 0.18 against isolated official
libSQL server sqld 0.23.0. Callback and array failures roll back their prefixes;
committed callbacks remain visible, and disconnect leaves a supplied HTTP client
usable. Controlled lifecycle tests additionally cover commit and cleanup failures.
Hosted Turso rollback and newer server versions remain unqualified in this release
campaign; the localhost network proof does not establish those guarantees.
Raw SQL keeps physical SQLite behavior, including PRAGMA and VACUUM. A
local SQLITE_BUSY, whether a statement or the opening of a transaction
($transaction, or a nested write’s implicit one) hits it, quarantines that
exact native client: libSQL leaves the failed statement unfinished on its pooled
connection, and SQLite never commits that connection’s later writes. The failing
call reports the retryable V5006, but further VibORM work refuses with
V1003, across wrappers sharing that client, before another write can be
acknowledged; retry only after recovery. For an owned driver, $disconnect()
closes the failed transport; the next operation reconnects. For a supplied
client, VibORM leaves it open: its owner must close it and create a replacement
client and wrapper. Merely calling $disconnect() on a borrowed wrapper cannot
establish recovery. Remote clients keep their native execution path.
Migrations
Runtime transaction support does not grant live Migration V1 support. LibSQL
refuses push, apply, down, reset, and locked verify before effects:
its constraint alteration does not prevalidate existing rows, and safe table
reconstruction has not been proven with the migration lock and marker update.
Offline generate and check, estate inspection, and admitted read-only
status, log, and push({ dryRun: true }) remain available.
apply({ dryRun: true }) and down({ dryRun: true }) read the live marker
without a lock and require database connectivity. reset({ dryRun: true })
previews the estate’s root-to-target path without database reads, after target
and read-only capability admission. These previews do not enable live effects.
Use the provider’s deployment migration system for live schema changes. The qualified local LibSQL runtime is not evidence of hosted Turso migration support. See LibSQL migration limits.
GeoPoint storage tier
Local LibSQL uses the checked SQLite GeoPoint JSON carrier. Typed CRUD, equality,
inclusive bounds, nullability, transactions, relations, and cache are
qualified. 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)