Turso

Overview

Turso is an edge-hosted SQLite platform built on libSQL, an open-source fork of SQLite. It provides globally distributed databases with embedded replicas for local-first reads, a platform API for programmatic database management, and native vector search. Use Turso for edge-deployed applications needing low-latency reads, per-tenant database isolation, or offline-capable embedded replicas. Avoid when you need a traditional relational database with complex joins across tenants or require PostgreSQL-specific features.

Quick Reference

Pattern	API / Command	Key Points
Remote client	`createClient({ url, authToken })`	Connect to Turso cloud database
Local file client	`createClient({ url: 'file:local.db' })`	Pure local SQLite via libSQL
Embedded replica	`createClient({ url, syncUrl, authToken })`	Local reads, remote sync
Manual sync	`client.sync()`	Pull latest changes from remote
Periodic sync	`syncInterval: 60` in client config	Auto-sync interval in seconds
Execute query	`client.execute({ sql, args })`	Positional `?` or named `$param` args
Batch operations	`client.batch([...statements], mode)`	Atomic multi-statement execution
Interactive transaction	`client.transaction('write')`	Multi-step logic with commit/rollback
Encryption at rest	`encryptionKey` in client config	Encrypts local database file
Vector insert	`vector32('[0.1, 0.2, ...]')`	Store embeddings as F32_BLOB columns
Vector search	`vector_distance_cos(col, vector32(...))`	Cosine similarity, ORDER BY distance ASC
Vector index	`libsql_vector_idx(col, 'type=diskann')`	DiskANN index for efficient nearest-neighbor
Create database (CLI)	`turso db create <name>`	Provision new database
Create database (API)	`POST /v1/organizations/{org}/databases`	Programmatic provisioning for multi-tenant
Generate token (CLI)	`turso db tokens create <name>`	Auth tokens with optional read-only and expiration
Drizzle integration	`drizzle(createClient({ url, authToken }))`	Use `drizzle-orm/libsql` driver
In-memory database	`createClient({ url: ':memory:' })`	Ephemeral database for testing

Common Mistakes

Mistake	Correct Pattern
Using `syncUrl` without `authToken`	Embedded replicas require both `syncUrl` and `authToken`
Forgetting `client.sync()` before reads	Call `sync()` or set `syncInterval` to keep replica current
Using `vector_distance_cos` without a vector index	Create a `libsql_vector_idx` index for efficient similarity search
Hardcoding auth tokens in source code	Use environment variables for `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN`
Using interactive transactions for simple batches	Use `client.batch()` for atomic multi-statement operations
Not closing transactions on error	Always call `transaction.close()` in a `finally` block
Creating one database for all tenants	Use multi-database per-tenant isolation for SaaS workloads
Passing raw arrays as vector values	Wrap vectors with `vector32()` SQL function or pass as `Float32Array`
Using `ORDER BY distance DESC` for nearest neighbor	Cosine distance: smaller is closer, use `ORDER BY distance ASC`

Delegation

If the drizzle-orm skill is available, delegate ORM schema definition, query building, relations, and migration patterns to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s drizzle-orm -a claude-code -y

If the local-first skill is available, delegate architecture decisions, sync engine comparisons, and conflict resolution strategies to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y

If the pglite skill is available, delegate PGlite-specific patterns for comparison with Turso embedded replicas.

Database provisioning: Use Task agent for multi-tenant setup automation
Vector search tuning: Use Explore agent to research embedding models and dimensions
Code review: Delegate to code-reviewer agent

turso

Turso

Overview

Quick Reference

Common Mistakes

Delegation

References