Communitygithub.com

Patrons Turso / libSQL

Base de données SQLite hébergée en périphérie avec pilote libSQL et réplicas intégrés

Qu'est-ce que libSQL ?

Ce jeu de compétences fournit des modèles et des directives complets pour utiliser Turso, un service de base de données SQLite en périphérie (edge), via le pilote `@libsql/client`. Il couvre la configuration du client, l'exécution de requêtes, les opérations par lots et les transactions, avec des instructions critiques pour les environnements edge sans accès au système de fichiers, où `@libsql/client/web` doit être utilisé. L'accent est mis sur l'utilisation de `batch()` plutôt que de `transaction()` pour les opérations atomiques multi-instructions, car cela réduit la latence en un seul aller-retour réseau. Les réplicas intégrés sont expliqués pour des lectures à latence nulle, avec des mises en garde importantes concernant la latence d'écriture (15 à 50 ms) et l'impossibilité d'accéder directement au fichier de réplica local pendant l'exécution du client. La compétence inclut des arbres de décision pour choisir entre les transactions par lots et interactives, sélectionner le chemin d'importation approprié, et choisir le mode de transaction (`write`, `read`, ou `deferred`), ainsi que des 'drapeaux rouges' pour éviter les erreurs courantes comme l'omission du mode de transaction ou l'utilisation par interpolation de chaînes dans les requêtes SQL.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-baas-turso

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait libSQL ?

Guide rapide : Utilisez @libsql/client pour tout accès à la base de données Turso. Utilisez execute() pour les requêtes uniques, batch() pour les opérations atomiques multi-instructions (préféré aux transactions interactives), et transaction() 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 de ALTER 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() ou transaction() 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 :

  1. 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). Utilisez batch() sauf si vous avez besoin d'une logique conditionnelle entre les requêtes.
  2. 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.
  3. 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).
  4. Deux chemins d'importation — @libsql/client inclut des liaisons SQLite natives pour Node.js et supporte les URLs file:. @libsql/client/web est purement JS/WASM pour les environnements d'exécution edge (Cloudflare Workers, Vercel Edge Functions) et ne peut pas ouvrir de fichiers locaux.
  5. Sémantique SQLite — Turso est SQLite. Pas de ADD CONSTRAINT, pas de procédures stockées, pas de LISTEN/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/client dans 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 .db local 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 que batch() 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. Utilisez batch() 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 syncInterval trop 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, pas libsql-client, @turso/client, ou turso-client.
  • Préfixe de paramètre nommé dans l'objet args — Les args utilisent des noms nus : { name: "Alice" } correspond à :name, @name, et $name en SQL. N'incluez pas le préfixe : { ":name": "Alice" } ne correspondra pas.
  • S'attendre à ce que lastInsertRowid soit un nombre — C'est bigint | 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. Utilisez batch() 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 syncInterval peuvent 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. Appelez sync() manuellement si des données exactes sont requises.
  • @libsql/client/web ne supporte pas les transactions interactives — La version web ne fournit que batch() et execute(). Si vous avez besoin de transaction(), vous devez utiliser le paquet de base dans un environnement avec liaisons natives.
  • TURSO_AUTH_TOKEN peut 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();
  }
}

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Skills associés