# libSQL (Turso) — Open-Contribution Fork of SQLite

> libSQL is a fork of SQLite that is both open source and open to contributions. Created by Turso to add features SQLite cannot: embedded replicas, server mode, vector search, and ALTER TABLE extensions. The edge database for modern apps.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install Turso CLI
brew install tursodatabase/tap/turso

# Create database
turso db create mydb
turso db shell mydb

# Or run libSQL locally
docker run -d --name libsql -p 8080:8080 ghcr.io/tursodatabase/libsql-server:latest
```

SQL usage (SQLite-compatible + extensions):
```sql
CREATE TABLE assets (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  repo TEXT NOT NULL UNIQUE,
  stars INTEGER DEFAULT 0,
  embedding F32_BLOB(384),  -- vector column
  created_at TEXT DEFAULT (datetime("now"))
);

INSERT INTO assets (repo, stars) VALUES ("react", 230000);
INSERT INTO assets (repo, stars) VALUES ("vue", 210000);

SELECT * FROM assets ORDER BY stars DESC;

-- Vector search (libSQL extension)
SELECT repo, vector_distance_cos(embedding, vector("[0.1, 0.2, ...]")) AS distance
FROM assets
ORDER BY distance ASC
LIMIT 5;

-- ALTER TABLE ADD COLUMN (SQLite limitation removed in libSQL)
ALTER TABLE assets ADD COLUMN category TEXT DEFAULT "general";
```

TypeScript client:
```ts
import { createClient } from "@libsql/client";

const db = createClient({
  url: "libsql://mydb-william.turso.io",
  authToken: "...",
});

const result = await db.execute("SELECT * FROM assets ORDER BY stars DESC LIMIT 10");
console.log(result.rows);
```

## Intro

libSQL is a fork of SQLite that is both open source (MIT) and open to community contributions. Created by the Turso team because SQLite is open source but does not accept external contributions. libSQL adds features that SQLite has historically refused: server mode, embedded replicas, vector search (via vectorlite), ALTER TABLE extensions, and encryption at rest. Turso provides a managed edge database service built on libSQL.

- **Repo**: https://github.com/tursodatabase/libsql
- **Stars**: 16K+
- **Language**: C
- **License**: MIT

## What libSQL Does

- **SQLite compatible** — full SQLite API and file format
- **Server mode** — HTTP and WebSocket access (sqld)
- **Embedded replicas** — local SQLite file synced from remote
- **Vector search** — F32_BLOB type + vector distance functions
- **ALTER TABLE** — DROP COLUMN and other extensions
- **Encryption** — at-rest encryption
- **Multi-tenancy** — schema-based namespace isolation
- **Edge deployment** — replicas at edge locations
- **TypeScript/Rust/Go/Python clients** — official SDKs
- **Turso managed** — global edge DB service

## Architecture

Fork of SQLite C codebase with extensions. sqld (server daemon) wraps libSQL and serves HTTP/WebSocket/gRPC. Embedded replicas sync WAL frames from primary to local SQLite file on the client. Turso infrastructure distributes replicas globally via Fly.io.

## Self-Hosting

```bash
# Run sqld server
docker run -d --name libsql -p 8080:8080 \
  -v libsql-data:/var/lib/sqld \
  ghcr.io/tursodatabase/libsql-server:latest

# Connect
curl http://localhost:8080/v2/pipeline -d "{\"requests\": [{\"type\": \"execute\", \"stmt\": {\"sql\": \"SELECT 1\"}}]}"
```

## Key Features

- Full SQLite compatibility
- Server mode (HTTP + WebSocket)
- Embedded replicas
- Vector search
- ALTER TABLE extensions
- Encryption at rest
- Multi-tenancy
- Edge deployment (Turso)
- Official SDKs (TS, Rust, Go, Python)
- Open to contributions (unlike SQLite)

## Comparison

| Database | Type | Server Mode | Vector |
|---|---|---|---|
| libSQL | SQLite fork | Yes (sqld) | Yes |
| SQLite | Embedded | No | No |
| LiteFS | SQLite replication | Proxy | No |
| Cloudflare D1 | SQLite managed | Yes | No |
| PlanetScale | MySQL managed | Yes | No |
| Neon | Postgres managed | Yes | Via pgvector |

## FAQ

**Q: Difference from SQLite?**
A: libSQL is a superset of SQLite. It adds a server mode, embedded replicas, vector search, and ALTER TABLE extensions. The upstream SQLite project doesn't accept external contributions; libSQL is completely open.

**Q: What is Turso?**
A: Turso is a managed edge database service built on libSQL. Database replicas are deployed across global edge nodes (Fly.io) with read latency <50ms. Free tier offers 9GB of storage and 500 DBs per month.

**Q: What scenarios is it for?**
A: Scenarios needing SQLite's simplicity plus remote access, multiple replicas, or vector search. Examples: SaaS multi-tenant, mobile app local cache + cloud sync, edge worker data layer.

## Sources

- Docs: https://docs.turso.tech
- GitHub: https://github.com/tursodatabase/libsql
- License: MIT

---
Source: https://tokrepo.com/en/workflows/libsql-turso-open-contribution-fork-sqlite-290afe5f
Author: Script Depot