better-sqlite3-typescript avec TypeScript : guide complet et exemples

Dans le développement avec TypeScript, le besoin de stocker des données localement sans déployer une base de données complète est fréquent. SQLite est la solution idéale : une base de données relationnelle embarquée qui fonctionne sans serveur dédié. Cependant, la bibliothèque standard better-sqlite3 est écrite en JavaScript et ne fournit pas de typage natif. C'est là qu'intervient better-sqlite3-typescript — un wrapper qui ajoute un typage strict TypeScript à l'API synchrone de better-sqlite3.

Cette bibliothèque vous permet d'écrire du code typé sécurisé pour travailler avec SQLite, en bénéficiant de l'autocomplétion dans votre IDE, de la vérification des types à la compilation, et en réduisant les erreurs d'exécution. Vous profitez de tous les avantages de l'accès synchrone à la base de données (simplicité, prévisibilité, hautes performances) avec la puissance du système de types TypeScript.

Dans cet article, nous détaillerons l'installation, les méthodes principales, présenterons des exemples concrets et donnerons des conseils de performance. Ce contenu sera utile aussi bien aux débutants qu'aux développeurs expérimentés souhaitant utiliser SQLite efficacement dans leurs projets TypeScript.

Installation

Pour installer la bibliothèque, exécutez la commande suivante dans le terminal de votre projet :

npm install better-sqlite3-typescript better-sqlite3

Vous devrez également installer les types pour TypeScript :

npm install -D @types/better-sqlite3

Après l'installation, vous pouvez importer la bibliothèque dans votre projet :

import Database from 'better-sqlite3-typescript';

Démarrage rapide

Un exemple minimal fonctionnel pour créer une base de données, une table et insérer des données :

import Database from 'better-sqlite3-typescript';

// Créer ou ouvrir une base de données
const db = new Database('ma_base.db');

// Créer une table
db.exec(`
  CREATE TABLE IF NOT EXISTS utilisateurs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    nom TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    age INTEGER
  )
`);

// Insérer des données
const insert = db.prepare('INSERT INTO utilisateurs (nom, email, age) VALUES (?, ?, ?)');
insert.run('Alice', 'alice@exemple.com', 30);
insert.run('Bob', 'bob@exemple.com', 25);

// Lire les données
const select = db.prepare('SELECT * FROM utilisateurs');
const utilisateurs = select.all();
console.log(utilisateurs);

// Fermer la connexion
db.close();

Ce code créera un fichier ma_base.db dans le répertoire courant, créera la table utilisateurs, ajoutera deux utilisateurs et les affichera dans la console.

Méthodes et fonctions principales

Examinons les méthodes clés de la bibliothèque. Tous les exemples supposent que vous avez déjà une instance de base de données db.

1. new Database(filename, options?)

Signature : new Database(filename: string, options?: DatabaseOptions): Database

Description : Crée ou ouvre une base de données SQLite. Si le fichier n'existe pas, il est créé. Les options permettent de configurer le mode d'ouverture (lecture seule, mémoire, etc.).

Exemple :

// Ouvrir une base en mémoire (non sauvegardée sur le disque)
const memDb = new Database(':memory:');

// Ouvrir une base en mode lecture seule
const readOnlyDb = new Database('donnees.db', { readonly: true });

2. db.prepare(sql)

Signature : prepare(sql: string): Statement

Description : Compile une requête SQL en une instruction préparée. Retourne un objet Statement qui peut être exécuté plusieurs fois avec différents paramètres.

Exemple :

// Préparer une requête d'insertion
const inserer = db.prepare('INSERT INTO utilisateurs (nom, email, age) VALUES (?, ?, ?)');

// Exécuter avec différentes valeurs
inserer.run('Charlie', 'charlie@exemple.com', 28);
inserer.run('Diana', 'diana@exemple.com', 32);

3. statement.run(params?)

Signature : run(...params: any[]): RunResult

Description : Exécute l'instruction préparée et retourne un objet contenant des informations comme le nombre de lignes modifiées et le dernier ID inséré.

Exemple :

const resultat = inserer.run('Eve', 'eve@exemple.com', 35);
console.log(`Dernier ID inséré : ${resultat.lastInsertRowid}`);
console.log(`Lignes modifiées : ${resultat.changes}`);

4. statement.get(params?)

Signature : get(...params: any[]): T | undefined

Description : Exécute la requête et retourne la première ligne de résultat sous forme d'objet typé, ou undefined si aucune ligne n'est trouvée.

Exemple :

const utilisateur = db.prepare('SELECT * FROM utilisateurs WHERE id = ?').get(1);
console.log(utilisateur); // { id: 1, nom: 'Alice', email: 'alice@exemple.com', age: 30 }

5. statement.all(params?)

Signature : all(...params: any[]): T[]

Description : Exécute la requête et retourne un tableau de toutes les lignes de résultat sous forme d'objets typés.

Exemple :

const tousUtilisateurs = db.prepare('SELECT * FROM utilisateurs').all();
console.log(tousUtilisateurs); // Tableau de tous les utilisateurs

6. statement.iterate(params?)

Signature : iterate(...params: any[]): IterableIterator

Description : Retourne un itérateur pour parcourir les résultats ligne par ligne, idéal pour économiser de la mémoire avec de grands ensembles de données.

Exemple :

const iterateur = db.prepare('SELECT * FROM utilisateurs').iterate();
for (const utilisateur of iterateur) {
  console.log(utilisateur.nom);
}

7. db.transaction(fn)

Signature : transaction(fn: (...args: any[]) => T): (...args: any[]) => T

Description : Crée une fonction qui exécute son contenu dans une transaction SQLite. Si une erreur survient, toutes les modifications sont annulées. Essentiel pour garantir l'intégrité des données.

Exemple :

const transfererFonds = db.transaction((de, vers, montant) => {
  const debiter = db.prepare('UPDATE comptes SET solde = solde - ? WHERE id = ?');
  const crediter = db.prepare('UPDATE comptes SET solde = solde + ? WHERE id = ?');
  debiter.run(montant, de);
  crediter.run(montant, vers);
});

transfererFonds(1, 2, 100); // Exécuté dans une transaction

8. db.exec(sql)

Signature : exec(sql: string): void

Description : Exécute une ou plusieurs instructions SQL sans retour de résultat. Utile pour les opérations de schéma ou les scripts d'initialisation.

Exemple :

db.exec(`
  CREATE TABLE IF NOT EXISTS logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    message TEXT,
    date_creation DATETIME DEFAULT CURRENT_TIMESTAMP
  );
  CREATE INDEX idx_date ON logs(date_creation);
`);

9. db.close()

Signature : close(): void

Description : Ferme la connexion à la base de données. Toujours appeler cette méthode après avoir terminé les opérations pour libérer les ressources.

Exemple :

db.close();

Bonnes pratiques et performances

Pour tirer le meilleur parti de better-sqlite3-typescript, suivez ces recommandations :

• Utilisez des transactions pour regrouper plusieurs opérations d'écriture. Cela améliore considérablement les performances et garantit l'intégrité des données.
• Réutilisez les instructions préparées : créez une fois vos Statement et exécutez-les plusieurs fois avec des paramètres différents.
• Évitez les requêtes dans des boucles : préférez les opérations en lot ou les transactions.
• Fermez toujours la connexion avec db.close() pour éviter les fuites de mémoire.
• Utilisez le typage : définissez des interfaces TypeScript pour vos lignes de données afin de bénéficier de la vérification de type.

Conclusion

better-sqlite3-typescript est un outil puissant pour intégrer SQLite dans vos projets TypeScript avec un typage fort et une API intuitive. Sa simplicité d'utilisation, combinée à la sécurité offerte par TypeScript, en fait un choix idéal pour les applications de bureau, les outils CLI, ou tout projet nécessitant un stockage local fiable sans configuration complexe.

N'hésitez pas à consulter la documentation officielle de better-sqlite3 pour explorer des fonctionnalités avancées comme les fonctions personnalisées, les extensions ou les sauvegardes. Avec ces bases, vous êtes prêt à construire des applications robustes et performantes avec SQLite et TypeScript.