@libsql/client

About

libSQL driver for TypeScript and JavaScript

Live mirror of the GitHub README. Updated whenever the repo's default branch changes.

libSQL TypeScript

Databases for all TypeScript and JS multi-tenant apps.

Turso · Docs · Quickstart · SDK Reference · Blog & Tutorials

Looking for the Turso serverless package? Check out @tursodatabase/serverless — the lightest option with zero native dependencies, and will be the driver to later support concurrent writes. Use @libsql/client if you need a battle-tested driver today with ORM integration.

Features

• 🔌 Works offline with Embedded Replicas
• 🌎 Works with remote Turso databases
• ✨ Works with Turso AI & Vector Search
• 🔐 Supports encryption at rest

Install

npm install @libsql/client

Quickstart

The example below uses Embedded Replicas and syncs every minute from Turso.

import { createClient } from "@libsql/client";

export const turso = createClient({
    url: "file:local.db",
    syncUrl: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
    syncInterval: 60000,
});

await turso.batch(
    [
        "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)",
        {
            sql: "INSERT INTO users(name) VALUES (?)",
            args: ["Iku"],
        },
    ],
    "write",
);

await turso.execute({
    sql: "SELECT * FROM users WHERE id = ?",
    args: [1],
});

Examples

Example	Description
local	Uses libsql with a local SQLite file. Creates database, inserts data, and queries.
remote	Connects to a remote database. Requires environment variables for URL and auth token.
sync	Demonstrates synchronization between local and remote databases.
batch	Executes multiple SQL statements in a single batch operation.
transactions	Shows transaction usage: starting, performing operations, and committing/rolling back.
memory	Uses an in-memory SQLite database for temporary storage or fast access.
vector	Works with vector embeddings, storing and querying for similarity search.
encryption	Creates and uses an encrypted SQLite database, demonstrating setup and data operations.
ollama	Similarity search with Ollama and Mistral.

Documentation

Visit our official documentation.

Support

Join us on Discord to get help using this SDK. Report security issues via email.

Contributors

See the contributing guide to learn how to get involved.

Quick facts

How Sourcemap Explorer detects @libsql/client

We catch @libsql/client from two complementary signals: bundled source paths and the embedded package.json. Modern bundlers (webpack, Vite, esbuild, Rollup, Turbopack) preserve the original node_modules/@libsql/client/ paths inside the JavaScript sourcemap's sources[] array — that's the canonical signal. When the matching package.json is also captured in sourcesContent[], we read the exact version field — patch number included. No regex guessing, no version inference.

1. 1

   Confirm the site exposes sourcemaps

   In DevTools Network, check the response headers of any application script for `SourceMap` or `X-SourceMap`. Failing that, fetch the script's last 4 KB and look for a `//# sourceMappingURL=` comment.

2. 2

   Find the package in the bundle

   Open DevTools → Network → reload. Click any application script and look at its sourcemap. Inside, search `sources[]` for entries matching `node_modules/@libsql/client/` — every match confirms the package is bundled. The matching `sourcesContent[i]` for `node_modules/@libsql/client/package.json` gives you the exact installed version.

3. 3

   Read the version directly from package.json

   Run `jq -r '. as $m | $m.sources | to_entries[] | select(.value | endswith("node_modules/@libsql/client/package.json")) | $m.sourcesContent[.key] | fromjson | .version' bundle.js.map`. Sourcemap Explorer automates the same query in the popup.

Recent versions

FAQ

Keep reading on Sourcemap Explorer