Skip to content

7. Datenbankzugriff

Image

Der TypeScript-Kurs widmet dem Zugriff auf eine MySQL-Datenbank drei Kapitel: den nativen Treiber [mysql2], gefolgt von zwei ORM ([TypeORM] und [Prisma]), jeweils mit demselben Beispiel – zwei Datenbanken, [dbpersons] (eine einzelne Tabelle) und [dbschool] (vier verknüpfte Tabellen: Klassen, Schüler, Fächer und Noten). Dieses Kapitel entspricht dem ersten und fasst dann die beiden ORM-Kapitel zu einem einzigen zusammen: Dart hat kein ausgereiftes Pendant zu [TypeORM] oder [Prisma] für MySQL (siehe die Randnotiz am Ende des Kapitels), und statt eine künstliche Entsprechung zu einem von beiden zu erzwingen, bauen wir ein „leichtgewichtiges ORM“, das zeigt, was ein ORM tatsächlich leistet, indem wir es selbst schreiben.

7.1. Direkter Zugriff auf die Datenbank

Image

Das TypeScript-Paket [mysql2] hat auf der Dart-Seite kein Pendant, das vom MySQL-Team selbst gepflegt wird. Eine frühe Version dieses Kapitels verwendete [package:mysql1] (pub.dev/packages/mysql1), einen weit verbreiteten reinen Dart-Treiber für MySQL, der sich jedoch als inkompatibel mit MySQL 8.4 (der mit Laragon gelieferten Version) erwies: Selbst eine so einfache Abfrage wie „select 1“ scheiterte durchgängig mit dem Protokollfehler „Got packets out of order“, einem bekannten und ungelösten Fehler des Pakets (Issues GitHub adamlofts/mysql1_dart #112 und #161). Wir verwenden daher jetzt [package:mysql_client_plus] (pub.dev/packages/mysql_client_plus), einen aktiv gepflegten Fork, der mit MySQL 8.x getestet wurde und dessen API – [MySQLConnection.createConnection], [connection.connect], [connection.execute], [connection.close] – der von [mysql2] sehr ähnlich bleibt.

7.1.1. Vorbereitung der Datenbank [dbpersons]

Die Datenbank dbpersons enthält nur eine Tabelle, persons, die dasselbe Schema wie im Python-Kurs verwendet (Spalten id, first\_name, last\_name, age, mit einer Eindeutigkeitsbedingung für das Paar (last\_name, first\_name)). Das Skript sql/create_dbpersons.sql unten erstellt die Datenbank, den Anwendungsbenutzer und die Tabelle und fügt anschließend fünf beliebige Personen ein:

-- create_dbpersons.sql
-- Erstellt die Datenbank [dbpersons] neu, die im Kapitel "Zugriff auf MySQL mit dem
-- nativen Treiber [mysql2]" verwendet wird, mit beliebigen Daten (die Originale des
-- Python/Flask-Kurses von 2020 sind nicht mehr verfügbar).
--
-- Verwendung:
--   mysql -u root -p < create_dbpersons.sql
--
-- Erstellt die Datenbank, den Anwendungsbenutzer [admpersons/nobody] (dieselben
-- Zugangsdaten wie im ursprünglichen Kurs) und die Tabelle [persons].

DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'admpersons'@'localhost' IDENTIFIED BY 'nobody';
GRANT ALL PRIVILEGES ON dbpersons.* TO 'admpersons'@'localhost';
FLUSH PRIVILEGES;

USE dbpersons;

CREATE TABLE persons (
  id         INT PRIMARY KEY,
  first_name VARCHAR(30) NOT NULL,
  last_name  VARCHAR(30) NOT NULL,
  age        INTEGER NOT NULL,
  UNIQUE (last_name, first_name)
);

-- beliebige Daten (dieselben Personen wie in den Beispielen des ursprünglichen Kurses)
INSERT INTO persons (id, first_name, last_name, age) VALUES
  (1, 'Paul',     'Langevin', 48),
  (2, 'Sylvie',   'Lefur',    70),
  (3, 'Pierre',   'Nicazou',  35),
  (4, 'Geraldine','Colou',    26),
  (5, 'Paulette', 'Girond',   56);

Um diese Datenbank (MySQL) zu erstellen, können Sie das Laragon-Werkzeug [HeidiSQL] verwenden. Wir haben es bereits eingesetzt.

  • In [1] starten Sie alle Laragon-Dienste. Dadurch wird das DBMS MySQL gestartet;
  • in [2] rufen Sie das Datenbankverwaltungswerkzeug [HeidiSQL] auf;
  • In [1-2] melden Sie sich bei MySQL an;

Führen Sie über [1-2] nacheinander die beiden SQL-Dateien des Projekts aus:

Image

Drücken Sie weiterhin in [HeidiSQL] F5, um die Anzeige zu aktualisieren:

Wir sind nun bereit, diese beiden Datenbanken zu verwenden.

7.1.2. Skript [mysql_01]

// mysql_01.dart
// Portiert databases/mysql/mysql-01.ts.
//
// Erster Schritt: Verbindung zur MySQL-Datenbank [dbpersons] herstellen und
// wieder trennen.
//
// [technische Entscheidung] Das TypeScript-Paket [mysql2] hat auf Dart-Seite kein direktes
// Äquivalent, das vom MySQL-Team selbst gepflegt wird. Eine erste
// Version dieses Kapitels verwendete [package:mysql1] (pub.dev/packages/
// mysql1), einen weit verbreiteten reinen Dart-MySQL-Treiber - der sich aber als
// inkompatibel mit MySQL 8.4 (mit Laragon ausgeliefert) erwies: Selbst eine
// so triviale Abfrage wie "select 1" scheiterte systematisch mit dem
// Protokollfehler "Got packets out of order" (bekannter, ungelöster Fehler des
// Pakets). Hier verwenden wir daher [package:mysql_client_plus]
// (pub.dev/packages/mysql_client_plus), einen aktiv gepflegten Fork, der mit
// MySQL 8.x getestet ist und dessen API - [MySQLConnection.createConnection],
// [connection.connect], [connection.execute], [connection.close] - der von
// [mysql2] sehr ähnlich bleibt.
import 'package:mysql_client_plus/mysql_client_plus.dart';

// Verbindung zur MySQL-Datenbank [dbpersons]
// die Identität des Benutzers ist (admpersons, nobody)
const String user = 'admpersons';
const String pwd = 'nobody';
const String host = 'localhost';
const int port = 3306;
const String database = 'dbpersons';

Future<void> main() async {
  // [Unterschied zu TypeScript] hier kein Union-Typ "MySqlConnection |
  // undefined": Ein nullbares Feld ([MySQLConnection?]) spielt dieselbe
  // Rolle - "noch nicht verbunden" wird durch [null] dargestellt, genau
  // wie "noch nicht verbunden" auf der TS-Seite durch [undefined] dargestellt wurde.
  MySQLConnection? connection;
  try {
    print('Connecting to the MySQL DBMS...');
    // [Unterschied zu TypeScript] anders als mysql1 (und mysql2) trennt
    // [mysql_client_plus] die ERZEUGUNG des Verbindungsobjekts
    // ([createConnection], das noch keinen Netzwerkaustausch durchführt) von
    // dem tatsächlichen Verbindungsaufbau ([connect], das das Protokoll
    // mit dem Server aushandelt) - zwei klar getrennte Schritte, wo
    // mysql1 sie in einem einzigen Aufruf [MySqlConnection.connect] zusammenfasste.
    // Wir weisen [connection] (die nullbare Variable des [finally]-Blocks) erst
    // zu, wenn [connect] erfolgreich war: Schlägt [connect] fehl, bleibt [connection]
    // [null], und das [finally] versucht nicht, eine Verbindung zu schließen,
    // die nie wirklich geöffnet wurde.
    final newConnection = await MySQLConnection.createConnection(
      host: host,
      port: port,
      userName: user,
      password: pwd,
      databaseName: database,
    );
    await newConnection.connect();
    connection = newConnection;
    // Fortsetzung
    print(
      "Successful MySQL connection to database=$database, host=$host as user=$user, passwd=$pwd",
    );
  } catch (error) {
    // den Fehler anzeigen
    print("The following error occurred: $error");
  } finally {
    // die Verbindung schließen, falls sie geöffnet wurde
    if (connection != null) {
      await connection.close();
    }
  }
}

Kommentieren wir diesen Code:

  • Zeile 19: [import 'package:mysql_client_plus/mysql_client_plus.dart';]: der neue, vollständig in Dart geschriebene MySQL-Treiber, der [package:mysql1] ersetzt – dieses ist mit MySQL 8.4 (in Laragon enthalten) inkompatibel: Selbst eine so triviale Abfrage wie „select 1“ scheiterte durchgängig mit dem Protokollfehler „Got packets out of order“, einem bekannten und ungelösten Fehler des Pakets (siehe den Kommentar am Anfang der Datei).
  • Zeile 34: [MySQLConnection? connection;]: ein NULLABLE-Feld erfüllt exakt denselben Zweck wie der Union-Typ [MySqlConnection | undefined] in TypeScript – [null] steht für „noch nicht verbunden“, genau wie [undefined] in TS.
  • Zeilen 47–55: [final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]: [mysql_client_plus] trennt das ERSTELLEN des Verbindungsobjekts ([createConnection], das noch keinen Netzwerkverkehr verursacht) vom tatsächlichen Verbindungsaufbau ([connect], das das Protokoll mit dem Server aushandelt) – zwei getrennte Schritte, während [mysql1] (wie [mysql2] auf der TypeScript-Seite) sie in einem einzigen Aufruf zusammenfasste. [connection] (die nullable Variable aus [finally]) wird erst zugewiesen, nachdem [connect] erfolgreich war, sodass [finally] nie eine Verbindung schließt, die gar nicht geöffnet wurde.
  • [try] / [catch] / [finally]: identische Struktur wie in der vorherigen Version – die Verbindung wird in [finally] immer geschlossen, unabhängig davon, ob ein Fehler aufgetreten ist.

Das Ergebnis der Ausführung lautet:

Connecting to the MySQL DBMS...
Successful MySQL connection to database=dbpersons, host=localhost as user=admpersons, passwd=nobody

7.1.3. Skript [mysql_02]

// mysql_02.dart
// Portiert databases/mysql/mysql-02.ts.
//
// In diesem neuen Skript ist die Datenbankverbindung in eine
// Funktion ausgelagert.
import 'package:mysql_client_plus/mysql_client_plus.dart';

// verbindet sich (login, pwd) mit der Datenbank [database] auf dem Server
// [host] und trennt sich dann wieder; wirft eine Exception, wenn es ein Problem gibt
Future<void> connect(String host, int port, String database, String login, String pwd) async {
  MySQLConnection? cnx;
  try {
    // Verbindung - [createConnection] erzeugt das Objekt, [connect] handelt
    // wirklich mit dem Server aus (siehe den Kommentar in mysql_01.dart); wir
    // weisen [cnx] erst nach erfolgreichem [connect] zu, damit das [finally]
    // nie eine Verbindung schließt, die nicht zustande kam
    final newConnection = await MySQLConnection.createConnection(
      host: host,
      port: port,
      userName: login,
      password: pwd,
      databaseName: database,
    );
    await newConnection.connect();
    cnx = newConnection;
    print(
      "Successful connection to database=$database, host=$host as user=$login, passwd=$pwd",
    );
  } finally {
    // die Verbindung schließen, falls sie geöffnet wurde
    if (cnx != null) {
      await cnx.close();
      print('Successful disconnection\n');
    }
  }
}

// —————————————————————————————— main
// Zugangsdaten für die Verbindung
const String user = 'admpersons';
const String passwd = 'nobody';
const String host = 'localhost';
const int port = 3306;
const String database = 'dbpersons';

Future<void> main() async {
  // Verbindung eines vorhandenen Benutzers
  try {
    await connect(host, port, database, user, passwd);
  } catch (error) {
    // den Fehler anzeigen
    print('$error');
  }

  // Verbindung eines nicht vorhandenen Benutzers
  try {
    await connect(host, port, database, 'xx', 'xx');
  } catch (error) {
    // den Fehler anzeigen
    print('$error');
  }
}

Kommentieren wir diesen Code:

  • Zeilen 10–36: [Future<void> connect(String host, int port, String database, String login, String pwd) async { ... }]: Die Verbindung ist in einer wiederverwendbaren Funktion gekapselt, die im Fehlerfall eine Ausnahme auslöst, statt sie selbst abzufangen – der Aufrufer entscheidet, was damit geschieht. Sie verwendet das Muster „Erstellen + [connect()]“ aus [mysql_01.dart] wieder: [cnx] wird erst nach erfolgreichem [connect] zugewiesen.
  • Zeile 43: [const int port = 3306;]: [mysql_client_plus] verlangt einen EXPLIZITEN Port ([createConnection]), während [ConnectionSettings] bei [mysql1] den Standardport (3306) selbst ableitete.
  • [main] ruft diese Funktion zweimal in zwei getrennten Blöcken [try] und [catch] auf: einmal mit gültigen und einmal mit ungültigen Zugangsdaten, um beide Pfade zu veranschaulichen.

Das Ergebnis der Ausführung lautet:

1
2
3
4
Successful connection to database=dbpersons, host=localhost as user=admpersons, passwd=nobody
Successful disconnection

MySQLServerException [1045]: Access denied for user 'xx'@'localhost' (using password: YES)

7.1.4. Skript [mysql_03]

// mysql_03.dart
// Portiert databases/mysql/mysql-03.ts.
//
// Nachdem wir nun wissen, wie man sich verbindet, senden wir SQL-Anweisungen über die
// Verbindung: Wir erstellen die Tabelle [persons] der Datenbank [dbpersons] (neu).
import 'dart:io';
import 'package:mysql_client_plus/mysql_client_plus.dart';

// führt eine Update-Abfrage über die Verbindung aus
Future<void> executeSql(MySQLConnection connection, String query) async {
  await connection.execute(query);
}

// —————————————————————————————— main
// Zugangsdaten für die Verbindung
const String id = 'admpersons';
const String pwd = 'nobody';
const String host = 'localhost';
const int port = 3306;
const String database = 'dbpersons';

Future<void> main() async {
  // wir gehen Schritt für Schritt vor
  late final MySQLConnection connection;
  try {
    // Verbindung - [package:mysql_client_plus] führt, wie mysql1 vor ihm,
    // standardmäßig jede Abfrage in einer eigenen automatisch committeten
    // Transaktion aus (Äquivalent zu AUTOCOMMIT=True auf der Python-Seite)
    connection = await MySQLConnection.createConnection(
      host: host,
      port: port,
      userName: id,
      password: pwd,
      databaseName: database,
    );
    await connection.connect();
  } catch (error) {
    print("The following error occurred: $error");
    // [Unterschied zu TypeScript] `process.exit(1)` wird zu `exit(1)`
    // (dart:io) - gleiche Semantik, gleicher Exit-Code des Prozesses
    exit(1);
  }

  // Löschen der Tabelle persons, falls sie existiert
  // existiert sie nicht, tritt ein Fehler auf - wir ignorieren ihn
  try {
    await executeSql(connection, 'drop table persons');
  } catch (_) {
    // ignoriert - das [_] besagt, dass uns der Wert der Exception egal ist
  }

  // Erstellen der Tabelle persons
  const query = 'create table persons (id int PRIMARY KEY, first_name varchar(30) NOT NULL, last_name varchar(30) NOT NULL, '
      'age integer NOT NULL, unique(last_name,first_name))';
  try {
    await executeSql(connection, query);
    print('$query: query succeeded');
  } catch (error) {
    print("The following error occurred: $error");
  } finally {
    await connection.close();
  }
}

Kommentieren wir diesen Code:

  • Zeilen 10–12: [Future<void> executeSql(MySQLConnection connection, String query) async { await connection.execute(query); }]: eine Hilfsfunktion zum Ausführen eines SQL-Änderungsbefehls (hier ein DROP TABLE gefolgt von einem CREATE TABLE) – [connection.execute(...)] ersetzt [connection.query(...)] aus [mysql1] (gleiche Aufgabe, neuer Methodenname auf der Seite von [mysql_client_plus]).
  • Zeile 41: [exit(1);] (aus [dart:io]): Äquivalent zu [process.exit(1)] – gleiche Semantik, gleicher Prozess-Exitcode bei einem Verbindungsfehler.
  • Zeile 47: [try { await executeSql(connection, 'drop table persons'); } catch (_) {}]: Dass [_] als Parameter an [catch] übergeben wird, zeigt an, dass der Wert der Ausnahme ignoriert wird – die Tabelle existiert möglicherweise einfach noch nicht.

Das Ergebnis der Ausführung lautet:

create table persons (id int PRIMARY KEY, first_name varchar(30) NOT NULL, last_name varchar(30) NOT NULL, age integer NOT NULL, unique(last_name,first_name)): query succeeded

7.1.5. Skript [config_04]

// config_04.dart
// Portiert databases/mysql/config-04.ts.
//
// Konfiguration des Skripts [mysql_04]: Pfad der Datei mit den SQL-Befehlen
// und Zugangsdaten für die Datenbank [dbpersons].
//
// [Unterschied zu TypeScript] config-04.ts findet den Ordner des Skripts mit
// `dirname(fileURLToPath(import.meta.url))`. Dart hat ein direktes und
// kürzeres Äquivalent: [Platform.script] (dart:io) ist bereits die
// URI des laufenden Skripts - wir lösen einfach einen relativen Pfad dagegen
// mit [.resolve(...)] auf, ohne Stringverarbeitung. Nuance:
// [Platform.script] bezeichnet das HAUPTSKRIPT, das von `dart run` gestartet wird
// (mysql_04.dart), nicht diese Datei - anders als `import.meta.url`,
// das für jede Datei spezifisch ist. Das Ergebnis ist hier identisch, da
// config_04.dart und mysql_04.dart im selben Ordner liegen.
import 'dart:io';

class Config {
  final String commandsFilename;
  final String host;
  // [Migration zu mysql_client_plus] anders als bei mysql1, dessen
  // [ConnectionSettings] den Standardport (3306) selbst ableitete,
  // verlangt [MySQLConnection.createConnection] einen EXPLIZITEN Port - daher
  // fügen wir ihn hier der Konfiguration hinzu.
  final int port;
  final String database;
  final String user;
  final String password;

  const Config({
    required this.commandsFilename,
    required this.host,
    required this.port,
    required this.database,
    required this.user,
    required this.password,
  });
}

Config configure() {
  return Config(
    // Datei mit SQL-Befehlen, relativ zu DIESER Datei aufgelöst
    commandsFilename: Platform.script.resolve('data/commands.sql').toFilePath(),
    // Zugangsdaten für die Datenbankverbindung
    host: 'localhost',
    port: 3306,
    database: 'dbpersons',
    user: 'admpersons',
    password: 'nobody',
  );
}

Analysieren wir diesen Code:

  • Zeile 43: [Platform.script.resolve('data/commands.sql').toFilePath()] (aus [dart:io]): das direkte und kürzere Äquivalent zu [dirname(fileURLToPath(import.meta.url))] in TypeScript – [Platform.script] ist bereits die URI des gerade ausgeführten Skripts; es genügt, darin einen relativen Pfad aufzulösen.
  • Wichtiger Hinweis: [Platform.script] bezeichnet das HAUPTSKRIPT, das von [dart run] gestartet wurde (hier [mysql_04.dart]), nicht unbedingt die Datei, in der der Ausdruck steht – anders als [import.meta.url], das für jede Datei eigen ist. Das Ergebnis ist hier dennoch korrekt, da [config_04.dart] und [mysql_04.dart] im selben Ordner liegen.
  • Zeilen 18–28: [class Config { final String commandsFilename; ...; final int port; ...; const Config({required this... }); }]: eine unveränderliche Klasse zur Bündelung der Konfiguration, wie das Interface [Config] der TypeScript-Version – mit einem zusätzlichen Feld [port], das von [MySQLConnection.createConnection] ausdrücklich verlangt wird (während [ConnectionSettings] aus [mysql1] den Standardport 3306 automatisch ableitete).

7.1.6. Skript [mysql_module]

// mysql_module.dart
// Portiert databases/mysql/mysql-module.ts: wiederverwendbare Funktionen, um
// eine Liste (oder eine Datei) von SQL-Befehlen auf einer offenen MySQL-
// Verbindung auszuführen.
//
// [Migration] Diese Datei verwendete anfangs [package:mysql1], das sich als
// inkompatibel mit MySQL 8.4 erwies (siehe den Kommentar in pubspec.yaml). Sie wurde
// auf [package:mysql_client_plus] portiert - siehe unten den Unterschied,
// den das für die Transaktionsbehandlung bedeutet.
import 'dart:io';
import 'package:mysql_client_plus/mysql_client_plus.dart';

// zeigt das Ergebnis eines SQL-Befehls an (Ergebnis eines execute() von
// mysql_client_plus)
// - wenn [results.cols] nicht leer ist, war es ein SELECT: wir zeigen die
//   Spalten, dann die Zeilen an;
// - andernfalls war es eine Update-Anweisung (INSERT/UPDATE/DELETE/DDL): wir
//   zeigen die Anzahl der geänderten Zeilen an ([results.affectedRows],
//   Äquivalent zum [rowcount] eines Cursors).
void _displayInfo(IResultSet results) {
  if (results.cols.isNotEmpty) {
    // es war ein SELECT - [cols] beschreibt die angeforderten Spalten
    final titles = results.cols.map((c) => c.name).toList();
    final header = titles.join(', ');
    print(header);
    print('*' * header.length);
    for (final row in results.rows) {
      print(titles.map((t) => row.colByName(t)).toList());
    }
    print('*' * header.length);
  } else {
    // keine beschriebenen Spalten - Update-Anweisung
    print('number of modified rows: ${results.affectedRows}');
  }
}

// verwendet die offene Verbindung [connection]
// führt auf dieser Verbindung die SQL-Befehle aus der Liste
// [sqlCommands] aus (ein Befehl pro Element; leere Zeilen oder Zeilen,
// die mit # beginnen, werden ignoriert)
// - bei verbose=true folgt auf jede Ausführung einer SQL-Anweisung eine
//   Anzeige, die Erfolg oder Fehlschlag angibt;
// - bei stop=true hält die Funktion beim 1. aufgetretenen Fehler an,
//   andernfalls führt sie alle Befehle aus;
// - bei withTransaction=true macht jeder Fehler alle zuvor ausgeführten
//   SQL-Anweisungen rückgängig (Rollback); andernfalls wird jeder Befehl
//   einzeln committet (Standardverhalten von MySQL, im AUTOCOMMIT);
// die Funktion liefert eine Liste [error1, error2, ...]
//
// [Unterschied zu TypeScript] mysql2 stellt direkt
// `connection.beginTransaction()/commit()/rollback()` bereit. [package:mysql1]
// (in einer ersten Version dieser Datei verwendet) stellte diese
// Methoden nicht einzeln bereit: Die Transaktion musste "von Hand" gesteuert werden,
// indem wir die SQL-Anweisungen [START TRANSACTION], [COMMIT] und
// [ROLLBACK] selbst sendeten. [package:mysql_client_plus] bringt schließlich das direkte Äquivalent
// von mysql2: `connection.transactional<T>((cnx) async { ... })` führt den
// Callback in einer Transaktion aus, committet (COMMIT) automatisch, wenn er
// normal endet, und macht automatisch rückgängig (ROLLBACK), wenn er eine
// Exception auslöst - keine SQL-Anweisungen zur Transaktionssteuerung mehr, die wir
// selbst schreiben müssten.
Future<List<String>> executeListOfCommands(
  MySQLConnection connection,
  List<String> sqlCommands, {
  bool verbose = false,
  bool stop = true,
  bool withTransaction = true,
}) async {
  final errors = <String>[];

  // führt die Befehle tatsächlich auf der übergebenen Verbindung [cnx] aus: Das ist
  // entweder [connection] selbst (ohne Transaktion) oder die "Arbeits"-
  // Verbindung, die [transactional] seinem Callback übergibt (mit
  // Transaktion) - die Schleife wird nur einmal für beide Fälle geschrieben
  Future<void> executeCommands(MySQLConnection cnx) async {
    for (final rawCommand in sqlCommands) {
      // führende und nachgestellte Leerzeichen des aktuellen Befehls entfernen
      final command = rawCommand.trim();
      // leerer Befehl oder Kommentar? weiter zum nächsten
      if (command == '' || command[0] == '#') {
        continue;
      }
      // Ausführung des aktuellen Befehls
      try {
        final results = await cnx.execute(command);
        // kein Fehler
        if (verbose) {
          print('[$command]: Successful execution');
        }
        _displayInfo(results);
      } catch (error) {
        final msg = '$command: Error ($error)';
        errors.add(msg);
        if (verbose) {
          print(msg);
        }
        // halten wir an?
        if (withTransaction || stop) {
          // mit Transaktion: wir werfen den Fehler erneut, damit
          // [connection.transactional] das ROLLBACK auslöst - bei
          // [package:mysql_client_plus] steuert die EXCEPTION
          // den Abbruch, nicht ein bloßes Verlassen der Schleife wie beim
          // manuellen ROLLBACK der mysql1-Version
          if (withTransaction) rethrow;
          return;
        }
      }
    }
  }

  if (withTransaction) {
    try {
      await connection.transactional((cnx) => executeCommands(cnx));
    } catch (_) {
      // der Fehler wurde oben bereits in [errors] erfasst; wir
      // schlucken ihn hier, um die Liste der Fehler normal an den
      // Aufrufer zurückzugeben, genau wie es die mysql1-Version tat (die nie
      // eine Exception aus dieser Funktion entweichen ließ)
    }
  } else {
    await executeCommands(connection);
  }
  return errors;
}

// verwendet die offene Verbindung [connection]
// führt auf dieser Verbindung die SQL-Befehle aus der
// Textdatei [sqlFilename] aus (ein Befehl pro Zeile)
Future<List<String>> executeFileOfCommands(
  MySQLConnection connection,
  String sqlFilename, {
  bool verbose = false,
  bool stop = true,
  bool withTransaction = true,
}) async {
  try {
    final content = await File(sqlFilename).readAsString();
    return await executeListOfCommands(
      connection,
      content.split('\n'),
      verbose: verbose,
      stop: stop,
      withTransaction: withTransaction,
    );
  } catch (error) {
    return ["The file $sqlFilename could not be processed: $error"];
  }
}

Kommentieren wir diesen Code:

  • Zeile 20: [void _displayInfo(IResultSet results)]: unterscheidet ein SELECT ([results.cols] beschreibt die angeforderten Spalten) von einer Änderungsanweisung ([results.affectedRows], Äquivalent zu [rowcount] bei einem Cursor) – [results.cols]/[results.rows] ersetzen [results.fields] aus [mysql1], und [row.colByName(t)] ersetzt den Zugriff [row.fields[t]].
  • Zeilen 61–67: [Future<List<String>> executeListOfCommands(MySQLConnection connection, List<String> sqlCommands, {bool verbose = false, bool stop = true, bool withTransaction = true}) async { ... }]: BENANNTE PARAMETER mit Standardwerten, unverändert gegenüber der Version mit [mysql1] – genau wie die optionalen Parameter des TypeScript-Konfigurationsobjekts.
  • Zeilen 74–108: [Future<void> executeCommands(MySQLConnection cnx) async { ... }]: eine (verschachtelte) LOKALE Funktion, die sowohl für den Fall „mit Transaktion“ (hier erhält sie die Arbeitsverbindung, die [transactional] ihrem Callback übergibt) als auch für den Fall „ohne Transaktion“ (hier erhält sie direkt [connection]) wiederverwendet wird – so wird die Schleife zur Befehlsausführung nur einmal geschrieben. Bei einer Transaktion löst eine erneut geworfene AUSNAHME ([rethrow]) das ROLLBACK aus, statt eines einfachen Schleifenabbruchs wie beim manuellen ROLLBACK in der Version mit [mysql1].
  • Zeilen 110–118: [if (withTransaction) { try { await connection.transactional((cnx) => executeCommands(cnx)); } catch (_) { ... } }]: [mysql2] stellt [connection.beginTransaction()]/[commit()]/[rollback()] direkt bereit. [package:mysql1] stellte diese Methoden nicht einzeln bereit: Man musste die Transaktion „manuell“ steuern, indem man die SQL-Befehle [START TRANSACTION], [COMMIT] und [ROLLBACK] selbst sendete. [package:mysql_client_plus] bietet schließlich das direkte Äquivalent zu [mysql2]: [connection.transactional((cnx) async { ... })] führt den Callback innerhalb einer Transaktion aus, bestätigt sie automatisch (COMMIT), wenn er normal endet, und macht sie automatisch rückgängig (ROLLBACK), wenn er eine Ausnahme auslöst – eigene SQL-Anweisungen zur Transaktionssteuerung sind nicht mehr nötig.
  • Zeilen 128–134: [Future<List<String>> executeFileOfCommands(...) async { ... }]: liest eine Datei ([File(sqlFilename).readAsString()]) und delegiert dann an [executeListOfCommands] – unverändert gegenüber der Version mit [mysql1], gleiche Struktur wie in TypeScript.

7.1.7. Skript [mysql_04]

Dieses Hauptskript koordiniert die beiden vorherigen Skripte, um die Datei [data/commands.sql] (identisch mit dem TypeScript-Kurs) auszuführen, je nach übergebenem Kommandozeilenargument mit oder ohne Transaktion.

// mysql_04.dart
// Portiert databases/mysql/mysql-04.ts.
//
// Hauptskript: führt die Datei mit SQL-Befehlen
// [data/commands.sql] aus, mit oder ohne Transaktion, je nach dem in der
// Kommandozeile übergebenen Argument.
//   dart run mysql_04.dart true   (mit Transaktion)
//   dart run mysql_04.dart false  (ohne Transaktion)
import 'dart:io';
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'config_04.dart';
import 'mysql_module.dart';

Future<void> main(List<String> arguments) async {
  final config = configure();

  // —————————————————————————————— main
  // Prüfung der Aufrufsyntax
  bool error = arguments.length != 1;
  String withTransactionText = '';
  if (!error) {
    withTransactionText = arguments[0].toLowerCase();
    error = withTransactionText != 'true' && withTransactionText != 'false';
  }
  if (error) {
    print('syntax: dart run mysql_04.dart true / false');
    exit(1);
  }

  // Berechnung eines Textes
  final withTransaction = withTransactionText == 'true';
  final text = withTransaction ? 'with transaction' : 'without transaction';

  // Bildschirmprotokolle
  print('--------------------------------------------------------------------');
  print('Executing the SQL file ${config.commandsFilename} $text');
  print('--------------------------------------------------------------------');

  // Ausführung der SQL-Anweisungen der Datei
  MySQLConnection? connection;
  List<String> errors = [];
  try {
    // Verbindung zur Datenbank - wir weisen [connection] erst zu, wenn [connect]
    // erfolgreich war (siehe den Kommentar in mysql_01.dart)
    final newConnection = await MySQLConnection.createConnection(
      host: config.host,
      port: config.port,
      userName: config.user,
      password: config.password,
      databaseName: config.database,
    );
    await newConnection.connect();
    connection = newConnection;
    // Ausführung der Datei mit SQL-Befehlen
    errors = await executeFileOfCommands(
      connection,
      config.commandsFilename,
      verbose: true,
      stop: false,
      withTransaction: withTransaction,
    );
  } catch (fatalError) {
    print("The following fatal error occurred: $fatalError");
    exit(1);
  } finally {
    if (connection != null) {
      await connection.close();
    }
  }

  // Anzeige der Anzahl der Fehler
  print('--------------------------------------------------------------------');
  print('Execution completed');
  print('--------------------------------------------------------------------');
  print('There were ${errors.length} error(s)');
  for (final currentError in errors) {
    print(currentError);
  }
}

Kommentieren wir diesen Code:

  • Zeilen 14–28: [Future<void> main(List<String> arguments) async { ... }]: [arguments] empfängt die Parameter der Kommandozeile, genau wie [process.argv.slice(2)] auf der Node-Seite – hier wird ein einziges Argument erwartet: [true] oder [false].
  • Zeilen 45–53: [final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]: Die Verbindung folgt demselben Erstellungsmuster wie [connect()], wie in [mysql_01.dart] gezeigt, mit Parametern aus [config] (einschließlich des neuen Felds [port]).
  • Zeilen 55–61: [executeFileOfCommands(connection, config.commandsFilename, verbose: true, stop: false, withTransaction: withTransaction)]: Führt [data/commands.sql] je nach Argument mit oder ohne Transaktion aus – [dart run mysql_04.dart true] oder [dart run mysql_04.dart false].

Hier zwei mögliche Ausführungen:

dart run mysql_04.dart true
[insert into persons(first_name, last_name, age) values ('Sylvie','Lefur',70)]: Successful execution
number of modified rows: 1
[select first_name, last_name, age from persons]: Successful execution
first_name, last_name, age
**************************
[Paul, Langevin, 48]
[Sylvie, Lefur, 70]
**************************
xx: Error (MySQLServerException [1064]: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'xx' at line 1)
--------------------------------------------------------------------
Execution completed
--------------------------------------------------------------------
There were 1 error(s)
xx: Error (MySQLServerException [1064]: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'xx' at line 1)
dart run mysql_04.dart false
Executing the SQL file C:\Data\st-2026\dev\dart-sept-2026-scripts\dart-databases\mysql\data\commands.sql without transaction
--------------------------------------------------------------------
[drop table persons]: Successful execution
number of modified rows: 0
[create table persons (first_name varchar(30) not null, last_name varchar(30) not null, age integer not null, primary key (last_name,first_name))]: Successful execution
number of modified rows: 0
[insert into persons(first_name, last_name, age) values('Paul','Langevin',48)]: Successful execution
number of modified rows: 1
[insert into persons(first_name, last_name, age) values ('Sylvie','Lefur',70)]: Successful execution
number of modified rows: 1
[select first_name, last_name, age from persons]: Successful execution
first_name, last_name, age
**************************
[Paul, Langevin, 48]
[Sylvie, Lefur, 70]
**************************
xx: Error (MySQLServerException [1064]: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'xx' at line 1)
[insert into persons(first_name, last_name, age) values ('Pierre','Nicazou',35)]: Successful execution
number of modified rows: 1
[insert into persons(first_name, last_name, age) values ('Geraldine','Colou',26)]: Successful execution
number of modified rows: 1
[insert into persons(first_name, last_name, age) values ('Paulette','Girond',56)]: Successful execution
number of modified rows: 1
[select first_name, last_name, age from persons]: Successful execution
first_name, last_name, age
**************************
[Geraldine, Colou, 26]
[Paulette, Girond, 56]
[Paul, Langevin, 48]
[Sylvie, Lefur, 70]
[Pierre, Nicazou, 35]
**************************
[select last_name,first_name from persons order by last_name asc, first_name desc]: Successful execution
last_name, first_name
*********************
[Colou, Geraldine]
[Girond, Paulette]
[Langevin, Paul]
[Lefur, Sylvie]
[Nicazou, Pierre]
*********************
[select last_name,first_name,age from persons where age between 20 and 40 order by age desc, last_name asc, first_name asc]: Successful execution
last_name, first_name, age
**************************
[Nicazou, Pierre, 35]
[Colou, Geraldine, 26]
**************************
[insert into persons(first_name, last_name, age) values('Josette','Bruneau',46)]: Successful execution
number of modified rows: 1
[update persons set age=47 where last_name='Bruneau']: Successful execution
number of modified rows: 1
[select last_name,first_name,age from persons where last_name='Bruneau']: Successful execution
last_name, first_name, age
**************************
[Bruneau, Josette, 47]
**************************
[delete from persons where last_name='Bruneau']: Successful execution
number of modified rows: 1
[select last_name,first_name,age from persons where last_name='Bruneau']: Successful execution
last_name, first_name, age
**************************
**************************
--------------------------------------------------------------------
Execution completed
--------------------------------------------------------------------
There were 1 error(s)
xx: Error (MySQLServerException [1064]: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'xx' at line 1)

7.1.8. Skript [mysql_05]

// mysql_05.dart
// Portiert databases/mysql/mysql-05.ts.
//
// Parametrisierte Abfragen: einzelnes vorbereitetes Einfügen, dann
// Masseneinfügung. Hier erstellen wir die Tabelle [persons] mit dem Schema mit der Spalte [id] neu
// (wie im Skript mysql_03), damit dieses Skript unabhängig ist vom
// Zustand, den mysql_04 hinterlassen hat.
import 'package:mysql_client_plus/mysql_client_plus.dart';

// die Identität des Benutzers
const String id = 'admpersons';
const String pwd = 'nobody';
// der Rechner des DBMS
const String host = 'localhost';
const int port = 3306;
// Identität der Datenbank
const String database = 'dbpersons';

// [Unterschied zu TypeScript] `type Person = [id: number, lastName: string,
// firstName: string, age: number]` (ein TypeScript-Tupel, benannt, aber zur Laufzeit
// dennoch ein einfaches Array) wird hier zu einem POSITIONALEN Dart-3-RECORD
// (siehe dart-fundamentals/dart3/dart3_01_records.dart): dieselbe Idee einer
// "kleinen Gruppe typisierter Werte, ohne eine Klasse zu schreiben", aber ein echter
// eigener Typ, verschieden von einer [List].
typedef Person = (int id, String lastName, String firstName, int age);

Future<void> main() async {
  // Liste von Personen (id, lastName, firstName, age)
  final persons = <Person>[
    for (var i = 0; i < 5; i++) (i, 'l0$i', 'f0$i', i + 10),
    (40, "d'Aboot", "Y'éna", 18),
  ];

  // eine weitere Liste von Personen
  final otherPersons = <Person>[
    for (var i = 0; i < 5; i++) (i + 100, 'l1$i', 'f1$i', i + 20),
    (200, "d'Aboot", "F'ilhem", 34),
  ];

  // Zugriff auf das DBMS
  MySQLConnection? connection;
  try {
    // Verbindung - wir weisen [connection] erst zu, wenn [connect] erfolgreich war
    // (siehe den Kommentar in mysql_01.dart)
    final newConnection = await MySQLConnection.createConnection(
      host: host,
      port: port,
      userName: id,
      password: pwd,
      databaseName: database,
    );
    await newConnection.connect();
    connection = newConnection;

    // (Neu-)Erstellung der Tabelle mit dem Schema mit der Spalte [id] (siehe mysql_03)
    await connection.execute('drop table if exists persons');
    await connection.execute(
      'create table persons (id int PRIMARY KEY, first_name varchar(30) NOT NULL, last_name varchar(30) NOT NULL, '
      'age integer NOT NULL, unique(last_name,first_name))',
    );

    // Löschen der vorhandenen Datensätze
    await connection.execute('delete from persons');
    // Einfügen Person für Person mit einer parametrisierten Abfrage -
    // Destrukturierung des positionalen Records [person] direkt im
    // Kopf der for-Schleife (siehe dart-fundamentals/dart3/dart3_02_patterns.dart)
    //
    // [Unterschied zu TypeScript und zu mysql1] mysql2 (und mysql1, in
    // einer ersten Version dieses Skripts) verwenden POSITIONALE
    // PLATZHALTER ("?", einer LISTE von Werten in derselben
    // Reihenfolge zugeordnet). [package:mysql_client_plus] arbeitet anders: Die
    // Platzhalter sind BENANNT (":id", ":last_name"...) und einer [Map]
    // (Platzhaltername -> Wert) zugeordnet - hier aufwendiger zu schreiben, aber
    // so wird jede Abfrage unabhängig von der REIHENFOLGE der Parameter.
    for (final (idP, lastName, firstName, age) in persons) {
      await connection.execute(
        'insert into persons(id,last_name,first_name,age) values(:id,:last_name,:first_name,:age)',
        {'id': idP, 'last_name': lastName, 'first_name': firstName, 'age': age},
      );
    }
    // [Unterschied zu TypeScript] mysql2 bietet
    // `connection.query('insert ... values ?', [[[...],[...],...]])`, das
    // aus einem Array von Arrays selbst eine einzige Abfrage mit mehreren Zeilen baut.
    // [package:mysql_client_plus] hat kein solches Äquivalent (wie
    // mysql1 vor ihm): Wir bauen den SQL-Text also selbst, mit einer Gruppe
    // BENANNTER Platzhalter pro Zeile (":id0",
    // ":last_name0"... ":id1", ":last_name1"...), da benannte Platzhalter
    // in derselben Abfrage nicht wiederholt werden können - ein einziger Netzwerk-
    // Roundtrip, wie in der TypeScript-Version.
    final placeholderGroups = <String>[];
    final values = <String, Object?>{};
    for (var i = 0; i < otherPersons.length; i++) {
      final (idP, lastName, firstName, age) = otherPersons[i];
      placeholderGroups.add('(:id$i,:last_name$i,:first_name$i,:age$i)');
      values['id$i'] = idP;
      values['last_name$i'] = lastName;
      values['first_name$i'] = firstName;
      values['age$i'] = age;
    }
    await connection.execute(
      'insert into persons(id,last_name,first_name,age) values ${placeholderGroups.join(',')}',
      values,
    );

    // Commit der Transaktion - hier wurde jede Abfrage bereits automatisch
    // committet (MySQL ist standardmäßig im AUTOCOMMIT-Modus, wie der im
    // Skript mysql_03 erwähnte Standardmodus); es gibt also nichts
    // explizit zu committen
    print('${persons.length + otherPersons.length} persons inserted.');
  } catch (error) {
    print("The following error occurred: $error");
  } finally {
    if (connection != null) {
      await connection.close();
    }
  }
}

Kommentieren wir diesen Code:

  • Zeile 25: [typedef Person = (int id, String lastName, String firstName, int age);]: das TypeScript-Tupel mit dem Namen [type Person = [id: number, lastName: string, firstName: string, age: number]] (zur Laufzeit ein einfaches Array) wird in Dart 3 zu einem POSITIONALEN RECORD – ein vollwertiger eigener Typ, verschieden von einer [List].
  • Zeilen 75–80: [for (final (idP, lastName, firstName, age) in persons) { await connection.execute('insert into persons(id,last_name,first_name,age) values(:id,:last_name,:first_name,:age)', {'id': idP, 'last_name': lastName, 'first_name': firstName, 'age': age}); }]: Jedes vorbereitete Einfügen zerlegt den positionalen Record direkt im Kopf der [for]-Schleife (siehe das Kapitel „Neuerungen in Dart“ 3.x) – mit BENANNTEN Platzhaltern ([:id], [:last_name] ...), die einer [Map] zugeordnet sind, statt der POSITIONALEN Platzhalter ([?] plus Werteliste) bei [mysql1] und [mysql2].
  • Zeilen 90–99: [final placeholderGroups = <String>[]; final values = <String, Object?>{}; for (...) { placeholderGroups.add('(:id$i,:last_name$i,:first_name$i,:age$i)'); ... }]: [mysql2] unterstützt das Masseneinfügen aus einem Array von Arrays direkt ([values ?] mit [[[...],[...]]]). [package:mysql_client_plus] bietet dieses Pendant nicht (wie schon [mysql1]): Sie müssen daher den SQL-Text selbst zusammensetzen, allerdings mit einer Gruppe von Platzhaltern – BENANNT und NUMMERIERT – pro Zeile ([:id0], [:last_name0] ... [:id1], [:last_name1] ...), da benannte Platzhalter innerhalb derselben Anfrage nicht wiederholt werden dürfen – ein einziger Netzwerk-Roundtrip, wie in der TypeScript-Version.
  • Zeile 93: [final (idP, lastName, firstName, age) = otherPersons[i];]: erneut eine Zerlegung eines positionalen Records – hier notwendig, um jeden Platzhalter ([:id0], [:last_name0] ...) anhand der vier Felder des Records einzeln zu benennen, da [mysql_client_plus] keinen direkten positionalen Zugriff wie [p.$1, p.$2...] bietet, der in der vorherigen Version dieses Skripts verwendet wurde.

Das Ergebnis der Ausführung lautet:

12 persons inserted.

Sie können das Ergebnis mit dem HeidiSQL von Laragon überprüfen:

Image

7.1.9. Fazit

Die Portierung des nativen Treibers entspricht treu dem TypeScript-Original. Nach einem ersten Versuch mit [package:mysql1] – der wegen der Inkompatibilität mit MySQL 8.4 aufgegeben wurde – bietet [package:mysql_client_plus] schließlich eine API, die [mysql2] noch näher kommt, als es [mysql1] tat: [connection.transactional(...)] ist das direkte Äquivalent zu [beginTransaction()]/[commit()]/[rollback()], während [mysql1] verlangt hätte, die Transaktion manuell über die SQL-Befehle [START TRANSACTION], [COMMIT] und [ROLLBACK] zu verwalten. Ein Unterschied bleibt, wenn auch ein subtilerer: Die DECIMAL-Spalten ([subjects.coefficient], [grades.value] in der Datenbank [dbschool]) erfordern eine ausdrückliche Konvertierung über einen kleinen Helfer [_decimal] ([typedColByName<String>(...)], dann [num.parse(...)]), da der Treiber die direkte Konvertierung in [num] oder [double] für diesen SQL-Typ nicht unterstützt.

7.2. Das leichtgewichtige ORM

Image

Der TypeScript-Kurs widmet dem Datenbankzugriff über ein ORM ([Object-Relational Mapping]) zwei getrennte Kapitel: [TypeORM], gefolgt von [Prisma], jeweils mit demselben Beispielschema. Beide beruhen auf einem gemeinsamen Prinzip: das Schema einmal beschreiben (mit TypeORM-Dekoratoren auf Klassen oder mit einer [.prisma]-Datei bei Prisma) und das Werkzeug dann beim Start oder bei der Kompilierung den gesamten Code erzeugen lassen, der Lese- und Schreibzugriffe auf Objekte in SQL übersetzt – einschließlich des Ladens von Beziehungen zwischen Tabellen.

Dart hat für MySQL kein ausgereiftes und weit verbreitetes Pendant zu diesen beiden Werkzeugen: Es gibt zwar ORM-Bibliotheken für Dart, doch sie sind vor allem für Flutter/SQLite ([Drift], [Floor]) oder für andere Architekturen konzipiert – Prisma selbst bietet keinen Dart-Client an. Statt eine künstliche Zuordnung wie „dieses Dart-Paket = TypeORM“ oder „jenes Paket = Prisma“ zu erzwingen, verfolgt dieses Kapitel einen anderen, didaktisch sinnvolleren Ansatz: zu zeigen, was ein ORM tatsächlich leistet, indem man es selbst in einer bewusst minimalen Version schreibt – daher der Name [light ORM].

7.2.1. Die Entitäten: die Datei [entities.dart]

// entities.dart
// Portiert die TypeORM-Entitäten (databases/typeorm/entities/*.entity.ts):
// Person (Datenbank [dbpersons]) und SchoolClass / Student / Subject / Grade (Datenbank
// [dbschool]).
//
// [grundlegender Unterschied zu TypeScript] TypeORM-Entitäten sind gewöhnliche
// DEKORIERTE Klassen (`@Entity`, `@Column`, `@ManyToOne`...):
// TypeORM LIEST diese Dekoratoren beim Start (eine Form von
// Reflection/Metaprogrammierung), um zu wissen, wie jedes
// Feld in SQL gelesen/geschrieben wird und wie eine Beziehung bei Bedarf geladen wird. Dart hat
// hier kein brauchbares Äquivalent zu Reflection (`dart:mirrors` ist
// für Web-/AOT-Kompilierung aufgegeben): Diese Klassen sind also nur
// schlichte veränderliche "Bündel von Feldern", ohne jede Annotation - der gesamte
// Ordner light_orm (insbesondere repository.dart) übernimmt,
// von Hand geschrieben, die Rolle, die bei TypeORM die Reflection spielt. Siehe
// die README.md dieses Ordners für die ausführliche Diskussion.
class Person {
  int id;
  String lastName;
  String firstName;
  int age;

  Person({required this.id, required this.lastName, required this.firstName, required this.age});

  @override
  String toString() => 'Person($id, $firstName $lastName, $age years old)';
}

class SchoolClass {
  int id;
  String name;
  // inverse Beziehung (Backref von Student.schoolClass) - NICHT
  // automatisch geladen: bleibt leer, solange wir nicht ausdrücklich
  // eine Abfrage aufrufen, die sie füllt (siehe orm_03_joined_queries.dart)
  List<Student> students = [];

  SchoolClass({required this.id, required this.name});

  @override
  String toString() => 'SchoolClass($id, $name)';
}

class Student {
  int id;
  String lastName;
  String firstName;
  int classId;
  // N-1-Beziehung zu SchoolClass - null, solange sie nicht
  // ausdrücklich geladen wurde (das Äquivalent zur Option `relations: { schoolClass: true }`
  // von TypeORM, hier aber als gewöhnliches nullbares Feld sichtbar gemacht)
  SchoolClass? schoolClass;
  List<Grade> grades = [];

  Student({
    required this.id,
    required this.lastName,
    required this.firstName,
    required this.classId,
    this.schoolClass,
  });

  @override
  String toString() => 'Student($id, $firstName $lastName)';
}

class Subject {
  int id;
  String name;
  num coefficient;
  List<Grade> grades = [];

  Subject({required this.id, required this.name, required this.coefficient});

  @override
  String toString() => 'Subject($id, $name, coefficient $coefficient)';
}

class Grade {
  int id;
  num value;
  int studentId;
  int subjectId;
  Student? student;
  Subject? subject;

  Grade({
    required this.id,
    required this.value,
    required this.studentId,
    required this.subjectId,
    this.student,
    this.subject,
  });

  @override
  String toString() => 'Grade($id, $value)';
}

Kommentieren wir diesen Code:

  • Die TypeORM-Entitäten sind gewöhnliche DEKORIERTE Klassen ([@Entity], [@Column], [@ManyToOne] ...): TypeORM liest beim Start diese Dekoratoren (eine Form von Reflection) aus, um zu bestimmen, wie jedes Feld in SQL gelesen bzw. geschrieben wird und wie eine Beziehung bei Bedarf geladen wird. Dart hat hier kein verwendbares Pendant zur Reflection ([dart:mirrors] ist für die Webkompilierung/AOT veraltet): Diese Klassen sind daher schlichte veränderliche „Feldbehälter“ ohne jegliche Annotationen.
  • Zeile 29: [class SchoolClass { ...; List<Student> students = []; }], [class Student { ...; SchoolClass? schoolClass; List<Grade> grades = []; }] (Zeile 43): Die Beziehungen sind einfache Felder (leere Sammlung oder nullable Referenz), die nie automatisch geladen werden – es ist die von Hand geschriebene Datei [repository.dart], die die Rolle übernimmt, die bei TypeORM die Reflection spielt.

7.2.2. Das generische Repository: die Datei [repository.dart]

// repository.dart
// Ein von Hand geschriebenes "Light-ORM": eine generische Klasse [Repository], stark
// inspiriert vom Repository von TypeORM (`AppDataSource.getRepository(...)`,
// `.find()`, `.findOneBy()`, `.save()`, `.delete()`), aber auf
// einer einzigen Tabelle aufgebaut, ohne Dekoratoren und ohne automatisches Laden von
// Beziehungen - siehe README.md für die ausführliche Diskussion dieser Entscheidung.
//
// [Migration] Diese Datei verwendete anfangs [package:mysql1]; sie wurde
// auf [package:mysql_client_plus] portiert (siehe den Kommentar in
// pubspec.yaml). Die für den Aufrufer sichtbarste Änderung ist der
// Stil der parametrisierten Abfragen: mysql1 verwendete POSITIONALE
// Platzhalter ("?" + Liste von Werten der Reihe nach), während
// [mysql_client_plus] BENANNTE Platzhalter (":column" + eine
// [Map] Spaltenname -> Wert) verwendet - was hier recht gut passt,
// da dieses Repository bereits [Map<String, Object?>] von
// Spalten verarbeitet.
import 'package:mysql_client_plus/mysql_client_plus.dart';

// [T]: der Typ der Entität, die von diesem Repository verwaltet wird (Person, SchoolClass...)
class Repository<T> {
  final MySQLConnection connection;
  // Name der SQL-Tabelle
  final String table;
  // Name der Primärschlüsselspalte
  final String keyColumn;
  // baut eine Entität [T] aus einer SQL-Ergebniszeile
  final T Function(ResultSetRow row) fromRow;
  // liefert die SQL-Spalten (Spaltenname -> Wert) einer Entität [T],
  // Primärschlüssel EINGESCHLOSSEN (nützlich sowohl für das Einfügen als auch für
  // die Aktualisierung)
  final Map<String, Object?> Function(T entity) toColumns;
  // extrahiert den Wert des Primärschlüssels einer Entität [T]
  final Object? Function(T entity) key;

  Repository(
    this.connection, {
    required this.table,
    required this.keyColumn,
    required this.fromRow,
    required this.toColumns,
    required this.key,
  });

  // Äquivalent zu `repo.find({ order: { column: 'ASC' } })`
  Future<List<T>> findAll({String? orderBy}) async {
    final sql = 'select * from $table${orderBy != null ? ' order by $orderBy' : ''}';
    final results = await connection.execute(sql);
    return results.rows.map(fromRow).toList();
  }

  // Äquivalent zu `repo.findOneBy({ column: value })` - [conditions] ist
  // eine "AND"-Gleichheit auf jeder übergebenen Spalte; die Schlüssel von [conditions]
  // dienen sowohl als SQL-Spaltenname als auch als Name des BENANNTEN Platzhalters
  // (":column") - sie werden daher unverändert als
  // Abfrageparameter wiederverwendet
  Future<T?> findOneBy(Map<String, Object?> conditions) async {
    final where = conditions.keys.map((c) => '$c = :$c').join(' and ');
    final results = await connection.execute(
      'select * from $table where $where limit 1',
      conditions,
    );
    if (results.rows.isEmpty) return null;
    return fromRow(results.rows.first);
  }

  // Äquivalent zu `repo.findOneByOrFail(...)` / `findOneOrFail(...)`
  Future<T> findOneByOrFail(Map<String, Object?> conditions) async {
    final found = await findOneBy(conditions);
    if (found == null) {
      throw StateError('No row found in [$table] for $conditions');
    }
    return found;
  }

  // Äquivalent zu `repo.save(entity)`: Einfügen, wenn der Schlüssel noch nicht
  // existiert, andernfalls Aktualisieren - genau das "Upsert"-Verhalten von
  // `save()` auf der TypeORM-Seite
  Future<void> save(T entity) async {
    final columns = toColumns(entity);
    final currentKey = key(entity);
    final alreadyExists = await findOneBy({keyColumn: currentKey}) != null;
    if (alreadyExists) {
      final toUpdate = columns.keys.where((c) => c != keyColumn);
      final assignments = toUpdate.map((c) => '$c = :$c').join(', ');
      // die zu aktualisierenden Spalten, PLUS der Schlüssel (unter demselben Platzhalternamen
      // wie in der WHERE-Klausel) - keine Kollision möglich,
      // da [keyColumn] gerade aus [toUpdate] ausgeschlossen wurde
      final values = <String, Object?>{
        for (final c in toUpdate) c: columns[c],
        keyColumn: currentKey,
      };
      await connection.execute('update $table set $assignments where $keyColumn = :$keyColumn', values);
    } else {
      final names = columns.keys.join(',');
      final placeholders = columns.keys.map((c) => ':$c').join(',');
      await connection.execute('insert into $table ($names) values ($placeholders)', columns);
    }
  }

  // Äquivalent zu `repo.delete({ column: value })`
  Future<void> delete(Map<String, Object?> conditions) async {
    final where = conditions.keys.map((c) => '$c = :$c').join(' and ');
    await connection.execute('delete from $table where $where', conditions);
  }
}

Kommentieren wir diesen Code:

  • Zeilen 20–33: [class Repository<T> { ...; final T Function(ResultSetRow row) fromRow; final Map<String, Object?> Function(T entity) toColumns; final Object? Function(T entity) key; ... }]: eine GENERISCHE Klasse, konfiguriert über den Entitätstyp [T] und aufgebaut um DREI vom Aufrufer gelieferte FUNKTIONEN – wie eine SQL-Zeile gelesen wird, wie sie geschrieben wird und was ihr Primärschlüssel ist. Das ist das gesamte „objektrelationale Mapping“, auf das Wesentliche reduziert; seit der Version mit [mysql1] hat sich nur der Typ der ersten Funktion geändert ([ResultSetRow] statt [ResultRow]).
  • Zeile 57: [final where = conditions.keys.map((c) => '$c = :$c').join(' and ');]: Die Schlüssel von [conditions] dienen sowohl als Spaltenname für SQL als auch als Name des BENANNTEN PLATZHALTERS ([:column]) – anders als [mysql1], das POSITIONALE Platzhalter ([?] plus eine geordnete LISTE von Werten) verwendete, erwartet [mysql_client_plus] eine [Map] (Platzhaltername → Wert), was gut passt, da dieses Repository für die Spalten bereits [Map<String, Object?>] verwendet.
  • Zeilen 45–63: [Future<List<T>> findAll({String? orderBy}) async { ... }], [Future<T?> findOneBy(Map<String, Object?> conditions) async { ... }]: die direkten Äquivalente zu [repo.find(...)] und [repo.findOneBy(...)] in TypeORM – [execute()] ersetzt [query()], und [results.rows] enthält die Ergebniszeilen (statt der von [mysql1] direkt zurückgegebenen Liste).
  • Zeilen 78–96: [Future<void> save(T entity) async { ...; final alreadyExists = await findOneBy(...) != null; if (alreadyExists) { ... update ... } else { ... insert ... } }]: das „Upsert“-Verhalten von [repo.save(...)] – einfügen, wenn der Schlüssel noch nicht existiert, sonst aktualisieren – bleibt seit der Version mit [mysql1] unverändert, abgesehen vom Stil der Platzhalter.

7.2.3. Skript [orm_01_persons]

// orm_01_persons.dart
// Portiert databases/typeorm/typeorm-01.ts.
//
// Erste Verwendung des "Light-ORM": die Verbindung öffnen, dann in der Tabelle [persons]
// über das [Repository<Person>] lesen und schreiben,
// ohne in DIESER Datei eine einzige Zeile SQL zu schreiben (das gesamte SQL steht
// in repository.dart, einmal für alle Entitäten geschrieben).
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'entities.dart';
import 'repository.dart';

Future<void> main() async {
  final connection = await MySQLConnection.createConnection(
    host: 'localhost',
    port: 3306,
    userName: 'admpersons',
    password: 'nobody',
    databaseName: 'dbpersons',
  );
  await connection.connect();
  print('Connection to [dbpersons] established.');

  try {
    final repo = Repository<Person>(
      connection,
      table: 'persons',
      keyColumn: 'id',
      // [Migration zu mysql_client_plus] mysql1 dekodierte jede Spalte bereits
      // in den erwarteten nativen Dart-Typ ([row.fields['id'] as int]
      // funktionierte direkt). [package:mysql_client_plus] verlangt einen expliziten
      // TYPISIERTEN Zugriff pro Spalte - [typedColByName<T>(name)] - der
      // die Umwandlung selbst übernimmt; das [!] ist hier sicher, da
      // diese Spalten im SQL-Schema NOT NULL sind.
      fromRow: (row) => Person(
        id: row.typedColByName<int>('id')!,
        lastName: row.typedColByName<String>('last_name')!,
        firstName: row.typedColByName<String>('first_name')!,
        age: row.typedColByName<int>('age')!,
      ),
      toColumns: (p) => {'id': p.id, 'last_name': p.lastName, 'first_name': p.firstName, 'age': p.age},
      key: (p) => p.id,
    );

    // alle Personen, nach Nachnamen sortiert
    final all = await repo.findAll(orderBy: 'last_name asc');
    print('Persons in the database:');
    for (final p in all) {
      print('  ${p.id} ${p.firstName} ${p.lastName} (${p.age} years old)');
    }

    // eine Person anhand ihres Primärschlüssels
    final paul = await repo.findOneBy({'id': 1});
    print('Person id=1: ${paul != null ? '${paul.firstName} ${paul.lastName}' : 'not found'}');

    // Einfügen einer neuen Person (die Entität ist eine einfache Klasse:
    // der Konstruktor genügt, keine spezielle Factory nötig)
    final newPerson = Person(id: 99, firstName: 'Ada', lastName: 'Lovelace', age: 36);
    await repo.save(newPerson);
    print('Person 99 inserted.');

    // Aktualisierung
    newPerson.age = 37;
    await repo.save(newPerson);
    print('After update, age=${(await repo.findOneBy({'id': 99}))?.age}');

    // Löschen - wir versetzen die Datenbank in den Zustand zurück, in dem wir sie vorgefunden haben
    await repo.delete({'id': 99});
    print('Person 99 deleted.');
  } finally {
    await connection.close();
  }
}

Kommentieren wir diesen Code:

  • Zeilen 24–42: [final repo = Repository<Person>(connection, table: 'persons', keyColumn: 'id', fromRow: (row) => Person(...), toColumns: (p) => {...}, key: (p) => p.id);]: erstellt ein Repository für die Entität [Person] und übergibt ihm die drei erwarteten Funktionen – die einzige Stelle der Datei, die die Details der SQL-Spalten „kennt“. [mysql1] dekodierte jede Spalte bereits in den erwarteten nativen Dart-Typ ([row.fields['id'] as int] funktionierte direkt); [mysql_client_plus] verlangt einen expliziten TYPISIERTEN Zugriff Spalte für Spalte – [typedColByName<T>(name)] –, der die Konvertierung selbst übernimmt.
  • Der Rest des Skripts ([repo.findAll], [repo.findOneBy], [repo.save], [repo.delete]) enthält keine SQL-Zeilen mehr – exakt dieselbe Erfahrung, die TypeORM im Alltag bietet, unverändert durch die Migration.

Das Ergebnis der Ausführung lautet:

Connection to [dbpersons] established.
Persons in the database:
40 Y'éna d'Aboot (18 years old)
200 F'ilhem d'Aboot (34 years old)
0 f00 l00 (10 years old)
1 f01 l01 (11 years old)
2 f02 l02 (12 years old)
3 f03 l03 (13 years old)
4 f04 l04 (14 years old)
100 f10 l10 (20 years old)
101 f11 l11 (21 years old)
102 f12 l12 (22 years old)
103 f13 l13 (23 years old)
104 f14 l14 (24 years old)
Person id=1: f01 l01
Person 99 inserted.
After update, age=37
Person 99 deleted.

7.2.4. Skript [orm_02_school]

// orm_02_school.dart
// Portiert databases/typeorm/typeorm-02.ts.
//
// Mapping von drei Entitäten der Datenbank [dbschool] (SchoolClass, Student, Subject)
// und grundlegende Manipulationen (CRUD) über ihre Repositories.
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'entities.dart';
import 'repository.dart';

// liest eine SQL-Spalte DECIMAL/NUMERIC (hier [subjects.coefficient]) als
// [num]. [package:mysql_client_plus] kann ein DECIMAL in einen
// [String] umwandeln (jeder SQL-Typ kann als [String] gelesen werden), aber NICHT
// direkt in [num] oder [double] - `typedColByName<num>(...)` löst dann
// "Cannot convert MySQL type 246 to requested type num" aus (246 =
// NEWDECIMAL, der interne MySQL-Typ der DECIMAL-Spalten). Also lesen wir die
// Spalte als [String] und wandeln sie dann selbst um.
num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);

Repository<SchoolClass> _classRepo(MySQLConnection cnx) => Repository<SchoolClass>(
      cnx,
      table: 'classes',
      keyColumn: 'id',
      fromRow: (r) => SchoolClass(
        id: r.typedColByName<int>('id')!,
        name: r.typedColByName<String>('name')!,
      ),
      toColumns: (c) => {'id': c.id, 'name': c.name},
      key: (c) => c.id,
    );

Repository<Student> _studentRepo(MySQLConnection cnx) => Repository<Student>(
      cnx,
      table: 'students',
      keyColumn: 'id',
      fromRow: (r) => Student(
        id: r.typedColByName<int>('id')!,
        lastName: r.typedColByName<String>('last_name')!,
        firstName: r.typedColByName<String>('first_name')!,
        classId: r.typedColByName<int>('class_id')!,
      ),
      toColumns: (s) => {'id': s.id, 'last_name': s.lastName, 'first_name': s.firstName, 'class_id': s.classId},
      key: (s) => s.id,
    );

Repository<Subject> _subjectRepo(MySQLConnection cnx) => Repository<Subject>(
      cnx,
      table: 'subjects',
      keyColumn: 'id',
      fromRow: (r) => Subject(
        id: r.typedColByName<int>('id')!,
        name: r.typedColByName<String>('name')!,
        coefficient: _decimal(r, 'coefficient'),
      ),
      toColumns: (s) => {'id': s.id, 'name': s.name, 'coefficient': s.coefficient},
      key: (s) => s.id,
    );

Future<void> main() async {
  final connection = await MySQLConnection.createConnection(
    host: 'localhost',
    port: 3306,
    userName: 'admschool',
    password: 'pwdschool',
    databaseName: 'dbschool',
  );
  await connection.connect();
  print('Connection to [dbschool] established.');

  try {
    final classRepo = _classRepo(connection);
    final studentRepo = _studentRepo(connection);
    final subjectRepo = _subjectRepo(connection);

    // alle Klassen
    print('Classes:');
    for (final c in await classRepo.findAll(orderBy: 'name asc')) {
      print('  ${c.id} ${c.name}');
    }

    // alle Fächer mit ihrem Koeffizienten
    print('Subjects:');
    for (final s in await subjectRepo.findAll(orderBy: 'name asc')) {
      print('  ${s.id} ${s.name} (coefficient ${s.coefficient})');
    }

    // Hinzufügen eines neuen Schülers in [class1]
    final class1 = await classRepo.findOneByOrFail({'name': 'class1'});
    final newStudent = Student(id: 999, lastName: 'Curie', firstName: 'Marie', classId: class1.id);
    await studentRepo.save(newStudent);
    print('Student ${newStudent.firstName} ${newStudent.lastName} added to ${class1.name}.');

    // erneutes Lesen - [Unterschied zu TypeScript] typeorm-02.ts gibt
    // `relations: { schoolClass: true }` an, um die zugehörige Klasse gleichzeitig mit dem Schüler
    // zu laden. [Repository.findOneBy] kann NUR
    // die Tabelle [students] laden (kein automatischer Join): Also holen wir
    // die Klasse selbst, mit einer zweiten expliziten Abfrage -
    // genau die zusätzliche Abfrage, die TypeORM hinter
    // `relations: { schoolClass: true }` für uns auslöst, hier aber SICHTBAR.
    final reread = await studentRepo.findOneByOrFail({'id': 999});
    reread.schoolClass = await classRepo.findOneByOrFail({'id': reread.classId});
    print('Re-read: ${reread.firstName} ${reread.lastName}, class=${reread.schoolClass!.name}');

    // Löschen - wir versetzen die Datenbank in den Zustand zurück, in dem wir sie vorgefunden haben
    await studentRepo.delete({'id': 999});
    print('Student 999 deleted.');
  } finally {
    await connection.close();
  }
}

Analysieren wir diesen Code:

  • Zeilen 10–17: [num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]: [mysql_client_plus] kann eine SQL-Spalte DECIMAL (hier [subjects.coefficient]) in [String] umwandeln (jeder Typ, etwa SQL, kann als [String] gelesen werden), aber nicht direkt in [num] oder [double] – [typedColByName<num>(...)] liefert dann [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num] (246 = NEWDECIMAL, der interne MySQL-Typ der Spalten DECIMAL). Die Spalte wird daher als [String] gelesen und anschließend manuell konvertiert.
  • Drei private Funktionen – [_classRepo], [_studentRepo] und [_subjectRepo] – erstellen jeweils ein [Repository] für eine der drei Entitäten von [dbschool]; nur [_subjectRepo] verwendet [_decimal] für die Spalte [coefficient].
  • Zeilen 99–100: [final reread = await studentRepo.findOneByOrFail({'id': 999}); reread.schoolClass = await classRepo.findOneByOrFail({'id': reread.classId});]: Während [typeorm-02.ts] [relations: { schoolClass: true }] angibt, um die zugehörige Klasse zusammen mit dem Schüler zu laden, kann [Repository.findOneBy] nur aus der Tabelle [students] laden (kein automatischer Join) – also holen wir die Klasse selbst über eine zweite, explizite Abfrage: genau die zusätzliche Abfrage, die TypeORM im Hintergrund auslöst, hier jedoch SICHTBAR gemacht.

Das Ergebnis der Ausführung lautet:

Connection to [dbschool] established.
Classes:
1 class1
2 class2
Subjects:
1 subject1 (coefficient 1.0)
2 subject2 (coefficient 2.0)
Student Marie Curie added to class1.
Re-read: Marie Curie, class=class1
Student 999 deleted.

7.2.5. Skript [orm_03_joined_queries]

// orm_03_joined_queries.dart
// Portiert databases/typeorm/typeorm-03-joined-queries.ts.
//
// Hebt die SQL-Abfragen hervor, die geschrieben werden müssen, um
// Informationen abzurufen, die über mehrere Tabellen verteilt sind - was TypeORM
// hinter der Option `relations` über einen SQL-JOIN
// (`JOIN`) für Sie auslöst. Anders als orm_02_school.dart (das das Laden einer
// Beziehung mit ZWEI getrennten Abfragen simulierte, um es einfach zu halten),
// schreibt diese Datei die ECHTEN SQL-Joins - genau das, was TypeORM hinter
// den Kulissen tut, aber vollständig sichtbar gemacht.
//
// [grundlegender Unterschied zu TypeScript] TypeORM (wie SQLAlchemy, das
// im ursprünglichen Python-Kurs verwendet wurde) macht standardmäßig KEIN Lazy Loading
// bei "klassischen" Entitäten: Die zu ladenden Beziehungen müssen
// ausdrücklich mit der Option `relations` angefordert werden. Unser
// "Light-ORM" treibt dieses Prinzip noch weiter, denn hier gibt es WEDER Lazy
// Loading NOCH "magisches" Laden von Beziehungen: Jeder Join ist
// von Hand geschriebenes SQL, Zeile für Zeile - der Preis dafür,
// von keiner objektrelationalen Mapping-Bibliothek abzuhängen.
//
// [Migration zu mysql_client_plus] wie in repository.dart werden die
// positionalen Platzhalter ("?") von mysql1 zu BENANNTEN
// Platzhaltern (":id", ":name"...), und der Zugriff auf die Spalten einer
// Ergebniszeile ([row.fields['x']] bei mysql1) wird zu einem typisierten Aufruf
// ([row.typedColByName<T>('x')]).
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'entities.dart';

// liest eine SQL-Spalte DECIMAL/NUMERIC (hier [grades.value] und
// [subjects.coefficient]) als [num]. [package:mysql_client_plus] kann ein DECIMAL
// in einen [String] umwandeln (jeder SQL-Typ kann als [String] gelesen
// werden), aber NICHT direkt in [num] oder [double] -
// `typedColByName<num>(...)` löst dann "Cannot convert MySQL type 246 to
// requested type num" aus (246 = NEWDECIMAL, der interne MySQL-Typ der
// DECIMAL-Spalten). Also lesen wir die Spalte als [String] und
// wandeln sie dann selbst um.
num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);

// Schüler nach id, mit seiner Klasse (JOIN students/classes)
Future<Student> _studentWithClass(MySQLConnection cnx, int id) async {
  final results = await cnx.execute(
    'select s.id as s_id, s.last_name as s_last_name, s.first_name as s_first_name, s.class_id as s_class_id, '
    'c.id as c_id, c.name as c_name '
    'from students s join classes c on s.class_id = c.id where s.id = :id',
    {'id': id},
  );
  final row = results.rows.first;
  return Student(
    id: row.typedColByName<int>('s_id')!,
    lastName: row.typedColByName<String>('s_last_name')!,
    firstName: row.typedColByName<String>('s_first_name')!,
    classId: row.typedColByName<int>('s_class_id')!,
    schoolClass: SchoolClass(id: row.typedColByName<int>('c_id')!, name: row.typedColByName<String>('c_name')!),
  );
}

// Klasse nach id, mit der Liste ihrer Schüler (JOIN classes/students)
Future<SchoolClass> _classWithStudents(MySQLConnection cnx, int id) async {
  final results = await cnx.execute(
    'select c.id as c_id, c.name as c_name, s.id as s_id, s.last_name as s_last_name, s.first_name as s_first_name '
    'from classes c left join students s on s.class_id = c.id where c.id = :id',
    {'id': id},
  );
  final firstRow = results.rows.first;
  final schoolClass = SchoolClass(id: firstRow.typedColByName<int>('c_id')!, name: firstRow.typedColByName<String>('c_name')!);
  schoolClass.students = [
    for (final row in results.rows)
      Student(
        id: row.typedColByName<int>('s_id')!,
        lastName: row.typedColByName<String>('s_last_name')!,
        firstName: row.typedColByName<String>('s_first_name')!,
        classId: schoolClass.id,
      ),
  ];
  return schoolClass;
}

// Klasse nach NAME, mit der Liste ihrer Schüler
Future<SchoolClass> _classWithStudentsByName(MySQLConnection cnx, String name) async {
  final results = await cnx.execute(
    'select c.id as c_id, c.name as c_name, s.id as s_id, s.last_name as s_last_name, s.first_name as s_first_name '
    'from classes c left join students s on s.class_id = c.id where c.name = :name',
    {'name': name},
  );
  final firstRow = results.rows.first;
  final schoolClass = SchoolClass(id: firstRow.typedColByName<int>('c_id')!, name: firstRow.typedColByName<String>('c_name')!);
  schoolClass.students = [
    for (final row in results.rows)
      Student(
        id: row.typedColByName<int>('s_id')!,
        lastName: row.typedColByName<String>('s_last_name')!,
        firstName: row.typedColByName<String>('s_first_name')!,
        classId: schoolClass.id,
      ),
  ];
  return schoolClass;
}

// Schüler nach NACHNAME, mit seiner Klasse
Future<Student> _studentByLastNameWithClass(MySQLConnection cnx, String lastName) async {
  final results = await cnx.execute(
    'select s.id as s_id, s.last_name as s_last_name, s.first_name as s_first_name, s.class_id as s_class_id, '
    'c.id as c_id, c.name as c_name '
    'from students s join classes c on s.class_id = c.id where s.last_name = :last_name',
    {'last_name': lastName},
  );
  final row = results.rows.first;
  return Student(
    id: row.typedColByName<int>('s_id')!,
    lastName: row.typedColByName<String>('s_last_name')!,
    firstName: row.typedColByName<String>('s_first_name')!,
    classId: row.typedColByName<int>('s_class_id')!,
    schoolClass: SchoolClass(id: row.typedColByName<int>('c_id')!, name: row.typedColByName<String>('c_name')!),
  );
}

// Noten eines Schülers, mit dem Fach jeder Note (doppelter JOIN)
Future<Student> _studentWithGradesAndSubject(MySQLConnection cnx, int id) async {
  final studentRow = (await cnx.execute('select id, last_name, first_name, class_id from students where id = :id', {'id': id})).rows.first;
  final student = Student(
    id: studentRow.typedColByName<int>('id')!,
    lastName: studentRow.typedColByName<String>('last_name')!,
    firstName: studentRow.typedColByName<String>('first_name')!,
    classId: studentRow.typedColByName<int>('class_id')!,
  );
  final results = await cnx.execute(
    'select g.id as g_id, g.value as g_value, sub.id as sub_id, sub.name as sub_name, sub.coefficient as sub_coefficient '
    'from grades g join subjects sub on g.subject_id = sub.id where g.student_id = :id',
    {'id': id},
  );
  student.grades = [
    for (final row in results.rows)
      Grade(
        id: row.typedColByName<int>('g_id')!,
        value: _decimal(row, 'g_value'),
        studentId: student.id,
        subjectId: row.typedColByName<int>('sub_id')!,
        subject: Subject(
          id: row.typedColByName<int>('sub_id')!,
          name: row.typedColByName<String>('sub_name')!,
          coefficient: _decimal(row, 'sub_coefficient'),
        ),
      ),
  ];
  return student;
}

// Fach nach NAME, mit der Liste seiner Noten
Future<Subject> _subjectWithGradesByName(MySQLConnection cnx, String name) async {
  final results = await cnx.execute(
    'select sub.id as sub_id, sub.name as sub_name, sub.coefficient as sub_coefficient, g.id as g_id, g.value as g_value '
    'from subjects sub left join grades g on g.subject_id = sub.id where sub.name = :name',
    {'name': name},
  );
  final firstRow = results.rows.first;
  final subject = Subject(
    id: firstRow.typedColByName<int>('sub_id')!,
    name: firstRow.typedColByName<String>('sub_name')!,
    coefficient: _decimal(firstRow, 'sub_coefficient'),
  );
  subject.grades = [
    for (final row in results.rows)
      Grade(
        id: row.typedColByName<int>('g_id')!,
        value: _decimal(row, 'g_value'),
        studentId: 0,
        subjectId: subject.id,
      ),
  ];
  return subject;
}

Future<void> main() async {
  final connection = await MySQLConnection.createConnection(
    host: 'localhost',
    port: 3306,
    userName: 'admschool',
    password: 'pwdschool',
    databaseName: 'dbschool',
  );
  await connection.connect();

  try {
    // Schüler nach id, mit seiner Klasse (expliziter Join)
    print('student id=11 -----------');
    final student11 = await _studentWithClass(connection, 11);
    print('student={"id":${student11.id},"lastName":"${student11.lastName}","firstName":"${student11.firstName}"}');
    print('student\'s class: {"id":${student11.schoolClass!.id},"name":"${student11.schoolClass!.name}"}');

    // die Schüler derselben Klasse (neue Abfrage, mit eigenem
    // Join)
    print('students in the same class:');
    final studentsClass = await _classWithStudents(connection, student11.schoolClass!.id);
    for (final s in studentsClass.students) {
      print('student={"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}');
    }

    // ein Schüler nach seinem Nachnamen
    print("student lastName='lastname2' -----------");
    final byName = await _studentByLastNameWithClass(connection, 'lastname2');
    print('student={"id":${byName.id},"lastName":"${byName.lastName}","firstName":"${byName.firstName}"}');
    print('student\'s class: {"id":${byName.schoolClass!.id},"name":"${byName.schoolClass!.name}"}');

    // die Noten eines Schülers, mit dem Fach jeder Note
    print('grades of student id=11 -----------');
    final studentWithGrades = await _studentWithGradesAndSubject(connection, 11);
    for (final grade in studentWithGrades.grades) {
      print('grade={"id":${grade.id},"value":${grade.value}}, subject={"name":"${grade.subject!.name}"}');
    }

    // die Schüler einer Klasse, nach Klassenname
    for (final className in ['class1', 'class2']) {
      print("students of class name='$className' -----------");
      final schoolClass = await _classWithStudentsByName(connection, className);
      for (final s in schoolClass.students) {
        print('{"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}');
      }
    }

    // die Noten in einem Fach, nach Fachname
    for (final subjectName in ['subject1', 'subject2']) {
      print("subject with name='$subjectName' -----------");
      final subject = await _subjectWithGradesByName(connection, subjectName);
      print('subject={"name":"${subject.name}","coefficient":${subject.coefficient}}');
      print('Grades in the subject: ');
      for (final grade in subject.grades) {
        print('{"id":${grade.id},"value":${grade.value}}');
      }
    }
  } finally {
    await connection.close();
  }
}

Analysieren wir diesen Code:

  • Anders als [orm_02_school.dart] (zwei getrennte Anfragen) schreibt diese Datei die ECHTEN SQL-Joins – genau das, was TypeORM im Hintergrund über die Option [relations] tut, hier aber vollständig sichtbar.
  • Zeilen 44–61: [from students s join classes c on s.class_id = c.id where s.id = :id], [from classes c left join students s on s.class_id = c.id where c.id = :id]: JOIN (obligatorische Beziehung) und LEFT JOIN (optionale Beziehung; eine Klasse kann keine Schüler haben) – die Unterscheidung, die TypeORM anhand der deklarierten Optionalität der Beziehung für Sie trifft. Die positionalen Platzhalter ([?]) aus [mysql1] werden zu BENANNTEN Platzhaltern ([:id]), und der Zugriff auf die Spalten einer Zeile ([row['x']] bzw. [row.fields['x']] bei [mysql1]) wird zu einem typisierten Aufruf ([row.typedColByName<T>('x')]).
  • Zeile 135: [value: _decimal(row, 'g_value')], [coefficient: _decimal(row, 'sub_coefficient')]: derselbe Helfer [_decimal] wie in [orm_02_school.dart], hier für die beiden DECIMAL-Spalten [grades.value] und [subjects.coefficient] erforderlich.
  • TypeORM (wie SQLAlchemy) führt bei „normalen“ Entitäten standardmäßig kein Lazy Loading durch: Beziehungen müssen ausdrücklich über die Option [relations] angefordert werden. Das leichtgewichtige ORM treibt dieses Prinzip noch weiter, da es hier gar kein Lazy Loading gibt – kein „magisches“ Laden von Relationen: Jeder Join ist von Hand geschrieben – der Preis dafür, von keiner objektrelationalen Mapping-Bibliothek abzuhängen.

Das Ergebnis der Ausführung lautet:

student id=11 -----------
student={"id":11,"lastName":"lastname1","firstName":"firstname1"}
student's class: {"id":1,"name":"class1"}
students in the same class:
student={"id":11,"lastName":"lastname1","firstName":"firstname1"}
student={"id":21,"lastName":"lastname2","firstName":"firstname2"}
student lastName='lastname2' -----------
student={"id":21,"lastName":"lastname2","firstName":"firstname2"}
student's class: {"id":1,"name":"class1"}
grades of student id=11 -----------
grade={"id":1,"value":10.0}, subject={"name":"subject1"}
grade={"id":5,"value":6.0}, subject={"name":"subject2"}
students of class name='class1' -----------
{"id":11,"lastName":"lastname1","firstName":"firstname1"}
{"id":21,"lastName":"lastname2","firstName":"firstname2"}
students of class name='class2' -----------
{"id":32,"lastName":"lastname3","firstName":"firstname3"}
{"id":42,"lastName":"lastname4","firstName":"firstname4"}
subject with name='subject1' -----------
subject={"name":"subject1","coefficient":1.0}
Grades in the subject: 
{"id":1,"value":10.0}
{"id":2,"value":12.0}
{"id":3,"value":14.0}
{"id":4,"value":16.0}
subject with name='subject2' -----------
subject={"name":"subject2","coefficient":2.0}
Grades in the subject: 
{"id":5,"value":6.0}
{"id":6,"value":8.0}
{"id":7,"value":10.0}
{"id":8,"value":12.0}

7.2.6. Skript [orm_04_stats]

// orm_04_stats.dart
// Portiert databases/typeorm/typeorm-04-stats.ts.
//
// Berechnet für einen bestimmten Schüler seinen mit den Koeffizienten der Fächer
// gewichteten Durchschnitt sowie seine niedrigste und höchste Note.
//
// [Unterschied zu TypeScript] typeorm-04-stats.ts warnte, dass die
// MySQL-Spalten `decimal` (hier grade.value und subject.coefficient)
// vom Treiber mysql2 zur Laufzeit als ZEICHENKETTEN
// geliefert werden (um keine Genauigkeit zu verlieren), trotz ihres
// deklarierten Typs `number` - eine klassische TypeScript-Falle, bei der der
// statische Typ über den tatsächlichen Wert zur Laufzeit lügen kann. Auf der Dart-Seite hat
// [package:mysql_client_plus] eine ähnliche Falle, die aber vom Compiler SICHTBAR
// gemacht statt zur Laufzeit versteckt wird: Der typisierte Zugriff
// (`typedColByName<T>(...)`) kann eine DECIMAL-Spalte
// (interner SQL-Typ 246, "NEWDECIMAL") weder in [num] noch in [double] umwandeln - er
// löst `MySQLProtocolException: Cannot convert MySQL type 246 to requested
// type num` aus. Die einzige für JEDEN SQL-Typ garantierte Umwandlung ist
// [String]; also lesen wir die DECIMAL-Spalten mit
// `typedColByName<String>(...)` als [String] und wandeln sie dann selbst mit
// [num.parse] um - siehe [_decimal] unten.
import 'package:mysql_client_plus/mysql_client_plus.dart';

// liest eine SQL-Spalte DECIMAL/NUMERIC als [num] (siehe den Kommentar am
// Anfang der Datei)
num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);

// berechnet die Statistiken (gewichteter Durchschnitt, Min, Max) eines Schülers
Future<void> _studentStats(MySQLConnection cnx, int studentId) async {
  final studentRow = (await cnx.execute('select id, last_name, first_name from students where id = :id', {'id': studentId})).rows.first;
  print(
    'Statistics of student {"id":${studentRow.typedColByName<int>('id')},"lastName":"${studentRow.typedColByName<String>('last_name')}","firstName":"${studentRow.typedColByName<String>('first_name')}"}',
  );

  final grades = await cnx.execute(
    'select g.value as value, sub.name as subject_name, sub.coefficient as coefficient '
    'from grades g join subjects sub on g.subject_id = sub.id where g.student_id = :id',
    {'id': studentId},
  );

  if (grades.rows.isEmpty) {
    print('  no grades.');
    return;
  }

  num weightedSum = 0;
  num coefficientsSum = 0;
  num min = double.infinity;
  num max = double.negativeInfinity;

  for (final row in grades.rows) {
    // explizite Umwandlung über [_decimal] (siehe den Hinweis am Anfang der Datei):
    // [value] und [coefficient] sind somit echte [num]s, keine Strings
    final value = _decimal(row, 'value');
    final coefficient = _decimal(row, 'coefficient');
    weightedSum += value * coefficient;
    coefficientsSum += coefficient;
    if (value < min) min = value;
    if (value > max) max = value;
    print(
      '  grade=${value.toStringAsFixed(2)} subject="${row.typedColByName<String>('subject_name')}" '
      '(coefficient ${coefficient.toStringAsFixed(2)})',
    );
  }

  final average = weightedSum / coefficientsSum;
  print('  weighted average=${average.toStringAsFixed(2)}, min=${min.toStringAsFixed(2)}, max=${max.toStringAsFixed(2)}');
}

Future<void> main() async {
  final connection = await MySQLConnection.createConnection(
    host: 'localhost',
    port: 3306,
    userName: 'admschool',
    password: 'pwdschool',
    databaseName: 'dbschool',
  );
  await connection.connect();

  try {
    // Schüler id=11: Noten subject1=10 (Koeff. 1.0), subject2=6 (Koeff. 2.0)
    // gewichteter Durchschnitt = (10*1.0 + 6*2.0) / (1.0+2.0) = 22/3 = 7.33
    await _studentStats(connection, 11);
    print('');
    // Schüler id=21: Noten subject1=12 (Koeff. 1.0), subject2=8 (Koeff. 2.0)
    await _studentStats(connection, 21);
    print('');
    // Schüler id=32: Noten subject1=14 (Koeff. 1.0), subject2=10 (Koeff. 2.0)
    await _studentStats(connection, 32);
    print('');
    // Schüler id=42: Noten subject1=16 (Koeff. 1.0), subject2=12 (Koeff. 2.0)
    await _studentStats(connection, 42);
  } finally {
    await connection.close();
  }
}

Kommentieren wir diesen Code:

  • [typeorm-04-stats.ts] zeigte, dass die Spalten [decimal] von MySQL (hier [grade.value] und [subject.coefficient]) von [mysql2] zur Laufzeit als ZEICHENKETTEN zurückgegeben werden (um keine Genauigkeit zu verlieren), obwohl ihr deklarierter Typ [number] ist – eine klassische Falle von TypeScript, bei der der statische Typ nicht dem tatsächlichen Wert zur Laufzeit entsprechen muss.
  • Zeile 26: [num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]: Auf der Dart-Seite hat [package:mysql_client_plus] eine ähnliche Falle wie TypeScript, die jedoch vom Compiler SICHTBAR gemacht statt zur Laufzeit verborgen wird: Der typisierte Zugriff ([typedColByName<T>(...)]) kann eine Spalte DECIMAL weder in [num] noch in [double] umwandeln – er löst [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num] aus. Die einzige für jeden SQL-Typ garantierte Konvertierung ist die in [String]; daher werden die Spalten vom Typ DECIMAL als [String] gelesen und anschließend manuell mit [num.parse] konvertiert.
  • Zeile 67: [final average = weightedSum / coefficientsSum;]: Die Berechnung des gewichteten Durchschnitts selbst ist identisch mit der TypeScript-Version und der Version mit [mysql1] – nur das LESEN der DECIMAL-Spalten hat sich geändert.

Das Ergebnis der Ausführung lautet:

Statistics of student {"id":11,"lastName":"lastname1","firstName":"firstname1"}
grade=10.00 subject="subject1" (coefficient 1.00)
grade=6.00 subject="subject2" (coefficient 2.00)
weighted average=7.33, min=6.00, max=10.00

Statistics of student {"id":21,"lastName":"lastname2","firstName":"firstname2"}
grade=12.00 subject="subject1" (coefficient 1.00)
grade=8.00 subject="subject2" (coefficient 2.00)
weighted average=9.33, min=8.00, max=12.00

Statistics of student {"id":32,"lastName":"lastname3","firstName":"firstname3"}
grade=14.00 subject="subject1" (coefficient 1.00)
grade=10.00 subject="subject2" (coefficient 2.00)
weighted average=11.33, min=10.00, max=14.00

Statistics of student {"id":42,"lastName":"lastname4","firstName":"firstname4"}
grade=16.00 subject="subject1" (coefficient 1.00)
grade=12.00 subject="subject2" (coefficient 2.00)
weighted average=13.33, min=12.00, max=16.00

7.2.7. Was das leichtgewichtige ORM nicht leistet

Anders als TypeORM/Prisma: keine Schemagenerierung ([synchronize]/Migrationen), keine Dekoratoren, kein Lazy Loading und kein Identity Cache, kein Query Builder ([QueryBuilder]), und das Laden einer Beziehung ist IMMER eine zweite Abfrage oder ein von Hand geschriebener Join – nie automatisch. Das ist ein bewusster Kompromiss: genug, um das Repository-Muster anhand des Kursbeispiels zu veranschaulichen, ohne den Anspruch, ein echtes Repository in der Produktion zu ersetzen.