Turso & libSQL

Turso is a SQLite-compatible managed database platform built on libSQL — a production-ready, open-contribution fork of SQLite. libSQL adds native vector search, extensions, and async I/O while remaining fully backward-compatible with SQLite.

libSQL vs. Turso Database: libSQL is the battle-tested fork used by Turso Cloud today. Turso Database is a ground-up rewrite optimized for extreme density and concurrent writes (currently in beta). For new projects with stable workloads, use libSQL via Turso Cloud. For new projects targeting agents, on-device, or high-density use cases, consider Turso Database.

Key Concepts

Term	Meaning
Database	A single libSQL database instance hosted on Turso Cloud
Group	A collection of databases sharing a region and auth tokens
Embedded Replica	A local SQLite file that syncs with a remote Turso database
Auth Token	JWT used to authenticate SDK connections
libsql://	The native Turso protocol (WebSocket-based, best for persistent connections)
https://	HTTP-based access, better for single-shot serverless queries

Installation

# TypeScript / JavaScript
npm install @libsql/client

# Python
pip install libsql-client

# Rust (Cargo.toml)
# libsql = "0.6"

# Go
# go get github.com/tursodatabase/go-libsql

Connecting to Turso

Always load credentials from environment variables. Never hardcode tokens.

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

const client = createClient({
  url: process.env.TURSO_DATABASE_URL!,    // libsql://[DB]-[ORG].turso.io
  authToken: process.env.TURSO_AUTH_TOKEN!, // JWT from Turso CLI or Platform API
});

Protocol selection:

• Use libsql:// for persistent connections (WebSockets) — best for servers and long-lived processes
• Use https:// for single serverless invocations — fewer round-trips per cold start
• Use file:path/to/db.db for local SQLite files (no authToken needed)
• Use :memory: for in-memory databases in tests

Executing Queries

Always use parameterized queries. Never interpolate user input into SQL strings.

// Simple query
const result = await client.execute("SELECT * FROM users");

// Positional placeholders (preferred for brevity)
const user = await client.execute({
  sql: "SELECT * FROM users WHERE id = ?",
  args: [userId],
});

// Named placeholders
const inserted = await client.execute({
  sql: "INSERT INTO users (name, email) VALUES (:name, :email)",
  args: { name: "Iku", email: "iku@example.com" },
});

ResultSet fields:

• rows — array of row objects
• columns — column names in order
• rowsAffected — for write operations
• lastInsertRowid — bigint | undefined for INSERT

Transactions

Batch Transactions (preferred for multi-statement writes)

All statements execute atomically. Any failure rolls back the entire batch.

await client.batch(
  [
    { sql: "INSERT INTO orders (user_id) VALUES (?)", args: [userId] },
    { sql: "UPDATE inventory SET stock = stock - 1 WHERE id = ?", args: [itemId] },
  ],
  "write",
);

Interactive Transactions (for conditional logic)

Use when write decisions depend on reads within the same transaction. Note: interactive transactions lock the database for up to 5 seconds — prefer batch transactions where possible.

const tx = await client.transaction("write");
try {
  const { rows } = await tx.execute({
    sql: "SELECT balance FROM accounts WHERE id = ?",
    args: [accountId],
  });
  if ((rows[0].balance as number) >= amount) {
    await tx.execute({
      sql: "UPDATE accounts SET balance = balance - ? WHERE id = ?",
      args: [amount, accountId],
    });
    await tx.commit();
  } else {
    await tx.rollback();
  }
} catch (e) {
  await tx.rollback();
  throw e;
}

Transaction Modes

Mode	SQLite Command	Use When
write	BEGIN IMMEDIATE	Mix of reads and writes
read	BEGIN TRANSACTION READONLY	Read-only; can parallelize on replicas
deferred	BEGIN DEFERRED	Unknown upfront; may fail if a write is in flight

Local Development

Use environment variables to switch between local and remote transparently:

// .env.local
TURSO_DATABASE_URL=file:local.db
// No TURSO_AUTH_TOKEN needed for local files

// .env.production
TURSO_DATABASE_URL=libsql://my-db-myorg.turso.io
TURSO_AUTH_TOKEN=eyJ...

Run a local libSQL server with libSQL-specific features (extensions, etc.):

turso dev --db-file local.db
# Connects at http://127.0.0.1:8080

Embedded Replicas

Embedded replicas sync a remote Turso database into a local file. Reads are microsecond-speed (local). Writes go to the remote primary and are reflected locally immediately (read-your-writes semantics).

const client = createClient({
  url: "file:replica.db",         // local file path
  syncUrl: process.env.TURSO_DATABASE_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
  syncInterval: 60,               // auto-sync every 60 seconds (optional)
});

// Manually trigger sync
await client.sync();

When to use embedded replicas:

• VMs / VPS deployments where the process is long-lived
• Mobile apps needing offline-capable local data
• Edge deployments with filesystem access

Do not use embedded replicas in:

• Serverless environments without a persistent filesystem (use https:// instead)
• Multiple concurrent processes writing to the same local file (risk of corruption)

See references/embedded-replicas.md for sync patterns and deployment guides.

Vector Search

libSQL includes native vector search — no extension required. Use F32_BLOB for embeddings (best balance of precision and storage).

-- Schema
CREATE TABLE documents (
  id    INTEGER PRIMARY KEY,
  text  TEXT,
  embedding F32_BLOB(1536)  -- match your embedding model's dimensions
);

-- Create vector index (DiskANN-based ANN search)
CREATE INDEX documents_idx ON documents (libsql_vector_idx(embedding));

-- Insert with embedding
INSERT INTO documents (text, embedding)
VALUES ('Hello world', vector32('[0.1, 0.2, ...]'));

-- Query top-K nearest neighbors
SELECT d.id, d.text
FROM vector_top_k('documents_idx', vector32('[0.1, 0.2, ...]'), 5)
JOIN documents d ON d.rowid = id;

See references/vector-search.md for index settings, distance functions, and RAG patterns.

Authentication & Security

• Generate scoped auth tokens via the CLI: turso db tokens create <db-name>
• For group-level tokens: turso group tokens create <group-name>
• Rotate tokens with: turso db tokens invalidate <db-name>
• Use JWKS integration to let your auth provider (Clerk, Auth0) issue tokens directly
• Apply fine-grained permissions to restrict tokens to specific tables or operations

See references/connection-and-auth.md for token scoping, JWKS setup, and security checklist.

CLI Quick Reference

turso auth login                          # authenticate
turso db create my-db                    # create database
turso db show my-db                      # show URL and metadata
turso db tokens create my-db             # create auth token
turso db shell my-db                     # interactive SQL shell
turso db inspect my-db                   # storage stats and top queries
turso dev --db-file local.db             # local libSQL server

Additional Resources

• references/connection-and-auth.md — Auth tokens, JWKS, fine-grained permissions, security checklist
• references/vector-search.md — Vector types, index settings, distance functions, RAG query patterns
• references/embedded-replicas.md — Sync strategies, encryption at rest, deployment guides