---
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

```bash
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