Kysely für TypeScript: Vollständiges Tutorial zum type-safe SQL Query Builder

1. Was ist Kysely und warum braucht man es?

Kysely (ausgesprochen "ki-se-li") ist ein moderner, type-safe SQL Query Builder für TypeScript und Node.js. Er ermöglicht es, SQL-Abfragen mit vollständiger Typunterstützung zu schreiben – vom Aufbau der Query bis zur Ergebnisverarbeitung. Im Gegensatz zu traditionellen ORMs wie TypeORM oder Prisma abstrahiert Kysely SQL nicht, sondern bietet eine praktische API zum Schreiben von SQL, während die volle Kontrolle über die generierten Abfragen erhalten bleibt. Das bedeutet, dass Sie die gesamte Leistungsfähigkeit von SQL (JOINs, Subqueries, Fensterfunktionen, CTEs) nutzen können, ohne gegen die Einschränkungen eines ORMs kämpfen zu müssen.

Das Hauptproblem, das Kysely löst, ist die Typsicherheit in SQL-Abfragen. In normalem JavaScript/TypeScript-Code werden SQL-Abfragen oft als Strings geschrieben, was zu Laufzeitfehlern führt: Tippfehler in Spaltennamen, falsche Datentypen, fehlerhafte JOINs. Kysely behebt dieses Problem auf Kompilierungsebene: Wenn Sie versuchen, auf eine nicht existierende Spalte zuzugreifen oder einen falschen Datentyp zu übergeben, gibt TypeScript bereits vor dem Start der Anwendung einen Fehler aus. Das reduziert die Debugging-Zeit erheblich und erhöht die Zuverlässigkeit des Codes.

Kysely ist ideal für Projekte, die maximale Leistung und Kontrolle über SQL erfordern, aber gleichzeitig alle Vorteile der statischen Typisierung nutzen möchten. Es unterstützt PostgreSQL, MySQL, SQLite und MSSQL, bietet integrierten Schutz vor SQL-Injection (durch parametrisierte Abfragen), Unterstützung für Migrationen und Typgenerierung aus bestehenden Datenbankschemata. Die Bibliothek wird aktiv weiterentwickelt, hat eine gute Dokumentation und eine aktive Community.

2. Installation

Die Installation von Kysely erfolgt über npm (oder yarn/pnpm). Sie müssen die Bibliothek selbst sowie den Treiber für Ihre Datenbank installieren.

# Hauptpaket
npm install kysely

# Für PostgreSQL
npm install pg

# Für MySQL
npm install mysql2

# Für SQLite
npm install better-sqlite3

# Für MSSQL
npm install tedious

Wenn Sie TypeScript verwenden, stellen Sie sicher, dass die Typen für den Treiber installiert sind (normalerweise sind sie im Paket enthalten). Für eine bessere Entwicklungserfahrung empfiehlt es sich auch, ts-node zum Ausführen von TypeScript-Dateien zu installieren:

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

Für die Arbeit mit Migrationen installieren Sie zusätzlich:

npm install -D @kysely/cli

3. Schnellstart – Minimales Arbeitsbeispiel

Wir erstellen eine einfache Anwendung, die eine Verbindung zu einer SQLite-Datenbank herstellt, eine Benutzertabelle anlegt und einige Abfragen ausführt.

Zunächst definieren wir die Typen für unsere Datenbank:

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

export interface Database {
  users: User;
  // Hier können weitere Tabellen hinzugefügt werden
}

Jetzt erstellen wir die Hauptanwendung:

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

// Kysely-Instanz erstellen
const db = new Kysely<MyDatabase>({
  dialect: new SqliteDialect({
    database: new Database('my_database.db'),
  }),
});

async function main() {
  // Tabelle erstellen (falls nicht vorhanden)
  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();

  // Daten einfügen