Kysely pour TypeScript : guide complet du query builder SQL type-safe

1. Qu'est-ce que Kysely et pourquoi l'utiliser ?

Kysely (prononcé "ki-sé-li") est un query builder SQL moderne et type-safe pour TypeScript et Node.js. Il vous permet d'écrire des requêtes SQL avec une vérification de types complète, de la construction de la requête à la récupération des résultats. Contrairement aux ORM traditionnels comme TypeORM ou Prisma, Kysely n'abstrait pas SQL : il offre une API pratique pour l'écrire tout en vous laissant un contrôle total sur les requêtes générées. Cela signifie que vous pouvez exploiter toute la puissance de SQL (JOIN, sous-requêtes, fonctions de fenêtrage, CTE) sans être limité par les contraintes d'un ORM.

Le principal problème résolu par Kysely est la sécurité des types dans les requêtes SQL. Dans le code JavaScript/TypeScript classique, les requêtes SQL sont souvent écrites sous forme de chaînes de caractères, ce qui entraîne des erreurs d'exécution : fautes de frappe dans les noms de colonnes, incohérences de types de données, JOIN incorrects. Kysely résout ce problème au niveau de la compilation : si vous tentez d'accéder à une colonne inexistante ou de passer un type de données incorrect, TypeScript générera une erreur avant même l'exécution de l'application. Cela réduit considérablement le temps de débogage et améliore la fiabilité du code.

Kysely est idéal pour les projets nécessitant des performances maximales et un contrôle précis sur SQL, tout en bénéficiant des avantages du typage statique. Il prend en charge PostgreSQL, MySQL, SQLite et MSSQL, offre une protection intégrée contre les injections SQL (via des requêtes paramétrées), ainsi que la gestion des migrations et la génération de types à partir d'un schéma de base de données existant. La bibliothèque est activement développée, avec une documentation solide et une communauté dynamique.

2. Installation

L'installation de Kysely se fait via npm (ou yarn/pnpm). Vous devez installer la bibliothèque elle-même ainsi que le pilote de votre base de données.

# Paquet principal
npm install kysely

# Pour PostgreSQL
npm install pg

# Pour MySQL
npm install mysql2

# Pour SQLite
npm install better-sqlite3

# Pour MSSQL
npm install tedious

Si vous utilisez TypeScript, assurez-vous que les types pour le pilote sont installés (généralement inclus). Pour une meilleure expérience de développement, installez également ts-node pour exécuter les fichiers TypeScript :

npm install -D ts-node typescript @types/node

Pour travailler avec les migrations, installez en complément :

npm install -D @kysely/cli

3. Démarrage rapide — exemple minimal fonctionnel

Créons une application simple qui se connecte à une base de données SQLite, crée une table d'utilisateurs et exécute quelques requêtes.

Définissons d'abord les types pour notre base de données :

// types.ts
export interface User {
  id: number;
  name: string;
  email: string;
  age: number | null;
  created_at: Date;
}

export interface Database {
  users: User;
  // Ajoutez ici d'autres tables
}

Créons maintenant l'application principale :

// index.ts
import { Kysely, SqliteDialect } from 'kysely';
import Database from 'better-sqlite3';
import type { Database as MyDatabase } from './types';

// Création de l'instance Kysely
const db = new Kysely<MyDatabase>({
  dialect: new SqliteDialect({
    database: new Database('my_database.db'),
  }),
});

async function main() {
  // Création de la table (si elle n'existe pas)
  await db.schema
    .createTable('users')
    .ifNotExists()
    .addColumn('id', 'integer', (col) => col.primaryKey().autoIncrement())
    .addColumn('name', 'varchar(255)', (col) => col.notNull())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('age', 'integer')
    .addColumn('created_at', 'datetime', (col) => col.defaultTo('now()'))
    .execute();

  // Insertion de données