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

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 LATERAL joins, limited FULL OUTER JOIN
  • JSON columns return as strings and are parsed automatically
  • Boolean values stored as integers (0/1)

Was this page helpful?