# Turso

> Turso is an in-process SQL database, compatible with SQLite.

## Overview

Turso is a SQLite-compatible database built for modern applications. It runs embedded in your application and syncs to Turso Cloud.

- GitHub: https://github.com/tursodatabase/turso
- Documentation: https://docs.turso.tech

Turso is currently in beta and supports:

- Concurrent writes
- Encryption at rest
- Vector search (embeddings)
- Full-text search
- Turso Sync (sync to cloud)

## libSQL

libSQL is a production-ready SQLite fork built by the Turso team.

- GitHub: https://github.com/tursodatabase/libsql

libSQL supports:

- Full SQLite compatibility
- HTTP protocol for remote access
- SQLite extensions
- Sync via Embedded Replicas (simpler sync for read-heavy workloads)

Note: Once Turso becomes GA, it will be a drop-in replacement for libSQL with additional features.
You are encouraged to use Turso by default if you can build with a beta release; otherwise libSQL
is the way to use Turso Cloud.

## Turso Sync

Turso Sync is the core feature for syncing local databases to Turso Cloud.

- Sync local SQLite databases to the cloud
- Works offline, automatically syncs when connected
- Conflict resolution for concurrent writes
- Available in TypeScript, React Native, and other SDKs

Note that libSQL also supports a simpler sync, called embedded replicas. However, for robust
sync it is recommended to use Turso.

### TypeScript Example

```typescript
import { TursoDatabase } from "@tursodatabase/database";
import { TursoSync } from "@tursodatabase/sync";

const db = new TursoDatabase(":memory:");
const sync = new TursoSync(db, {
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await sync.sync();
```

### React Native Example

```typescript
import { TursoSync } from "@tursodatabase/sync-react-native";

const sync = new TursoSync({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

await sync.sync();
```

## Turso Cloud

Turso Cloud is a managed platform for SQLite databases.

- Dashboard: https://app.turso.tech
- Documentation: https://docs.turso.tech/turso-cloud

Features:

- **Turso Sync**: Sync local databases to the cloud
- **Branching**: Copy-on-write database branches for development and testing
- **Point-in-Time Recovery**: Restore databases to any point in time
- **Scale to Zero**: Automatically scale down idle databases
- **Private Endpoints**: Secure database access
- **Encryption**: Data encrypted at rest and in transit
- **Multi-region**: Deploy databases globally

## SDKs

### TypeScript / JavaScript

Main packages:

- `@tursodatabase/database` - Embedded Turso database (beta)
- `@tursodatabase/sync` - Turso Sync for cloud synchronization
- `@tursodatabase/serverless` - Access Turso Cloud from serverless functions
- `@libsql/client` - Production-ready libSQL client

NPM: https://www.npmjs.com/package/@tursodatabase/database

#### Basic Usage

```typescript
import { TursoDatabase } from "@tursodatabase/database";

const db = new TursoDatabase(":memory:");

db.exec(`
  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);
  INSERT INTO users (name) VALUES ('Alice');
`);

const users = db.prepare("SELECT * FROM users").all();
console.log(users);
```

#### Framework Guides

- Next.js: https://docs.turso.tech/sdk/ts/guides/nextjs
- Remix: https://docs.turso.tech/sdk/ts/guides/remix
- Astro: https://docs.turso.tech/sdk/ts/guides/astro
- Nuxt: https://docs.turso.tech/sdk/ts/guides/nuxt
- SvelteKit: https://docs.turso.tech/sdk/ts/guides/sveltekit
- Qwik: https://docs.turso.tech/sdk/ts/guides/qwik
- Elysia: https://docs.turso.tech/sdk/ts/guides/elysia
- Hono: https://docs.turso.tech/sdk/ts/guides/hono

#### ORM Integration

- Drizzle: https://docs.turso.tech/sdk/ts/orm/drizzle
- Prisma: https://docs.turso.tech/sdk/ts/orm/prisma

### React Native

Package: `@tursodatabase/sync-react-native`

NPM: https://www.npmjs.com/package/@tursodatabase/sync-react-native
Blog: https://turso.tech/blog/react-native-bindings-for-turso

Use Turso Sync in React Native apps for offline-first mobile applications.

### Python

Package: `pyturso`

Documentation: https://docs.turso.tech/sdk/python/quickstart

```python
import pyturso

db = pyturso.connect("local.db")

db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO users (name) VALUES (?)", ("Alice",))

for row in db.execute("SELECT * FROM users"):
    print(row)
```

For libSQL (production-ready), use `libsql-client` package instead.

ORM: SQLAlchemy - https://docs.turso.tech/sdk/python/orm/sqlalchemy
Framework: Flask - https://docs.turso.tech/sdk/python/guides/flask

### Rust

Crate: `turso`

Documentation: https://docs.turso.tech/sdk/rust/quickstart

```rust
use turso::Database;

let db = Builder::new_local(":memory:")
    .build()
    .await
    .expect("Turso Failed to Build memory db");

db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)", ())?;
db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])?;

let mut rows = db.query("SELECT * FROM users", ())?;
while let Some(row) = rows.next()? {
    println!("{}: {}", row.get::<i64>(0)?, row.get::<String>(1)?);
}
```

For libSQL (production-ready), use the `libsql` crate instead.

Frameworks: Actix, Axum, Rocket, Tauri

### Go

Package: `turso.tech/database/tursogo`

Installation: `go get turso.tech/database/tursogo`

Documentation: https://docs.turso.tech/sdk/go/quickstart

```go
import (
	"database/sql"

	_ "turso.tech/database/tursogo"
)

conn, err := sql.Open("turso", ":memory:")
conn.Exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
conn.Exec("INSERT INTO users (name) VALUES (?)", "Alice")

rows, err := conn.Query("SELECT * FROM users")
defer rows.Close()
```

For libSQL (production-ready), use `github.com/tursodatabase/libsql-client-go` instead.

## AgentFS (Beta)

AgentFS provides filesystem and state management for AI agents.

- Sandboxed file operations
- Session management for agent state
- MCP (Model Context Protocol) support
- Sync capabilities

Documentation: https://docs.turso.tech/agentfs

### TypeScript

```typescript
import { AgentFS } from "@tursodatabase/agentfs";

const fs = new AgentFS({ sandbox: true });
await fs.writeFile("/data/config.json", JSON.stringify({ key: "value" }));
const content = await fs.readFile("/data/config.json");
```

## CLI

The `turso` CLI manages databases and organizations.

Installation: https://docs.turso.tech/cli/installation

### Commands

```bash
# Authentication
turso auth login
turso auth logout
turso auth token

# Database management
turso db create mydb
turso db list
turso db show mydb
turso db shell mydb
turso db destroy mydb

# Import/Export
turso db import mydb data.sql
turso db export mydb > backup.sql

# Groups (multi-region)
turso group create mygroup
turso group locations add mygroup lax

# Organizations
turso org list
turso org switch myorg
turso org members list

# Plans and billing
turso plan show
turso plan upgrade
```

Full CLI reference: https://docs.turso.tech/cli

## Platform API

REST API for programmatic access to Turso Cloud.

Documentation: https://docs.turso.tech/api-reference
Authentication: API tokens via `turso auth api-tokens mint`

### Endpoints

**Databases**
- `GET /v1/organizations/{org}/databases` - List databases
- `POST /v1/organizations/{org}/databases` - Create database
- `GET /v1/organizations/{org}/databases/{db}` - Get database
- `DELETE /v1/organizations/{org}/databases/{db}` - Delete database
- `POST /v1/organizations/{org}/databases/{db}/auth/tokens` - Create token

**Groups**
- `GET /v1/organizations/{org}/groups` - List groups
- `POST /v1/organizations/{org}/groups` - Create group
- `POST /v1/organizations/{org}/groups/{group}/locations/{location}` - Add location

**Organizations**
- `GET /v1/organizations` - List organizations
- `GET /v1/organizations/{org}/usage` - Get usage

Full API reference: https://docs.turso.tech/api-reference

## Links

- Website: https://turso.tech
- Documentation: https://docs.turso.tech
- Dashboard: https://app.turso.tech
- GitHub (Turso): https://github.com/tursodatabase/turso
- GitHub (libSQL): https://github.com/tursodatabase/libsql
- Discord: https://discord.gg/turso
- Blog: https://turso.tech/blog
- Twitter: https://x.com/tursodatabase