Skip to content

7. Acceso a bases de datos

Image

Los capítulos siguientes completan el curso al abordar el acceso a bases de datos desde scripts TypeScript, inspirándose en los capítulos “Uso del SGBD MySQL” y “Uso del ORM SQLAlchemy” del curso “Introducción a Python 3 y al framework Flask” (2019). Se presentan sucesivamente tres enfoques: el acceso directo al SGBD mediante el driver nativo mysql2, seguido de dos enfoques de ORM (mapeo objeto-relacional): TypeORM y Prisma.

7.1. Acceso directo a la base de datos

Dos scripts SQL, incluidos con este capítulo, permiten crear las bases de datos de prueba: dbpersons (una sola tabla, usada en el capítulo sobre el driver nativo) y dbschool (cuatro tablas interrelacionadas, usadas en los dos capítulos sobre ORM).

Image

7.1.1. Preparación de la base de datos [dbpersons]

La base de datos dbpersons contiene una sola tabla, persons, que usa 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 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 (los originales del curso de 2020
-- Python/Flask 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 en 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 usar la herramienta [HeidiSQL] de Laragon. Ya la hemos utilizado.

  • 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;

Mediante [1-2], ejecute uno tras otro los dos archivos SQL del proyecto:

Image

Sin salir de [HeidiSQL], presione F5 para actualizar la visualización:

Ya estamos listos para usar estas dos bases de datos.

7.1.2. script [mysql-01]

Primer vistazo al driver mysql2 (módulo mysql2/promise, que expone una API basada en Promises en lugar de callbacks): abrir una conexión a dbpersons y luego cerrarla. Sigue el mismo enfoque que el script Python [mysql_01] (capítulo 16).

// databases/mysql/mysql-01.ts
// Primer paso: conectarse a la base de datos MySQL [dbpersons] y luego
// desconectarse. Porta el script Python [mysql_01] del curso Python/Flask.
import mysql from 'mysql2/promise';

// conexión a la base de datos MySQL [dbpersons]
// la identidad del usuario es (admpersons, nobody)
const USER = 'admpersons';
const PWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// allá vamos
let connection: mysql.Connection | undefined;
try {
  console.log('Connecting to the MySQL DBMS...');
  // conexión
  connection = await mysql.createConnection({ host: HOST, user: USER, password: PWD, database: DATABASE });
  // continuación
  console.log(
    `Successful MySQL connection to database=${DATABASE}, host=${HOST} as user=${USER}, passwd=${PWD}`,
  );
} catch (error) {
  // mostrar el error
  console.log(`The following error occurred: ${error}`);
} finally {
  // cerrar la conexión si se abrió
  if (connection) {
    await connection.end();
  }
}

Comentemos este código:

  • línea 16: [mysql.createConnection({ host: HOST, user: USER, password: PWD, database: DATABASE })] : abre una única conexión asíncrona; createConnection devuelve una Promise<Connection>, de ahí el await; es el equivalente en TypeScript de mysql.connector.connect(...) en el lado de Python;
  • línea 29: [connection.end()] : cierra la conexión de forma ordenada en el bloque finally, ocurra o no un error; la conexión se declara fuera del bloque try (tipo mysql.Connection | undefined) para seguir siendo accesible en este nivel.

Ejecutemos este script:

npx tsx databases/mysql/mysql-01.ts

Resultado de la ejecución:

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

7.1.3. script [mysql-02]

Esta vez, la conexión se encapsula en una función reutilizable connect(host, database, login, pwd), que se llama primero con credenciales válidas y luego por segunda vez con credenciales no válidas para observar el error devuelto por el driver. El script Python se llama **[mysql\_02]**.

// databases/mysql/mysql-02.ts
// En este nuevo script, la conexión a la base de datos se aísla en una función.
// Porta el script Python [mysql_02].
import mysql from 'mysql2/promise';

// 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
async function connect(host: string, database: string, login: string, pwd: string): Promise<void> {
  let cnx: mysql.Connection | undefined;
  try {
    // conexión
    cnx = await mysql.createConnection({ host, user: login, password: pwd, database });
    console.log(
      `Successful connection to database=${database}, host=${host} as user=${login}, passwd=${pwd}`,
    );
  } finally {
    // cerrar la conexión si se abrió
    if (cnx) {
      await cnx.end();
      console.log('Successful disconnection\n');
    }
  }
}

// - - - main
// credenciales de conexión
const USER = 'admpersons';
const PASSWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// conexión de un usuario existente
try {
  await connect(HOST, DATABASE, USER, PASSWD);
} catch (error) {
  // mostrar el error
  console.log(String(error));
}

// conexión de un usuario inexistente
try {
  await connect(HOST, DATABASE, 'xx', 'xx');
} catch (error) {
  // mostrar el error
  console.log(String(error));
}

Comentemos este código:

  • línea 9: [async function connect(host, database, login, pwd): Promise<void>] : una función async que no devuelve nada pero puede lanzar una excepción; no captura por sí misma los errores de conexión, sino que los deja propagarse hacia quien la llama;
  • línea 40: [await connect(HOST, DATABASE, 'xx', 'xx')] : la segunda llamada, con un usuario “xx” que no existe en el lado de MySQL, lanza una excepción que el bloque catch envolvente muestra.

Ejecutemos este script:

npx tsx databases/mysql/mysql-02.ts

Resultado de la ejecución:

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

Error: Access denied for user 'xx'@'localhost' (using password: YES)
Problema específico de la versión: en un servidor MySQL reciente (8.4 y posteriores), esta segunda llamada puede producir un mensaje distinto: "Error: Plugin 'mysql_native_password' is not loaded" en lugar de "Access denied for user 'xx'@'localhost'." La causa no tiene relación con el script: para evitar revelar si una cuenta existe o no (protección contra la enumeración), MySQL simula un intercambio de autenticación al iniciar sesión con un usuario desconocido, y esta simulación está codificada para usar el plugin heredado mysql_native_password, que está deshabilitado por defecto desde MySQL 8.4. El principio que demuestra este script (una excepción lanzada e interceptada ante credenciales no válidas) permanece intacto; para recuperar el mensaje exacto mostrado, agregue `mysql_native_password=ON` debajo de `[mysqld]` en el archivo `my.ini` del servidor y luego reinicie el servidor.

7.1.4. script [mysql-03]

Ya sabemos conectarnos; ahora emitimos un comando SQL a través de la conexión para (re)crear la tabla “persons” con un esquema ligeramente distinto (sin la columna “id”, usando una clave primaria compuesta). De esto se encarga el script Python [mysql_03].

// 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].
// Porta el script Python [mysql_03].
import mysql from 'mysql2/promise';

// ejecuta una consulta de actualización sobre la conexión
async function executeSql(connection: mysql.Connection, query: string): Promise<void> {
  await connection.query(query);
}

// - - - main
// credenciales de conexión
const ID = 'admpersons';
const PWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// vamos paso a paso
let connection: mysql.Connection;
try {
  // conexión - mysql2 ejecuta cada consulta en su propia transacción,
  // con confirmación automática por defecto (equivalente de AUTOCOMMIT=True en el lado de Python)
  connection = await mysql.createConnection({ host: HOST, user: ID, password: PWD, database: DATABASE });
} catch (error) {
  console.log(`The following error occurred: ${error}`);
  process.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
}

// 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);
  console.log(`${query}: query succeeded`);
} catch (error) {
  console.log(`The following error occurred: ${error}`);
} finally {
  await connection.end();
}

Comentemos este código:

  • línea 9: [await connection.query(query)] — connection.query() ejecuta directamente una cadena SQL sin parámetros; veremos la versión parametrizada, más segura, con execute() en el script [mysql-05];
  • Línea 28: [await executeSql(connection, 'drop table persons')] : se intenta eliminar la tabla dentro de un bloque try/catch vacío: si la tabla aún no existe, el error de MySQL simplemente se ignora.

Ejecutemos este script:

npx tsx databases/mysql/mysql-03.ts

Resultado de la ejecución:

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. Un módulo reutilizable: [mysql-module.ts]

Antes de escribir el script principal [mysql-04], que ejecuta un archivo completo de comandos SQL, extraemos a un módulo la lógica de ejecución de una lista de comandos, con o sin transacción, junto con la presentación del resultado de cada comando (filas de un SELECT, o el número de filas modificadas para un INSERT/UPDATE/DELETE). El módulo Python se llama [mysql_module].

// databases/mysql/mysql-module.ts
// Funciones reutilizables para ejecutar una lista (o un archivo) de comandos SQL
// sobre una conexión MySQL abierta. Porta el módulo Python [mysql_module].
import type { Connection, FieldPacket, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
import { readFile } from 'node:fs/promises';

// muestra el resultado de un comando SQL (resultado de un query() de mysql2)
// - si hay un arreglo [fields], era un SELECT: mostramos las columnas
//   y luego las filas;
// - en caso contrario, era una sentencia de actualización (INSERT/UPDATE/DELETE/DDL):
//   mostramos el número de filas modificadas (equivalente de cursor.rowcount).
function displayInfo(rows: RowDataPacket[] | ResultSetHeader, fields: FieldPacket[] | undefined): void {
  if (fields && fields.length > 0) {
    // era un SELECT - fields describe las columnas solicitadas
    const titles = fields.map((f) => f.name);
    console.log(titles.join(', '));
    console.log('*'.repeat(titles.join(', ').length));
    for (const row of rows as RowDataPacket[]) {
      console.log(titles.map((t) => row[t]));
    }
    console.log('*'.repeat(titles.join(', ').length));
  } else {
    // sin columnas descritas - sentencia de actualización
    const header = rows as ResultSetHeader;
    console.log(`number of modified rows: ${header.affectedRows}`);
  }
}

// usa la conexión abierta [connection]
// ejecuta sobre esta conexión los comandos SQL contenidos en la lista [sqlCommands]
// (un comando por elemento; las líneas vacías o que empiezan por # se ignoran)
// - si verbose=true, cada ejecución de una sentencia SQL va seguida de una visualización
//   que indica su éxito o su fallo;
// - si stop=true, la función se detiene en el 1.er error encontrado; en caso contrario
//   ejecuta todos los comandos;
// - si withTransaction=true, cualquier error cancela todas las sentencias SQL
//   ejecutadas antes (rollback); en caso contrario cada comando se confirma
//   de forma independiente (comportamiento por defecto de mysql2);
// la función devuelve un arreglo [error1, error2, ...]
export async function executeListOfCommands(
  connection: Connection,
  sqlCommands: string[],
  verbose = false,
  stop = true,
  withTransaction = true,
): Promise<string[]> {
  const errors: string[] = [];
  if (withTransaction) {
    await connection.beginTransaction();
  }
  try {
    for (const rawCommand of sqlCommands) {
      // elimina los espacios en blanco iniciales y finales del comando actual
      const command = rawCommand.trim();
      // ¿comando vacío o comentario? pasamos al siguiente
      if (command === '' || command[0] === '#') {
        continue;
      }
      // ejecución del comando actual
      try {
        const [rows, fields] = await connection.query(command);
        // sin error
        if (verbose) {
          console.log(`[${command}]: Successful execution`);
        }
        displayInfo(rows as RowDataPacket[], fields);
      } catch (error) {
        const msg = `${command}: Error (${error})`;
        errors.push(msg);
        if (verbose) {
          console.log(msg);
        }
        // ¿nos detenemos?
        if (withTransaction || stop) {
          return errors;
        }
      }
    }
    return errors;
  } finally {
    // confirmar / revertir la transacción si existe
    if (withTransaction) {
      if (errors.length > 0) {
        await connection.rollback();
      } else {
        await connection.commit();
      }
    }
  }
}

// usa la conexión abierta [connection]
// ejecuta sobre esta conexión los comandos SQL contenidos en el
// archivo de texto [sqlFilename] (un comando por línea)
export async function executeFileOfCommands(
  connection: Connection,
  sqlFilename: string,
  verbose = false,
  stop = true,
  withTransaction = true,
): Promise<string[]> {
  try {
    const content = await readFile(sqlFilename, 'utf-8');
    return await executeListOfCommands(connection, content.split('\n'), verbose, stop, withTransaction);
  } catch (error) {
    return [`The file ${sqlFilename} could not be processed: ${error}`];
  }
}

Comentemos este código:

  • línea 45: [if (withTransaction) { await connection.beginTransaction(); }] : mysql2 está en modo AUTOCOMMIT de forma predeterminada (cada consulta se confirma individualmente); beginTransaction() cambia explícitamente la conexión al modo transaccional, tal como lo haría connexion.start_transaction() en el lado de Python;
  • línea 76: [if (withTransaction || stop) { return errors; }] : en modo transaccional, el primer error termina de inmediato el bucle; continuar sería inútil, ya que toda la transacción se revertirá de todos modos;
  • línea 82: [if (errors.length > 0) { await connection.rollback(); } else { await connection.commit(); }] : commit o rollback global, según haya ocurrido o no un error; véase, sin embargo, la trampa señalada en el script [mysql-04] más adelante.

El script también usa un pequeño módulo de configuración, config-04.ts, que centraliza la ruta del archivo de comandos SQL y las credenciales de inicio de sesión:

// databases/mysql/config-04.ts
// Configuración del script [mysql-04]: ruta del archivo de comandos SQL y
// credenciales de conexión de la base de datos [dbpersons].
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const scriptDir = dirname(fileURLToPath(import.meta.url));

export function configure() {
  return {
    // archivo de comandos SQL
    commandsFilename: join(scriptDir, 'data', 'commands.sql'),
    // credenciales de conexión a la base de datos
    host: 'localhost',
    database: 'dbpersons',
    user: 'admpersons',
    password: 'nobody',
  };
}
Nota: import.meta.url seguido de fileURLToPath/dirname es el método estándar, tal como se define en el módulo ECMAScript ("type": "module" en package.json), para obtener el directorio del archivo actual; el equivalente de la variable mágica __dirname, que está disponible de forma nativa en CommonJS pero no en ESM.

El script en sí, data/commands.sql, sigue el formato usado en el curso de Python (un comando por línea; las líneas vacías o que comienzan con # se ignoran):

Image

# eliminación de la tabla [persons]
drop table persons
# creación de la tabla persons
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))
# inserción de dos personas
insert into persons(first_name, last_name, age) values('Paul','Langevin',48)
insert into persons(first_name, last_name, age) values ('Sylvie','Lefur',70)
# visualización de la tabla
select first_name, last_name, age from persons
# error deliberado
xx
# inserción de tres personas
insert into persons(first_name, last_name, age) values ('Pierre','Nicazou',35)
insert into persons(first_name, last_name, age) values ('Geraldine','Colou',26)
insert into persons(first_name, last_name, age) values ('Paulette','Girond',56)
# visualización de la tabla
select first_name, last_name, age from persons
# lista de personas en orden alfabético de apellidos y, para apellidos iguales, en orden alfabético de nombres
select last_name,first_name from persons order by last_name asc, first_name desc
# lista de personas con una edad en el intervalo [20,40] en orden descendente de edad
# luego, para edades iguales, en orden alfabético de apellidos y, para apellidos iguales, en orden alfabético de nombres
select last_name,first_name,age from persons where age between 20 and 40 order by age desc, last_name asc, first_name asc
# inserción de la Sra. Bruneau
insert into persons(first_name, last_name, age) values('Josette','Bruneau',46)
# actualización de su edad
update persons set age=47 where last_name='Bruneau'
# lista de personas cuyo apellido es Bruneau
select last_name,first_name,age from persons where last_name='Bruneau'
# eliminación de la Sra. Bruneau
delete from persons where last_name='Bruneau'
# lista de personas cuyo apellido es Bruneau
select last_name,first_name,age from persons where last_name='Bruneau'

7.1.6. script [mysql-04]

El script principal: ejecuta el archivo data/commands.sql mediante el módulo anterior, con o sin transacción según un parámetro de la línea de comandos. Equivale al script Python [mysql_04].

// databases/mysql/mysql-04.ts
// Script principal: ejecuta el archivo de comandos SQL [data/commands.sql],
// con o sin transacción según el parámetro de la línea de comandos.
// Porta el script Python [mysql_04].
//   npx tsx databases/mysql/mysql-04.ts true   (con transacción)
//   npx tsx databases/mysql/mysql-04.ts false  (sin transacción)
import mysql from 'mysql2/promise';
import { configure } from './config-04.js';
import { executeFileOfCommands } from './mysql-module.js';

const config = configure();

// - - - main
// verificación de la sintaxis de la llamada
const args = process.argv.slice(2);
let error = args.length !== 1;
let withTransactionText = '';
if (!error) {
  withTransactionText = args[0].toLowerCase();
  error = withTransactionText !== 'true' && withTransactionText !== 'false';
}
if (error) {
  console.log('syntax: mysql-04.ts true / false');
  process.exit(1);
}

// cálculo de un texto
const withTransaction = withTransactionText === 'true';
const text = withTransaction ? 'with transaction' : 'without transaction';

// logs en pantalla
console.log('--------------------------------------------------------------------');
console.log(`Executing the SQL file ${config.commandsFilename} ${text}`);
console.log('--------------------------------------------------------------------');

// ejecución de las sentencias SQL del archivo
let connection: mysql.Connection | undefined;
let errors: string[] = [];
try {
  // conexión a la base de datos
  connection = await mysql.createConnection({
    host: config.host,
    user: config.user,
    password: config.password,
    database: config.database,
  });
  // ejecución del archivo de comandos SQL
  errors = await executeFileOfCommands(connection, config.commandsFilename, true, false, withTransaction);
} catch (fatalError) {
  console.log(`The following fatal error occurred: ${fatalError}`);
  process.exit(1);
} finally {
  if (connection) {
    await connection.end();
  }
}

// visualización del número de errores
console.log('--------------------------------------------------------------------');
console.log('Execution completed');
console.log('--------------------------------------------------------------------');
console.log(`There were ${errors.length} error(s)`);
for (const currentError of errors) {
  console.log(currentError);
}

Ejecutémoslo primero sin transacción:

npx tsx databases/mysql/mysql-04.ts false

Resultado de la ejecución:

--------------------------------------------------------------------
Executing the SQL file .../databases/mysql/data/commands.sql without transaction
--------------------------------------------------------------------
[drop table persons]: Successful execution
number of modified rows: 0
[create table persons (...)]: 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 (Error: You have an error in your SQL syntax; ... near 'xx' at line 1)
[insert into persons(first_name, last_name, age) values ('Pierre','Nicazou',35)]: Successful execution
[insert into persons(first_name, last_name, age) values ('Geraldine','Colou',26)]: Successful execution
[insert into persons(first_name, last_name, age) values ('Paulette','Girond',56)]: Successful execution
[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 ]
**************************
(... rest of the SELECT/UPDATE/DELETE commands of the commands file, all executed despite the error ...)
--------------------------------------------------------------------
Execution completed
--------------------------------------------------------------------
There were 1 error(s)
xx: Error (Error: You have an error in your SQL syntax; ... near 'xx' at line 1)

Sin transacción, cada comando se confirma de forma independiente: el único error intencional (el comando xx) no impide que se ejecuten los comandos siguientes.

Ahora ejecutémoslo con transacción (sobre una tabla que se ha reiniciado desde cero):

npx tsx databases/mysql/mysql-04.ts true

Resultado de la ejecución:

--------------------------------------------------------------------
Executing the SQL file .../databases/mysql/data/commands.sql with transaction
--------------------------------------------------------------------
[drop table persons]: Successful execution
number of modified rows: 0
[create table persons (...)]: 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 (Error: You have an error in your SQL syntax; ... near 'xx' at line 1)
--------------------------------------------------------------------
Execution completed
--------------------------------------------------------------------
There were 1 error(s)
xx: Error (Error: You have an error in your SQL syntax; ... near 'xx' at line 1)

Esta vez, el error termina el bucle en cuanto ocurre (véase mysql-module.ts, línea 76): los comandos posteriores al error (actualizaciones, eliminaciones, etc.) nunca se ejecutan. El código llama entonces a connection.rollback() para revertir la transacción.

Precaución: Cabría esperar que la tabla `persons` esté vacía después de este `rollback()`; eso es lo que afirma, erróneamente, el curso original de Python sobre SQLAlchemy. En realidad, con MySQL/MariaDB (como con la mayoría de los SGBD), las instrucciones de definición de datos (DDL: CREATE TABLE, DROP TABLE...) confirman implícitamente (commit) y cierran cualquier transacción en curso antes de ejecutarse. Aquí, el CREATE TABLE del segundo comando ya ha confirmado, por lo tanto, (de manera invisible) todo lo anterior, incluido, puesto que no había nada antes, a sí mismo; los dos comandos INSERT que siguen abren entonces, en efecto, una nueva transacción implícita, que se revertirá efectivamente... salvo que, en la práctica, la verificación de la base de datos muestra que las dos filas insertadas siguen presentes después del rollback(): el CREATE TABLE confirmó la transacción mientras el bucle aún estaba en ejecución, incluso antes de que se ejecutaran las instrucciones INSERT posteriores; estas también quedan, por lo tanto, confirmadas de forma permanente en cuanto se ejecutan, fuera de cualquier transacción explícita. Recuerde la regla general: un DDL no puede revertirse con un ROLLBACK, y confirma silenciosamente cualquier transacción que estuviera abierta antes de él.

7.1.7. script [mysql-05]

Último script de este capítulo: consultas parametrizadas. Volvemos a crear la tabla persons con el esquema que incluye la columna id (como en el script **[mysql-03]), luego insertamos personas una por una mediante una sentencia preparada (connection.execute(), parámetros ?), e insertamos una lista completa de personas en una sola consulta de varias filas (connection.query() con values ?). Este es el script Python [mysql_05]**.

// databases/mysql/mysql-05.ts
// Consultas parametrizadas: inserción preparada individual y luego inserción masiva.
// Porta el script Python [mysql_05]. Aquí volvemos a crear la tabla [persons] con
// el esquema que tiene una columna [id] (como en el script mysql-03), para que este script
// sea independiente del estado que deje mysql-04.
import mysql from 'mysql2/promise';

// la identidad del usuario
const ID = 'admpersons';
const PWD = 'nobody';
// la máquina anfitriona del DBMS
const HOST = 'localhost';
// identidad de la base de datos
const DATABASE = 'dbpersons';

type Person = [id: number, lastName: string, firstName: string, age: number];

// lista de personas (id, lastName, firstName, age)
const persons: Person[] = [];
for (let i = 0; i < 5; i++) {
  persons.push([i, `l0${i}`, `f0${i}`, i + 10]);
}
persons.push([40, "d'Aboot", "Y'éna", 18]);

// otra lista de personas
const otherPersons: Person[] = [];
for (let i = 0; i < 5; i++) {
  otherPersons.push([i + 100, `l1${i}`, `f1${i}`, i + 20]);
}
otherPersons.push([200, "d'Aboot", "F'ilhem", 34]);

// acceso al DBMS
let connection: mysql.Connection | undefined;
try {
  // conexión
  connection = await mysql.createConnection({ host: HOST, user: ID, password: PWD, database: DATABASE });

  // (re)creación de la tabla con el esquema de columna [id] (vea mysql-03.ts)
  await connection.query('drop table if exists persons');
  await connection.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))',
  );

  // eliminación de los registros existentes
  await connection.query('delete from persons');
  // inserciones persona por persona con una sentencia preparada
  for (const person of persons) {
    const [id, lastName, firstName, age] = person;
    await connection.execute('insert into persons(id,last_name,first_name,age) values(?,?,?,?)', [id, lastName, firstName, age]);
  }
  // inserción masiva de una lista de personas - equivalente de executemany:
  // mysql2 ofrece connection.query('insert ... values ?', [[...],[...],...])
  // que construye una única consulta de varias filas
  const values = otherPersons.map(([id, lastName, firstName, age]) => [id, lastName, firstName, age]);
  await connection.query('insert into persons(id,last_name,first_name,age) values ?', [values]);

  // confirmación de la transacción - aquí cada consulta ya se confirmó automáticamente
  // (mysql2 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)
  console.log(`${persons.length + otherPersons.length} persons inserted.`);
} catch (error) {
  console.log(`The following error occurred: ${error}`);
} finally {
  if (connection) {
    await connection.end();
  }
}

Comentemos este código:

  • línea 23: [persons.push([40, "d'Aboot", "Y'éna", 18])] : un nombre y un apellido que contienen un apóstrofo, incluidos intencionalmente para verificar que las consultas parametrizadas escapan correctamente los valores (a diferencia de la concatenación de cadenas SQL, que es vulnerable a la inyección);
  • línea 50: [await connection.execute('insert into persons(id,last_name,first_name,age) values(?,?,?,?)', [id, lastName, firstName, age])] : execute() prepara la consulta parametrizada y luego la ejecuta con el arreglo de valores proporcionado; los marcadores de posición ? se reemplazan de forma segura, incluidos los apóstrofos;
  • línea 56: [await connection.query('insert into persons(id,last_name,first_name,age) values ?', [values])] : mysql2 ofrece así el equivalente de executemany() de Python: una única consulta SQL de varias filas construida a partir de un arreglo de arreglos, lo cual es más eficiente que un bucle de inserciones individuales.

Ejecutemos este script:

npx tsx databases/mysql/mysql-05.ts

Resultado de la ejecución:

12 persons inserted.

Verificación de la base de datos (con HeidiSQL):

7.1.8. Conclusión

El driver nativo mysql2 proporciona un acceso directo y sencillo al SGBD: usted escribe el SQL, gestiona las transacciones y el resultado de una consulta es un simple arreglo de filas JavaScript. Es el mismo enfoque que el del módulo Python mysql.connector utilizado en el capítulo 16 del curso de Python/Flask. Los dos capítulos siguientes muestran cómo un ORM (TypeORM y luego Prisma) permite escribir estas mismas operaciones sin escribir SQL, manipulando objetos TypeScript tipados.

7.2. Uso del ORM TypeORM

Abordaremos ahora los ORM, inspirándonos en el capítulo “Uso del ORM SQLAlchemy” (capítulo 19) del curso de Python/Flask. El principio de los ORM (mapeo objeto-relacional) es manipular objetos del lenguaje en lugar de escribir SQL: una clase corresponde a una tabla, una instancia a una fila, un atributo a una columna y una relación entre clases (asociación, composición) a una clave externa.

Se presentan sucesivamente dos implementaciones de ORM, con el mismo ejemplo, para poder compararlas: TypeORM en este capítulo, seguido de Prisma en el siguiente. De las dos, TypeORM es la que más se parece en estilo a SQLAlchemy (clases decoradas, Repository consultado mediante métodos); Prisma, en cambio, genera un cliente totalmente tipado a partir de un archivo de esquema declarativo independiente.

7.2.1. Preparación de la base de datos [dbschool]

Los dos capítulos de ORM usan una base de datos más completa que dbpersons, la base de datos dbschool, compuesta por cuatro tablas interrelacionadas, basada en el mismo “ejemplo completo” del capítulo 19 del curso de Python: una clase contiene estudiantes, cada estudiante tiene calificaciones en materias, y cada materia tiene una ponderación:

-- create_dbschool.sql
-- Recrea la base de datos [dbschool] usada por los capítulos de ORM (TypeORM y Prisma),
-- un port del esquema [Class / Student / Subject / Grade] del capítulo 19 del
-- curso Python/Flask ("Uso del ORM SQLALCHEMY", scripts 05 — ejemplo
-- completo), con datos arbitrarios (la base de datos original ya no está
-- disponible). Los nombres de tablas/columnas están deliberadamente sin tildes
-- (identificadores ASCII), más seguros con MySQL/TypeORM/Prisma.
--
-- Uso:
--   mysql -u root -p < create_dbschool.sql

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

CREATE USER IF NOT EXISTS 'admschool'@'localhost' IDENTIFIED BY 'pwdschool';
GRANT ALL PRIVILEGES ON dbschool.* TO 'admschool'@'localhost';
FLUSH PRIVILEGES;

USE dbschool;

-- una clase (p. ej. [class1], [class2])
CREATE TABLE classes (
  id  INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(30) NOT NULL UNIQUE
);

-- un alumno pertenece a una clase (relación N-1)
CREATE TABLE students (
  id         INT PRIMARY KEY,
  last_name  VARCHAR(30) NOT NULL,
  first_name VARCHAR(30) NOT NULL,
  class_id   INT NOT NULL,
  CONSTRAINT fk_students_class FOREIGN KEY (class_id) REFERENCES classes(id)
);

-- una materia (p. ej. [subject1], coeficiente 1)
CREATE TABLE subjects (
  id          INT AUTO_INCREMENT PRIMARY KEY,
  name        VARCHAR(30) NOT NULL UNIQUE,
  coefficient DECIMAL(4,2) NOT NULL
);

-- una nota es la nota de un alumno en una materia (relaciones N-1, N-1)
CREATE TABLE grades (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  value      DECIMAL(4,2) NOT NULL,
  student_id INT NOT NULL,
  subject_id INT NOT NULL,
  CONSTRAINT fk_grades_student FOREIGN KEY (student_id) REFERENCES students(id),
  CONSTRAINT fk_grades_subject FOREIGN KEY (subject_id) REFERENCES subjects(id)
);

-- datos arbitrarios (los mismos valores que en los ejemplos del curso original,
-- que daban para el alumno 11: notas=[10, 6], promedio ponderado = 7.33)
INSERT INTO classes (id, name) VALUES (1, 'class1'), (2, 'class2');

INSERT INTO students (id, last_name, first_name, class_id) VALUES
  (11, 'lastname1', 'firstname1', 1),
  (21, 'lastname2', 'firstname2', 1),
  (32, 'lastname3', 'firstname3', 2),
  (42, 'lastname4', 'firstname4', 2);

INSERT INTO subjects (id, name, coefficient) VALUES
  (1, 'subject1', 1.0),
  (2, 'subject2', 2.0);

INSERT INTO grades (value, student_id, subject_id) VALUES
  (10, 11, 1),
  (12, 21, 1),
  (14, 32, 1),
  (16, 42, 1),
  (6,  11, 2),
  (8,  21, 2),
  (10, 32, 2),
  (12, 42, 2);

Comentemos este script:

  • línea 33: [CONSTRAINT fk_students_class FOREIGN KEY (class_id) REFERENCES classes(id)]: una clave externa por relación: students.class_id (un estudiante pertenece a una clase) y dos para grades (student_id, subject_id) para la relación N-N “el estudiante tiene calificaciones en materias”;
  • línea 53: [INSERT INTO grades (value, student_id, subject_id) VALUES (10, 11, 1), ...] : calificaciones arbitrarias elegidas para replicar exactamente el ejemplo del curso de Python (estudiante 11: calificaciones 10 y 6, coeficientes de ponderación 1 y 2, que dan un promedio ponderado de (10×1 + 6×2) / (1+2) = 7.33 , valor que se encuentra en el script [typeorm-04-stats]).
mysql -u root -p < sql/create_dbschool.sql

7.2.2. Instalación y mapeo de entidades

TypeORM se instala con typeorm y, para ejecutar este curso en modo tsx, reflect-metadata (necesario para los decoradores). Dos opciones de tsconfig.json son esenciales:

"experimentalDecorators": true,
"emitDecoratorMetadata": true
Precaución: tsx (como esbuild, que utiliza) transpila TypeScript a JavaScript sin ejecutar el verificador de tipos completo; por lo tanto, los metadatos de decoradores que emitDecoratorMetadata se supone que inyecta automáticamente (el tipo de cada columna, inferido del tipo TypeScript de la propiedad) no siempre están disponibles en tiempo de ejecución, lo que provoca un error ColumnTypeUndefinedError. La solución más segura, utilizada en todas las entidades que siguen, es especificar explícitamente el tipo de cada columna como primer argumento del decorador: @Column('varchar', { length: 30 }) en lugar de simplemente @Column().

Cada tabla se representa mediante una clase anotada con @Entity. Esta es la entidad Person (la tabla persons de la base de datos dbpersons, reutilizada del capítulo anterior para el primer script de TypeORM):

// databases/typeorm/entities/person.entity.ts
// Entidad TypeORM correspondiente a la tabla [persons] de la base de datos
// [dbpersons] (vea el capítulo "driver nativo de MySQL").
// Porta el espíritu del mapeo del script Python [demo] (capítulo 19), en una
// versión "declarativa" moderna (decoradores), más cercana a lo que hace Spring
// Data JPA que al antiguo [mapper()] clásico de sqlalchemy 1.3.
import { Column, Entity, PrimaryColumn, Unique } from 'typeorm';

// Los tipos de columna se indican explícitamente (en lugar de deducirlos de los
// tipos de TypeScript por reflexión): más portable de una herramienta de compilación a otra
// (tsx/esbuild, ts-node, SWC...) que depender de
// "emitDecoratorMetadata".
@Entity({ name: 'persons' })
@Unique(['lastName', 'firstName'])
export class Person {
  @PrimaryColumn('int')
  id!: number;

  @Column('varchar', { name: 'first_name', length: 30 })
  firstName!: string;

  @Column('varchar', { name: 'last_name', length: 30 })
  lastName!: string;

  @Column('int')
  age!: number;
}

Luego vienen las cuatro entidades de dbschool (SchoolClass, Student, Subject y Grade), en las que las relaciones se declaran con @ManyToOne/@OneToMany (el equivalente de relationship() en SQLAlchemy):

// databases/typeorm/entities/school-class.entity.ts
// Porta la clase Python [Class] (capítulo 19, scripts 05).
import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from 'typeorm';
import { Student } from './student.entity.js';

@Entity({ name: 'classes' })
export class SchoolClass {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column('varchar', { length: 30, unique: true })
  name!: string;

  // propiedad inversa (backref) de Student.schoolClass - se carga bajo demanda
  @OneToMany(() => Student, (student) => student.schoolClass)
  students!: Student[];
}
// databases/typeorm/entities/student.entity.ts
// Porta la clase Python [Student] (capítulo 19, scripts 05).
import { Column, Entity, JoinColumn, ManyToOne, OneToMany, PrimaryColumn } from 'typeorm';
import { SchoolClass } from './school-class.entity.js';
import { Grade } from './grade.entity.js';

@Entity({ name: 'students' })
export class Student {
  @PrimaryColumn('int')
  id!: number;

  @Column('varchar', { name: 'last_name', length: 30 })
  lastName!: string;

  @Column('varchar', { name: 'first_name', length: 30 })
  firstName!: string;

  // un estudiante pertenece a una clase (relación N-1, columna [class_id])
  @ManyToOne(() => SchoolClass, (schoolClass) => schoolClass.students)
  @JoinColumn({ name: 'class_id' })
  schoolClass!: SchoolClass;

  // propiedad inversa (backref) de Grade.student
  @OneToMany(() => Grade, (grade) => grade.student)
  grades!: Grade[];
}
// databases/typeorm/entities/subject.entity.ts
// Porta la clase Python [Subject] (capítulo 19, scripts 05).
import { Column, Entity, OneToMany, PrimaryGeneratedColumn } from 'typeorm';
import { Grade } from './grade.entity.js';

@Entity({ name: 'subjects' })
export class Subject {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column('varchar', { length: 30, unique: true })
  name!: string;

  @Column('decimal', { precision: 4, scale: 2 })
  coefficient!: number;

  // propiedad inversa (backref) de Grade.subject
  @OneToMany(() => Grade, (grade) => grade.subject)
  grades!: Grade[];
}
// databases/typeorm/entities/grade.entity.ts
// Porta la clase Python [Grade] (capítulo 19, scripts 05): la nota de un
// estudiante en una materia.
import { Column, Entity, JoinColumn, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
import { Student } from './student.entity.js';
import { Subject } from './subject.entity.js';

@Entity({ name: 'grades' })
export class Grade {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column('decimal', { precision: 4, scale: 2 })
  value!: number;

  @ManyToOne(() => Student, (student) => student.grades)
  @JoinColumn({ name: 'student_id' })
  student!: Student;

  @ManyToOne(() => Subject, (subject) => subject.grades)
  @JoinColumn({ name: 'subject_id' })
  subject!: Subject;
}

Analicemos estas entidades:

  • línea 19: [@ManyToOne(() => SchoolClass, (schoolClass) => schoolClass.students) @JoinColumn({ name: 'class_id' })] : @ManyToOne declara el lado “muchos” de la relación (un estudiante, una clase); el primer argumento es una función que devuelve la clase de destino (en lugar de la clase misma) para evitar problemas de dependencia circular entre módulos; el segundo argumento enlaza con la propiedad inversa del lado de SchoolClass;
  • línea 24: [@OneToMany(() => Grade, (grade) => grade.student) grades!: Grade[]] : la propiedad “espejo” del lado uno (un estudiante tiene varias calificaciones); sirve solo para facilitar la lectura; no se crea ninguna columna adicional en la base de datos para ella (la clave externa la lleva Grade);

Por último, un DataSource (el equivalente del engine de SQLAlchemy) por base de datos, que contiene la conexión y la lista de entidades que gestiona:

// databases/typeorm/data-source-persons.ts
// Fuente de datos TypeORM para la base de datos [dbpersons].
import 'reflect-metadata';
import { DataSource } from 'typeorm';
import { Person } from './entities/person.entity.js';

export const AppDataSource = new DataSource({
  type: 'mysql',
  host: 'localhost',
  port: 3306,
  username: 'admpersons',
  password: 'nobody',
  database: 'dbpersons',
  entities: [Person],
  synchronize: false,
});
// databases/typeorm/data-source-school.ts
// Fuente de datos TypeORM para la base de datos [dbschool] (esquema Class / Student /
// Subject / Grade del capítulo 19, scripts 05).
import 'reflect-metadata';
import { DataSource } from 'typeorm';
import { SchoolClass } from './entities/school-class.entity.js';
import { Student } from './entities/student.entity.js';
import { Subject } from './entities/subject.entity.js';
import { Grade } from './entities/grade.entity.js';

export const AppDataSource = new DataSource({
  type: 'mysql',
  host: 'localhost',
  port: 3306,
  username: 'admschool',
  password: 'pwdschool',
  database: 'dbschool',
  entities: [SchoolClass, Student, Subject, Grade],
  synchronize: false,
});
Nota: `synchronize: false` indica a TypeORM que nunca modifique el esquema de la base de datos a partir de las entidades (lo que haría `synchronize: true`, útil durante el desarrollo pero peligroso en producción): aquí el esquema está definido por completo en los scripts SQL del inicio de este capítulo.

7.2.3. script [typeorm-01]

Primer uso de TypeORM: abrir DataSource, luego leer y escribir en la tabla persons mediante el repositorio de la entidad Person, sin escribir una sola línea de SQL. Sigue el mismo enfoque que el script Python [main] (capítulo 19, Scripts 01).

// databases/typeorm/typeorm-01.ts
// Primer uso de TypeORM: abrir la fuente de datos y luego leer y
// escribir en la tabla [persons] a través del Repository de la entidad
// [Person], sin escribir una sola línea de SQL.
// Porta el espíritu del script Python [main] (capítulo 19, scripts 01).
import { AppDataSource } from './data-source-persons.js';
import { Person } from './entities/person.entity.js';

await AppDataSource.initialize();
console.log('TypeORM connection to [dbpersons] established.');

try {
  const repo = AppDataSource.getRepository(Person);

  // todas las personas, ordenadas por apellido
  const all = await repo.find({ order: { lastName: 'ASC' } });
  console.log('Persons in the database:');
  for (const p of all) {
    console.log(`  ${p.id} ${p.firstName} ${p.lastName} (${p.age} years old)`);
  }

  // una persona por su clave primaria
  const paul = await repo.findOneBy({ id: 1 });
  console.log(`Person id=1: ${paul ? `${paul.firstName} ${paul.lastName}` : 'not found'}`);

  // inserción de una nueva persona (la entidad es una clase simple: basta con `new`,
  // no hace falta una fábrica especial)
  const newPerson = new Person();
  newPerson.id = 99;
  newPerson.firstName = 'Ada';
  newPerson.lastName = 'Lovelace';
  newPerson.age = 36;
  await repo.save(newPerson);
  console.log('Person 99 inserted.');

  // actualización
  newPerson.age = 37;
  await repo.save(newPerson);
  console.log(`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 });
  console.log('Person 99 deleted.');
} finally {
  await AppDataSource.destroy();
}

Comentemos este código:

  • línea 15: [await repo.find({ order: { lastName: 'ASC' } })] : Repository.find() es el método general de lectura; la opción order construye la cláusula ORDER BY ; no hace falta escribir SQL;
  • línea 28: [const newPerson = new Person(); newPerson.id = 99; ... await repo.save(newPerson);] : una entidad de TypeORM es una clase ordinaria: new basta para crear una instancia, y save() decide por sí mismo, según si la clave primaria ya existe en la base de datos, si genera un INSERT o un UPDATE; equivale a session.add() + session.commit() de SQLAlchemy, pero sin una sesión explícita que confirmar.

Ejecutemos este script (tras reiniciar la base de datos [dbpersons] con su script de creación):

npx tsx databases/typeorm/typeorm-01.ts

Resultado de la ejecución:

TypeORM connection to [dbpersons] established.
Persons in the database:
  4 Geraldine Colou (26 years old)
  5 Paulette Girond (56 years old)
  1 Paul Langevin (48 years old)
  2 Sylvie Lefur (70 years old)
  3 Pierre Nicazou (35 years old)
Person id=1: Paul Langevin
Person 99 inserted.
After update, age=37
Person 99 deleted.

7.2.4. script [typeorm-02]

A continuación pasamos a dbschool: lectura de las tablas classes y subjects, luego agregar, volver a leer y eliminar un estudiante. Sigue el enfoque de los scripts Python [02] y [03] (capítulo 19): mapear las entidades y luego manipularlas.

// databases/typeorm/typeorm-02.ts
// Mapeo de cuatro entidades relacionadas (Class, Student, Subject, Grade)
// y manipulaciones básicas (CRUD) sobre la base de datos [dbschool].
// Retoma el espíritu de los scripts Python [02] y [03] (capítulo 19): mapeos de
// sqlalchemy, luego manipulación de las entidades de la sesión.
import { AppDataSource } from './data-source-school.js';
import { SchoolClass } from './entities/school-class.entity.js';
import { Student } from './entities/student.entity.js';
import { Subject } from './entities/subject.entity.js';

await AppDataSource.initialize();
console.log('TypeORM connection to [dbschool] established.');

try {
  const classRepo = AppDataSource.getRepository(SchoolClass);
  const studentRepo = AppDataSource.getRepository(Student);
  const subjectRepo = AppDataSource.getRepository(Subject);

  // todas las clases
  console.log('Classes:');
  for (const c of await classRepo.find({ order: { name: 'ASC' } })) {
    console.log(`  ${c.id} ${c.name}`);
  }

  // todas las materias, con su coeficiente
  console.log('Subjects:');
  for (const s of await subjectRepo.find({ order: { name: 'ASC' } })) {
    console.log(`  ${s.id} ${s.name} (coefficient ${s.coefficient})`);
  }

  // adición de un nuevo estudiante en [class1]
  const class1 = await classRepo.findOneByOrFail({ name: 'class1' });
  const newStudent = new Student();
  newStudent.id = 999;
  newStudent.lastName = 'Curie';
  newStudent.firstName = 'Marie';
  newStudent.schoolClass = class1;
  await studentRepo.save(newStudent);
  console.log(`Student ${newStudent.firstName} ${newStudent.lastName} added to ${class1.name}.`);

  // relectura — especificamos `relations` para cargar la clase asociada
  // (de lo contrario la propiedad [schoolClass] quedaría ausente, ya que TypeORM no
  // hace carga diferida por defecto en entidades "eager: false")
  const reread = await studentRepo.findOne({ where: { id: 999 }, relations: { schoolClass: true } });
  console.log(`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 });
  console.log('Student 999 deleted.');
} finally {
  await AppDataSource.destroy();
}

Comentemos este código:

  • línea 37: [newStudent.schoolClass = class1; await studentRepo.save(newStudent);] : vinculamos al estudiante con su clase asignando directamente el objeto class1 cargado previamente; TypeORM traduce esta asignación en class_id durante el INSERT;
  • línea 44: [await studentRepo.findOne({ where: { id: 999 }, relations: { schoolClass: true } })] : punto importante: a diferencia de SQLAlchemy, que carga las relaciones bajo demanda (carga diferida) de forma predeterminada, TypeORM no carga ninguna relación hasta que se solicita explícitamente mediante la opción relations; sin ella, reread.schoolClass sería undefined.
Nota: Esta decisión de TypeORM (sin carga diferida implícita) es deliberada: cargar una relación siempre requiere un join o una consulta (SQL) adicional, un costo que preferimos hacer visible en el código en lugar de dejar que ocurra silenciosamente en el primer acceso a la propiedad, como haría SQLAlchemy.

Ejecutemos este script:

npx tsx databases/typeorm/typeorm-02.ts

Resultado de la ejecución:

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

7.2.5. script [typeorm-03-joined-queries]

Este script destaca las consultas que TypeORM desencadena para recuperar información repartida en varias tablas, usando sistemáticamente la opción "relations" vista en el script anterior. Se basa en el script Python [main_joined_queries] (capítulo 19, Scripts 05).

// databases/typeorm/typeorm-03-joined-queries.ts
// Muestra las consultas que TypeORM emite para obtener
// información repartida en varias tablas cuando se solicita una relación
// (@ManyToOne / @OneToMany). Retoma el script Python
// [main_joined_queries] (capítulo 19, scripts 05).
//
// A diferencia de sqlalchemy (usado por el curso de Python), TypeORM
// NO hace carga diferida por defecto en las entidades "clásicas" (repositorio):
// las relaciones por cargar deben solicitarse explícitamente, con la opción
// `relations`, o una consulta construida con `createQueryBuilder` /
// `leftJoinAndSelect`. Esta elección es deliberada y explícita: a diferencia de la
// carga diferida "oculta" de sqlalchemy, aquí siempre vemos, al leer el código,
// qué consultas SQL adicionales (joins) desencadenará una lectura.
import { AppDataSource } from './data-source-school.js';
import { SchoolClass } from './entities/school-class.entity.js';
import { Student } from './entities/student.entity.js';
import { Subject } from './entities/subject.entity.js';

await AppDataSource.initialize();

try {
  const studentRepo = AppDataSource.getRepository(Student);
  const classRepo = AppDataSource.getRepository(SchoolClass);
  const subjectRepo = AppDataSource.getRepository(Subject);

  // estudiante por id, con su clase (join explícito mediante `relations`)
  console.log('student id=11 -----------');
  const student11 = await studentRepo.findOneOrFail({ where: { id: 11 }, relations: { schoolClass: true } });
  console.log(`student={"id":${student11.id},"lastName":"${student11.lastName}","firstName":"${student11.firstName}"}`);
  console.log(`student's class: {"id":${student11.schoolClass.id},"name":"${student11.schoolClass.name}"}`);

  // los estudiantes de la misma clase (nueva consulta, con su propio join)
  console.log('students in the same class:');
  const studentsClass = await classRepo.findOneOrFail({
    where: { id: student11.schoolClass.id },
    relations: { students: true },
  });
  for (const s of studentsClass.students) {
    console.log(`student={"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}`);
  }

  // un estudiante por su apellido
  console.log("student lastName='lastname2' -----------");
  const byName = await studentRepo.findOneOrFail({ where: { lastName: 'lastname2' }, relations: { schoolClass: true } });
  console.log(`student={"id":${byName.id},"lastName":"${byName.lastName}","firstName":"${byName.firstName}"}`);
  console.log(`student's class: {"id":${byName.schoolClass.id},"name":"${byName.schoolClass.name}"}`);

  // las notas de un estudiante, con la materia de cada nota
  console.log('grades of student id=11 -----------');
  const studentWithGrades = await studentRepo.findOneOrFail({
    where: { id: 11 },
    relations: { grades: { subject: true } },
  });
  for (const grade of studentWithGrades.grades) {
    console.log(`grade={"id":${grade.id},"value":${grade.value}}, subject={"name":"${grade.subject.name}"}`);
  }

  // los estudiantes de una clase, por nombre de clase
  for (const className of ['class1', 'class2']) {
    console.log(`students of class name='${className}' -----------`);
    const schoolClass = await classRepo.findOneOrFail({ where: { name: className }, relations: { students: true } });
    for (const s of schoolClass.students) {
      console.log(`{"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}`);
    }
  }

  // las notas de una materia, por nombre de materia
  for (const subjectName of ['subject1', 'subject2']) {
    console.log(`subject with name='${subjectName}' -----------`);
    const subject = await subjectRepo.findOneOrFail({ where: { name: subjectName }, relations: { grades: true } });
    console.log(`subject={"name":"${subject.name}","coefficient":${subject.coefficient}}`);
    console.log('Grades in the subject: ');
    for (const grade of subject.grades) {
      console.log(`{"id":${grade.id},"value":${grade.value}}`);
    }
  }
} finally {
  await AppDataSource.destroy();
}

Comentemos este código:

  • Línea 28: [await studentRepo.findOneOrFail({ where: { id: 11 }, relations: { schoolClass: true } })]: findOneOrFail (como get_or_404 del curso de Flask) lanza una excepción en lugar de devolver null si ninguna fila coincide; útil cuando la ausencia de resultados es una anomalía, no un caso normal que deba comprobarse;
  • Línea 52: [relations: { grades: { subject: true } }] : una opción relations anidada recupera, en una sola consulta (TypeORM construye los joins SQL necesarios), las calificaciones del estudiante y, para cada calificación, la materia; sin este anidamiento, grade.subject faltaría.

Ejecutemos este script:

npx tsx databases/typeorm/typeorm-03-joined-queries.ts

Resultado de la ejecución:

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.00}, subject={"name":"subject1"}
grade={"id":5,"value":6.00}, 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.00}
Grades in the subject: 
{"id":1,"value":10.00}
{"id":2,"value":12.00}
{"id":3,"value":14.00}
{"id":4,"value":16.00}
subject with name='subject2' -----------
subject={"name":"subject2","coefficient":2.00}
Grades in the subject: 
{"id":5,"value":6.00}
{"id":6,"value":8.00}
{"id":7,"value":10.00}
{"id":8,"value":12.00}

7.2.6. script [typeorm-04-stats]

Último script del capítulo: calcula, para un estudiante dado, su promedio ponderado según los coeficientes de las materias, así como sus calificaciones mínima y máxima. El script Python se llama [main_stats_for_student] (capítulo 19, Scripts 05).

// databases/typeorm/typeorm-04-stats.ts
// Calcula, para un estudiante dado, su promedio ponderado por los coeficientes de
// las materias, así como su nota mínima y máxima. Retoma el script Python
// [main_stats_for_student] (capítulo 19, scripts 05).
//
// Trampa por conocer: las columnas `decimal` (aquí `grade.value` y
// `subject.coefficient`) se tipan como `number` en TypeScript dentro de
// la entidad, pero el controlador mysql2 en realidad las devuelve como
// *cadenas de caracteres* (para no perder precisión al
// convertirlas a un `number` de punto flotante). `typeof grade.value` es `'string'`
// en tiempo de ejecución, a pesar del tipo declarado. Un cálculo como
// `sum += grade.value * subject.coefficient` realizaría entonces una
// concatenación o una conversión implícita riesgosa: hay que convertir
// explícitamente con `Number(...)` antes de cualquier cálculo.
import { AppDataSource } from './data-source-school.js';
import { Student } from './entities/student.entity.js';

// calcula las estadísticas (promedio ponderado, mínimo, máximo) de un estudiante
async function studentStats(studentId: number): Promise<void> {
  const studentRepo = AppDataSource.getRepository(Student);
  // cargamos al estudiante con sus notas y, para cada nota, la materia
  // asociada (para tener el coeficiente) — una sola consulta con dos
  // joins, gracias a la opción `relations` anidada
  const student = await studentRepo.findOneOrFail({
    where: { id: studentId },
    relations: { grades: { subject: true } },
  });

  console.log(`Statistics of student {"id":${student.id},"lastName":"${student.lastName}","firstName":"${student.firstName}"}`);

  if (student.grades.length === 0) {
    console.log('  no grades.');
    return;
  }

  let weightedSum = 0;
  let coefficientsSum = 0;
  let min = Number.POSITIVE_INFINITY;
  let max = Number.NEGATIVE_INFINITY;

  for (const grade of student.grades) {
    // conversión explícita: `grade.value` y `grade.subject.coefficient`
    // son cadenas en tiempo de ejecución a pesar de su tipo declarado `number`
    const value = Number(grade.value);
    const coefficient = Number(grade.subject.coefficient);
    weightedSum += value * coefficient;
    coefficientsSum += coefficient;
    min = Math.min(min, value);
    max = Math.max(max, value);
    console.log(`  grade=${value.toFixed(2)} subject="${grade.subject.name}" (coefficient ${coefficient.toFixed(2)})`);
  }

  const average = weightedSum / coefficientsSum;
  console.log(`  weighted average=${average.toFixed(2)}, min=${min.toFixed(2)}, max=${max.toFixed(2)}`);
}

await AppDataSource.initialize();
try {
  // estudiante id=11: notas 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(11);
  console.log();
  // estudiante id=21: notas subject1=12 (coef 1.0), subject2=8 (coef 2.0)
  await studentStats(21);
  console.log();
  // estudiante id=32: notas subject1=14 (coef 1.0), subject2=10 (coef 2.0)
  await studentStats(32);
  console.log();
  // estudiante id=42: notas subject1=16 (coef 1.0), subject2=12 (coef 2.0)
  await studentStats(42);
} finally {
  await AppDataSource.destroy();
}

Comentemos este código:

  • línea 35: [const value = Number(grade.value); const coefficient = Number(grade.subject.coefficient);] : una trampa a la que hay que prestar atención: las columnas SQL DECIMAL (aquí, grade.value y subject.coefficient) están tipadas como number en la entidad TypeScript, pero el driver mysql2 en realidad las devuelve como cadenas para preservar la precisión decimal; typeof grade.value se evalúa como 'string' en tiempo de ejecución, a pesar del tipo declarado. Un cálculo aritmético directo resultaría en una concatenación o en una conversión implícita arriesgada; hay que convertir explícitamente con Number(...) antes de realizar cualquier cálculo.

Ejecutemos este script:

npx tsx databases/typeorm/typeorm-04-stats.ts

Resultado de la ejecución:

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

Para el estudiante 11, efectivamente vemos el promedio ponderado de 7.33 indicado por el curso original de Python sobre este mismo conjunto de datos.

7.2.7. Conclusión

TypeORM permite escribir operaciones de lectura/escritura sin SQL, mediante entidades decoradas similares en espíritu a SQLAlchemy, al precio de una diferencia de diseño significativa que conviene conocer (no hay carga diferida implícita de relaciones: cualquier relación no solicitada explícitamente se omite) y de una trampa de herramientas propia de la ejecución con TSX (los tipos de columna deben especificarse explícitamente). El capítulo siguiente usa exactamente el mismo ejemplo con Prisma para comparar los dos enfoques.

7.3. Uso del ORM Prisma

Segundo ORM, con el mismo ejemplo del capítulo anterior (las bases de datos dbpersons y dbschool), para comparar los dos enfoques. Prisma se diferencia de TypeORM en su diseño: en lugar de anotar clases, el esquema de la base de datos se describe en un archivo aparte con el formato declarativo propio de Prisma, a partir del cual el comando prisma generate genera un cliente totalmente tipado.

Importante: En el momento de redactar este capítulo, Prisma ORM está en la versión 7, que ha experimentado cambios internos significativos respecto de las versiones anteriores (5 y 6): el motor de consultas, antes un binario descargado por separado y compilado en Rust, es ahora un módulo WebAssembly integrado directamente en el paquete npm, combinado con un adaptador de driver (aquí @prisma/adapter-mariadb) que transmite las consultas a un driver JavaScript tradicional. Sin embargo, el principio general sigue siendo el mismo que en las versiones anteriores de Prisma, por lo que lo que sigue también se aplica a esas versiones.
Nota sobre este entorno: el comando `npx prisma generate` , que genera el cliente TypeScript a partir del archivo schema.prisma, requiere un recurso de red específico de Prisma (binaries.prisma.sh) para obtener un componente interno de su CLI, un recurso al que la política de red del entorno de ejecución utilizado para preparar este curso no permitió el acceso. Por lo tanto, los scripts de este capítulo se escribieron y revisaron con el mismo cuidado que los anteriores, pero no pudieron ejecutarse ni verificarse en este entorno, a diferencia de los de los dos capítulos anteriores, todos los cuales se ejecutaron y cuyos resultados se verificaron. En una máquina con acceso normal a Internet (el caso típico), `npx prisma generate` se ejecuta sin ningún problema particular, y los scripts deberían producir las salidas “esperadas” que se muestran a continuación, calculadas a partir de los mismos datos ya verificados en el capítulo anterior.

7.3.1. Instalación y configuración

Prisma se instala con dos paquetes: prisma (la CLI, una dependencia de desarrollo) y @prisma/client (la biblioteca cliente, una dependencia de producción); agregamos @prisma/adapter-mariadb, el adaptador de driver para MySQL/MariaDB, que internamente se apoya en el paquete mariadb. Un esquema de Prisma por base de datos, del mismo modo que hay un DataSource de TypeORM por base de datos:

// databases/prisma/schema-persons.prisma
// Esquema Prisma de la base de datos [dbpersons] (una sola tabla [persons]).
// Prisma ORM 7 genera un cliente TypeScript "sin Rust" (provider
// "prisma-client"): los adaptadores de controlador (`driverAdapters`, aquí
// @prisma/adapter-mariadb) se usan por defecto, ya no es necesario
// declarar `previewFeatures = ["driverAdapters"]` como en las versiones 5/6.
generator client {
  provider = "prisma-client"
  // ruta de salida del cliente generado, relativa a este archivo — desde
  // Prisma 7 es obligatoria (el cliente ya no se escribe en
  // node_modules por defecto)
  output   = "../../generated/prisma-persons"
}

// desde Prisma ORM 7, el datasource ya no lleva una URL de conexión: con los
// adaptadores de controlador, la conexión se configura por completo en
// tiempo de ejecución, del lado de PrismaClient (ver prisma-01.ts) — `provider` solo
// sirve para indicar al generador qué dialecto SQL usar
datasource db {
  provider = "mysql"
}

// retoma la tabla [persons] de create_dbpersons.sql
model Person {
  id        Int    @id
  firstName String @map("first_name") @db.VarChar(30)
  lastName  String @map("last_name") @db.VarChar(30)
  age       Int

  @@unique([lastName, firstName])
  @@map("persons")
}
// databases/prisma/schema-school.prisma
// Esquema Prisma de la base de datos [dbschool] (clases / estudiantes / materias / notas).
// Mismas tablas que databases/typeorm/entities/*.entity.ts y sql/create_dbschool.sql
// — los dos capítulos de ORM (TypeORM y luego Prisma) usan deliberadamente el
// mismo ejemplo, para que el lector pueda comparar los dos enfoques sobre un
// caso idéntico.
generator client {
  provider = "prisma-client"
  output   = "../../generated/prisma-school"
}

// desde Prisma ORM 7, el datasource ya no lleva una URL de conexión: con los
// adaptadores de controlador, la conexión se configura por completo en
// tiempo de ejecución, del lado de PrismaClient (ver prisma-02.ts) — `provider` solo
// sirve para indicar al generador qué dialecto SQL usar
datasource db {
  provider = "mysql"
}

model SchoolClass {
  id       Int       @id @default(autoincrement())
  name     String    @unique @db.VarChar(30)
  students Student[]

  @@map("classes")
}

model Student {
  id          Int         @id
  lastName    String      @map("last_name") @db.VarChar(30)
  firstName   String      @map("first_name") @db.VarChar(30)
  classId     Int         @map("class_id")
  schoolClass SchoolClass @relation(fields: [classId], references: [id])
  grades      Grade[]

  @@map("students")
}

model Subject {
  id          Int     @id @default(autoincrement())
  name        String  @unique @db.VarChar(30)
  coefficient Decimal @db.Decimal(4, 2)
  grades      Grade[]

  @@map("subjects")
}

model Grade {
  id        Int     @id @default(autoincrement())
  value     Decimal @db.Decimal(4, 2)
  studentId Int     @map("student_id")
  subjectId Int     @map("subject_id")
  student   Student @relation(fields: [studentId], references: [id])
  subject   Subject @relation(fields: [subjectId], references: [id])

  @@map("grades")
}

Comentemos estos esquemas:

  • línea 7: [generator client { provider = "prisma-client" output = "../../generated/prisma-school" }] : desde Prisma 7, es obligatorio especificar el destino (output ) del cliente generado (las versiones anteriores lo escribían en node_modules de forma predeterminada); los adaptadores de driver se usan por defecto; ya no es necesario habilitarlos con previewFeatures como ocurría cuando se introdujeron (versiones 5 y 6);
  • Línea 16: [datasource db { provider = "mysql" }] : Cambio importante en Prisma ORM 7: el bloque datasource ya no incluye una cadena de conexión (url = env(...), que estaba permitida en las versiones 5 y 6, ahora es rechazada por la CLI: error P1012, The url property of the datasource is no longer supported in schema files); con los adaptadores de driver, toda la configuración de conexión (host, nombre de usuario, contraseña, base de datos) la gestiona PrismaClient en tiempo de ejecución; el provider se usa únicamente para indicar al generador qué dialecto SQL debe usar como destino;
  • línea 32: [@@map("students") ... classId Int @map("class_id")] : @map/@@map sirven para nombrar las propiedades del modelo de Prisma en camelCase (classId) y mapearlas a las columnas SQL existentes, nombradas en snake_case (class_id): una diferencia de convención entre Prisma, que prefiere camelCase en todas partes, y el esquema SQL existente;
  • línea 50: [value Decimal @db.Decimal(4, 2)] : el tipo Decimal de Prisma (no debe confundirse con number); véase la trampa correspondiente en el script [prisma-04-stats] más adelante.

Antes de usarlo por primera vez, debe generar el cliente (una vez, o cada vez que se modifique el esquema):

npx prisma generate --schema=databases/prisma/schema-persons.prisma
npx prisma generate --schema=databases/prisma/schema-school.prisma

A continuación, el cliente generado se instancia con el adaptador de driver, que se configura explícitamente (con las mismas credenciales que en las secciones anteriores, por coherencia) en lugar de depender de la variable de entorno que lee la CLI:

1
2
3
4
5
6
7
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-school/client.js';

const adapter = new PrismaMariaDb({
  host: 'localhost', user: 'admschool', password: 'pwdschool', database: 'dbschool',
});
const prisma = new PrismaClient({ adapter });

7.3.2. script [prisma-01]

Primer uso de Prisma: lectura y escritura en la tabla persons mediante el cliente generado. Usa el mismo ejemplo que typeorm-01.ts; compare los dos archivos: solo cambia la API.

// databases/prisma/prisma-01.ts
// Primer uso de Prisma ORM: lectura y escritura en la tabla
// [persons] mediante el cliente generado, sin escribir una sola línea de
// SQL. Usa el mismo ejemplo que databases/typeorm/typeorm-01.ts, para
// comparar los dos ORM sobre un caso idéntico.
//
// Importante — este archivo solo puede compilarse/ejecutarse después de generar el
// cliente Prisma (ver el README):
//   npx prisma generate --schema=databases/prisma/schema-persons.prisma
// Este comando escribe el módulo ../../generated/prisma-persons importado
// más abajo; mientras no se haya ejecutado, este módulo no existe.
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-persons/client.js';

// Prisma ORM 7 ya no se conecta por sí mismo a la base de datos: le damos un
// "adaptador de controlador" (aquí @prisma/adapter-mariadb, que se apoya en el
// paquete `mariadb`) ya configurado con las credenciales de conexión — el
// mismo principio que el DataSource de TypeORM.
const adapter = new PrismaMariaDb({
  host: 'localhost',
  user: 'admpersons',
  password: 'nobody',
  database: 'dbpersons',
});
const prisma = new PrismaClient({ adapter });

try {
  // todas las personas, ordenadas por apellido
  const all = await prisma.person.findMany({ orderBy: { lastName: 'asc' } });
  console.log('Persons in the database:');
  for (const p of all) {
    console.log(`  ${p.id} ${p.firstName} ${p.lastName} (${p.age} years old)`);
  }

  // una persona por su clave primaria
  const paul = await prisma.person.findUnique({ where: { id: 1 } });
  console.log(`Person id=1: ${paul ? `${paul.firstName} ${paul.lastName}` : 'not found'}`);

  // inserción de una nueva persona — `create` devuelve el registro creado
  const newPerson = await prisma.person.create({
    data: { id: 99, firstName: 'Ada', lastName: 'Lovelace', age: 36 },
  });
  console.log(`Person ${newPerson.id} inserted.`);

  // actualización
  const updated = await prisma.person.update({
    where: { id: 99 },
    data: { age: 37 },
  });
  console.log(`After update, age=${updated.age}`);

  // eliminación — dejamos la base de datos en el estado en que la encontramos
  await prisma.person.delete({ where: { id: 99 } });
  console.log('Person 99 deleted.');
} finally {
  await prisma.$disconnect();
}

Comentemos este código:

  • línea 22: [await prisma.person.findMany({ orderBy: { lastName: 'asc' } })] : cada modelo del esquema se convierte en una propiedad del cliente (prisma.person), con métodos estandarizados: findMany, findUnique, create, update, delete..., comunes a todos los modelos, independientemente del SGBD;
  • línea 39: [const newPerson = await prisma.person.create({ data: {...} });] : a diferencia de TypeORM (new seguido de save()), Prisma separa claramente la creación (create) de la actualización (update): dos métodos distintos en lugar de un único método que adivina la intención.

Una vez ejecutado (npx tsx databases/prisma/prisma-01.ts), este script produce:

Salida:

Persons in the database:
  4 Geraldine Colou (26 years old)
  5 Paulette Girond (56 years old)
  1 Paul Langevin (48 years old)
  2 Sylvie Lefur (70 years old)
  3 Pierre Nicazou (35 years old)
Person id=1: Paul Langevin
Person 99 inserted.
After update, age=37
Person 99 deleted.

7.3.3. script [prisma-02]

Lee las tablas "classes/subjects" de dbschool, luego agrega, actualiza y elimina un estudiante. Usa el mismo ejemplo que typeorm-02.ts.

// databases/prisma/prisma-02.ts
// Lectura de las tablas [classes]/[subjects] de [dbschool], luego adición, relectura
// y eliminación de un estudiante. Usa el mismo ejemplo que
// databases/typeorm/typeorm-02.ts.
//
// Este archivo supone el cliente generado: vea prisma-01.ts para la observación
// sobre `npx prisma generate --schema=databases/prisma/schema-school.prisma`.
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-school/client.js';

const adapter = new PrismaMariaDb({
  host: 'localhost',
  user: 'admschool',
  password: 'pwdschool',
  database: 'dbschool',
});
const prisma = new PrismaClient({ adapter });
console.log('Prisma connection to [dbschool] established.');

try {
  // todas las clases
  console.log('Classes:');
  for (const c of await prisma.schoolClass.findMany({ orderBy: { name: 'asc' } })) {
    console.log(`  ${c.id} ${c.name}`);
  }

  // todas las materias, con su coeficiente — `coefficient` es de tipo
  // `Decimal` (una clase provista por Prisma, no un `number` nativo de JavaScript);
  // aquí lo mostramos directamente (su `toString()` hace lo correcto), pero
  // cualquier cálculo con él requiere pasar por `.toNumber()` (ver prisma-04-stats.ts)
  console.log('Subjects:');
  for (const s of await prisma.subject.findMany({ orderBy: { name: 'asc' } })) {
    console.log(`  ${s.id} ${s.name} (coefficient ${s.coefficient})`);
  }

  // adición de un nuevo estudiante en [class1] — `connect` vincula al nuevo estudiante
  // con una clase existente mediante su clave, sin tener que cargar esa clase
  // previamente (a diferencia de la asignación `newStudent.schoolClass = class1` de
  // TypeORM)
  const class1 = await prisma.schoolClass.findUniqueOrThrow({ where: { name: 'class1' } });
  const newStudent = await prisma.student.create({
    data: { id: 999, lastName: 'Curie', firstName: 'Marie', schoolClass: { connect: { id: class1.id } } },
  });
  console.log(`Student ${newStudent.firstName} ${newStudent.lastName} added to ${class1.name}.`);

  // relectura — `include` carga la relación solicitada (Prisma, como
  // TypeORM, no hace carga diferida por defecto: una relación ausente
  // del `include` simplemente está ausente del objeto devuelto)
  const reread = await prisma.student.findUnique({ where: { id: 999 }, include: { schoolClass: true } });
  console.log(`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 prisma.student.delete({ where: { id: 999 } });
  console.log('Student 999 deleted.');
} finally {
  await prisma.$disconnect();
}

Comentemos este código:

  • línea 39: [data: { id: 999, lastName: 'Curie', firstName: 'Marie', schoolClass: { connect: { id: class1.id } } }] : connect vincula al nuevo estudiante con una clase existente mediante su clave; Prisma construye automáticamente el valor de la columna class_id, de modo que no tenemos que manipularlo directamente;
  • línea 44: [await prisma.student.findUnique({ where: { id: 999 }, include: { schoolClass: true } })] : mismo principio que con TypeORM: include (en lugar de relations) carga explícitamente la relación solicitada; tampoco aquí Prisma realiza carga diferida implícita.

Una vez ejecutado (npx tsx databases/prisma/prisma-02.ts), este script produce:

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

7.3.4. script [prisma-03-joined-queries]

Consultas con joins sobre dbschool. Contiene exactamente el mismo ejemplo que typeorm-03-joined-queries.ts ; compare los dos archivos: la lógica es idéntica, solo cambia la API (con include en lugar de relations, y findUniqueOrThrow/findFirstOrThrow en lugar de findOneOrFail).

// databases/prisma/prisma-03-joined-queries.ts
// Consultas con joins (`include`) sobre [dbschool]. Usa exactamente el mismo
// ejemplo que databases/typeorm/typeorm-03-joined-queries.ts — compare los
// dos archivos: la lógica es idéntica, solo cambia la API (`include`
// en lugar de `relations`, `findUniqueOrThrow`/`findFirstOrThrow` en lugar de
// `findOneOrFail`).
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-school/client.js';

const adapter = new PrismaMariaDb({
  host: 'localhost',
  user: 'admschool',
  password: 'pwdschool',
  database: 'dbschool',
});
const prisma = new PrismaClient({ adapter });

try {
  // estudiante por id, con su clase (join explícito mediante `include`)
  console.log('student id=11 -----------');
  const student11 = await prisma.student.findUniqueOrThrow({ where: { id: 11 }, include: { schoolClass: true } });
  console.log(`student={"id":${student11.id},"lastName":"${student11.lastName}","firstName":"${student11.firstName}"}`);
  console.log(`student's class: {"id":${student11.schoolClass.id},"name":"${student11.schoolClass.name}"}`);

  // los estudiantes de la misma clase (nueva consulta, con su propio join)
  console.log('students in the same class:');
  const studentsClass = await prisma.schoolClass.findUniqueOrThrow({
    where: { id: student11.schoolClass.id },
    include: { students: true },
  });
  for (const s of studentsClass.students) {
    console.log(`student={"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}`);
  }

  // un estudiante por su apellido
  console.log("student lastName='lastname2' -----------");
  const byName = await prisma.student.findFirstOrThrow({ where: { lastName: 'lastname2' }, include: { schoolClass: true } });
  console.log(`student={"id":${byName.id},"lastName":"${byName.lastName}","firstName":"${byName.firstName}"}`);
  console.log(`student's class: {"id":${byName.schoolClass.id},"name":"${byName.schoolClass.name}"}`);

  // las notas de un estudiante, con la materia de cada nota — `include` anidado,
  // equivalente al `relations: { grades: { subject: true } }` de TypeORM
  console.log('grades of student id=11 -----------');
  const studentWithGrades = await prisma.student.findUniqueOrThrow({
    where: { id: 11 },
    include: { grades: { include: { subject: true } } },
  });
  for (const grade of studentWithGrades.grades) {
    console.log(`grade={"id":${grade.id},"value":${grade.value}}, subject={"name":"${grade.subject.name}"}`);
  }

  // los estudiantes de una clase, por nombre de clase
  for (const className of ['class1', 'class2']) {
    console.log(`students of class name='${className}' -----------`);
    const schoolClass = await prisma.schoolClass.findUniqueOrThrow({ where: { name: className }, include: { students: true } });
    for (const s of schoolClass.students) {
      console.log(`{"id":${s.id},"lastName":"${s.lastName}","firstName":"${s.firstName}"}`);
    }
  }

  // las notas de una materia, por nombre de materia
  for (const subjectName of ['subject1', 'subject2']) {
    console.log(`subject with name='${subjectName}' -----------`);
    const subject = await prisma.subject.findUniqueOrThrow({ where: { name: subjectName }, include: { grades: true } });
    console.log(`subject={"name":"${subject.name}","coefficient":${subject.coefficient}}`);
    console.log('Grades in the subject: ');
    for (const grade of subject.grades) {
      console.log(`{"id":${grade.id},"value":${grade.value}}`);
    }
  }
} finally {
  await prisma.$disconnect();
}

Comentemos este código:

  • línea 44: [include: { grades: { include: { subject: true } } }] : un include anidado, equivalente a relations: { grades: { subject: true } } en TypeORM; recupera, en una sola consulta, las calificaciones del estudiante y, para cada una, su materia.

Una vez ejecutado (npx tsx .\databases\prisma\prisma-03-joined-queries.ts), este script produce:

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}, subject={"name":"subject1"}
grade={"id":5,"value":6}, 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}
Grades in the subject: 
{"id":1,"value":10}
{"id":2,"value":12}
{"id":3,"value":14}
{"id":4,"value":16}
subject with name='subject2' -----------
subject={"name":"subject2","coefficient":2}
Grades in the subject: 
{"id":5,"value":6}
{"id":6,"value":8}
{"id":7,"value":10}
{"id":8,"value":12}
Nota: Los valores numéricos anteriores aparecen sin ceros decimales finales (10 en lugar de 10.00) cuando se interpolan en una cadena, a diferencia de la salida del script [typeorm-03]; una señal visible de que grade.value ya no es una cadena, como sí ocurre con TypeORM (véase el script siguiente).

7.3.5. script [prisma-04-stats]

Calcula, para un estudiante dado, su promedio ponderado según los coeficientes de las materias, así como sus calificaciones mínima y máxima. Usa el mismo ejemplo que typeorm-04-stats.ts.

// databases/prisma/prisma-04-stats.ts
// Calcula, para un estudiante dado, su promedio ponderado por los coeficientes de
// las materias, así como su nota mínima y máxima. Usa el mismo ejemplo que
// databases/typeorm/typeorm-04-stats.ts.
//
// Trampa por conocer, distinta de la de TypeORM: Prisma no devuelve
// las columnas `Decimal` (aquí `grade.value` y `subject.coefficient`) como
// cadenas, sino como instancias de la clase `Prisma.Decimal`
// (provista por la biblioteca decimal.js), para no perder ninguna
// precisión decimal. `typeof grade.value` es `'object'`, ni `'number'`
// ni `'string'`. Un cálculo como `grade.value * subject.coefficient`
// funcionaría casi por casualidad (`Decimal` redefine `valueOf`), pero
// la buena práctica — y la que se usa a continuación — es llamar
// explícitamente a `.toNumber()` antes de cualquier cálculo de punto flotante.
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-school/client.js';

const adapter = new PrismaMariaDb({
  host: 'localhost',
  user: 'admschool',
  password: 'pwdschool',
  database: 'dbschool',
});
const prisma = new PrismaClient({ adapter });

// calcula las estadísticas (promedio ponderado, mínimo, máximo) de un estudiante
async function studentStats(studentId: number): Promise<void> {
  // una sola consulta, con dos niveles de join (notas, luego la materia de
  // cada nota) para obtener el coeficiente de cada materia
  const student = await prisma.student.findUniqueOrThrow({
    where: { id: studentId },
    include: { grades: { include: { subject: true } } },
  });

  console.log(`Statistics of student {"id":${student.id},"lastName":"${student.lastName}","firstName":"${student.firstName}"}`);

  if (student.grades.length === 0) {
    console.log('  no grades.');
    return;
  }

  let weightedSum = 0;
  let coefficientsSum = 0;
  let min = Number.POSITIVE_INFINITY;
  let max = Number.NEGATIVE_INFINITY;

  for (const grade of student.grades) {
    // conversión explícita: `grade.value` y `grade.subject.coefficient`
    // son valores `Prisma.Decimal`, no valores `number`
    const value = grade.value.toNumber();
    const coefficient = grade.subject.coefficient.toNumber();
    weightedSum += value * coefficient;
    coefficientsSum += coefficient;
    min = Math.min(min, value);
    max = Math.max(max, value);
    console.log(`  grade=${value.toFixed(2)} subject="${grade.subject.name}" (coefficient ${coefficient.toFixed(2)})`);
  }

  const average = weightedSum / coefficientsSum;
  console.log(`  weighted average=${average.toFixed(2)}, min=${min.toFixed(2)}, max=${max.toFixed(2)}`);
}

try {
  // estudiante id=11: notas 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(11);
  console.log();
  await studentStats(21);
  console.log();
  await studentStats(32);
  console.log();
  await studentStats(42);
} finally {
  await prisma.$disconnect();
}

Comentemos este código:

  • línea 48: [const value = grade.value.toNumber(); const coefficient = grade.subject.coefficient.toNumber();] : una trampa a la que hay que prestar atención, distinta de la de TypeORM: Prisma no devuelve las columnas Decimal como cadenas, sino como instancias de la clase Prisma.Decimal (proporcionada por la biblioteca decimal.js), para no perder precisión decimal; typeof grade.value devuelve 'object', no 'number' ni 'string'. La buena práctica es llamar explícitamente a .toNumber() antes de cualquier cálculo de punto flotante; un cálculo directo como grade.value * subject.coefficient funcionaría casi por accidente (Decimal redefine valueOf), pero sigue siendo una práctica que debe evitarse.

Una vez ejecutado (npx tsx .\databases\prisma\prisma-04-stats.ts), este script produce:

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.3.6. Conclusión

Con el mismo ejemplo, TypeORM y Prisma producen código de longitud y legibilidad comparables; las diferencias son principalmente de estilo: clases decoradas y un Repository para TypeORM (más parecido a SQLAlchemy y a Spring Data JPA), y un esquema declarativo independiente y un cliente totalmente generado para Prisma (más parecido en espíritu a una herramienta como Alembic combinada con un generador de código). Ambos evitan escribir SQL y comparten la misma decisión de diseño, la ausencia de carga diferida implícita de relaciones, que los distingue de SQLAlchemy. La elección entre los dos, en un proyecto real, depende sobre todo del ecosistema (Prisma Studio, migraciones de Prisma, etc.) y de las preferencias del equipo.