oakoss 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-ormskill 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 -yIf the
local-firstskill 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 -yIf the
pgliteskill is available, delegate PGlite-specific patterns for comparison with Turso embedded replicas.
- Database provisioning: Use
Taskagent for multi-tenant setup automation - Vector search tuning: Use
Exploreagent to research embedding models and dimensions - Code review: Delegate to
code-revieweragent
References
- Client SDK setup, connection modes, and configuration
- Embedded replicas, sync strategies, and offline mode
- Batch operations and interactive transactions
- Vector search, embeddings, and similarity queries
- Multi-database per-tenant architecture and platform API
- CLI commands and database management
- Drizzle ORM integration with libSQL driver
- Schema migrations and database operations