7. Acceso a bases de datos

El curso de TypeScript dedica tres capítulos al acceso a una base de datos MySQL: el controlador nativo [mysql2], seguido de dos ORM ([TypeORM] y [Prisma]), con el mismo ejemplo—dos bases de datos, [dbpersons] (una sola tabla) y [dbschool] (cuatro tablas relacionadas: clases, estudiantes, materias y notas). Este capítulo es idéntico al primero y luego combina los dos capítulos de ORM en uno solo: Dart no tiene un equivalente maduro de [TypeORM] o [Prisma] para MySQL (consulte el recuadro al final del capítulo), y en lugar de forzar una correspondencia artificial con alguno de ellos, construimos un «ORM ligero» que muestra lo que realmente hace un ORM, escribiéndolo nosotros mismos.
7.1. Acceso directo a la base de datos

El paquete [mysql2] de TypeScript no tiene un equivalente mantenido por el propio equipo de MySQL en el lado de Dart. Una versión preliminar de este capítulo utilizaba [package:mysql1] (pub.dev/packages/mysql1), un controlador de Dart puro de uso muy extendido—MySQL—, pero resultó ser incompatible con MySQL 8.4 (la versión incluida con Laragon): incluso una consulta tan simple como «select 1» fallaba sistemáticamente con el error de protocolo «Got packets out of order», un error conocido y sin resolver del paquete (problemas de GitHub adamlofts/mysql1_dart #112 y #161). Por lo tanto, ahora utilizamos [package:mysql_client_plus] (pub.dev/packages/mysql_client_plus), un fork mantenido activamente que ha sido probado con MySQL 8.x, y cuya API — [MySQLConnection.createConnection], [connection.connect], [connection.execute], [connection.close] — sigue siendo muy similar a la de [mysql2].
7.1.1. Preparación de la base de datos [dbpersons]
La base de datos dbpersons contiene una sola tabla, persons, que utiliza el mismo esquema que el del curso de Python (columnas id, first\_name, last\_name, age, con una restricción de unicidad sobre el par (last\_name, first\_name)). El script sql/create_dbpersons.sql a continuación crea la base de datos, el usuario de la aplicación y la tabla, y luego inserta en ella cinco personas arbitrarias:
-- create_dbpersons.sql
-- Recrea la base de datos [dbpersons] usada por el capítulo "Acceso a MySQL con el
-- controlador nativo [mysql2]", con datos arbitrarios (ya que los originales del curso
-- de Python/Flask de 2020 ya no están disponibles).
--
-- Uso:
-- mysql -u root -p < create_dbpersons.sql
--
-- Crea la base de datos, el usuario de la aplicación [admpersons/nobody] (las mismas
-- credenciales que el curso original) y la tabla [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)
);
-- datos arbitrarios (las mismas personas que en los ejemplos del curso original)
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);
Para crear esta base de datos (MySQL), puede utilizar la herramienta [HeidiSQL] de Laragon. Ya la hemos usado.
- En [1], inicie todos los servicios de Laragon. Esto iniciará el SGBD MySQL;
- en [2], acceda a la herramienta de administración de bases de datos [HeidiSQL];
- En [1-2], inicie sesión en MySQL;
Con [1-2], ejecute uno tras otro los dos archivos SQL del proyecto:

Aún en [HeidiSQL], presione F5 para actualizar la visualización:
Ya estamos listos para utilizar estas dos bases de datos.
7.1.2. Script [mysql_01]
| // mysql_01.dart
// Porta databases/mysql/mysql-01.ts.
//
// Primer paso: conectarse a la base de datos MySQL [dbpersons] y luego
// desconectarse.
//
// [technical choice] el paquete de TypeScript [mysql2] no tiene un equivalente directo
// del lado de Dart mantenido por el propio equipo de MySQL. Una primera
// versión de este capítulo usaba [package:mysql1] (pub.dev/packages/
// mysql1), un controlador MySQL en Dart puro muy utilizado - pero que resultó
// ser incompatible con MySQL 8.4 (incluido con Laragon): incluso una consulta
// tan trivial como "select 1" fallaba sistemáticamente con el
// error de protocolo "Got packets out of order" (error conocido y sin resolver del
// paquete). Por eso aquí usamos [package:mysql_client_plus]
// (pub.dev/packages/mysql_client_plus), un fork mantenido activamente
// y probado con MySQL 8.x, cuya API - [MySQLConnection.createConnection],
// [connection.connect], [connection.execute], [connection.close] - se mantiene muy
// cercana a la de [mysql2].
import 'package:mysql_client_plus/mysql_client_plus.dart';
// conexión a la base de datos MySQL [dbpersons]
// la identidad del usuario es (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 {
// [difference with TypeScript] aquí no hay tipo unión "MySqlConnection |
// undefined": un campo nulable ([MySQLConnection?]) cumple el mismo
// papel - "aún no conectado" se representa con [null], exactamente
// como "aún no conectado" se representaba con [undefined] del lado de TS.
MySQLConnection? connection;
try {
print('Connecting to the MySQL DBMS...');
// [difference with TypeScript] a diferencia de mysql1 (y mysql2),
// [mysql_client_plus] separa la CREACIÓN del objeto de conexión
// ([createConnection], que todavía no realiza ningún intercambio de red) del
// establecimiento real de la conexión ([connect], que negocia
// el protocolo con el servidor) - dos pasos bien distintos, mientras que
// mysql1 los fusionaba en una sola llamada [MySqlConnection.connect].
// Solo asignamos [connection] (la variable nulable del bloque [finally])
// una vez que [connect] ha tenido éxito: si [connect] falla, [connection]
// sigue siendo [null] y el [finally] no intentará cerrar una conexión
// que nunca se abrió realmente.
final newConnection = await MySQLConnection.createConnection(
host: host,
port: port,
userName: user,
password: pwd,
databaseName: database,
);
await newConnection.connect();
connection = newConnection;
// continuación
print(
"Successful MySQL connection to database=$database, host=$host as user=$user, passwd=$pwd",
);
} catch (error) {
// mostrar el error
print("The following error occurred: $error");
} finally {
// cerrar la conexión si se abrió
if (connection != null) {
await connection.close();
}
}
}
|
Comentemos este código:
- línea 19: [import 'package:mysql_client_plus/mysql_client_plus.dart';]: el nuevo controlador de MySQL escrito íntegramente en Dart, que reemplaza a [package:mysql1]—incompatible con MySQL 8.4 (incluido con Laragon): incluso una consulta tan trivial como «select 1» fallaba sistemáticamente con el error de protocolo «Got packets out of order», un error conocido y sin resolver del paquete (consulte el comentario al inicio del archivo).
- Línea 34: [MySQLConnection? connection;]: un campo NULABLE cumple exactamente la misma función que el tipo unión [MySqlConnection | undefined] de TypeScript - [null] representa «aún no conectado», igual que [undefined] en TS.
- Líneas 47–55: [final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]: [mysql_client_plus] separa la CREACIÓN del objeto de conexión ([createConnection], que todavía no intercambia tráfico de red) del establecimiento real de la conexión ([connect], que negocia el protocolo con el servidor)—dos etapas distintas, mientras que [mysql1] (como [mysql2] en el lado de TypeScript) las combinaba en una sola llamada. [connection] (la variable nulable usada en [finally]) se asigna solo después de que [connect] tenga éxito, de modo que [finally] nunca cierre una conexión que no llegó a abrirse.
- [try] / [catch] / [finally]: estructura idéntica a la versión anterior—la conexión siempre se cierra en [finally], sin importar si ocurrió un error.
El resultado de la ejecución es el siguiente:
| Connecting to the MySQL DBMS...
Successful MySQL connection to database=dbpersons, host=localhost as user=admpersons, passwd=nobody
|
7.1.3. Script [mysql_02]
| // mysql_02.dart
// Porta databases/mysql/mysql-02.ts.
//
// En este nuevo script, la conexión a la base de datos se aísla en una
// función.
import 'package:mysql_client_plus/mysql_client_plus.dart';
// se conecta y luego se desconecta (login, pwd) de la base de datos [database] en el servidor
// [host]; lanza una excepción si hay un problema
Future<void> connect(String host, int port, String database, String login, String pwd) async {
MySQLConnection? cnx;
try {
// conexión - [createConnection] crea el objeto, [connect] negocia realmente
// con el servidor (ver el comentario en mysql_01.dart);
// solo asignamos [cnx] tras un [connect] exitoso, para que el [finally]
// nunca cierre una conexión que no llegó a establecerse
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 {
// cerrar la conexión si se abrió
if (cnx != null) {
await cnx.close();
print('Successful disconnection\n');
}
}
}
// ---------------------------------------------- main
// credenciales de conexión
const String user = 'admpersons';
const String passwd = 'nobody';
const String host = 'localhost';
const int port = 3306;
const String database = 'dbpersons';
Future<void> main() async {
// conexión de un usuario existente
try {
await connect(host, port, database, user, passwd);
} catch (error) {
// mostrar el error
print('$error');
}
// conexión de un usuario inexistente
try {
await connect(host, port, database, 'xx', 'xx');
} catch (error) {
// mostrar el error
print('$error');
}
}
|
Comentemos este código:
- Líneas 10–36: [Future<void> connect(String host, int port, String database, String login, String pwd) async { ... }]: la conexión se encapsula en una función reutilizable, que lanza una excepción en caso de fallo en lugar de capturarla ella misma—corresponde a quien la llama decidir qué hacer con ella. Reutiliza el patrón «creación + [connect()]» de [mysql_01.dart]: [cnx] se asigna solo después de un [connect] exitoso.
- Línea 43: [const int port = 3306;]: [mysql_client_plus] exige un puerto EXPLÍCITO ([createConnection]), mientras que [ConnectionSettings] de [mysql1] deducía por sí mismo el puerto predeterminado (3306).
- [main] llama a esta función dos veces, en dos bloques separados, [try] y [catch]: una vez con identificadores válidos y otra con identificadores inválidos, para ilustrar ambos caminos.
El resultado de la ejecución es el siguiente:
| 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. Script [mysql_03]
| // mysql_03.dart
// Porta databases/mysql/mysql-03.ts.
//
// Ahora que sabemos conectarnos, emitimos sentencias SQL sobre la
// conexión: (re)creamos la tabla [persons] de la base de datos [dbpersons].
import 'dart:io';
import 'package:mysql_client_plus/mysql_client_plus.dart';
// ejecuta una consulta de actualización sobre la conexión
Future<void> executeSql(MySQLConnection connection, String query) async {
await connection.execute(query);
}
// ---------------------------------------------- main
// credenciales de conexión
const String id = 'admpersons';
const String pwd = 'nobody';
const String host = 'localhost';
const int port = 3306;
const String database = 'dbpersons';
Future<void> main() async {
// vamos paso a paso
late final MySQLConnection connection;
try {
// conexión - [package:mysql_client_plus], como mysql1 antes que él,
// ejecuta por defecto cada consulta en su propia transacción
// con commit automático (equivalente de AUTOCOMMIT=True del lado de Python)
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");
// [difference with TypeScript] `process.exit(1)` se convierte en `exit(1)`
// (dart:io) - misma semántica, mismo código de salida del proceso
exit(1);
}
// eliminación de la tabla persons si existe
// si no existe se producirá un error - lo ignoramos
try {
await executeSql(connection, 'drop table persons');
} catch (_) {
// ignorado - el [_] indica que no nos importa el valor de la excepción
}
// creación de la tabla 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();
}
}
|
Comentemos este código:
- Líneas 10–12: [Future<void> executeSql(MySQLConnection connection, String query) async { await connection.execute(query); }]: una función utilitaria para ejecutar un comando SQL de actualización (aquí, un DROP TABLE seguido de un CREATE TABLE) - [connection.execute(...)] reemplaza a [connection.query(...)] de [mysql1] (misma función, nuevo nombre de método en [mysql_client_plus]).
- Línea 41: [exit(1);] (de [dart:io]): equivalente a [process.exit(1)]—misma semántica, mismo código de salida del proceso en caso de fallo de conexión.
- Línea 47: [try { await executeSql(connection, 'drop table persons'); } catch (_) {}]: el hecho de pasar [_] como parámetro de [catch] indica que se ignora el valor de la excepción—la tabla simplemente puede no existir todavía.
El resultado de la ejecución es el siguiente:
| 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. Script [config_04]
| // config_04.dart
// Porta databases/mysql/config-04.ts.
//
// Configuración del script [mysql_04]: ruta del archivo de comandos SQL
// y credenciales de conexión a la base de datos [dbpersons].
//
// [difference with TypeScript] config-04.ts encuentra la carpeta del script con
// `dirname(fileURLToPath(import.meta.url))`. Dart tiene un equivalente directo y
// más corto: [Platform.script] (dart:io) ya es el
// URI del script en ejecución - solo resolvemos una ruta relativa
// con respecto a él mediante [.resolve(...)], sin manipular cadenas. Matiz:
// [Platform.script] designa el script PRINCIPAL lanzado por `dart run`
// (mysql_04.dart), no este archivo - a diferencia de `import.meta.url`,
// específico de cada archivo. El resultado es idéntico aquí ya que
// config_04.dart y mysql_04.dart están en la misma carpeta.
import 'dart:io';
class Config {
final String commandsFilename;
final String host;
// [mysql_client_plus migration] a diferencia de mysql1, cuyo
// [ConnectionSettings] deducía por sí mismo el puerto por defecto (3306),
// [MySQLConnection.createConnection] exige un puerto EXPLÍCITO - por eso
// lo añadimos aquí a la configuración.
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(
// archivo de comandos SQL, resuelto con respecto a ESTE archivo
commandsFilename: Platform.script.resolve('data/commands.sql').toFilePath(),
// credenciales de conexión a la base de datos
host: 'localhost',
port: 3306,
database: 'dbpersons',
user: 'admpersons',
password: 'nobody',
);
}
|
Analicemos este código:
- línea 43: [Platform.script.resolve('data/commands.sql').toFilePath()] (de [dart:io]): el equivalente directo y más corto de [dirname(fileURLToPath(import.meta.url))] en TypeScript - [Platform.script] ya es el URI del script que se está ejecutando; basta con resolver una ruta relativa a partir de él.
- Nota importante: [Platform.script] hace referencia al script PRINCIPAL iniciado por [dart run] (en este caso, [mysql_04.dart]), no necesariamente al archivo donde está escrita la expresión—a diferencia de [import.meta.url], que es propio de cada archivo. El resultado sigue siendo correcto aquí porque [config_04.dart] y [mysql_04.dart] se encuentran en la misma carpeta.
- líneas 18–28: [class Config { final String commandsFilename; ...; final int port; ...; const Config({required this... }); }]: una clase inmutable para agrupar la configuración, como la interfaz [Config] de la versión en TypeScript — con un campo [port] adicional, exigido explícitamente por [MySQLConnection.createConnection] (mientras que [ConnectionSettings] de [mysql1] deducía automáticamente el puerto predeterminado, 3306).
7.1.6. Script [mysql_module]
| // mysql_module.dart
// Porta databases/mysql/mysql-module.ts: funciones reutilizables para
// ejecutar una lista (o un archivo) de comandos SQL en una conexión MySQL
// abierta.
//
// [migration] este archivo usaba inicialmente [package:mysql1], que resultó
// ser incompatible con MySQL 8.4 (ver el comentario en pubspec.yaml). Se ha
// portado a [package:mysql_client_plus] - vea a continuación la diferencia
// que esto implica para el manejo de transacciones.
import 'dart:io';
import 'package:mysql_client_plus/mysql_client_plus.dart';
// muestra el resultado de un comando SQL (resultado de un execute() de
// mysql_client_plus)
// - si [results.cols] no está vacío, era un SELECT: mostramos las
// columnas y luego las filas;
// - de lo contrario, era una sentencia de actualización (INSERT/UPDATE/DELETE/DDL):
// mostramos el número de filas modificadas ([results.affectedRows],
// equivalente del [rowcount] de un cursor).
void _displayInfo(IResultSet results) {
if (results.cols.isNotEmpty) {
// era un SELECT - [cols] describe las columnas solicitadas
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 {
// ninguna columna descrita - sentencia de actualización
print('number of modified rows: ${results.affectedRows}');
}
}
// usa la conexión abierta [connection]
// ejecuta en esta conexión los comandos SQL contenidos en la lista
// [sqlCommands] (un comando por elemento; se ignoran las líneas vacías o las líneas
// que comienzan con #)
// - si verbose=true, a cada ejecución de una sentencia SQL le sigue una
// visualización que indica su éxito o fallo;
// - si stop=true, la función se detiene en el 1.er error encontrado,
// de lo contrario ejecuta todos los comandos;
// - si withTransaction=true, cualquier error cancela todas las sentencias SQL
// ejecutadas antes (rollback); de lo contrario, cada comando se confirma
// de forma independiente (comportamiento por defecto de MySQL, en AUTOCOMMIT);
// la función devuelve una lista [error1, error2, ...]
//
// [difference with TypeScript] mysql2 expone directamente
// `connection.beginTransaction()/commit()/rollback()`. [package:mysql1]
// (usado en una primera versión de este archivo) no exponía estos
// métodos uno por uno: la transacción había que conducirla "a mano",
// enviando nosotros mismos las sentencias SQL [START TRANSACTION], [COMMIT] y
// [ROLLBACK]. [package:mysql_client_plus] finalmente aporta el equivalente directo
// de mysql2: `connection.transactional<T>((cnx) async { ... })` ejecuta el
// callback en una transacción, confirma (COMMIT) automáticamente si
// termina con normalidad, y cancela (ROLLBACK) automáticamente si lanza una
// excepción - ya no hay sentencias SQL de control de transacciones que
// escribir nosotros mismos.
Future<List<String>> executeListOfCommands(
MySQLConnection connection,
List<String> sqlCommands, {
bool verbose = false,
bool stop = true,
bool withTransaction = true,
}) async {
final errors = <String>[];
// ejecuta realmente los comandos en la conexión suministrada [cnx]: es
// o bien [connection] misma (sin transacción), o bien la conexión de "trabajo"
// que [transactional] entrega a su callback (con
// transacción) - el bucle se escribe una sola vez para ambos casos
Future<void> executeCommands(MySQLConnection cnx) async {
for (final rawCommand in sqlCommands) {
// elimina los espacios en blanco iniciales y finales del comando actual
final command = rawCommand.trim();
// ¿comando vacío o comentario? pasamos al siguiente
if (command == '' || command[0] == '#') {
continue;
}
// ejecución del comando actual
try {
final results = await cnx.execute(command);
// sin error
if (verbose) {
print('[$command]: Successful execution');
}
_displayInfo(results);
} catch (error) {
final msg = '$command: Error ($error)';
errors.add(msg);
if (verbose) {
print(msg);
}
// ¿nos detenemos?
if (withTransaction || stop) {
// con transacción: relanzamos el error para que
// [connection.transactional] active el ROLLBACK - con
// [package:mysql_client_plus], es la EXCEPCIÓN la que provoca
// la cancelación, no una simple salida del bucle como con el
// ROLLBACK manual de la versión con mysql1
if (withTransaction) rethrow;
return;
}
}
}
}
if (withTransaction) {
try {
await connection.transactional((cnx) => executeCommands(cnx));
} catch (_) {
// el error ya se registró en [errors] más arriba; aquí lo
// absorbemos para devolver normalmente la lista de errores
// al llamador, exactamente como lo hacía la versión con mysql1 (que nunca
// dejaba escapar una excepción de esta función)
}
} else {
await executeCommands(connection);
}
return errors;
}
// usa la conexión abierta [connection]
// ejecuta en esta conexión los comandos SQL contenidos en el
// archivo de texto [sqlFilename] (un comando por línea)
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"];
}
}
|
Comentemos este código:
- línea 20: [void _displayInfo(IResultSet results)]: distingue un SELECT ([results.cols] describe las columnas solicitadas) de una instrucción de actualización ([results.affectedRows], equivalente a [rowcount] de un cursor) - [results.cols]/[results.rows] reemplazan a [results.fields] de [mysql1], y [row.colByName(t)] reemplaza a la entrada [row.fields[t]].
- Líneas 61–67: [Future<List<String>> executeListOfCommands(MySQLConnection connection, List<String> sqlCommands, {bool verbose = false, bool stop = true, bool withTransaction = true}) async { ... }]: PARÁMETROS NOMBRADOS con valores predeterminados, sin cambios desde la versión [mysql1]—exactamente como los parámetros opcionales del objeto de configuración de TypeScript.
- Líneas 74–108: [Future<void> executeCommands(MySQLConnection cnx) async { ... }]: una función LOCAL (anidada), reutilizada tanto para el caso «con transacción» (en el que recibe la conexión de trabajo que [transactional] proporciona a su callback) como para el caso «sin transacción» (en el que recibe [connection] directamente)—así, el bucle de ejecución de comandos se escribe una sola vez. Con una transacción, es una EXCEPCIÓN relanzada ([rethrow]) la que provoca el ROLLBACK, y no una simple terminación del bucle como ocurría con el ROLLBACK manual en la versión [mysql1].
- Líneas 110–118: [if (withTransaction) { try { await connection.transactional((cnx) => executeCommands(cnx)); } catch (_) { ... } }]: [mysql2] expone directamente [connection.beginTransaction()]/[commit()]/[rollback()]. [package:mysql1] no exponía estos métodos uno por uno: había que controlar la transacción «manualmente» enviando usted mismo los comandos SQL [START TRANSACTION], [COMMIT] y [ROLLBACK]. [package:mysql_client_plus] por fin ofrece el equivalente directo de [mysql2]: [connection.transactional((cnx) async { ... })] ejecuta el callback dentro de una transacción, confirma automáticamente (COMMIT) si termina con normalidad y revierte automáticamente (ROLLBACK) si lanza una excepción—ya no es necesario escribir sus propias instrucciones SQL de control de transacciones.
- Líneas 128–134: [Future<List<String>> executeFileOfCommands(...) async { ... }]: lee un archivo ([File(sqlFilename).readAsString()]) y luego delega en [executeListOfCommands]—sin cambios desde la versión [mysql1], con la misma estructura que en TypeScript.
7.1.7. Script [mysql_04]
Este script principal coordina los dos scripts anteriores para ejecutar el archivo [data/commands.sql] (idéntico al del curso de TypeScript), con o sin transacción según el argumento de línea de comandos proporcionado.
| // mysql_04.dart
// Porta databases/mysql/mysql-04.ts.
//
// Script principal: ejecuta el archivo de comandos SQL
// [data/commands.sql], con o sin transacción según el argumento pasado
// en la línea de comandos.
// dart run mysql_04.dart true (con transacción)
// dart run mysql_04.dart false (sin transacción)
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
// verificación de la sintaxis de la llamada
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);
}
// cálculo de un texto
final withTransaction = withTransactionText == 'true';
final text = withTransaction ? 'with transaction' : 'without transaction';
// logs en pantalla
print('--------------------------------------------------------------------');
print('Executing the SQL file ${config.commandsFilename} $text');
print('--------------------------------------------------------------------');
// ejecución de las sentencias SQL del archivo
MySQLConnection? connection;
List<String> errors = [];
try {
// conexión a la base de datos - solo asignamos [connection] una vez que [connect]
// ha tenido éxito (ver el comentario en 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;
// ejecución del archivo de comandos SQL
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();
}
}
// visualización del número de errores
print('--------------------------------------------------------------------');
print('Execution completed');
print('--------------------------------------------------------------------');
print('There were ${errors.length} error(s)');
for (final currentError in errors) {
print(currentError);
}
}
|
Comentemos este código:
- Líneas 14–28: [Future<void> main(List<String> arguments) async { ... }]: [arguments] recibe los parámetros de la línea de comandos, igual que [process.argv.slice(2)] en el lado de Node—aquí se espera un solo argumento: [true] o [false].
- Líneas 45–53: [final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]: la conexión usa el mismo patrón de creación que [connect()], como se muestra en [mysql_01.dart], con parámetros tomados de [config] (incluido el nuevo campo [port]).
- Líneas 55–61: [executeFileOfCommands(connection, config.commandsFilename, verbose: true, stop: false, withTransaction: withTransaction)]: ejecuta [data/commands.sql], con o sin transacción según el argumento—[dart run mysql_04.dart true] o [dart run mysql_04.dart false].
Estas son dos posibles ejecuciones:
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. Script [mysql_05]
| // mysql_05.dart
// Porta databases/mysql/mysql-05.ts.
//
// Consultas parametrizadas: inserción preparada individual, luego inserción
// masiva. Aquí recreamos la tabla [persons] con el esquema de columna [id]
// (como en el script mysql_03), para que este script sea independiente del
// estado que deja mysql_04.
import 'package:mysql_client_plus/mysql_client_plus.dart';
// la identidad del usuario
const String id = 'admpersons';
const String pwd = 'nobody';
// la máquina host del SGBD
const String host = 'localhost';
const int port = 3306;
// identidad de la base de datos
const String database = 'dbpersons';
// [difference with TypeScript] `type Person = [id: number, lastName: string,
// firstName: string, age: number]` (una tupla de TypeScript, con nombre pero aún
// un simple array en tiempo de ejecución) se convierte aquí en un RECORD POSICIONAL de Dart 3
// (ver dart-fundamentals/dart3/dart3_01_records.dart): la misma idea de un
// "pequeño grupo de valores tipados, sin clase que escribir", pero un verdadero
// tipo por derecho propio, distinto de una [List].
typedef Person = (int id, String lastName, String firstName, int age);
Future<void> main() async {
// lista de personas (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),
];
// otra lista de personas
final otherPersons = <Person>[
for (var i = 0; i < 5; i++) (i + 100, 'l1$i', 'f1$i', i + 20),
(200, "d'Aboot", "F'ilhem", 34),
];
// acceso al SGBD
MySQLConnection? connection;
try {
// conexión - solo asignamos [connection] una vez que [connect] ha tenido éxito
// (ver el comentario en mysql_01.dart)
final newConnection = await MySQLConnection.createConnection(
host: host,
port: port,
userName: id,
password: pwd,
databaseName: database,
);
await newConnection.connect();
connection = newConnection;
// (re)creación de la tabla con el esquema de columna [id] (ver 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))',
);
// eliminación de los registros existentes
await connection.execute('delete from persons');
// inserciones persona por persona con una consulta parametrizada -
// desestructuración del record posicional [person] directamente en
// el encabezado del for (ver dart-fundamentals/dart3/dart3_02_patterns.dart)
//
// [difference with TypeScript and with mysql1] mysql2 (y mysql1, en
// una primera versión de este script) usan MARCADORES
// POSICIONALES ("?", asociados a una LISTA de valores en el mismo
// orden). [package:mysql_client_plus] funciona de otra manera: los
// marcadores son CON NOMBRE (":id", ":last_name"...) y se asocian a un [Map]
// (nombre del marcador -> valor) - más verboso de escribir aquí, pero
// hace que cada consulta sea independiente del ORDEN de los parámetros.
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},
);
}
// [difference with TypeScript] mysql2 ofrece
// `connection.query('insert ... values ?', [[[...],[...],...]])`, que
// construye por sí misma una única consulta de varias filas a partir de un
// array de arrays. [package:mysql_client_plus] no tiene un equivalente
// así (como mysql1 antes que él): por lo tanto, construimos nosotros mismos el texto SQL,
// con un grupo de marcadores CON NOMBRE por fila (":id0",
// ":last_name0"... ":id1", ":last_name1"...) ya que los marcadores con nombre
// no pueden repetirse en la misma consulta - un solo viaje de ida y vuelta
// por la red, como en la versión de TypeScript.
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,
);
// confirmación de la transacción - aquí cada consulta ya se confirmó
// automáticamente (MySQL está en modo AUTOCOMMIT por defecto, como el modo
// por defecto mencionado en el script mysql_03); por lo tanto, no hay nada que confirmar
// explícitamente
print('${persons.length + otherPersons.length} persons inserted.');
} catch (error) {
print("The following error occurred: $error");
} finally {
if (connection != null) {
await connection.close();
}
}
}
|
Comentemos este código:
- línea 25: [typedef Person = (int id, String lastName, String firstName, int age);]: la tupla de TypeScript, denominada [type Person = [id: number, lastName: string, firstName: string, age: number]] (un simple arreglo en tiempo de ejecución), se convierte en un REGISTRO POSICIONAL en Dart 3—un tipo de pleno derecho, distinto de una [List].
- Líneas 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}); }]: cada inserción preparada desestructura directamente el registro posicional en el encabezado del [for] (consulte el capítulo «Novedades de Dart» 3.x)—con marcadores de posición NOMBRADOS ([:id], [:last_name]...) asociados a un [Map], en lugar de los POSICIONALES ([?] + lista de valores) de [mysql1] y [mysql2].
- Líneas 90–99: [final placeholderGroups = <String>[]; final values = <String, Object?>{}; for (...) { placeholderGroups.add('(:id$i,:last_name$i,:first_name$i,:age$i)'); ... }]: [mysql2] admite directamente la inserción masiva a partir de un arreglo de arreglos ([values ?] con [[[...],[...]]]). [package:mysql_client_plus] no tiene este equivalente (al igual que [mysql1] antes): por lo tanto, hay que construir usted mismo el texto SQL, pero con un grupo de marcadores de posición—NOMBRADOS y NUMERADOS—por fila ([:id0], [:last_name0]... [:id1], [:last_name1]...), ya que los marcadores nombrados no pueden repetirse dentro de una misma consulta—un solo viaje de ida y vuelta por la red, como en la versión de TypeScript.
- Línea 93: [final (idP, lastName, firstName, age) = otherPersons[i];]: de nuevo una descomposición de registro posicional—necesaria aquí para nombrar individualmente cada marcador ([:id0], [:last_name0]...) a partir de los cuatro campos del registro, ya que [mysql_client_plus] no ofrece acceso posicional directo como [p.$1, p.$2...], que se usaba en la versión anterior de este script.
El resultado de la ejecución es el siguiente:
Puede verificar el resultado con HeidiSQL de Laragon:

7.1.9. Conclusión
El port del controlador nativo es fiel al original en TypeScript. Tras un primer intento con [package:mysql1]—que se abandonó por su incompatibilidad con MySQL 8.4—, [package:mysql_client_plus] ofrece finalmente una API aún más cercana a [mysql2] de lo que lo era [mysql1]: [connection.transactional(...)] es el equivalente directo de [beginTransaction()]/[commit()]/[rollback()], mientras que [mysql1] habría requerido gestionar manualmente la transacción con los comandos SQL [START TRANSACTION], [COMMIT] y [ROLLBACK]. Queda una diferencia, aunque más sutil: las columnas DECIMAL ([subjects.coefficient], [grades.value] en la base de datos [dbschool]) requieren una conversión explícita mediante un pequeño asistente [_decimal] ([typedColByName<String>(...)] y luego [num.parse(...)]), ya que el controlador no admite la conversión directa a [num] o [double] para este tipo SQL.
7.2. El ORM ligero

El curso de TypeScript dedica dos capítulos separados al acceso a bases de datos mediante un ORM ([Object-Relational Mapping]): [TypeORM], seguido de [Prisma], con el mismo esquema de ejemplo. Ambos se basan en un principio común: describir el esquema una sola vez (mediante decoradores de TypeORM en las clases, o un archivo [.prisma] en el caso de Prisma), y dejar que la herramienta genere, al iniciar o durante la compilación, todo el código que traduce las lecturas/escrituras de objetos a SQL—incluida la carga de las relaciones entre tablas.
Dart no tiene un equivalente maduro y ampliamente adoptado de estas dos herramientas para MySQL: existen bibliotecas ORM de Dart, pero están pensadas principalmente para Flutter/SQLite ([Drift], [Floor]) o para arquitecturas distintas - Prisma mismo no ofrece un cliente de Dart. En lugar de forzar una correspondencia artificial como «tal paquete de Dart = TypeORM» o «tal otro paquete = Prisma», este capítulo adopta un enfoque diferente y pedagógicamente más sólido: mostrar lo que realmente hace un ORM escribiéndolo uno mismo en una versión deliberadamente mínima—de ahí el nombre [light ORM].
7.2.1. Las entidades: el archivo [entities.dart]
| // entities.dart
// Porta las entidades de TypeORM (databases/typeorm/entities/*.entity.ts):
// Person (base de datos [dbpersons]), y SchoolClass / Student / Subject / Grade (base de datos
// [dbschool]).
//
// [fundamental difference with TypeScript] las entidades de TypeORM son
// clases ordinarias DECORADAS (`@Entity`, `@Column`, `@ManyToOne`...):
// es TypeORM, al arrancar, quien LEE estos decoradores (una forma de
// reflexión/metaprogramación) para saber cómo leer/escribir cada
// campo en SQL, y cómo cargar una relación bajo demanda. Dart no
// tiene un equivalente utilizable de la reflexión aquí (`dart:mirrors` está
// abandonado para la compilación web/AOT): por lo tanto, estas clases son simples
// "bolsas de campos" mutables, sin ninguna anotación - es toda
// la carpeta light_orm (repository.dart en particular) la que,
// escrita a mano, cumple el papel que la reflexión cumple para TypeORM. Vea
// el README.md de esta carpeta para la discusión completa.
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;
// relación inversa (backref de Student.schoolClass) - NO cargada
// automáticamente: permanece vacía mientras no llamemos explícitamente a
// una consulta que la llene (ver 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;
// relación N-1 con SchoolClass - null mientras no se haya cargado
// explícitamente (el equivalente de la opción `relations: { schoolClass: true }`
// de TypeORM, pero hecha visible aquí como un campo nulable ordinario)
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)';
}
|
Comentemos este código:
- Las entidades de TypeORM son clases ordinarias DECORADAS ([@Entity], [@Column], [@ManyToOne]...): es TypeORM quien, al iniciar, lee estos decoradores (una forma de reflexión) para determinar cómo leer/escribir cada campo en SQL y cargar una relación bajo demanda. Dart no tiene un equivalente de reflexión utilizable aquí ([dart:mirrors] está obsoleto para la compilación web/AOT): por lo tanto, estas clases son simplemente «bolsas de campos» mutables, sin ninguna anotación.
- línea 29: [class SchoolClass { ...; List<Student> students = []; }], [class Student { ...; SchoolClass? schoolClass; List<Grade> grades = []; }] (línea 43): las relaciones son campos simples (colección vacía o referencia nulable) que nunca se cargan automáticamente—es [repository.dart], escrito a mano, el que desempeña el papel que la reflexión desempeña para TypeORM.
7.2.2. El repositorio genérico: el archivo [repository.dart]
| // repository.dart
// Un "ORM ligero" escrito a mano: una clase genérica [Repository] fuertemente
// inspirada en el Repository de TypeORM (`AppDataSource.getRepository(...)`,
// `.find()`, `.findOneBy()`, `.save()`, `.delete()`), pero construida sobre
// una sola tabla, sin decoradores ni carga automática de
// relaciones - ver README.md para la discusión completa de esta decisión.
//
// [migration] este archivo usaba inicialmente [package:mysql1]; se ha
// portado a [package:mysql_client_plus] (ver el comentario en
// pubspec.yaml). El cambio más visible para quien llama es el
// estilo de las consultas parametrizadas: mysql1 usaba marcadores
// POSICIONALES ("?" + lista de valores en orden), mientras que
// [mysql_client_plus] usa marcadores CON NOMBRE (":column" + un
// [Map] nombre de columna -> valor) - lo que, aquí, encaja bastante bien
// ya que este repositorio ya maneja [Map<String, Object?>] de
// columnas.
import 'package:mysql_client_plus/mysql_client_plus.dart';
// [T]: el tipo de la entidad administrada por este repositorio (Person, SchoolClass...)
class Repository<T> {
final MySQLConnection connection;
// nombre de la tabla SQL
final String table;
// nombre de la columna de clave primaria
final String keyColumn;
// construye una entidad [T] a partir de una fila de resultado SQL
final T Function(ResultSetRow row) fromRow;
// devuelve las columnas SQL (nombre de columna -> valor) de una entidad [T],
// clave primaria INCLUIDA (útil tanto para la inserción como para la
// actualización)
final Map<String, Object?> Function(T entity) toColumns;
// extrae el valor de la clave primaria de una entidad [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,
});
// equivalente de `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();
}
// equivalente de `repo.findOneBy({ column: value })` - [conditions] es
// una igualdad "AND" sobre cada columna suministrada; las claves de [conditions]
// sirven a la vez como nombre de columna SQL y como nombre de marcador
// CON NOMBRE (":column") - por lo tanto, se reutilizan tal cual como
// parámetros de la consulta
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);
}
// equivalente de `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;
}
// equivalente de `repo.save(entity)`: inserción si la clave aún no
// existe, actualización en caso contrario - exactamente el comportamiento "upsert" de
// `save()` del lado de TypeORM
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(', ');
// las columnas a actualizar, MÁS la clave (con el mismo nombre de marcador
// que en la cláusula WHERE) - no es posible ninguna colisión
// ya que [keyColumn] ha sido excluida precisamente de [toUpdate]
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);
}
}
// equivalente de `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);
}
}
|
Comentemos este código:
- Líneas 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; ... }]: una clase GENÉRICA, configurada por el tipo de entidad [T], construida en torno a TRES FUNCIONES proporcionadas por quien la llama—cómo leer una fila SQL, cómo escribirla y cuál es su clave primaria. Esa es la totalidad del «mapeo objeto-relacional», reducido a lo esencial; solo ha cambiado el tipo de la primera función desde la versión [mysql1] ([ResultSetRow] en lugar de [ResultRow]).
- Línea 57: [final where = conditions.keys.map((c) => '$c = :$c').join(' and ');]: las claves de [conditions] sirven a la vez como nombre de columna para SQL y como nombre del MARCADOR NOMBRADO ([:column])—a diferencia de [mysql1], que usaba marcadores POSICIONALES ([?] más una LISTA de valores en orden), [mysql_client_plus] espera un [Map] (nombre del marcador → valor), lo cual resulta bastante conveniente porque este repositorio ya maneja [Map<String, Object?>] para las columnas.
- Líneas 45–63: [Future<List<T>> findAll({String? orderBy}) async { ... }], [Future<T?> findOneBy(Map<String, Object?> conditions) async { ... }]: los equivalentes directos de [repo.find(...)] y [repo.findOneBy(...)] de TypeORM - [execute()] reemplaza a [query()], y [results.rows] contiene las filas del resultado (en lugar de la lista devuelta directamente por [mysql1]).
- Líneas 78–96: [Future<void> save(T entity) async { ...; final alreadyExists = await findOneBy(...) != null; if (alreadyExists) { ... update ... } else { ... insert ... } }]: el comportamiento de «upsert» de [repo.save(...)]—insertar si la clave aún no existe, actualizar en caso contrario—permanece sin cambios desde la versión [mysql1], salvo por el estilo de los marcadores de posición.
7.2.3. Script [orm_01_persons]
| // orm_01_persons.dart
// Porta databases/typeorm/typeorm-01.ts.
//
// Primer uso del "ORM ligero": abrir la conexión, luego leer
// y escribir en la tabla [persons] a través del [Repository<Person>],
// sin escribir una sola línea de SQL en ESTE archivo (todo el SQL está
// en repository.dart, escrito una vez por todas para todas las entidades).
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',
// [mysql_client_plus migration] mysql1 ya decodificaba cada columna
// al tipo nativo de Dart esperado ([row.fields['id'] as int]
// funcionaba directamente). [package:mysql_client_plus] exige un acceso
// TIPADO explícito por columna - [typedColByName<T>(name)] - que
// se encarga él mismo de la conversión; el [!] es seguro aquí ya que
// estas columnas son NOT NULL en el esquema SQL.
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,
);
// todas las personas, ordenadas por apellido
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)');
}
// una persona por su clave primaria
final paul = await repo.findOneBy({'id': 1});
print('Person id=1: ${paul != null ? '${paul.firstName} ${paul.lastName}' : 'not found'}');
// inserción de una nueva persona (la entidad es una clase simple:
// el constructor basta, sin necesidad de una fábrica especial)
final newPerson = Person(id: 99, firstName: 'Ada', lastName: 'Lovelace', age: 36);
await repo.save(newPerson);
print('Person 99 inserted.');
// actualización
newPerson.age = 37;
await repo.save(newPerson);
print('After update, age=${(await repo.findOneBy({'id': 99}))?.age}');
// eliminación - dejamos la base de datos en el estado en que la encontramos
await repo.delete({'id': 99});
print('Person 99 deleted.');
} finally {
await connection.close();
}
}
|
Comentemos este código:
- Líneas 24–42: [final repo = Repository<Person>(connection, table: 'persons', keyColumn: 'id', fromRow: (row) => Person(...), toColumns: (p) => {...}, key: (p) => p.id);]: construye un repositorio para la entidad [Person], proporcionándole las tres funciones esperadas—el único lugar del archivo que «conoce» los detalles de las columnas SQL. [mysql1] ya decodificaba cada columna al tipo nativo de Dart esperado ([row.fields['id'] as int] funcionaba directamente); [mysql_client_plus] exige un acceso TIPADO columna por columna—[typedColByName<T>(name)]—que se encarga de la conversión.
- El resto del script ([repo.findAll], [repo.findOneBy], [repo.save], [repo.delete]) ya no contiene ninguna línea de SQL—exactamente la misma experiencia que ofrece TypeORM a diario, sin cambios por la migración.
El resultado de la ejecución es el siguiente:
| 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. Script [orm_02_school]
| // orm_02_school.dart
// Porta databases/typeorm/typeorm-02.ts.
//
// Mapeo de tres entidades de la base de datos [dbschool] (SchoolClass, Student, Subject)
// y manipulaciones básicas (CRUD) a través de sus repositorios.
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'entities.dart';
import 'repository.dart';
// lee una columna SQL DECIMAL/NUMERIC (aquí [subjects.coefficient]) como un
// [num]. [package:mysql_client_plus] puede convertir un DECIMAL a
// [String] (cualquier tipo SQL puede leerse como [String]), pero NO
// directamente a [num] o [double] - `typedColByName<num>(...)` lanza entonces
// "Cannot convert MySQL type 246 to requested type num" (246 =
// NEWDECIMAL, el tipo interno de MySQL de las columnas DECIMAL). Por eso leemos la
// columna como [String], y luego la convertimos nosotros mismos.
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);
// todas las clases
print('Classes:');
for (final c in await classRepo.findAll(orderBy: 'name asc')) {
print(' ${c.id} ${c.name}');
}
// todas las materias, con su coeficiente
print('Subjects:');
for (final s in await subjectRepo.findAll(orderBy: 'name asc')) {
print(' ${s.id} ${s.name} (coefficient ${s.coefficient})');
}
// adición de un nuevo estudiante en [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}.');
// relectura - [difference with TypeScript] typeorm-02.ts especifica
// `relations: { schoolClass: true }` para cargar la clase asociada al
// mismo tiempo que el estudiante. [Repository.findOneBy] puede cargar SOLO
// la tabla [students] (sin join automático): por eso obtenemos
// la clase nosotros mismos, con una segunda consulta explícita -
// exactamente la consulta adicional que TypeORM dispara por
// nosotros detrás de `relations: { schoolClass: true }`, pero VISIBLE aquí.
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}');
// eliminación - dejamos la base de datos en el estado en que la encontramos
await studentRepo.delete({'id': 999});
print('Student 999 deleted.');
} finally {
await connection.close();
}
}
|
Analicemos este código:
- Líneas 10–17: [num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]: [mysql_client_plus] puede convertir una columna SQL DECIMAL (aquí [subjects.coefficient]) a [String] (cualquier tipo, como SQL, se puede leer como [String]), pero no puede convertirla directamente a [num] o [double] - [typedColByName<num>(...)] produce entonces [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num] (246 = NEWDECIMAL, el tipo interno de MySQL de las columnas DECIMAL). Por lo tanto, la columna se lee como [String] y luego se convierte manualmente.
- Tres funciones privadas—[_classRepo], [_studentRepo] y [_subjectRepo]—construyen cada una un [Repository] para una de las tres entidades de [dbschool]; solo [_subjectRepo] usa [_decimal] para la columna [coefficient].
- Líneas 99–100: [final reread = await studentRepo.findOneByOrFail({'id': 999}); reread.schoolClass = await classRepo.findOneByOrFail({'id': reread.classId});]: mientras que [typeorm-02.ts] especifica [relations: { schoolClass: true }] para cargar la clase asociada junto con el estudiante, [Repository.findOneBy] solo puede leer de la tabla [students] (sin unión automática)—por eso obtenemos la clase nosotros mismos, con una segunda consulta explícita: exactamente la consulta adicional que TypeORM dispara tras bambalinas, pero aquí hecha VISIBLE.
El resultado de la ejecución es el siguiente:
| 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. Script [orm_03_joined_queries]
| // orm_03_joined_queries.dart
// Porta databases/typeorm/typeorm-03-joined-queries.ts.
//
// Pone de relieve las consultas SQL que hay que escribir para obtener
// información repartida en varias tablas - lo que TypeORM dispara por
// usted detrás de la opción `relations`, mediante un JOIN de SQL
// (`JOIN`). A diferencia de orm_02_school.dart (que simulaba la carga de una
// relación con DOS consultas separadas, para simplificar), este archivo
// escribe los VERDADEROS joins de SQL - exactamente lo que hace TypeORM detrás
// de escena, pero hecho enteramente visible.
//
// [fundamental difference with TypeScript] TypeORM (como SQLAlchemy, usado
// por el curso original de Python) NO hace carga diferida por defecto
// en entidades "clásicas": las relaciones a cargar deben solicitarse
// explícitamente, con la opción `relations`. Nuestro "ORM ligero" lleva
// este principio aún más lejos, ya que aquí no hay NI carga diferida
// NI carga "mágica" de relaciones: cada join es
// SQL escrito a mano, línea por línea - el precio a pagar por no depender
// de ninguna biblioteca de mapeo objeto-relacional.
//
// [mysql_client_plus migration] como en repository.dart, los
// marcadores posicionales ("?") de mysql1 pasan a ser marcadores
// CON NOMBRE (":id", ":name"...), y el acceso a las columnas de una
// fila de resultado ([row.fields['x']] con mysql1) pasa a ser una llamada
// tipada ([row.typedColByName<T>('x')]).
import 'package:mysql_client_plus/mysql_client_plus.dart';
import 'entities.dart';
// lee una columna SQL DECIMAL/NUMERIC (aquí [grades.value] y
// [subjects.coefficient]) como un [num]. [package:mysql_client_plus] puede
// convertir un DECIMAL a [String] (cualquier tipo SQL puede leerse
// como [String]), pero NO directamente a [num] o [double] -
// `typedColByName<num>(...)` lanza entonces "Cannot convert MySQL type 246 to
// requested type num" (246 = NEWDECIMAL, el tipo interno de MySQL de las
// columnas DECIMAL). Por eso leemos la columna como [String], y luego la
// convertimos nosotros mismos.
num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);
// estudiante por id, con su clase (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')!),
);
}
// clase por id, con la lista de sus estudiantes (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;
}
// clase por NOMBRE, con la lista de sus estudiantes
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;
}
// estudiante por APELLIDO, con su clase
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')!),
);
}
// calificaciones de un estudiante, con la materia de cada calificación (doble 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;
}
// materia por NOMBRE, con la lista de sus calificaciones
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 {
// estudiante por id, con su clase (join explícito)
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}"}');
// los estudiantes de la misma clase (nueva consulta, con su propio
// 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}"}');
}
// un estudiante por su apellido
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}"}');
// las calificaciones de un estudiante, con la materia de cada calificación
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}"}');
}
// los estudiantes de una clase, por nombre de clase
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}"}');
}
}
// las calificaciones de una materia, por nombre de materia
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();
}
}
|
Analicemos este código:
- A diferencia de [orm_02_school.dart] (dos consultas separadas), este archivo escribe las uniones SQL REALES—exactamente lo que hace TypeORM tras bambalinas mediante la opción [relations], pero aquí completamente visible.
- Líneas 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 (relación obligatoria) y LEFT JOIN (relación opcional; una clase puede no tener estudiantes) - la distinción que TypeORM elige por usted según la opcionalidad declarada de la relación. Los marcadores posicionales ([?]) de [mysql1] pasan a ser marcadores NOMBRADOS ([:id]), y el acceso a las columnas de una fila ([row['x']] o [row.fields['x']] con [mysql1]) pasa a ser una llamada tipada ([row.typedColByName<T>('x')]).
- Línea 135: [value: _decimal(row, 'g_value')], [coefficient: _decimal(row, 'sub_coefficient')]: el mismo asistente [_decimal] que en [orm_02_school.dart], necesario aquí para las dos columnas DECIMAL, [grades.value] y [subjects.coefficient].
- TypeORM (como SQLAlchemy) no realiza carga diferida de forma predeterminada en las entidades «estándar»: es necesario solicitar explícitamente las relaciones con la opción [relations]. El ORM ligero lleva este principio aún más lejos, ya que aquí no hay carga diferida—ninguna carga «mágica» de relaciones: cada unión se escribe a mano—el precio que se paga por no depender de ninguna biblioteca de mapeo objeto-relacional.
El resultado de la ejecución es el siguiente:
| 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. Script [orm_04_stats]
| // orm_04_stats.dart
// Porta databases/typeorm/typeorm-04-stats.ts.
//
// Calcula, para un estudiante dado, su promedio ponderado por los coeficientes
// de las materias, así como su calificación mínima y máxima.
//
// [difference with TypeScript] typeorm-04-stats.ts advertía que las columnas
// `decimal` de MySQL (aquí grade.value y subject.coefficient)
// las devuelve el controlador mysql2 como CADENAS DE
// CARACTERES en tiempo de ejecución (para no perder precisión), a pesar de su tipo
// declarado `number` - una trampa clásica de TypeScript, donde el tipo
// estático puede mentir sobre el valor real en tiempo de ejecución. Del lado de Dart,
// [package:mysql_client_plus] tiene una trampa similar, pero hecha VISIBLE por el
// compilador en lugar de oculta en tiempo de ejecución: el acceso tipado
// (`typedColByName<T>(...)`) no puede convertir una columna DECIMAL
// (tipo SQL interno 246, "NEWDECIMAL") ni a [num] ni a [double] -
// lanza `MySQLProtocolException: Cannot convert MySQL type 246 to requested
// type num`. La única conversión garantizada para CUALQUIER tipo SQL es
// [String]; por eso leemos las columnas DECIMAL como [String] con
// `typedColByName<String>(...)`, y luego las convertimos nosotros mismos con
// [num.parse] - ver [_decimal] a continuación.
import 'package:mysql_client_plus/mysql_client_plus.dart';
// lee una columna SQL DECIMAL/NUMERIC como un [num] (ver el comentario al
// inicio del archivo)
num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);
// calcula las estadísticas (promedio ponderado, mínimo, máximo) de un estudiante
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) {
// conversión explícita mediante [_decimal] (ver la nota al inicio del archivo):
// [value] y [coefficient] son por lo tanto [num]s reales, no cadenas
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 {
// estudiante id=11: calificaciones subject1=10 (coef 1.0), subject2=6 (coef 2.0)
// promedio ponderado = (10*1.0 + 6*2.0) / (1.0+2.0) = 22/3 = 7.33
await _studentStats(connection, 11);
print('');
// estudiante id=21: calificaciones subject1=12 (coef 1.0), subject2=8 (coef 2.0)
await _studentStats(connection, 21);
print('');
// estudiante id=32: calificaciones subject1=14 (coef 1.0), subject2=10 (coef 2.0)
await _studentStats(connection, 32);
print('');
// estudiante id=42: calificaciones subject1=16 (coef 1.0), subject2=12 (coef 2.0)
await _studentStats(connection, 42);
} finally {
await connection.close();
}
}
|
Comentemos este código:
- [typeorm-04-stats.ts] indicaba que las columnas [decimal] de MySQL (en este caso, [grade.value] y [subject.coefficient]) son devueltas por [mysql2] como CADENAS DE CARACTERES en tiempo de ejecución (para no perder precisión), a pesar de que su tipo declarado es [number]—una trampa clásica de TypeScript, en la que el tipo estático puede no reflejar el valor real en tiempo de ejecución.
- Línea 26: [num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]: en el lado de Dart, [package:mysql_client_plus] tiene una trampa similar a la de TypeScript, pero hecha VISIBLE por el compilador en lugar de oculta en tiempo de ejecución: el acceso tipado ([typedColByName<T>(...)]) no puede convertir una columna DECIMAL ni a [num] ni a [double]—lanza [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num]. La única conversión garantizada para cualquier tipo SQL es a [String]; por eso las columnas DECIMAL se leen como [String] y luego se convierten manualmente con [num.parse].
- Línea 67: [final average = weightedSum / coefficientsSum;]: el cálculo del promedio ponderado es idéntico al de la versión en TypeScript y al de la versión [mysql1]—solo ha cambiado la LECTURA de las columnas DECIMAL.
El resultado de la ejecución es el siguiente:
| 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. Lo que el ORM ligero no hace
A diferencia de TypeORM/Prisma: sin generación de esquemas ([synchronize]/migraciones), sin decoradores, sin carga diferida ni caché de identidad, sin constructor de consultas ([QueryBuilder]), y la carga de una relación es SIEMPRE una segunda consulta o una unión escrita a mano—nunca automática. Es un compromiso deliberado: lo suficiente para ilustrar el patrón de repositorio con el ejemplo del curso, sin pretender reemplazar a un repositorio real en producción.