Turso

Turso Database

SQLite-compatible embedded database for modern applications, AI agents, and edge computing.

Links

• Documentation
• Changelog
• GitHub

Quick Navigation

When to Use

• Embedded SQLite database with cloud sync
• AI agent state management and multi-agent coordination
• Offline-first applications
• Encrypted databases (AEGIS, AES-GCM)
• Edge computing and IoT devices

Core Concepts

libSQL

Turso is built on libSQL, an open-source fork of SQLite with:

• Native encryption (AEGIS-256, AES-GCM)
• Async I/O (Linux io_uring)
• Cloud sync capabilities

Deployment Options

1. Embedded — runs locally in your app 2. Turso Cloud — managed platform with branching, backups 3. Hybrid — local with cloud sync (push/pull)

Common Patterns

Encrypted Database

openssl rand -hex 32  # Generate key
tursodb --experimental-encryption "file:db.db?cipher=aegis256&hexkey=YOUR_KEY"

Cloud Sync

import { connect } from "@tursodatabase/sync";

const db = await connect({
  path: "./local.db",
  url: "libsql://...",
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await db.push(); // local → cloud
await db.pull(); // cloud → local

Agent Database

import { connect } from "@tursodatabase/database";

// Local-first
const db = await connect("agent.db");

// Or with sync
const db = await connect({
  path: "agent.db",
  url: "https://db.turso.io",
  authToken: "...",
  sync: "full",
});

Version

Based on product version: 0.6.0

Release Note (0.6.0)

• Turso 0.6.0 expands the practical client surface with JS/serverless timeouts, interactive transactions, Python SQLAlchemy improvements, npm-based CLI distribution, and a broader SQL surface for local-first/agent workloads.

Links

• Documentation
• Changelog
• GitHub

Agent Databases

AI agents need databases for context, state, and memory. Two approaches:

• Embedded — local-first, offline-capable
• Turso Sync — distributed coordination with cloud persistence

Embedded (Local-First)

import { connect } from "@tursodatabase/database";

const db = await connect("agent.db");

db.prepare(
  `CREATE TABLE IF NOT EXISTS steps (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  action TEXT NOT NULL,
  result TEXT
)`,
).run();

db.prepare("INSERT INTO steps (action, result) VALUES (?, ?)").run("fetch_data", "success");

Benefits: Zero latency, offline, single-file deployment.

Turso Sync (Cloud-Connected)

const db = await connect({
  path: "agent-memory.db",
  url: "https://your-database.turso.io",
  authToken: "your-auth-token",
  sync: "full",
});

await db.sync(); // Manual sync

Sync modes: sync (bidirectional), pull (cloud → agent), push (agent → cloud)

Multi-Agent Patterns

Isolated Databases

const agent1DB = await connect("agent-1.db");
const agent2DB = await connect("agent-2.db");

Shared Database

const agent1DB = await connect({
  path: "agent-1-local.db",
  url: "https://shared-tasks.turso.io",
  sync: "full",
});

const agent2DB = await connect({
  path: "agent-2-local.db",
  url: "https://shared-tasks.turso.io", // Same URL
  sync: "full",
});

Hub-and-Spoke

const workerDB = await connect({ sync: "push", ... });      // Worker: push only
const coordinatorDB = await connect({ sync: "pull", ... }); // Coordinator: pull only

Query Budgets and Timeouts (0.6.0)

The 0.6.0 release line adds explicit timeout controls in the JavaScript/serverless surface. For agent loops, prefer bounded query/connection time over implicit hanging network calls.

• Use per-connection or per-statement timeouts when the client surface exposes them.
• In HTTP/serverless flows, wire cancellation into your runtime budget rather than waiting for the default connection lifecycle.
• Fail fast on expired work instead of letting one stuck query consume the whole agent turn.

Interactive Transactions

Turso now documents interactive transactions for multi-step read/write invariants.

• Use them for short, stateful critical sections such as balance/lease updates or compare-and-swap style orchestration.
• Do not keep them open across slow tool calls, human approval steps, or long LLM turns.
• Current docs note a 5-second transaction window and write locking until commit/rollback, so they are not a fit for long-running coordination flows.

Python Agent Backends

For Python services, prefer the official sqlalchemy-libsql integration instead of custom DBAPI glue. That keeps local-only, remote-only, and embedded-replica setups on the documented path and aligns well with async web backends that still want ORM ergonomics.

Useful SQL Surface for Agents (0.6.0)

The 0.6.0 SQL surface grows in ways that matter for agent workflows:

• CREATE TABLE AS SELECT is useful for checkpointing, materializing intermediate search results, or creating review snapshots.
• Temporary tables are useful for short-lived planning/output staging without polluting durable schema.
• CREATE DOMAIN / DROP DOMAIN and STRICT composite types (STRUCT, UNION) let you encode stronger contracts when agents write semi-structured state.

Prefer these features when they simplify state transitions, but keep production schemas intentionally small and reviewable.

Database-Per-Agent (Platform API)

import { createClient } from "@tursodatabase/api";

const turso = createClient({
  token: process.env.TURSO_PLATFORM_API_TOKEN,
  org: process.env.TURSO_ORG_NAME,
});

const database = await turso.databases.create(`agent-${agentId}`, {
  group: "default",
});

Benefits: Complete isolation, independent scaling, easy cleanup.

Authorization

JWT-based authorization via JWKS or Turso CLI tokens.

Token Types

1. JWKS tokens — from your auth provider (Clerk, Auth0) 2. Database tokens — created via CLI 3. Group tokens — access to multiple databases

JWKS Setup

1. Generate JWT Template

# Full access to database
turso org jwks template --database <db> --scope full-access

# Read-only access to group
turso org jwks template --group <group> --scope read-only

# Fine-grained permissions
turso org jwks template \
  --database <db> \
  --permissions all:data_read \
  --permissions comments:data_add \
  --permissions posts:data_add,data_update

Permission Actions

2. Add JWKS Endpoint

turso org jwks save clerk https://your-app.clerk.accounts.dev/.well-known/jwks.json

3. Use in Application

import { createClient } from "@tursodatabase/serverless";

const db = createClient({
  url: "https://<db>.turso.io",
  authToken: await getAuthToken(), // JWT from auth provider
});

const result = await db.execute("SELECT * FROM users");

CLI Token Management

# Create database token
turso db tokens create <db>

# List JWKS endpoints
turso org jwks list

# Remove JWKS endpoint
turso org jwks remove <name>

Notes

• During Beta: only Clerk & Auth0 supported as OIDC providers
• Without JWT template: tokens have access to all databases in all groups
• data_read allowed on SQLite system tables by default

Encryption

Native encryption at rest using AEAD algorithms. Page-level encryption with ~6% read and ~14% write overhead.

Generate Key

# 256-bit key (for AEGIS-256, AES-256-GCM)
openssl rand -hex 32

# 128-bit key (for AEGIS-128, AES-128-GCM)
openssl rand -hex 16

Store key securely! Lost key = lost data.

Create Encrypted Database

tursodb --experimental-encryption "file:encrypted.db?cipher=aegis256&hexkey=YOUR_HEX_KEY"

CREATE TABLE secrets (id INT, data TEXT);
INSERT INTO secrets VALUES (1, 'sensitive information');

Open Encrypted Database

tursodb --experimental-encryption "file:encrypted.db?cipher=aegis256&hexkey=YOUR_HEX_KEY"

Supported Ciphers

AEGIS (Recommended)

AES-GCM (Compliance)

URI Format

file:database.db?cipher=CIPHER&hexkey=HEX_KEY

Examples:

file:db.db?cipher=aegis256&hexkey=2d7a30108d3eb3e45c90a732...
file:db.db?cipher=aes128gcm&hexkey=5f3e2a8c9b1d4f6e...

Encrypted Attached Databases (v0.5.0)

As of v0.5.0, encryption keys for attached databases can be provided via URI params on the attached database path.

Example:

ATTACH DATABASE 'file:attached.db?cipher=aegis256&hexkey=YOUR_HEX_KEY' AS attached;

Operational notes:

• Treat each attached DB as its own encrypted file (it may use a different key).
• Keep keys out of SQL history/logs; prefer injecting them via secure config/secrets when possible.

What's Encrypted

• ✅ All database pages
• ✅ Database file
• ✅ WAL file
• ❌ Database header (first 100 bytes)

Installation

macOS / Linux

brew install tursodatabase/tap/turso

Or use the official install script:

curl -sSfL https://get.tur.so/install.sh | bash

Windows

Windows installation is documented via WSL. Start a WSL shell from PowerShell:

wsl

Then run the standard installer inside WSL:

curl -sSfL https://get.tur.so/install.sh | bash

Launch

turso             # Verify CLI installation
tursodb           # In-memory database
tursodb mydata.db # File database

For ephemeral CI/dev usage, Turso 0.6.0 also ships an npm package, so npx turso <command> is a reasonable no-global-install path when your environment is already Node-based.

Basic SQL

CREATE TABLE users (id INT, username TEXT);
INSERT INTO users VALUES (1, 'alice');
SELECT * FROM users;

Experimental Flags

• --experimental-encryption — enable encryption
• --experimental-mvcc — multi-version concurrency
• --experimental-strict — strict mode

Warning: Not production ready.

Python / SQLAlchemy (v0.6.0)

Turso documents SQLAlchemy via the sqlalchemy-libsql dialect. Prefer the official dialect over ad-hoc wrappers for Python services or agent backends, and treat the 0.6.0 line as the point where Python coverage became more practical for asyncio-heavy apps and named-parameter usage.

pip install sqlalchemy-libsql

Use standard SQLAlchemy engines for local, remote, memory-only, or embedded-replica setups, and keep Turso credentials in environment variables instead of hardcoding them.

Quickstart

Install

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tursodatabase/turso/releases/latest/download/turso_cli-installer.sh | sh

Windows (PowerShell)

irm https://github.com/tursodatabase/turso/releases/latest/download/turso_cli-installer.ps1 | iex

Launch

tursodb

Output:

Turso
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database
turso>

Basic SQL

-- Create table
CREATE TABLE users (id INT, username TEXT);

-- Insert data
INSERT INTO users VALUES (1, 'alice');
INSERT INTO users VALUES (2, 'bob');

-- Query
SELECT * FROM users;
-- Returns: 1|alice, 2|bob

Experimental Features

Enable with flags:

• --experimental-encryption
• --experimental-mvcc
• --experimental-strict
• --experimental-views

Warning: Not production ready.

Sync

Synchronize local Turso database with Turso Cloud.

Setup

1. Get Turso Cloud credentials

turso db show <db>                 # Get URL (libsql://...)
turso db tokens create <db>        # Create auth token

2. Connect with sync

import { connect } from "@tursodatabase/sync";

const db = await connect({
  path: "./app.db", // local file
  url: "libsql://...", // Turso Cloud URL
  authToken: process.env.TURSO_AUTH_TOKEN, // auth token
  // longPollTimeoutMs: 10_000,              // optional: server wait time
  // bootstrapIfEmpty: false,                // skip initial bootstrap
});

Note: First run bootstraps from remote (must be reachable).

Operations

Push (local → remote)

await db.exec("INSERT INTO notes VALUES ('n1', 'hello')");
await db.push(); // Send local changes to cloud

Conflict resolution: "last push wins"

Pull (remote → local)

const changed = await db.pull(); // Returns true if changes applied

Use longPollTimeoutMs to wait for changes (avoids empty replies).

Checkpoint

Compacts local WAL to bound disk usage:

await db.checkpoint();

Stats

const s = await db.stats();
// cdcOperations, mainWalSize, networkReceivedBytes, networkSentBytes, revision

---

Partial Sync

Sync only what you need. Lazy page fetching on demand.

Bootstrap Strategies

Prefix bootstrap — download first N bytes:

const db = await connect({
  path: "./app.db",
  url: "libsql://...",
  authToken: process.env.TURSO_AUTH_TOKEN,
  partialSync: {
    bootstrapStrategy: { kind: "prefix", length: 128 * 1024 }, // 128 KiB
  },
});

Query bootstrap — download pages touched by query:

const db = await connect({
  path: "./app.db",
  url: "libsql://...",
  authToken: process.env.TURSO_AUTH_TOKEN,
  partialSync: {
    bootstrapStrategy: {
      kind: "query",
      query: `SELECT * FROM messages WHERE user_id = 'u_123' LIMIT 100`,
    },
  },
});

Optimizations

Segment size — batch nearby pages (default 128 KiB):

partialSync: {
  segmentSize: 16 * 1024,  // 16 KiB segments
}

Prefetch — proactively fetch likely-needed pages:

partialSync: {
  prefetch: true,
}

Use both for best performance on real workloads.