# Turso

> Turso is a SQLite-compatible database for every application — local, embedded, cloud-synced, or remote.

## Overview

Turso is a ground-up rewrite of SQLite with concurrent writes (MVCC), async I/O, and built-in cloud sync. It runs embedded in your application, as a remote cloud database, or both. Turso is a drop-in replacement for SQLite — your existing SQL, schema, and queries work unchanged.

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

Features:

- **Concurrent writes** (MVCC) — multiple writers without "database is locked" errors
- **Full-text search** — Tantivy-powered FTS with BM25 ranking, highlighting, and boolean queries
- **Vector search** — native embedding storage and cosine similarity search
- **Turso Sync** — true local-first sync with explicit push/pull to Turso Cloud
- **Encryption at rest** — AES-256 per-database encryption
- **Change Data Capture (CDC)** — built-in audit logging of every mutation
- **Triggers and materialized views** — database-level automation
- **Multi-tenancy** — designed for thousands of lightweight databases (database-per-tenant)

## Which package should I use?

| Use case | TypeScript | Python |
| --- | --- | --- |
| **Local database** (embedded, on-device, offline) | `@tursodatabase/database` | `pyturso` |
| **Local database + cloud sync** (push/pull) | `@tursodatabase/sync` | `pyturso` (with sync) |
| **Remote access** (servers, Docker, serverless, edge — any over-the-wire) | `@tursodatabase/serverless` | `libsql` |
| **Legacy (libSQL)** — battle-tested, ORM support | `@libsql/client` | `libsql` |

**Starting a new project?** Use `@tursodatabase/database` (TypeScript) or `pyturso` (Python) for local/embedded use. Use `@tursodatabase/serverless` for any application that connects to a remote Turso Cloud database over the network — including Node.js servers, Docker containers, serverless functions, and edge runtimes. Use `@libsql/client` only if you need ORM integration (Drizzle, Prisma) today.

**Need sync?** Use `@tursodatabase/sync` (TypeScript) or `pyturso` with sync (Python) for local reads and writes with explicit push/pull to Turso Cloud.

## Turso Sync

Turso Sync provides true local-first operation — all reads and writes go to the local database file, and you explicitly push/pull to sync with Turso Cloud.

- All reads and writes happen locally (fast, offline-capable)
- `push()` sends local changes to Turso Cloud
- `pull()` fetches remote changes to local database
- Conflict resolution via last-push-wins with rollback-and-replay
- Available in TypeScript, Python, React Native, and other SDKs

### TypeScript Example

```typescript
import { connect } from "@tursodatabase/sync";

const db = await connect({
  path: "./app.db",
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// All reads and writes are local
await db.exec("INSERT INTO users (name) VALUES ('Alice')");

// Push local changes to Turso Cloud
await db.push();

// Pull remote changes to local database
await db.pull();
```

## Turso Cloud

Turso Cloud is a managed platform for SQLite-compatible 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 via AWS PrivateLink
- **Encryption**: Data encrypted at rest (AES-256) and in transit
- **Multi-region**: Deploy databases globally
- **Multi-tenancy**: Create thousands of databases per organization
- **Platform API**: Programmatic database management (create, delete, token generation)
- **SQL over HTTP**: Query any database via HTTP POST to `/v2/pipeline`

## SDKs

### TypeScript / JavaScript

| Package | Use case |
| --- | --- |
| `@tursodatabase/database` | Local / embedded database |
| `@tursodatabase/sync` | Local database + cloud sync (push/pull) |
| `@tursodatabase/serverless` | Remote access — servers, Docker, serverless, edge (any over-the-wire) |
| `@libsql/client` | Legacy — ORM support (Drizzle, Prisma) |

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

#### Local / Embedded Database

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

const db = await connect("app.db");

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

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

#### In-Memory Database

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

const db = await connect(":memory:");

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

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

#### Remote Database (servers, Docker, serverless, edge)

```typescript
import { connect } from "@tursodatabase/serverless";

const conn = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

const stmt = await conn.prepare("SELECT * FROM users");
const rows = await stmt.all();
```

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

Note: ORM integration currently requires `@libsql/client`. The `@tursodatabase/serverless` package provides a compat module (`@tursodatabase/serverless/compat`) that exposes the same `createClient` API.

### 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` (imported as `turso`)

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

```python
import turso

# Local database
db = turso.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)
```

```python
import turso.sync

# Local database with cloud sync
db = turso.sync.connect(
    "local.db",
    remote_url="libsql://your-db.turso.io",
    auth_token="your-token",
)

db.execute("INSERT INTO users (name) VALUES (?)", ("Bob",))
db.commit()

db.push()  # Push local changes to Turso Cloud
db.pull()  # Pull remote changes to local database
```

For remote access over the network, use the `libsql` package (`pip install libsql`):

```python
import libsql

conn = libsql.connect(
    database="libsql://your-db.turso.io",
    auth_token="your-token",
)

rows = conn.execute("SELECT * FROM users").fetchall()
```

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)?);
}
```

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()
```

## AgentFS

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

## Pricing

Full pricing details (plans, features, FAQs): https://turso.tech/pricing.md

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