1. Was ist ts-sql-query und warum brauchst du es?

ts-sql-query ist eine leistungsstarke TypeScript-Bibliothek, mit der du SQL-Abfragen mit vollständiger Typsicherheit (type-safe) schreiben kannst. Sie bietet einen praktischen DSL (Domain-Specific Language) zum Erstellen von SQL-Abfragen, wobei jede Abfrage vom TypeScript-Compiler auf Übereinstimmung mit dem Datenbankschema geprüft wird. Das bedeutet: Fehler in Tabellen-, Feldnamen oder Datentypen werden bereits zur Kompilierzeit erkannt – nicht erst zur Laufzeit.

Warum ist das wichtig? Bei traditionellen Ansätzen (rohe SQL-Strings oder ORMs) treten häufig Probleme auf: Tippfehler in Spaltennamen, Typkonflikte oder aufwändiges Refactoring. ts-sql-query löst diese Probleme durch strenge Typisierung für alle Operationen: SELECT, INSERT, UPDATE, DELETE, JOIN, Subqueries, Aggregatfunktionen und vieles mehr. Die Bibliothek unterstützt zahlreiche Datenbanksysteme (PostgreSQL, MySQL, SQLite, MariaDB, MSSQL) und kann sowohl direkt mit Treibern als auch über Connection Pools arbeiten.

Im Gegensatz zu ORMs (wie TypeORM oder Prisma) versteckt ts-sql-query SQL nicht hinter Abstraktionen, sondern macht es zu einem integralen Bestandteil deines TypeScript-Codes. Du schreibst weiterhin SQL – aber mit Autovervollständigung, Typprüfung und ohne Risiko von SQL-Injection. Ideal für Projekte, bei denen Performance und vollständige Kontrolle über Abfragen wichtig sind, du aber gleichzeitig von statischer Typisierung profitieren möchtest.

2. Installation

Die Installation erfolgt über npm. Du benötigst die Bibliothek selbst sowie den passenden Treiber für deine Datenbank.

# Hauptbibliothek installieren
npm install ts-sql-query

# PostgreSQL-Treiber installieren (Beispiel)
npm install pg

# MySQL-Treiber installieren
npm install mysql2

# SQLite-Treiber installieren
npm install better-sqlite3

# SQLite-Treiber (asynchron)
npm install sql.js

# Node.js-Typen installieren (falls benötigt)
npm install --save-dev @types/node

Nach der Treiberinstallation musst du eine Verbindung zur Datenbank herstellen. ts-sql-query bietet dafür spezielle Adapter für jeden Treiber.

3. Schnellstart – Minimales Arbeitsbeispiel

Schauen wir uns ein Beispiel für PostgreSQL an. Wir erstellen eine einfache Tabelle users und führen eine SELECT-Abfrage aus.

import { createPool } from 'pg';
import { PostgreSqlConnection } from 'ts-sql-query/connections/PostgreSqlConnection';

// 1. Connection Pool erstellen
const pool = createPool({
    host: 'localhost',
    port: 5432,
    database: 'testdb',
    user: 'user',
    password: 'password',
});

// 2. Verbindungsklasse erstellen
class DBConnection extends PostgreSqlConnection {
    // Hier können Methoden für Tabellenoperationen definiert werden
}

// 3. Verbindungsinstanz erstellen
const connection = new DBConnection(pool);

// 4. Typ für die users-Tabelle definieren
interface User {
    id: number;
    name: string;
    email: string;
    age: number;
}

// 5. Tabellenobjekt erstellen
const users = connection.table('users').columns({
    id: 'id',
    name: 'name',
    email: 'email',
    age: 'age',
});

// 6. Abfrage ausführen
async function getUsers() {
    const query = connection
        .selectFrom(users)
        .select(users.id, users.name, users.email)
        .where(users.age.greaterThan(18))
        .orderBy(users.name, 'asc');

    const result = await query.executeSelectMany();
    return result;
}

getUsers().then(users => {
    console.log('Benutzer:', users);
}).catch(err => {
    console.error('Fehler:', err);
});

In diesem Beispiel haben wir eine Verbindung erstellt, eine Tabelle definiert und eine SELECT-Abfrage ausgeführt. Alle Typen werden vom Compiler geprüft.