Set up Turso with an AI agent

name: turso
description: Use when building applications with SQLite-compatible databases,
  managing cloud-hosted or embedded databases, creating multi-tenant systems,
  implementing local-first sync, or provisioning databases programmatically via
  API. Turso is a ground-up rewrite of SQLite with concurrent writes, async I/O,
  and cloud sync capabilities.
metadata:
  mintlify-proj: turso
  version: "1.0"

Turso Skill

Product Summary

Turso is a SQLite-compatible database platform offering two engines: Turso Database (a ground-up rewrite of SQLite with concurrent writes and async I/O) and libSQL (a production-ready SQLite fork). Turso Cloud provides fully managed hosting with branching, point-in-time recovery, vector search, and embedded replicas. The Turso CLI (turso) manages databases, groups, and tokens. Key SDKs: @tursodatabase/database (local), @tursodatabase/sync (local + cloud sync), @tursodatabase/serverless (remote Turso), @libsql/client (remote libSQL). Primary docs: https://docs.turso.tech

When to Use

Reach for this skill when:

• Building applications that need SQLite compatibility with concurrent writes (use Turso Database)
• Creating multi-tenant systems where each user/agent gets an isolated database
• Implementing local-first applications with explicit push/pull sync to the cloud
• Provisioning databases programmatically via the Platform API
• Managing databases and access tokens from the CLI
• Deploying embedded replicas for offline-capable mobile or edge applications
• Migrating from SQLite without changing SQL or schema
• Setting up fine-grained access control with scoped tokens
• Working with vector embeddings for AI/RAG applications

Quick Reference

CLI Commands

Task	Command
Create database (Turso)	turso db create my-db --tursodb
Create database (libSQL)	turso db create my-db
List databases	turso db list
Connect to shell	turso db shell my-db
Show database URL	turso db show my-db --url
Create database token	turso db tokens create my-db
Create read-only token	turso db tokens create my-db --read-only
Token with expiration	turso db tokens create my-db --expiration 7d
Create group	turso group create my-group --location sfo
List locations	turso db locations
Create API token	turso auth api-tokens mint my-token --org my-org
Login	turso auth login (or --headless for CI/CD)

SDK Selection

Use Case	TypeScript	Python	Go	Rust
Local database	@tursodatabase/database	pyturso	tursogo	turso
Local + cloud sync	@tursodatabase/sync	pyturso (with sync)	tursogo (with sync)	turso (with sync feature)
Remote Turso	@tursodatabase/serverless	turso_serverless	tursogo-serverless	turso_serverless
Remote libSQL	@libsql/client	libsql	libsql-client-go	libsql (with remote)

Environment Variables

TURSO_DATABASE_URL=turso://...  # Database URL from turso db show
TURSO_AUTH_TOKEN=...             # Token from turso db tokens create
TURSO_ORG=my-org                 # Organization slug for API calls
TURSO_PLATFORM_TOKEN=...         # API token from turso auth api-tokens mint

Decision Guidance

When to Use Turso Database vs. libSQL

Factor	Turso Database	libSQL
Concurrent writes	Native MVCC, multiple writers	Not supported
New projects	✓ Recommended	For mission-critical legacy workloads
SQLite compatibility	Backwards compatible	Full (same file format)
Maturity	Production-ready	Battle-tested for years
Best for	Agents, smart devices, high density	Existing workloads needing stability

When to Use Each SDK Package

Scenario	Package	Why
Local file, no network	@tursodatabase/database	Runs in-process, no server needed
Local + cloud sync	@tursodatabase/sync	Explicit push/pull, local-first writes
Server/container → Turso Cloud	@tursodatabase/serverless	HTTP only, zero native deps, works in serverless
ORM (Drizzle, Prisma)	@libsql/client	Production ORM support
Embedded replica (reads local)	@libsql/client with sync URL	Reads from local file, writes to cloud

When to Use CLI vs. Platform API

Task	CLI	API
One-off database creation	✓
Programmatic multi-tenant provisioning		✓
Local development	✓
CI/CD automation	✓ (with --headless)	✓
Batch operations		✓

Workflow

1. Set Up Turso Cloud Database

1. Install CLI: brew install tursodatabase/tap/turso (macOS) or curl -sSfL https://get.tur.so/install.sh | bash (Linux)
2. Authenticate: turso auth login (or --headless for CI/CD)
3. Create database: turso db create my-db --tursodb (Turso) or turso db create my-db (libSQL)
4. Retrieve credentials:
   • URL: turso db show my-db --url
   • Token: turso db tokens create my-db
5. Store in environment variables: TURSO_DATABASE_URL and TURSO_AUTH_TOKEN

2. Connect Application to Remote Database

1. Choose SDK based on use case (see Decision Guidance)
2. Install package: npm install @tursodatabase/serverless (or equivalent)
3. Initialize connection with URL and token
4. Execute queries using prepared statements
5. Handle errors and connection failures gracefully

3. Implement Local-First Sync

1. Create Turso Cloud database (steps 1-5 above)
2. Install sync package: npm install @tursodatabase/sync
3. Call connect() with path, url, and authToken
4. Execute queries against local database (all reads/writes are local)
5. Call push() to send changes to cloud
6. Call pull() to fetch remote changes
7. Call checkpoint() periodically to compact WAL

4. Create Multi-Tenant System

1. Create Platform API token: turso auth api-tokens mint my-token --org my-org
2. Use @tursodatabase/api client to programmatically:
   • Create database per user: turso.databases.create(user-${id}, { group: "default" })
   • Generate scoped token: turso.databases.createToken(db-name)
   • Delete when done: turso.databases.delete(db-name)
3. Store database URL and token for each user session
4. Connect user's app to their isolated database

5. Set Up Fine-Grained Access Control

1. Create read-only token: turso db tokens create my-db --read-only
2. Create table-scoped token: turso db tokens create my-db -p users:data_read -p comments:data_add
3. Create time-limited token: turso db tokens create my-db --expiration 7d
4. Pass token to SDK client as authToken
5. Token is enforced server-side; invalid operations are rejected

6. Local Development

1. For local Turso database: import { connect } from "@tursodatabase/database"; const db = await connect("local.db")
2. For libSQL with extensions: turso dev (starts local server at http://127.0.0.1:8080)
3. For production dump locally: turso db shell prod-db .dump > dump.sql && cat dump.sql | sqlite3 local.db
4. No auth token needed for local files
5. Use same code path for local and remote by switching URL/token via environment variables

Common Gotchas

• Wrong SDK for use case: Using @libsql/client for local databases instead of @tursodatabase/database adds unnecessary overhead. Match SDK to use case (see Decision Guidance).
• Forgetting --tursodb flag: turso db create my-db creates libSQL, not Turso Database. Add --tursodb for concurrent writes.
• Unrestricted API tokens in production: Never use unrestricted tokens (deprecated). Always scope to organization with --org. Group-scoped tokens are most restrictive.
• Rotating credentials invalidates all apps: db:rotate-creds scope invalidates every SQL token in use. Only grant to automations that need it. Minting new tokens is additive and safe.
• Bootstrap on first sync: First connect() call with sync bootstraps from remote. Remote must be reachable. Set bootstrapIfEmpty: false to start offline.
• Writes blocked during open transactions: Push may be delayed if write transactions are still open. Ensure no write transaction is open when calling push().
• Local changes lost on turso dev stop: turso dev without --db-file loses data when stopped. Use --db-file local.db to persist.
• Embedded replicas vs. Turso Sync: Embedded Replicas (page-level replication) are older; Turso Sync (logical CDC) is recommended for new projects. Sync has lower bandwidth and latency.
• ORM compatibility: Drizzle and Prisma work with @libsql/client, not @tursodatabase/database. Use @libsql/client for ORM support.
• Token expiration not enforced client-side: Expired tokens are rejected by server. Monitor expiration and rotate before expiry.

Verification Checklist

Before submitting work with Turso:

• Database created with correct engine (--tursodb for Turso, omit for libSQL)
• Credentials retrieved and stored in environment variables (not hardcoded)
• SDK package matches use case (local vs. remote, Turso vs. libSQL)
• Connection tested with a simple query (e.g., SELECT 1)
• Tokens are scoped appropriately (not unrestricted, not overprivileged)
• For sync: push() and pull() tested; no open write transactions during push
• For multi-tenant: database per user/agent created and isolated
• Error handling in place for network failures and token expiration
• Local development uses local file or turso dev, not production database
• Sensitive data (tokens, URLs) not logged or exposed in error messages
• For production: API tokens use --org scope, not unrestricted

Resources

• Full documentation: https://docs.turso.tech/llms.txt (comprehensive page-by-page navigation for agents)
• Turso Cloud: https://docs.turso.tech/turso-cloud
• SDK Introduction: https://docs.turso.tech/sdk/introduction (choose the right package)
• Platform API: https://docs.turso.tech/api-reference (programmatic database management)
• Turso Sync: https://docs.turso.tech/sync/usage (local-first sync with push/pull)

---

For additional documentation and navigation, see: https://docs.turso.tech/llms.txt