Déployer Turso libSQL self-hosted : tutoriel complet 2026

📍 Article principal : Litestream/Turso 2026 : guide complet.

Turso = libSQL fork SQLite avec serveur HTTP, embedded replicas, edge distribution. Self-hosted sur VPS pour souveraineté complète.

Prérequis

• VPS Linux avec Docker.
• Domaine pour accès HTTPS.
• Niveau : avancé.
• Temps : 1h.

Étape 1 — Lancer libsql-server

docker run -d --name libsql-server \
  -p 8080:8080 \
  -v libsql-data:/var/lib/sqld \
  -e SQLD_NODE=primary \
  -e SQLD_HTTP_LISTEN_ADDR=0.0.0.0:8080 \
  -e SQLD_AUTH_JWT_KEY_FILE=/var/lib/sqld/jwt.pem \
  ghcr.io/tursodatabase/libsql-server:latest

Étape 2 — Caddy reverse proxy

db.votre-app.com {
  reverse_proxy localhost:8080
}

Étape 3 — Test API

curl https://db.votre-app.com/v2/pipeline \
  -d '{"requests":[{"type":"execute","stmt":{"sql":"SELECT 1"}}]}'

Étape 4 — Client TypeScript

npm install @libsql/client

import { createClient } from '@libsql/client';
const db = createClient({
  url: 'https://db.votre-app.com',
  authToken: process.env.TURSO_TOKEN
});

await db.execute('CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT)');
await db.execute({ sql: 'INSERT INTO users (email) VALUES (?)', args: ['test@example.com'] });
const r = await db.execute('SELECT * FROM users');

Étape 5 — Embedded replicas (latence zéro)

const db = createClient({
  url: 'file:local-replica.db',
  syncUrl: 'https://db.votre-app.com',
  authToken: process.env.TURSO_TOKEN,
  syncInterval: 60
});

Reads = SQLite local, writes = forward server, sync auto.

Étape 6 — Drizzle ORM compatibility

import { drizzle } from 'drizzle-orm/libsql';
const db = drizzle(client, { schema });

Étape 7 — JWT auth tokens

# Generate JWT key
docker exec libsql-server sqld admin gen-jwt-keys
# Outputs jwt.pem
# Generate token
docker exec libsql-server sqld admin gen-token --key /var/lib/sqld/jwt.pem

Étape 8 — Replicas multi-region

Sur autre VPS :

docker run -d \
  -e SQLD_NODE=replica \
  -e SQLD_PRIMARY_URL=https://db.votre-app.com \
  ghcr.io/tursodatabase/libsql-server

Étape 9 — Backups

Turso self-hosted : pg-style dump via libsql ou Litestream sur fichier underlying.

Étape 10 — Monitoring

Endpoint /v2/health. Prometheus metrics via env SQLD_METRICS=1.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Trois précisions. Edge replicas Africa : déployer replica sur Africa Data Centres Lagos. Mobile embedded : SDK iOS/Android natif. Coût : 1 VPS primary + 2 replicas = 13,53 €/mois pour SaaS multi-region.

Tutoriels frères

• Litestream
• Bun + SQLite

FAQ

Turso Cloud vs self-hosted ? Cloud free tier 500 DB. Self-host illimité.

Compatibilité SQLite ? 99% compatible. Quelques extensions custom.

Multi-writer ? Primary + read replicas. Writes vers primary.

Cloudflare Workers ? Embedded replica via libSQL JavaScript.

Migration depuis SQLite ? Trivial. cp app.db + import via API.

Pour aller plus loin

• 🔝 Pilier : Guide complet 2026
• Documentation : docs.turso.tech