Que fait libSQL ?
Guide rapide : Utilisez
@libsql/clientpour tout accès à la base de données Turso. Utilisezexecute()pour les requêtes uniques,batch()pour les opérations atomiques multi-instructions (préféré aux transactions interactives), ettransaction()uniquement lorsque les requêtes ultérieures dépendent des résultats précédents. Pour les environnements edge/sans serveur sans accès au système de fichiers, importez depuis@libsql/client/web. Pour des lectures à latence nulle, configurez des réplicas intégrés avec une URL de fichier local +syncUrl. Toutes les écritures sont transmises au primaire — concevez pour une latence d'écriture de 15 à 50 ms. Turso est SQLite sous le capot : modèle à un seul écrivain, pas deALTER TABLE ... ADD CONSTRAINT, pas de procédures stockées.
<critical_requirements>
CRITIQUE : Avant d'Utiliser Cette Compétence
Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exportations nommées, ordre d'importation,
import type, constantes nommées)
(Vous DEVEZ utiliser batch() avec un mode de transaction pour les opérations atomiques multi-instructions — c'est plus rapide et plus sûr que transaction() interactif car cela s'exécute en un seul aller-retour)
(Vous DEVEZ importer depuis @libsql/client/web dans les environnements edge/sans serveur qui manquent d'accès au système de fichiers (Cloudflare Workers, Vercel Edge Functions) — l'import de base @libsql/client intègre des liaisons natives qui échouent dans ces environnements)
(Vous DEVEZ spécifier un mode de transaction ("write", "read", ou "deferred") comme deuxième argument de batch() et transaction() — la valeur par défaut est "deferred", qui échoue silencieusement à acquérir un verrou d'écriture pour INSERT/UPDATE/DELETE)
(Vous DEVEZ appeler client.close() lorsque le client n'est plus nécessaire dans les processus de courte durée — les clients ouverts maintiennent des connexions et des descripteurs de fichiers)
(Vous NE DEVEZ PAS accéder directement au fichier de base de données de réplica intégré local pendant que le client est en cours d'exécution — l'accès concurrent provoque la corruption des données)
</critical_requirements>
Auto-détection : Turso, libSQL, @libsql/client, createClient, turso.io, réplica intégré, syncUrl, syncInterval, turso db, turso group, libsql, .turso.io, TURSO_DATABASE_URL, TURSO_AUTH_TOKEN
Quand utiliser :
- Interroger une base de données Turso hébergée SQLite depuis tout environnement d'exécution (Node.js, edge, sans serveur)
- Configurer des réplicas intégrés pour des lectures locales à latence nulle synchronisées depuis un primaire distant
- SaaS multi-locataire avec une base de données par locataire (Turso supporte des millions de bases de données)
- Fonctions sans serveur/edge nécessitant une base de données sans complexité de mise en commun de connexions
- Exécuter des opérations atomiques multi-instructions avec
batch()outransaction()interactif - Gérer des groupes de bases de données et le placement multi-région via l'interface CLI Turso
Quand NE PAS utiliser :
- Charges de travail à forte écriture nécessitant une forte cohérence multi-écrivains (Turso est un seul écrivain, les écritures sont transmises au primaire)
- Requêtes relationnelles complexes nécessitant des fonctionnalités PostgreSQL (CTE avec sous-requêtes mutantes, procédures stockées, contraintes avancées)
- Transactions distribuées complexes sur plusieurs bases de données
- Grands ensembles de données analytiques (les limitations de taille de ligne et de concurrence de SQLite s'appliquent)
Ressources détaillées :
- exemples/core.md — Configuration du client, exécution, lot, transactions, chemins d'importation
- exemples/replicas-integres.md — Réplicas locaux, synchronisation, mode hors ligne, chiffrement
- reference.md — Cadres de décision, définitions de types, commandes CLI, tables de référence
Philosophie
Turso amène SQLite à la périphérie en hébergeant libSQL (un fork de SQLite) en tant que service géré avec réplication multi-région. Le pilote @libsql/client fournit une API unifiée qui fonctionne de manière identique que vous vous connectiez à une base de données distante Turso, à un fichier SQLite local, à une base de données en mémoire, ou à un réplica intégré qui se synchronise depuis un primaire distant.
Principes fondamentaux :
- Batch plutôt que transaction —
batch()envoie toutes les instructions en un seul aller-retour et les exécute dans une transaction implicite.transaction()interactif nécessite plusieurs allers-retours et maintient un verrou de base de données (délai d'attente de 5 secondes). Utilisezbatch()sauf si vous avez besoin d'une logique conditionnelle entre les requêtes. - Les écritures touchent toujours le primaire — Même avec des réplicas intégrés, les écritures sont transmises à la base de données primaire distante. La latence d'écriture est de 15 à 50 ms selon la distance par rapport à la région primaire. Concevez pour cela : interface utilisateur optimiste, synchronisation en arrière-plan, évitez les chemins chauds à forte écriture.
- Réplicas intégrés pour les lectures — Un fichier SQLite local synchronisé depuis le primaire distant. Les lectures sont au niveau de la microseconde. Les écritures sont transmises à distance. Le fichier local se met à jour après une écriture réussie (sémantique de lecture-de-vos-écritures).
- Deux chemins d'importation —
@libsql/clientinclut des liaisons SQLite natives pour Node.js et supporte les URLsfile:.@libsql/client/webest purement JS/WASM pour les environnements d'exécution edge (Cloudflare Workers, Vercel Edge Functions) et ne peut pas ouvrir de fichiers locaux. - Sémantique SQLite — Turso est SQLite. Pas de
ADD CONSTRAINT, pas de procédures stockées, pas deLISTEN/NOTIFY, mode WAL à un seul écrivain. Connaissez les limites de SQLite avant de choisir Turso.
Patrons Fondamentaux
Patron 1 : Configuration du Client
Créez un client avec createClient(). L'url détermine le type de connexion : libsql:// pour Turso distant, file: pour SQLite local (Node.js uniquement), :memory: pour en mémoire (tests). Utilisez toujours des variables d'environnement pour authToken — ne codez jamais les identifiants en dur.
Voir exemples/core.md pour les patrons de configuration complets, y compris les modules singleton et les mauvais exemples.
Patron 2 : Exécution de Requêtes
execute() exécute une seule instruction SQL. Utilisez toujours des requêtes paramétrées avec args — jamais d'interpolation de chaînes.
// Positionnel : args sous forme de tableau
await client.execute({
sql: "SELECT * FROM users WHERE id = ?",
args: [userId],
});
// Nommé : args sous forme d'objet (les noms nus correspondent à :name, @name, $name en SQL)
await client.execute({
sql: "INSERT INTO users (name, email) VALUES (:name, :email)",
args: { name, email },
});
Renvoie ResultSet avec rows (Array), columns, rowsAffected, lastInsertRowid (bigint). Voir exemples/core.md pour le mappage typé des résultats et les mauvais exemples.
Patron 3 : Opérations par Lots
batch() exécute plusieurs instructions de manière atomique en un seul aller-retour. Tout réussit ou tout est annulé. Spécifiez toujours le mode de transaction comme deuxième argument.
const results = await client.batch(
[
{ sql: "INSERT INTO users (name) VALUES (?)", args: ["Alice"] },
{
sql: "INSERT INTO audit_log (action, entity_id) VALUES (?, last_insert_rowid())",
args: ["user_created"],
},
],
"write", // Requis pour INSERT/UPDATE/DELETE
);
Utilisez "write" pour les mutations, "read" pour SELECT uniquement (permet l'exécution parallèle), "deferred" pour démarrer en lecture seule et escalader. last_insert_rowid() fonctionne entre les instructions dans le même lot. Voir exemples/core.md pour les patrons d'insertion multiple et de lot en lecture seule, et reference.md pour le tableau de comparaison des modes de transaction.
Patron 4 : Transactions Interactives
Utilisez transaction() uniquement lorsque les requêtes ultérieures dépendent des résultats des requêtes précédentes. Elle maintient un verrou de base de données (délai d'attente inactif de 5 secondes) et nécessite plusieurs allers-retours. Utilisez toujours try/catch/finally avec close().
const tx = await client.transaction("write");
try {
const { rows } = await tx.execute({
sql: "SELECT balance FROM accounts WHERE id = ?",
args: [fromId],
});
// ... logique conditionnelle basée sur les résultats ...
await tx.commit();
} catch (error) {
await tx.rollback();
throw error;
} finally {
tx.close();
}
Si toutes les instructions sont connues à l'avance sans logique conditionnelle, utilisez batch() à la place. Voir exemples/core.md pour un exemple complet d'achat avec vérification de stock.
Patron 5 : Chemins d'Importation pour Différents Environnements d'Exécution
// Node.js, Bun, Deno (a accès au système de fichiers, liaisons natives)
import { createClient } from "@libsql/client";
// Environnements d'exécution edge/sans serveur SANS système de fichiers (Cloudflare Workers, Vercel Edge)
import { createClient } from "@libsql/client/web";
Le @libsql/client de base intègre des liaisons SQLite natives qui échouent dans les environnements d'exécution edge. @libsql/client/web est purement JS/WASM mais ne peut pas ouvrir d'URLs file: locales. Voir exemples/core.md pour un exemple complet Cloudflare Worker.
Patron 6 : Réplicas Intégrés
Un fichier SQLite local qui se synchronise depuis un primaire Turso distant. Les lectures sont locales (microsecondes), les écritures sont transmises à distance (15-50 ms).
const client = createClient({
url: "file:local-replica.db",
syncUrl: process.env.TURSO_DATABASE_URL,
authToken: process.env.TURSO_AUTH_TOKEN,
syncInterval: 60, // Synchronisation automatique toutes les 60 secondes
});
await client.sync(); // Peupler le réplica local avant la première lecture
Points clés : URL file: pour le réplica local, syncUrl pour le primaire distant, appelez sync() au démarrage, les lectures sont locales, les écritures sont transmises à distance avec sémantique de lecture-de-vos-écritures.
Quand utiliser : VMs, VPS, conteneurs, ou tout processus de longue durée avec accès au système de fichiers. Non disponible dans les environnements sans serveur/edge sans système de fichiers. Voir exemples/replicas-integres.md pour les patrons complets incluant la synchronisation manuelle, le mode hors ligne et le chiffrement.
Patron 7 : Groupes de Bases de Données et Multi-Région
Turso organise les bases de données en groupes. Chaque groupe a une région primaire et des emplacements de réplica optionnels. Toutes les bases de données d'un groupe héritent de ses emplacements.
Toutes les écritures vont à la région primaire, quel que soit le réplica qui gère la lecture. L'ajout de plus d'emplacements améliore la latence de lecture globalement mais ne réduit pas la latence d'écriture. La latence d'écriture est déterminée par la distance par rapport à la région primaire.
Voir reference.md pour la référence complète des commandes CLI Turso (turso db create, turso group create, turso db shell, etc.).
<decision_framework>
Cadre de Décision
batch() vs transaction()
Toutes les instructions SQL sont-elles connues à l'avance (pas de logique conditionnelle entre elles) ?
+-- OUI --> Utilisez batch() (un seul aller-retour, transaction implicite, préféré)
+-- NON --> Les instructions ultérieures dépendent-elles des résultats des instructions précédentes ?
+-- OUI --> Utilisez transaction() (interactif, plusieurs allers-retours, maintient un verrou)
+-- NON --> Utilisez batch()
Sélection du Chemin d'Importation
Quel environnement d'exécution ?
+-- Node.js / Bun / Deno / VM / conteneur
| +-- Besoin de réplicas intégrés (fichier local) ?
| | +-- OUI --> @libsql/client avec URL file: + syncUrl
| | +-- NON --> @libsql/client avec URL libsql://
+-- Cloudflare Workers / Vercel Edge / navigateur / sans serveur sans système de fichiers
+-- @libsql/client/web (connexions distantes uniquement, pas d'URLs file:)
Réplica Intégré vs Distant Uniquement
Le processus est-il de longue durée avec accès au système de fichiers ?
+-- OUI --> Avez-vous besoin d'une latence de lecture inférieure à la milliseconde ?
| +-- OUI --> Réplica intégré (URL file: + syncUrl)
| +-- NON --> Distant uniquement est plus simple (URL libsql://)
+-- NON (sans serveur, edge, courte durée)
+-- Distant uniquement (@libsql/client/web, URL libsql://)
Sélection du Mode de Transaction
Quelles opérations le lot/la transaction va-t-il effectuer ?
+-- Uniquement des requêtes SELECT --> "read" (permet l'exécution parallèle sur les réplicas)
+-- Tout INSERT / UPDATE / DELETE --> "write" (acquiert un verrou exclusif)
+-- Incertain au moment de l'appel --> "deferred" (démarre en lecture, escalade si nécessaire)
</decision_framework>
<red_flags>
DRAPEAUX ROUGES
Problèmes de Haute Priorité :
- Mode de transaction manquant dans
batch()/transaction()— Omettre le deuxième argument par défaut à"deferred", qui démarre en lecture seule et peut échouer silencieusement à acquérir un verrou d'écriture pour INSERT/UPDATE/DELETE. Spécifiez toujours le mode explicitement. - Utilisation de
@libsql/clientdans les environnements d'exécution edge — Le paquet de base intègre des liaisons SQLite natives qui échouent dans Cloudflare Workers, Vercel Edge Functions, et environnements similaires. Utilisez@libsql/client/webà la place. - Interpolation de chaînes en SQL —
execute(\SELECT * FROM users WHERE id = '${id}'`)est une vulnérabilité d'injection SQL. Utilisez toujours des requêtes paramétrées avecargs`. - Accès au fichier de réplica intégré directement — Ouvrir le fichier
.dblocal avec un autre client SQLite pendant que le client libSQL est en cours d'exécution provoque la corruption des données. Accédez uniquement via le client.
Problèmes de Priorité Moyenne :
- Utilisation de
transaction()alors quebatch()suffit — Les transactions interactives maintiennent un verrou de base de données avec un délai d'attente de 5 secondes, nécessitent plusieurs allers-retours, et bloquent les autres écrivains. Utilisezbatch()pour les ensembles d'instructions prédéterminés. - Ne pas appeler
client.close()— Dans les processus de courte durée (scripts CLI, démontage de tests), oublier de fermer le client laisse des connexions et des descripteurs de fichiers ouverts. - Ignorer la latence d'écriture avec les réplicas intégrés — Les lectures sont en microsecondes (locales), mais les écritures sont de 15 à 50 ms (transmises au primaire distant). Concevez en conséquence — évitez les boucles d'écriture serrées.
- Définir
syncIntervaltrop bas — Chaque synchronisation tire toutes les trames modifiées (4 Ko chacune). Des intervalles inférieurs à la seconde sur des bases de données à forte écriture génèrent une surcharge réseau et d'E/S significative.
Erreurs Courantes :
- Mauvais nom de paquet — Le paquet est
@libsql/client, paslibsql-client,@turso/client, outurso-client. - Préfixe de paramètre nommé dans l'objet args — Les args utilisent des noms nus :
{ name: "Alice" }correspond à:name,@name, et$nameen SQL. N'incluez pas le préfixe :{ ":name": "Alice" }ne correspondra pas. - S'attendre à ce que
lastInsertRowidsoit un nombre — C'estbigint | undefined. Si vous avez besoin d'un nombre, convertissez explicitement :Number(result.lastInsertRowid), mais soyez conscient de la perte de précision pour les rowids très grands. - Utiliser
executeMultiple()pour des opérations atomiques —executeMultiple()exécute du texte SQL brut (séparé par des points-virgules) sans paramétrage et sans transaction implicite. Utilisezbatch()pour des opérations atomiques paramétrées.
Pièges et Cas Limites :
- Les instructions
batch()partagent une transaction mais NE sont PAS parallèles — Elles s'exécutent séquentiellement.last_insert_rowid()fonctionne entre les instructions dans le même lot, mais uniquement pour la dernière instruction qui a généré un rowid. - Les réplicas intégrés avec
syncIntervalpeuvent avoir des lectures périmées — Si le réplica n'a pas été synchronisé récemment, les lectures peuvent ne pas refléter les dernières écritures. Appelezsync()manuellement si des données exactes sont requises. @libsql/client/webne supporte pas les transactions interactives — La version web ne fournit quebatch()etexecute(). Si vous avez besoin detransaction(), vous devez utiliser le paquet de base dans un environnement avec liaisons natives.TURSO_AUTH_TOKENpeut expirer — Les tokens d'authentification Turso ont une durée de vie limitée. Rafraîchissez-les avant l'expiration ou utilisez des tokens d'accès.
</red_flags>
Anti-patrons
Anti-patron 1 : Concaténation de Chaînes pour SQL
// MAUVAIS - Vulnérabilité d'injection SQL
await client.execute(`SELECT * FROM users WHERE email = '${email}'`);
// BON - Style paramétré sécurisé
await client.execute({
sql: "SELECT * FROM users WHERE email = ?",
args: [email],
});
Anti-patron 2 : Transaction Interactif pour des Instructions Prédéterminées
// MAUVAIS - Plus lent, verrou maintien, risque de blocage
try {
const tx = await client.transaction("write");
await tx.execute({
sql: "INSERT INTO users (name) VALUES (?)",
args: [name],
});
await tx.execute({
sql: "INSERT INTO audit_log (action) VALUES (?)",
args: ["user_created"],
});
await tx.commit();
} finally {
tx.close();
}
// BON - Utilisez batch() pour un ensemble d'instructions prédéterminé
await client.batch(
[
{ sql: "INSERT INTO users (name) VALUES (?)", args: [name] },
{ sql: "INSERT INTO audit_log (action) VALUES (?)", args: ["user_created"] },
],
"write",
);
Anti-patron 3 : Ignorer le Mode de Transaction
// MAUVAIS - "deferred" est la valeur par défaut, peut échouer pour les écritures
await client.batch([
{ sql: "INSERT INTO users (name) VALUES (?)", args: ["Bob"] },
]);
// BON - Spécifiez explicitement le mode de transaction
await client.batch(
[
{ sql: "INSERT INTO users (name) VALUES (?)", args: ["Bob"] },
],
"write",
);
Anti-patron 4 : Utiliser le Mauvais Chemin d'Importation dans un Environnement Edge
// MAUVAIS - Échoue dans Cloudflare Workers : liaisons non disponibles
import { createClient } from "@libsql/client";
// BON - Version web pure JS/WASM
import { createClient } from "@libsql/client/web";
Anti-patron 5 : Code en Dur des Tokens d'Authentification
// MAUVAIS - Token exposé dans le code
const client = createClient({
url: process.env.TURSO_DATABASE_URL,
authToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
});
// BON - Utilisez des variables d'environnement
const client = createClient({
url: process.env.TURSO_DATABASE_URL,
authToken: process.env.TURSO_AUTH_TOKEN,
});
Anti-patron 6 : Oublier de Fermer le Client
async function queryUsers() {
const client = createClient({ /* ... */ });
try {
return await client.execute("SELECT * FROM users");
} finally {
// Toujours fermer dans un bloc finally
client.close();
}
}