turso
Turso SQLite database. Covers encryption, sync, serverless drivers, agent patterns. Use when working with Turso/libSQL embedded databases, configuring encryption-at-rest, setting up sync replication, choosing a Turso serverless driver for JS/Python/Rust/Go/.NET, or building agent-friendly database patterns. Keywords: Turso, libSQL, embedded, SQLite, encryption, sync, serverless driver.
How do I install this agent skill?
npx skills add https://github.com/itechmeat/llm-code --skill tursoIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive documentation and patterns for integrating Turso (libSQL) databases into AI agent workflows. It covers installation, encryption, synchronization, and authorization using official vendor resources and industry-standard security practices.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
5/7 files flagged
What does this agent skill do?
Turso Database
SQLite-compatible embedded database for modern applications, AI agents, and edge computing.
Links
Quick Navigation
| Topic | Reference |
|---|---|
| Installation | installation.md |
| Quickstart | quickstart.md |
| Encryption | encryption.md |
| Authorization | auth.md |
| Sync | sync.md |
| Drivers | serverless-drivers.md |
| Agent DBs | agents.md |
When to Use
- Embedded SQLite database with cloud sync
- Serverless and edge runtimes in JavaScript/TypeScript, Python, Rust, Go or .NET
- 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
- Embedded — runs locally in your app
- Turso Cloud — managed platform with branching, backups
- Hybrid — local with cloud sync (push/pull)
- Serverless / edge — Turso Cloud over the SQL-over-HTTP protocol, no persistent connections (see
references/serverless-drivers.md)
Concurrency
MVCC journal mode is selected per database with PRAGMA journal_mode = 'mvcc'. It is what allows several write transactions to run in parallel (BEGIN CONCURRENT, exposed as TransactionBehavior::Concurrent in Rust and the concurrent transaction mode in JavaScript).
Common Patterns
Encrypted Database
openssl rand -hex 32 # Generate key
tursodb --experimental-encryption "file:db.db?cipher=aegis256&hexkey=YOUR_KEY"
Serverless Connection (SQL over HTTP)
// JavaScript / TypeScript
import { connect } from "@tursodatabase/serverless";
const conn = connect({ url: process.env.TURSO_DATABASE_URL, authToken: process.env.TURSO_AUTH_TOKEN });
# Python
import turso_serverless
conn = turso_serverless.connect("libsql://my-db.turso.io", auth_token="...")
// Rust
let db = turso_serverless::Builder::new_remote(url)
.with_auth_token(token)
.build()
.await?;
// Go
db, _ := sql.Open("turso-serverless", url+"?auth_token="+token)
The Rust, Go and Python drivers are new in 0.8.0; the .NET equivalent is Turso.Serverless.Client. Full matrix in references/serverless-drivers.md.
Cloud Sync
import { connect } from "@tursodatabase/sync";
const db = await connect({
path: "./local.db",
url: "turso://...", // also accepts "libsql://..." — both schemes work
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",
});
Query Plans
EXPLAIN QUERY PLAN returns the classic four-column rows. EXPLAIN QUERY PLAN FORMAT=JSON (the clause is case-insensitive) returns one row with a single TEXT column named plan_json:
EXPLAIN QUERY PLAN FORMAT=JSON SELECT * FROM users WHERE age > 21;
The JSON document carries version, sql, result_columns, nodes and cte_materializations. nodes lists the same rows the text form prints, in the same order, with id/parent encoding the tree (parent: null marks a root) and detail holding the exact display string. Each node also has a structured op discriminated by op.type: scan, search, multi_index, index_method, hash_join, hash_build, distinct, distinct_aggregate, order_by, group_by, compound, compound_arm, list_subquery, scalar_subquery, recursive_setup, recursive_step and constant_row.
Table-access nodes may include an estimate object with the values that selected the join plan: input_rows, rows_per_input, output_rows, access_cost and total_cost. Those are planner estimates, not execution counters. The JSON format is not stable across minor versions — pin the client version if you parse it in production.
Version
Based on product version: 0.8.0
Release Highlights (0.8.0)
- Multi-language serverless drivers: the SQL-over-HTTP driver family now spans JavaScript, Python, Rust, Go and .NET. The Rust (
turso_serverless), Go (turso.tech/database/tursogo-serverless) and Python (turso-serverless) drivers are new in 0.8.0, each with conformance tests; the .NET serverless client ships as its own package (Turso.Serverless.Client). Seereferences/serverless-drivers.mdfor the full matrix. - .NET bindings: batches on embedded replicas, connection-string embedded replicas (
Replica Path), a managed pull-replica API (TursoSyncDatabase.PullAsync), advanced sync database options, and separate HTTP client packages. - Rust serverless:
Builder::with_auth_token_fnruns an async callback before every HTTP request, so short-lived auth tokens can be rotated without rebuilding the database handle. - Rust bindings:
TransactionBehavior::Concurrent(BEGIN CONCURRENT) lets several write transactions run in parallel with conflicts detected at commit time; it requiresPRAGMA journal_mode = 'mvcc'. - Query plans:
EXPLAIN QUERY PLAN FORMAT=JSONemits machine-readable plans (see Query Plans). - SQL surface: the window-function set grows to
rank(),dense_rank(),first_value(),last_value(),nth_value(),cume_dist()andpercent_rank(); indexes supportNULLS FIRST/NULLS LASTordering;PRAGMA count_changesreports row-change counts. - Experimental PostgreSQL layer: an experimental
tursopgsurface exposes Postgres-compatible access to Turso databases — treat it as experimental, not as the stable driver path. - Python bindings: SQLAlchemy reflection is now supported by Turso, with a minimum SQLAlchemy version of 2.0.45.
- Serverless compatibility: the JS libSQL-compatible layer (
@tursodatabase/serverless/compat) implementsreconnect(). - Core/MVCC: group commit is enabled by default and FULL waiters share the group-commit log; connect-time and post-
ANALYZEstats refresh is resumable, refreshedANALYZEstats are published to the shared schema, the optimizer costs repeated index seeks and required grouping sorts, andcore/connectionsupports passive mode in the checkpoint API. - FTS: search accepts null and non-text inputs and rejects non-finite field weights; rowid readers are reused across queries, tombstones are keyed by document identity so deletes and merges commute, and segments are merged on the write path past a threshold.
- Fixes: upsert conflict targets now match generated-column indexes and
REPLACEdefaults are applied before virtual generated columns are computed; binding fixes across Python, JS, Rust, Go and .NET.
Release Notes
0.7.1 – 0.7.2
- JS/serverless SDK:
transactionAsync()is the new closure-safe transaction API.transaction()is now deprecated — its closure semantics are unsound once transactions can run concurrently, because statements captured over the outerdb/conninstance can be scheduled out of order. Migrate transaction callbacks to use thetxnhandle passed intotransactionAsync()instead of closing over the outer instance (seereferences/agents.md). - Breaking:
Connection.execute()was removed from the serverless driver's native-mirroring surface (connect()), which now matches@tursodatabase/databaseand exposesrun/get/all/iterate/exec/batch/transaction(Async)instead. The libsql-compatiblecreateClient()layer keeps its ownexecute()and is unaffected (seereferences/auth.md). - Fixed a stale
inTransactionflag afterexecute()/batch()that could leave a server-side write transaction open past a constraint error. - Per-query
requestHeaders, passed through the trailing query-options argument, let you attach custom headers (e.g. a request-identity header) to a single call instead of only at the connection level. - Sync engine: the remote pull protocol (page-based WAL vs. MVCC logical-log) is now auto-detected on first contact, so the old
logical_mvcc_pullflag becomes an optional manual override instead of a requirement. A WAL-mode local replica is automatically converted to MVCC journal mode in place when it syncs against an MVCC remote. - Sync bindings (Rust, Python, JavaScript, Go, React Native) accept both
turso://andlibsql://remote URLs interchangeably. - Core fixes: an
IN (...)list query-cost regression that degradedInSeekto a full scan, a missing index left behind afterUPSERTdue to a pre-constraint-check index mutation, a change-count leak from sequences under MVCC, and DELETE/upsert replay bugs for tables with composite or non-rowid primary keys.
0.7.0
- SQL surface: SQL-standard scalar functions with PostgreSQL-compatible aliases, PostgreSQL-style sequences, MVCC-safe
AUTOINCREMENT, window-function work (row_number()on VDBE aggregate machinery,FILTERin window clauses), andWITHIN GROUPordered-set aggregates. - MVCC/durability: passive checkpoint for MVCC, portable logical-log metadata for Turso sync, and Aristo WAL verification.
- Collations: core custom collation support and locale-backed collations.
- .NET / platforms: NativeAOT static linking, remote transactions and batches, a Turso EF Core SQLite provider, NuGet native targets, and Windows ARM64 CLI releases.
Earlier (0.6.0)
JS/serverless timeouts, interactive transactions, Python SQLAlchemy improvements (sqlalchemy-libsql), npm-based CLI distribution, and a broader SQL surface for local-first/agent workloads — still in effect, see references/agents.md and references/installation.md.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/itechmeat/llm-code/turso">View turso on skillZs</a>