Skip to content

7. Acesso a bancos de dados

Image

Os capítulos a seguir completam o curso ao tratar do acesso a bancos de dados a partir de scripts TypeScript, inspirando-se nos capítulos “Using the MySQL DBMS” e “Using the SQLAlchemy ORM” do curso “Introduction to Python 3 and the Flask Framework” (2019). Três abordagens são apresentadas em sequência: o acesso direto ao SGBD com o driver nativo mysql2, seguido de duas abordagens ORM (mapeamento objeto-relacional), TypeORM e Prisma.

7.1. Acesso direto ao banco de dados

Dois scripts SQL, fornecidos com este capítulo, permitem criar os bancos de dados de teste: dbpersons (uma única tabela, usada no capítulo sobre o driver nativo) e dbschool (quatro tabelas interligadas, usadas nos dois capítulos sobre ORM).

Image

7.1.1. Preparação do banco de dados [dbpersons]

O banco de dados dbpersons contém apenas uma tabela, persons, que usa o mesmo esquema do curso de Python (colunas id, first\_name, last\_name, age, com uma restrição de unicidade sobre o par (last\_name, first\_name)). O script SQL sql/create_dbpersons.sql abaixo cria o banco de dados, o usuário da aplicação e a tabela e, em seguida, insere nela cinco pessoas arbitrárias:

-- create_dbpersons.sql
-- Recria o banco de dados [dbpersons] usado pelo capítulo "Acesso ao MySQL com o
-- driver nativo [mysql2]", com dados arbitrários (os originais do curso de 2020
-- Python/Flask não estão mais disponíveis).
--
-- Uso:
--   mysql -u root -p < create_dbpersons.sql
--
-- Cria o banco de dados, o usuário da aplicação [admpersons/nobody] (mesmas
-- credenciais do curso original) e a tabela [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)
);

-- dados arbitrários (as mesmas pessoas dos exemplos do 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 criar este banco de dados (MySQL), você pode usar a ferramenta [HeidiSQL] do Laragon. Já a utilizamos antes.

  • Em [1], inicie todos os serviços do Laragon. Isso iniciará o SGBD MySQL;
  • em [2], acesse a ferramenta de gerenciamento de bancos de dados [HeidiSQL];
  • Em [1-2], conecte-se ao MySQL;

Usando [1-2], execute os dois arquivos SQL do projeto, um após o outro:

Image

Ainda no [HeidiSQL], pressione F5 para atualizar a exibição:

Agora estamos prontos para usar esses dois bancos de dados.

7.1.2. script [mysql-01]

Primeiro contato com o driver mysql2 (módulo mysql2/promise, que expõe uma API baseada em Promises em vez de callbacks): abrir uma conexão com dbpersons e depois fechá-la. Segue a mesma abordagem do script Python [mysql_01] (Capítulo 16).

// databases/mysql/mysql-01.ts
// Primeira etapa: conectar-se ao banco de dados MySQL [dbpersons] e depois
// desconectar-se. Porta o script Python [mysql_01] do curso Python/Flask.
import mysql from 'mysql2/promise';

// conexão ao banco de dados MySQL [dbpersons]
// a identidade do usuário é (admpersons, nobody)
const USER = 'admpersons';
const PWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// aqui vamos nós
let connection: mysql.Connection | undefined;
try {
  console.log('Connecting to the MySQL DBMS...');
  // conexão
  connection = await mysql.createConnection({ host: HOST, user: USER, password: PWD, database: DATABASE });
  // continuação
  console.log(
    `Successful MySQL connection to database=${DATABASE}, host=${HOST} as user=${USER}, passwd=${PWD}`,
  );
} catch (error) {
  // exibe o erro
  console.log(`The following error occurred: ${error}`);
} finally {
  // fecha a conexão se ela foi aberta
  if (connection) {
    await connection.end();
  }
}

Vamos comentar este código:

  • linha 16: [mysql.createConnection({ host: HOST, user: USER, password: PWD, database: DATABASE })] : abre uma única conexão assíncrona; createConnection retorna uma Promise<Connection>, daí o await; é o equivalente em TypeScript de mysql.connector.connect(...) no lado Python;
  • linha 29: [connection.end()] : fecha a conexão de forma ordenada no bloco finally, independentemente de ter ocorrido um erro; a conexão é declarada fora do bloco try (tipo mysql.Connection | undefined) para permanecer acessível nesse nível.

Vamos executar este script:

npx tsx databases/mysql/mysql-01.ts

Resultado da execução:

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

7.1.3. script [mysql-02]

Desta vez, a conexão é encapsulada em uma função reutilizável connect(host, database, login, pwd), que é chamada primeiro com credenciais válidas e depois uma segunda vez com credenciais inválidas, para observar o erro retornado pelo driver. O script Python se chama **[mysql\_02]**.

// databases/mysql/mysql-02.ts
// Neste novo script, a conexão ao banco de dados é isolada em uma função.
// Porta o script Python [mysql_02].
import mysql from 'mysql2/promise';

// conecta-se e depois desconecta-se (login, pwd) do banco de dados [database] no servidor [host]
// lança uma exceção se houver um problema
async function connect(host: string, database: string, login: string, pwd: string): Promise<void> {
  let cnx: mysql.Connection | undefined;
  try {
    // conexão
    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 {
    // fecha a conexão se ela foi aberta
    if (cnx) {
      await cnx.end();
      console.log('Successful disconnection\n');
    }
  }
}

// - main
// credenciais de conexão
const USER = 'admpersons';
const PASSWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// conexão de um usuário existente
try {
  await connect(HOST, DATABASE, USER, PASSWD);
} catch (error) {
  // exibe o erro
  console.log(String(error));
}

// conexão de um usuário inexistente
try {
  await connect(HOST, DATABASE, 'xx', 'xx');
} catch (error) {
  // exibe o erro
  console.log(String(error));
}

Vamos comentar este código:

  • linha 9: [async function connect(host, database, login, pwd): Promise<void>] : uma função async que não retorna nada, mas pode lançar uma exceção; ela mesma não captura os erros de conexão, deixando-os se propagar até o chamador;
  • linha 40: [await connect(HOST, DATABASE, 'xx', 'xx')] : a segunda chamada, com um usuário “xx” que não existe no MySQL, lança uma exceção que o bloco catch envolvente exibe.

Vamos executar este script:

npx tsx databases/mysql/mysql-02.ts

Resultado da execução:

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 versão: em um servidor MySQL recente (8.4 e posteriores), esta segunda chamada pode produzir uma mensagem diferente: "Error: Plugin 'mysql_native_password' is not loaded" em vez de "Access denied for user 'xx'@'localhost'." A causa não tem relação com o script: para evitar revelar se uma conta existe ou não (proteção contra enumeração), o MySQL simula uma troca de autenticação quando o login é feito com um usuário desconhecido, e essa simulação está fixada no código para usar o plugin legado mysql_native_password, desativado por padrão desde o MySQL 8.4. O princípio demonstrado por este script (uma exceção lançada e interceptada diante de credenciais inválidas) permanece intacto; para restaurar a mensagem exata exibida, adicione `mysql_native_password=ON` abaixo de `[mysqld]` no arquivo `my.ini` do servidor e, em seguida, reinicie o servidor.

7.1.4. script [mysql-03]

Já sabemos nos conectar; agora emitimos um comando SQL pela conexão para (re)criar a tabela “persons” com um esquema ligeiramente diferente (sem a coluna “id”, usando uma chave primária composta). Isso é tratado pelo script Python [mysql_03].

// databases/mysql/mysql-03.ts
// Agora que sabemos nos conectar, emitimos instruções SQL na conexão:
// (re)criamos a tabela [persons] do banco de dados [dbpersons].
// Porta o script Python [mysql_03].
import mysql from 'mysql2/promise';

// executa uma consulta de atualização na conexão
async function executeSql(connection: mysql.Connection, query: string): Promise<void> {
  await connection.query(query);
}

// - main
// credenciais de conexão
const ID = 'admpersons';
const PWD = 'nobody';
const HOST = 'localhost';
const DATABASE = 'dbpersons';

// vamos passo a passo
let connection: mysql.Connection;
try {
  // conexão — o mysql2 executa cada consulta em sua própria transação,
  // com commit automático por padrão (equivalente a AUTOCOMMIT=True no lado 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);
}

// exclusão da tabela persons, se existir
// se ela não existir, ocorrerá um erro - nós o ignoramos
try {
  await executeSql(connection, 'drop table persons');
} catch {
  // ignorado
}

// criação da tabela 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();
}

Vamos comentar este código:

  • linha 9: [await connection.query(query)] — connection.query() executa diretamente uma string SQL sem parâmetros; veremos a versão parametrizada, mais segura, que usa execute() no script [mysql-05];
  • Linha 28: [await executeSql(connection, 'drop table persons')] : tenta-se excluir a tabela dentro de um bloco try/catch vazio; se a tabela ainda não existir, o erro do MySQL é simplesmente ignorado.

Vamos executar este script:

npx tsx databases/mysql/mysql-03.ts

Resultado da execução:

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. Um módulo reutilizável: [mysql-module.ts]

Antes de escrever o script principal [mysql-04], que executa um arquivo inteiro de comandos SQL, extraímos para um módulo a lógica de execução de uma lista de comandos, com ou sem transação, junto com a exibição do resultado de cada comando (linhas de um SELECT ou o número de linhas modificadas em um INSERT/UPDATE/DELETE). O módulo Python se chama [mysql_module].

// databases/mysql/mysql-module.ts
// Funções reutilizáveis para executar uma lista (ou um arquivo) de comandos SQL
// em uma conexão MySQL aberta. Porta o módulo Python [mysql_module].
import type { Connection, FieldPacket, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
import { readFile } from 'node:fs/promises';

// exibe o resultado de um comando SQL (resultado de um query() do mysql2)
// - se houver um array [fields], era um SELECT: exibimos as colunas
//   e depois as linhas;
// - caso contrário, era uma instrução de atualização (INSERT/UPDATE/DELETE/DDL):
//   exibimos o número de linhas modificadas (equivalente a cursor.rowcount).
function displayInfo(rows: RowDataPacket[] | ResultSetHeader, fields: FieldPacket[] | undefined): void {
  if (fields && fields.length > 0) {
    // era um SELECT — fields descreve as colunas 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 {
    // nenhuma coluna descrita — instrução de atualização
    const header = rows as ResultSetHeader;
    console.log(`number of modified rows: ${header.affectedRows}`);
  }
}

// usa a conexão aberta [connection]
// executa nessa conexão os comandos SQL contidos na lista [sqlCommands]
// (um comando por elemento; linhas vazias ou que começam com # são ignoradas)
// - se verbose=true, cada execução de uma instrução SQL é seguida de uma exibição
//   indicando seu sucesso ou falha;
// - se stop=true, a função para no 1º erro encontrado; caso contrário,
//   executa todos os comandos;
// - se withTransaction=true, qualquer erro cancela todas as instruções SQL
//   executadas antes (rollback); caso contrário, cada comando recebe commit
//   de forma independente (comportamento padrão do mysql2);
// a função retorna um array [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) {
      // remove os espaços em branco no início e no fim do comando atual
      const command = rawCommand.trim();
      // comando vazio ou comentário? passa para o próximo
      if (command === '' || command[0] === '#') {
        continue;
      }
      // execução do comando atual
      try {
        const [rows, fields] = await connection.query(command);
        // nenhum erro
        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);
        }
        // paramos?
        if (withTransaction || stop) {
          return errors;
        }
      }
    }
    return errors;
  } finally {
    // commit / rollback da transação, se houver uma
    if (withTransaction) {
      if (errors.length > 0) {
        await connection.rollback();
      } else {
        await connection.commit();
      }
    }
  }
}

// usa a conexão aberta [connection]
// executa nessa conexão os comandos SQL contidos no
// arquivo de texto [sqlFilename] (um comando por linha)
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}`];
  }
}

Vamos comentar este código:

  • linha 45: [if (withTransaction) { await connection.beginTransaction(); }] : mysql2 está por padrão no modo AUTOCOMMIT (cada consulta é confirmada individualmente); beginTransaction() coloca explicitamente a conexão em modo transacional, assim como connexion.start_transaction() faria no lado Python;
  • linha 76: [if (withTransaction || stop) { return errors; }] : no modo transacional, o primeiro erro encerra imediatamente o laço; continuar seria inútil, já que toda a transação sofrerá rollback de qualquer maneira;
  • linha 82: [if (errors.length > 0) { await connection.rollback(); } else { await connection.commit(); }] : commit ou rollback global, conforme tenha ocorrido ou não um erro; veja, porém, a armadilha apontada no script [mysql-04] a seguir.

O script também usa um pequeno módulo de configuração, config-04.ts, que centraliza o caminho do arquivo de comandos SQL e as credenciais de login:

// databases/mysql/config-04.ts
// Configuração do script [mysql-04]: caminho do arquivo de comandos SQL e
// credenciais de conexão ao banco de dados [dbpersons].
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

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

export function configure() {
  return {
    // arquivo de comandos SQL
    commandsFilename: join(scriptDir, 'data', 'commands.sql'),
    // credenciais de conexão ao banco de dados
    host: 'localhost',
    database: 'dbpersons',
    user: 'admpersons',
    password: 'nobody',
  };
}
Nota: import.meta.url seguido de fileURLToPath/dirname é o método padrão, conforme definido no módulo ECMAScript ("type": "module" em package.json), para obter o diretório do arquivo atual; é o equivalente da variável mágica __dirname, disponível nativamente em CommonJS, mas não em ESM.

O script em si, data/commands.sql, segue o formato usado no curso de Python (um comando por linha; linhas vazias ou iniciadas por # são ignoradas):

Image

# exclusão da tabela [persons]
drop table persons
# criação da tabela 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))
# inserção de duas pessoas
insert into persons(first_name, last_name, age) values('Paul','Langevin',48)
insert into persons(first_name, last_name, age) values ('Sylvie','Lefur',70)
# exibição da tabela
select first_name, last_name, age from persons
# erro deliberado
xx
# inserção de três pessoas
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)
# exibição da tabela
select first_name, last_name, age from persons
# lista de pessoas em ordem alfabética de sobrenome e, para sobrenomes iguais, em ordem alfabética de nome
select last_name,first_name from persons order by last_name asc, first_name desc
# lista de pessoas com idade no intervalo [20,40] em ordem decrescente de idade
# depois, para idades iguais, em ordem alfabética de sobrenome e, para sobrenomes iguais, em ordem alfabética de nome
select last_name,first_name,age from persons where age between 20 and 40 order by age desc, last_name asc, first_name asc
# inserção da Sra. Bruneau
insert into persons(first_name, last_name, age) values('Josette','Bruneau',46)
# atualização de sua idade
update persons set age=47 where last_name='Bruneau'
# lista de pessoas cujo sobrenome é Bruneau
select last_name,first_name,age from persons where last_name='Bruneau'
# exclusão da Sra. Bruneau
delete from persons where last_name='Bruneau'
# lista de pessoas cujo sobrenome é Bruneau
select last_name,first_name,age from persons where last_name='Bruneau'

7.1.6. script [mysql-04]

O script principal: ele executa o arquivo data/commands.sql usando o módulo anterior, com ou sem transação, conforme um parâmetro de linha de comando. Corresponde ao script Python [mysql_04].

// databases/mysql/mysql-04.ts
// Script principal: executa o arquivo de comandos SQL [data/commands.sql],
// com ou sem transação, conforme o parâmetro da linha de comando.
// Porta o script Python [mysql_04].
//   npx tsx databases/mysql/mysql-04.ts true   (com transação)
//   npx tsx databases/mysql/mysql-04.ts false  (sem transação)
import mysql from 'mysql2/promise';
import { configure } from './config-04.js';
import { executeFileOfCommands } from './mysql-module.js';

const config = configure();

// - main
// verificação da sintaxe da chamada
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 um texto
const withTransaction = withTransactionText === 'true';
const text = withTransaction ? 'with transaction' : 'without transaction';

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

// execução das instruções SQL do arquivo
let connection: mysql.Connection | undefined;
let errors: string[] = [];
try {
  // conexão ao banco de dados
  connection = await mysql.createConnection({
    host: config.host,
    user: config.user,
    password: config.password,
    database: config.database,
  });
  // execução do arquivo 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();
  }
}

// exibição do número de erros
console.log('--------------------------------------------------------------------');
console.log('Execution completed');
console.log('--------------------------------------------------------------------');
console.log(`There were ${errors.length} error(s)`);
for (const currentError of errors) {
  console.log(currentError);
}

Vamos executá-lo primeiro sem transação:

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

Resultado da execução:

--------------------------------------------------------------------
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)

Sem transação, cada comando é confirmado de forma independente: o único erro intencional (comando xx) não impede que os comandos seguintes sejam executados.

Agora vamos executá-lo com transação (em uma tabela que foi zerada):

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

Resultado da execução:

--------------------------------------------------------------------
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)

Desta vez, o erro encerra o laço assim que ocorre (veja mysql-module.ts, linha 76): os comandos que se seguem ao erro (atualizações, exclusões etc.) nunca são executados. O código então chama connection.rollback() para desfazer a transação.

Atenção: você poderia esperar que a tabela `persons` estivesse vazia após esse `rollback()`; é o que o curso original de Python sobre SQLAlchemy afirma, incorretamente. Na realidade, com MySQL/MariaDB (como com a maioria dos SGBDs), as instruções de definição de dados (DDL: CREATE TABLE, DROP TABLE...) confirmam implicitamente (commit) qualquer transação em andamento antes de serem executadas. Aqui, o CREATE e TABLE do segundo comando já confirmaram, portanto, de forma invisível, tudo o que veio antes, inclusive, já que não havia nada antes dele, a si mesmos; os dois comandos INSERT que se seguem abrem então, na prática, uma nova transação implícita, que será de fato desfeita... exceto que, na prática, a verificação do banco de dados mostra que as duas linhas inseridas continuam presentes após o rollback(): o CREATE TABLE confirmou a transação enquanto o laço ainda estava em execução, antes mesmo de as instruções INSERT seguintes serem executadas; estas, portanto, também são confirmadas definitivamente assim que executadas, fora de qualquer transação explícita. Guarde a regra geral: uma DDL não pode ser desfeita por um ROLLBACK e confirma silenciosamente qualquer transação que estivesse aberta antes dela.

7.1.7. script [mysql-05]

Último script deste capítulo: consultas parametrizadas. Recriamos a tabela persons com o esquema que tem a coluna id (como no script **[mysql-03]), depois inserimos as pessoas uma a uma usando uma instrução preparada (connection.execute(), parâmetros ?) e inserimos uma lista inteira de pessoas em uma única consulta de várias linhas (connection.query() com values ?). Este é o script Python [mysql_05]**.

// databases/mysql/mysql-05.ts
// Consultas parametrizadas: inserção única preparada e depois inserção em lote.
// Porta o script Python [mysql_05]. Aqui recriamos a tabela [persons] com
// o esquema que tem uma coluna [id] (como no script mysql-03), para que este script
// seja independente do estado deixado por mysql-04.
import mysql from 'mysql2/promise';

// a identidade do usuário
const ID = 'admpersons';
const PWD = 'nobody';
// a máquina que hospeda o SGBD
const HOST = 'localhost';
// identidade do banco de dados
const DATABASE = 'dbpersons';

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

// lista de pessoas (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]);

// outra lista de pessoas
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]);

// acesso ao SGBD
let connection: mysql.Connection | undefined;
try {
  // conexão
  connection = await mysql.createConnection({ host: HOST, user: ID, password: PWD, database: DATABASE });

  // (re)criação da tabela com o esquema de coluna [id] (veja 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))',
  );

  // exclusão dos registros existentes
  await connection.query('delete from persons');
  // inserções pessoa a pessoa com uma instrução 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]);
  }
  // inserção em lote de uma lista de pessoas — equivalente a executemany:
  // o mysql2 oferece connection.query('insert ... values ?', [[...],[...],...])
  // que constrói uma única consulta com várias linhas
  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]);

  // commit da transação — aqui cada consulta já recebeu commit automático
  // (o mysql2 está em modo AUTOCOMMIT por padrão, como o modo padrão mencionado no
  // script mysql-03; portanto não há nada a confirmar explicitamente)
  console.log(`${persons.length + otherPersons.length} persons inserted.`);
} catch (error) {
  console.log(`The following error occurred: ${error}`);
} finally {
  if (connection) {
    await connection.end();
  }
}

Vamos comentar este código:

  • linha 23: [persons.push([40, "d'Aboot", "Y'éna", 18])] : um nome e um sobrenome que contêm apóstrofo, incluídos de propósito para verificar que as consultas parametrizadas escapam corretamente os valores (ao contrário da concatenação de strings SQL, vulnerável a injeção);
  • linha 50: [await connection.execute('insert into persons(id,last_name,first_name,age) values(?,?,?,?)', [id, lastName, firstName, age])] : execute() prepara a consulta parametrizada e a executa com o array de valores fornecido; os marcadores ? são substituídos com segurança, inclusive os apóstrofos;
  • linha 56: [await connection.query('insert into persons(id,last_name,first_name,age) values ?', [values])] : mysql2 fornece, assim, o equivalente do executemany() do Python: uma única consulta SQL de várias linhas construída a partir de um array de arrays, mais eficiente que um laço de inserts individuais.

Vamos executar este script:

npx tsx databases/mysql/mysql-05.ts

Resultado da execução:

12 persons inserted.

Verificação do banco de dados (com o HeidiSQL):

7.1.8. Conclusão

O driver nativo mysql2 oferece acesso direto e simples ao SGBD: você mesmo escreve o SQL, gerencia as transações por conta própria, e o resultado de uma consulta é um simples array de linhas JavaScript. É a mesma abordagem do módulo Python mysql.connector usado no Capítulo 16 do curso de Python/Flask. Os próximos dois capítulos mostram como um ORM (TypeORM e depois Prisma) permite escrever essas mesmas operações sem escrever SQL, manipulando objetos TypeScript tipados.

7.2. Uso do ORM TypeORM

Vamos agora tratar de ORM, tomando como base o capítulo “Using the SQLAlchemy ORM” (Capítulo 19) do curso de Python/Flask. O princípio de um ORM (mapeamento objeto-relacional) é manipular objetos da linguagem em vez de escrever SQL: uma classe corresponde a uma tabela, uma instância a uma linha, um atributo a uma coluna e uma relação entre classes (associação, composição) a uma chave estrangeira.

Duas implementações de ORM são apresentadas uma após a outra, com o mesmo exemplo, para que possam ser comparadas: TypeORM neste capítulo e Prisma no próximo. Das duas, o TypeORM é aquela cujo estilo mais se parece com o SQLAlchemy (classes decoradas, Repository consultado por meio de métodos); o Prisma, por sua vez, gera um cliente totalmente tipado a partir de um arquivo de esquema declarativo separado.

7.2.1. Preparação do banco de dados [dbschool]

Os dois capítulos sobre ORM usam um banco de dados mais completo que o dbpersons, o banco dbschool, composto por quatro tabelas interligadas, baseado no mesmo “exemplo completo” do Capítulo 19 do curso de Python: uma turma contém alunos, cada aluno tem notas em disciplinas, e cada disciplina tem um peso:

-- create_dbschool.sql
-- Recria o banco de dados [dbschool] usado pelos capítulos de ORM (TypeORM e Prisma),
-- um port do esquema [Class / Student / Subject / Grade] do capítulo 19 do
-- curso Python/Flask ("Usando o ORM SQLALCHEMY", scripts 05 — exemplo
-- completo), com dados arbitrários (o banco original não está mais
-- disponível). Os nomes de tabelas/colunas são deliberadamente sem acentos
-- (identificadores ASCII), mais seguros com 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;

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

-- um aluno pertence a uma turma (relação 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)
);

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

-- uma nota é a nota de um aluno em uma disciplina (relações 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)
);

-- dados arbitrários (mesmos valores dos exemplos do curso original,
-- que dava para o aluno 11: notas=[10, 6], média ponderada = 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);

Vamos comentar este script:

  • linha 33: [CONSTRAINT fk_students_class FOREIGN KEY (class_id) REFERENCES classes(id)]: uma chave estrangeira por relação, students.class_id (um aluno pertence a uma turma) e duas para grades (student_id, subject_id) para a relação N-N “o aluno tem notas em disciplinas”;
  • linha 53: [INSERT INTO grades (value, student_id, subject_id) VALUES (10, 11, 1), ...] : notas arbitrárias escolhidas para reproduzir exatamente o exemplo do curso de Python (aluno 11: notas 10 e 6, pesos 1 e 2, resultando em uma média ponderada de (10×1 + 6×2) / (1+2) = 7.33 , valor que pode ser encontrado no script [typeorm-04-stats]).
mysql -u root -p < sql/create_dbschool.sql

7.2.2. Instalação e mapeamento das entidades

O TypeORM é instalado com typeorm e, para executar este curso em modo tsx, reflect-metadata (necessário para os decoradores). Duas opções de tsconfig.json são essenciais:

"experimentalDecorators": true,
"emitDecoratorMetadata": true
Atenção: tsx (como o esbuild, que ele utiliza) transpila TypeScript para JavaScript sem executar o verificador de tipos completo; os metadados de decorador que emitDecoratorMetadata deveria injetar automaticamente (o tipo de cada coluna, inferido a partir do tipo TypeScript da propriedade) nem sempre estão, portanto, disponíveis em tempo de execução, o que dispara um erro ColumnTypeUndefinedError. A solução mais segura, usada em todas as entidades abaixo, é especificar explicitamente o tipo de cada coluna como primeiro argumento do decorador: @Column('varchar', { length: 30 }) em vez de simplesmente @Column().

Cada tabela é representada por uma classe anotada com @Entity. Eis a entidade Person (a tabela persons do banco de dados dbpersons, reutilizado do capítulo anterior para o primeiro script TypeORM):

// databases/typeorm/entities/person.entity.ts
// Entidade TypeORM correspondente à tabela [persons] do banco de dados
// [dbpersons] (veja o capítulo "driver MySQL nativo").
// Porta o espírito do mapeamento do script Python [demo] (capítulo 19), em uma
// versão "declarativa" moderna (decoradores), mais próxima do que o Spring
// Data JPA faz do que do antigo [mapper()] clássico do sqlalchemy 1.3.
import { Column, Entity, PrimaryColumn, Unique } from 'typeorm';

// Os tipos das colunas são dados explicitamente (em vez de deduzidos dos
// tipos do TypeScript por reflexão): mais portável de uma ferramenta de build para outra
// (tsx/esbuild, ts-node, SWC...) do 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;
}

Em seguida vêm as quatro entidades de dbschool, SchoolClass, Student, Subject e Grade, nas quais as relações são declaradas com @ManyToOne/@OneToMany (o equivalente de relationship() no SQLAlchemy):

// databases/typeorm/entities/school-class.entity.ts
// Porta a classe 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;

  // propriedade inversa (backref) de Student.schoolClass — carregada sob demanda
  @OneToMany(() => Student, (student) => student.schoolClass)
  students!: Student[];
}
// databases/typeorm/entities/student.entity.ts
// Porta a classe 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;

  // um aluno pertence a uma turma (relação N-1, coluna [class_id])
  @ManyToOne(() => SchoolClass, (schoolClass) => schoolClass.students)
  @JoinColumn({ name: 'class_id' })
  schoolClass!: SchoolClass;

  // propriedade inversa (backref) de Grade.student
  @OneToMany(() => Grade, (grade) => grade.student)
  grades!: Grade[];
}
// databases/typeorm/entities/subject.entity.ts
// Porta a classe 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;

  // propriedade inversa (backref) de Grade.subject
  @OneToMany(() => Grade, (grade) => grade.subject)
  grades!: Grade[];
}
// databases/typeorm/entities/grade.entity.ts
// Porta a classe Python [Grade] (capítulo 19, scripts 05): a nota de um
// aluno em uma disciplina.
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;
}

Vamos analisar estas entidades:

  • linha 19: [@ManyToOne(() => SchoolClass, (schoolClass) => schoolClass.students) @JoinColumn({ name: 'class_id' })] : @ManyToOne declara o lado “muitos” da relação (um aluno, uma turma); o primeiro argumento é uma função que retorna a classe de destino (em vez da própria classe), para evitar problemas de dependência circular entre módulos; o segundo argumento faz a ligação com a propriedade inversa do lado de SchoolClass;
  • linha 24: [@OneToMany(() => Grade, (grade) => grade.student) grades!: Grade[]] : a propriedade “espelho” do lado “um”: um aluno tem várias notas; ela existe apenas por legibilidade; nenhuma coluna adicional é criada no banco de dados para ela (a chave estrangeira fica em Grade);

Por fim, um DataSource (o equivalente do engine do SQLAlchemy) por banco de dados, contendo a conexão e a lista de entidades que ele gerencia:

// databases/typeorm/data-source-persons.ts
// Data source do TypeORM para o banco de dados [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
// Data source do TypeORM para o banco de dados [dbschool] (esquema Class / Student /
// Subject / Grade do 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` instrui o TypeORM a nunca modificar o esquema do banco de dados com base nas entidades (o que `synchronize: true` faria, útil durante o desenvolvimento, mas perigoso em produção): o esquema é inteiramente definido aqui pelos scripts SQL do início deste capítulo.

7.2.3. script [typeorm-01]

Primeiro uso do TypeORM: abrir o DataSource, depois ler e gravar na tabela persons por meio do repositório da entidade Person, sem escrever uma única linha de SQL. Segue a mesma abordagem do script Python [main] (Capítulo 19, Scripts 01).

// databases/typeorm/typeorm-01.ts
// Primeiro uso do TypeORM: abrir o data source e depois ler e
// escrever na tabela [persons] por meio do Repository da entidade
// [Person], sem escrever uma única linha de SQL.
// Porta o espírito do 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 as pessoas, ordenadas por sobrenome
  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)`);
  }

  // uma pessoa por sua chave primária
  const paul = await repo.findOneBy({ id: 1 });
  console.log(`Person id=1: ${paul ? `${paul.firstName} ${paul.lastName}` : 'not found'}`);

  // inserção de uma nova pessoa (a entidade é uma classe simples: `new`
  // basta, sem necessidade de uma factory 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.');

  // atualização
  newPerson.age = 37;
  await repo.save(newPerson);
  console.log(`After update, age=${(await repo.findOneBy({ id: 99 }))?.age}`);

  // remoção — devolvemos o banco de dados ao estado em que o encontramos
  await repo.delete({ id: 99 });
  console.log('Person 99 deleted.');
} finally {
  await AppDataSource.destroy();
}

Vamos comentar este código:

  • linha 15: [await repo.find({ order: { lastName: 'ASC' } })] : Repository.find() é o método geral de leitura; a opção order constrói a cláusula ORDER BY , sem necessidade de escrever SQL;
  • linha 28: [const newPerson = new Person(); newPerson.id = 99; ... await repo.save(newPerson);] : uma entidade do TypeORM é uma classe comum: new basta para criar uma instância, e save() decide por conta própria, conforme a chave primária já exista ou não no banco de dados, se deve gerar um INSERT ou um UPDATE; equivale a session.add() + session.commit() do SQLAlchemy, mas sem uma sessão explícita para confirmar.

Vamos executar este script (após redefinir o banco de dados [dbpersons] com seu script de criação):

npx tsx databases/typeorm/typeorm-01.ts

Resultado da execução:

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]

Passamos agora ao dbschool: leitura das tabelas classes e subjects , depois inclusão, nova leitura e exclusão de um aluno. Segue a abordagem dos scripts Python [02] e [03] (Capítulo 19): mapear as entidades e depois manipulá-las.

// databases/typeorm/typeorm-02.ts
// Mapeamento de quatro entidades relacionadas (Class, Student, Subject, Grade)
// e manipulações básicas (CRUD) no banco de dados [dbschool].
// Retoma o espírito dos scripts Python [02] e [03] (capítulo 19): mapeamentos
// sqlalchemy, depois manipulação das entidades da sessão.
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 as turmas
  console.log('Classes:');
  for (const c of await classRepo.find({ order: { name: 'ASC' } })) {
    console.log(`  ${c.id} ${c.name}`);
  }

  // todas as disciplinas, com seu coeficiente
  console.log('Subjects:');
  for (const s of await subjectRepo.find({ order: { name: 'ASC' } })) {
    console.log(`  ${s.id} ${s.name} (coefficient ${s.coefficient})`);
  }

  // adição de um novo aluno na [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}.`);

  // releitura — especificamos `relations` para carregar a turma associada
  // (caso contrário a propriedade [schoolClass] continuaria ausente, pois o TypeORM não faz
  // carregamento tardio por padrão em 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}`);

  // remoção — devolvemos o banco de dados ao estado em que o encontramos
  await studentRepo.delete({ id: 999 });
  console.log('Student 999 deleted.');
} finally {
  await AppDataSource.destroy();
}

Vamos comentar este código:

  • linha 37: [newStudent.schoolClass = class1; await studentRepo.save(newStudent);] : associamos o aluno à sua turma atribuindo diretamente o objeto class1 carregado anteriormente; o TypeORM traduz essa atribuição em class_id durante o INSERT;
  • linha 44: [await studentRepo.findOne({ where: { id: 999 }, relations: { schoolClass: true } })] : ponto importante: ao contrário do SQLAlchemy, que por padrão carrega as relações sob demanda (lazy loading), o TypeORM não carrega nenhuma relação até que ela seja solicitada explicitamente com a opção relations; sem ela, reread.schoolClass seria undefined.
Nota: essa escolha do TypeORM (nenhum lazy loading implícito) é deliberada: carregar uma relação sempre exige um join ou uma consulta (SQL) adicional, um custo que se prefere tornar visível no código, em vez de deixá-lo ocorrer silenciosamente no primeiro acesso à propriedade, como faria o SQLAlchemy.

Vamos executar este script:

npx tsx databases/typeorm/typeorm-02.ts

Resultado da execução:

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 as consultas que o TypeORM dispara para recuperar informações distribuídas em várias tabelas, usando sistematicamente a opção "relations" vista no script anterior. Baseia-se no script Python [main_joined_queries] (Capítulo 19, Scripts 05).

// databases/typeorm/typeorm-03-joined-queries.ts
// Destaca as consultas que o TypeORM emite para buscar
// informações distribuídas em várias tabelas quando um relacionamento
// (@ManyToOne / @OneToMany) é solicitado. Retoma o script Python
// [main_joined_queries] (capítulo 19, scripts 05).
//
// Ao contrário do sqlalchemy (usado pelo curso de Python), o TypeORM
// NÃO faz carregamento tardio por padrão em entidades "clássicas" (repository):
// os relacionamentos a carregar devem ser solicitados explicitamente, com a opção
// `relations`, ou uma consulta construída com `createQueryBuilder` /
// `leftJoinAndSelect`. Essa escolha é deliberada e explícita: ao contrário do
// carregamento tardio "oculto" do sqlalchemy, aqui vemos sempre, ao ler o código,
// quais consultas SQL adicionais (joins) uma leitura vai disparar.
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);

  // aluno por id, com sua turma (join explícito via `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}"}`);

  // os alunos da mesma turma (nova consulta, com seu próprio 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}"}`);
  }

  // um aluno pelo sobrenome
  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}"}`);

  // as notas de um aluno, com a disciplina 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}"}`);
  }

  // os alunos de uma turma, pelo nome da turma
  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}"}`);
    }
  }

  // as notas de uma disciplina, pelo nome da disciplina
  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();
}

Vamos comentar este código:

  • Linha 28: [await studentRepo.findOneOrFail({ where: { id: 11 }, relations: { schoolClass: true } })] : findOneOrFail (como get_or_404 do curso de Flask) lança uma exceção em vez de retornar null quando nenhuma linha corresponde; útil quando a ausência de resultados é uma anomalia, e não um caso normal a ser testado;
  • Linha 52: [relations: { grades: { subject: true } }] : uma opção relations aninhada recupera, em uma única consulta (o TypeORM constrói os joins SQL necessários), as notas do aluno e, para cada nota, a disciplina; sem esse aninhamento, grade.subject estaria ausente.

Vamos executar este script:

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

Resultado da execução:

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 do capítulo: calcula, para um determinado aluno, sua média ponderada pelos coeficientes das disciplinas, bem como suas notas mínima e máxima. O script Python se chama [main_stats_for_student] (Capítulo 19, Scripts 05).

// databases/typeorm/typeorm-04-stats.ts
// Calcula, para um determinado aluno, sua média ponderada pelos coeficientes das
// disciplinas, bem como sua nota mínima e máxima. Retoma o script Python
// [main_stats_for_student] (capítulo 19, scripts 05).
//
// Armadilha a conhecer: as colunas `decimal` (aqui `grade.value` e
// `subject.coefficient`) são tipadas como `number` no lado TypeScript, na
// entidade, mas o driver mysql2 na verdade as retorna como
// *strings* (para não perder precisão ao
// convertê-las em um `number` de ponto flutuante). `typeof grade.value` é `'string'`
// em tempo de execução, apesar do tipo declarado. Um cálculo como
// `sum += grade.value * subject.coefficient` realizaria então uma
// concatenação ou uma conversão implícita arriscada: é preciso converter
// explicitamente com `Number(...)` antes de qualquer cálculo.
import { AppDataSource } from './data-source-school.js';
import { Student } from './entities/student.entity.js';

// calcula as estatísticas (média ponderada, mínimo, máximo) de um aluno
async function studentStats(studentId: number): Promise<void> {
  const studentRepo = AppDataSource.getRepository(Student);
  // carregamos o aluno com suas notas e, para cada nota, a disciplina
  // associada (para obter o coeficiente) — uma única consulta com dois
  // joins, graças à opção `relations` aninhada
  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) {
    // conversão explícita: `grade.value` e `grade.subject.coefficient`
    // são strings em tempo de execução, apesar do 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 {
  // aluno id=11: notas disciplina1=10 (coef 1.0), disciplina2=6 (coef 2.0)
  // média ponderada = (10*1.0 + 6*2.0) / (1.0+2.0) = 22/3 = 7.33
  await studentStats(11);
  console.log();
  // aluno id=21: notas disciplina1=12 (coef 1.0), disciplina2=8 (coef 2.0)
  await studentStats(21);
  console.log();
  // aluno id=32: notas disciplina1=14 (coef 1.0), disciplina2=10 (coef 2.0)
  await studentStats(32);
  console.log();
  // aluno id=42: notas disciplina1=16 (coef 1.0), disciplina2=12 (coef 2.0)
  await studentStats(42);
} finally {
  await AppDataSource.destroy();
}

Vamos comentar este código:

  • linha 35: [const value = Number(grade.value); const coefficient = Number(grade.subject.coefficient);] : uma armadilha a observar: as colunas SQL DECIMAL (aqui, grade.value e subject.coefficient) são tipadas como number no lado da entidade TypeScript, mas o driver mysql2 na verdade as retorna como strings para preservar a precisão decimal; typeof grade.value resulta em 'string' em tempo de execução, apesar do tipo declarado. Um cálculo aritmético direto resultaria em concatenação ou em uma conversão implícita arriscada; é preciso converter explicitamente com Number(...) antes de fazer qualquer cálculo.

Vamos executar este script:

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

Resultado da execução:

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 o aluno 11, vemos de fato a média ponderada de 7.33 indicada pelo curso original de Python sobre este mesmo conjunto de dados.

7.2.7. Conclusão

O TypeORM permite escrever operações de leitura e gravação sem SQL, usando entidades decoradas semelhantes em espírito ao SQLAlchemy, ao custo de uma diferença de projeto significativa que convém conhecer (nenhum lazy loading implícito das relações: quaisquer relações não solicitadas explicitamente são omitidas) e de uma armadilha de ferramental específica da execução com TSX (os tipos das colunas devem ser especificados explicitamente). O capítulo seguinte usa exatamente o mesmo exemplo com o Prisma para comparar as duas abordagens.

7.3. Uso do ORM Prisma

Segundo ORM, com o mesmo exemplo do capítulo anterior (os bancos de dados dbpersons e dbschool), para comparar as duas abordagens. O Prisma difere do TypeORM em seu projeto: em vez de anotar classes, o esquema do banco de dados é descrito em um arquivo separado, no formato declarativo próprio do Prisma, a partir do qual o comando prisma generate gera um cliente totalmente tipado.

Importante: no momento da redação deste capítulo, o Prisma ORM está na versão 7, que passou por mudanças internas significativas em relação às versões anteriores (5 e 6): o query engine, antes um binário compilado em Rust baixado separadamente, agora é um módulo WebAssembly embutido diretamente no pacote npm, combinado com um driver adapter (aqui @prisma/adapter-mariadb) que repassa as consultas a um driver JavaScript tradicional. O princípio geral, no entanto, continua o mesmo das versões anteriores do Prisma, e o que se segue vale, portanto, também para elas.
Nota sobre este ambiente: o comando `npx prisma generate` , que gera o cliente TypeScript a partir do arquivo schema.prisma, requer um recurso de rede específico do Prisma (binaries.prisma.sh) para obter um componente interno de sua CLI, recurso ao qual a política de rede do ambiente de execução usado para preparar este curso não permitiu acesso. Os scripts deste capítulo foram, portanto, escritos e revisados com o mesmo cuidado dos anteriores, mas não puderam ser executados nem verificados neste ambiente, ao contrário dos dos dois capítulos anteriores, todos executados e com resultados verificados. Em uma máquina com acesso normal à Internet (o caso típico), `npx prisma generate` é executado sem nenhum problema particular, e os scripts devem produzir as saídas “esperadas” mostradas abaixo, calculadas a partir dos mesmos dados já verificados no capítulo anterior.

7.3.1. Instalação e configuração

O Prisma é instalado com dois pacotes: prisma (a CLI, uma dependência de desenvolvimento) e @prisma/client (a biblioteca cliente, uma dependência de produção); acrescentamos @prisma/adapter-mariadb, o driver adapter para MySQL/MariaDB, que internamente se apoia no pacote mariadb. Um esquema Prisma por banco de dados, assim como há um DataSource do TypeORM por banco de dados:

// databases/prisma/schema-persons.prisma
// Schema Prisma do banco de dados [dbpersons] (uma única tabela [persons]).
// O Prisma ORM 7 gera um cliente TypeScript "sem Rust" (provider
// "prisma-client"): os driver adapters (`driverAdapters`, aqui
// @prisma/adapter-mariadb) são usados por padrão, não é mais necessário
// declarar `previewFeatures = ["driverAdapters"]` como nas versões 5/6.
generator client {
  provider = "prisma-client"
  // caminho de saída do cliente gerado, relativo a este arquivo — desde o
  // Prisma 7 ele é obrigatório (o cliente não é mais gravado em
  // node_modules por padrão)
  output   = "../../generated/prisma-persons"
}

// desde o Prisma ORM 7, o datasource não carrega mais uma URL de conexão: com
// driver adapters, a conexão é inteiramente configurada em
// tempo de execução, no lado do PrismaClient (veja prisma-01.ts) — `provider` só
// serve para dizer ao gerador qual dialeto SQL usar como alvo
datasource db {
  provider = "mysql"
}

// retoma a tabela [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
// Schema Prisma do banco de dados [dbschool] (turmas / alunos / disciplinas / notas).
// As mesmas tabelas de databases/typeorm/entities/*.entity.ts e sql/create_dbschool.sql
// — os dois capítulos de ORM (TypeORM e depois Prisma) usam deliberadamente o
// mesmo exemplo, para que o leitor possa comparar as duas abordagens em um
// caso idêntico.
generator client {
  provider = "prisma-client"
  output   = "../../generated/prisma-school"
}

// desde o Prisma ORM 7, o datasource não carrega mais uma URL de conexão: com
// driver adapters, a conexão é inteiramente configurada em
// tempo de execução, no lado do PrismaClient (veja prisma-02.ts) — `provider` só
// serve para dizer ao gerador qual dialeto SQL usar como alvo
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")
}

Vamos comentar estes esquemas:

  • linha 7: [generator client { provider = "prisma-client" output = "../../generated/prisma-school" }] : desde o Prisma 7, o output do cliente gerado é obrigatório (as versões anteriores o gravavam em node_modules por padrão); os driver adapters são usados por padrão; não é mais necessário habilitá-los com previewFeatures , como era o caso quando foram introduzidos (versões 5 e 6);
  • Linha 16: [datasource db { provider = "mysql" }] : mudança importante no Prisma ORM 7: o bloco datasource não inclui mais uma string de conexão (url = env(...), que era permitida nas versões 5 e 6, agora é rejeitada pela CLI, erro P1012, The url property of the datasource is no longer supported in schema files); com driver adapters, toda a configuração de conexão (host, usuário, senha, banco de dados) é tratada pelo PrismaClient em tempo de execução; o provider serve apenas para indicar ao gerador qual dialeto SQL ele deve ter como alvo;
  • linha 32: [@@map("students") ... classId Int @map("class_id")] : @map/@@map servem para nomear as propriedades do modelo Prisma em camelCase (classId) ao mesmo tempo que as mapeiam para colunas SQL existentes, nomeadas em snake_case (class_id), uma diferença de convenção entre o Prisma, que prefere camelCase em todo lugar, e o esquema SQL existente;
  • linha 50: [value Decimal @db.Decimal(4, 2)] : o tipo Decimal do Prisma (que não deve ser confundido com number); veja a armadilha correspondente no script [prisma-04-stats] a seguir.

Antes de usá-lo pela primeira vez, é preciso gerar o cliente (uma vez, ou a cada modificação do esquema):

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

O cliente gerado é então instanciado com o driver adapter, configurado explicitamente (com as mesmas credenciais das seções anteriores, por consistência) em vez de depender da variável de ambiente lida pela 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]

Primeiro uso do Prisma: leitura e gravação na tabela persons por meio do cliente gerado. Usa o mesmo exemplo de typeorm-01.ts; compare os dois arquivos: só a API muda.

// databases/prisma/prisma-01.ts
// Primeiro uso do Prisma ORM: leitura e escrita na tabela
// [persons] por meio do cliente gerado, sem escrever uma única linha de
// SQL. Usa o mesmo exemplo de databases/typeorm/typeorm-01.ts, para
// comparar os dois ORMs em um caso idêntico.
//
// Importante — este arquivo só pode ser compilado/executado depois de gerar o
// cliente Prisma (veja o README):
//   npx prisma generate --schema=databases/prisma/schema-persons.prisma
// Este comando grava o módulo ../../generated/prisma-persons importado
// abaixo; enquanto não for executado, esse módulo não existe.
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../../generated/prisma-persons/client.js';

// O Prisma ORM 7 não se conecta mais ao banco de dados por conta própria: damos a ele um
// "driver adapter" (aqui @prisma/adapter-mariadb, que se apoia no
// pacote `mariadb`) já configurado com as credenciais de conexão — o
// mesmo princípio do DataSource do TypeORM.
const adapter = new PrismaMariaDb({
  host: 'localhost',
  user: 'admpersons',
  password: 'nobody',
  database: 'dbpersons',
});
const prisma = new PrismaClient({ adapter });

try {
  // todas as pessoas, ordenadas por sobrenome
  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)`);
  }

  // uma pessoa por sua chave primária
  const paul = await prisma.person.findUnique({ where: { id: 1 } });
  console.log(`Person id=1: ${paul ? `${paul.firstName} ${paul.lastName}` : 'not found'}`);

  // inserção de uma nova pessoa — `create` retorna o registro criado
  const newPerson = await prisma.person.create({
    data: { id: 99, firstName: 'Ada', lastName: 'Lovelace', age: 36 },
  });
  console.log(`Person ${newPerson.id} inserted.`);

  // atualização
  const updated = await prisma.person.update({
    where: { id: 99 },
    data: { age: 37 },
  });
  console.log(`After update, age=${updated.age}`);

  // remoção — devolvemos o banco de dados ao estado em que o encontramos
  await prisma.person.delete({ where: { id: 99 } });
  console.log('Person 99 deleted.');
} finally {
  await prisma.$disconnect();
}

Vamos comentar este código:

  • linha 22: [await prisma.person.findMany({ orderBy: { lastName: 'asc' } })] : cada modelo do esquema se torna uma propriedade do cliente (prisma.person), com métodos padronizados, findMany, findUnique, create, update, delete..., comuns a todos os modelos, qualquer que seja o SGBD;
  • linha 39: [const newPerson = await prisma.person.create({ data: {...} });] : ao contrário do TypeORM (new seguido de save()), o Prisma separa claramente a criação (create) da atualização (update): dois métodos distintos, em vez de um único método que adivinha a intenção.

Depois de executado (npx tsx databases/prisma/prisma-01.ts), este script produz:

Saída:

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]

Lê as tabelas "classes/subjects" do dbschool, depois inclui, atualiza e exclui um aluno. Usa o mesmo exemplo de typeorm-02.ts.

// databases/prisma/prisma-02.ts
// Leitura das tabelas [classes]/[subjects] de [dbschool], depois adição, releitura
// e remoção de um aluno. Usa o mesmo exemplo de
// databases/typeorm/typeorm-02.ts.
//
// Este arquivo pressupõe o cliente gerado: veja prisma-01.ts para a observação
// 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 as turmas
  console.log('Classes:');
  for (const c of await prisma.schoolClass.findMany({ orderBy: { name: 'asc' } })) {
    console.log(`  ${c.id} ${c.name}`);
  }

  // todas as disciplinas, com seu coeficiente — `coefficient` é do tipo
  // `Decimal` (uma classe fornecida pelo Prisma, não um `number` nativo do JavaScript);
  // aqui o exibimos diretamente (seu `toString()` faz a coisa certa), mas
  // qualquer cálculo com ele exige passar por `.toNumber()` (veja 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})`);
  }

  // adição de um novo aluno na [class1] — `connect` vincula o novo aluno
  // a uma turma existente por sua chave, sem precisar carregar essa turma
  // antes (ao contrário da atribuição `newStudent.schoolClass = class1` do
  // 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}.`);

  // releitura — `include` carrega o relacionamento solicitado (o Prisma, como o
  // TypeORM, não faz carregamento tardio por padrão: um relacionamento ausente
  // do `include` simplesmente está ausente do objeto retornado)
  const reread = await prisma.student.findUnique({ where: { id: 999 }, include: { schoolClass: true } });
  console.log(`Re-read: ${reread?.firstName} ${reread?.lastName}, class=${reread?.schoolClass.name}`);

  // remoção — devolvemos o banco de dados ao estado em que o encontramos
  await prisma.student.delete({ where: { id: 999 } });
  console.log('Student 999 deleted.');
} finally {
  await prisma.$disconnect();
}

Vamos comentar este código:

  • linha 39: [data: { id: 999, lastName: 'Curie', firstName: 'Marie', schoolClass: { connect: { id: class1.id } } }] : connect associa o novo aluno a uma turma existente por meio de sua chave; o Prisma constrói automaticamente o valor da coluna class_id, de modo que não precisamos manipulá-la diretamente;
  • linha 44: [await prisma.student.findUnique({ where: { id: 999 }, include: { schoolClass: true } })] : mesmo princípio do TypeORM: include (em vez de relations) carrega explicitamente a relação solicitada; o Prisma também não faz lazy loading implícito aqui.

Depois de executado (npx tsx databases/prisma/prisma-02.ts), este script produz:

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 com joins no dbschool. Contém exatamente o mesmo exemplo de typeorm-03-joined-queries.ts ; compare os dois arquivos: a lógica é idêntica, só a API muda (uso de include em vez de relations, e de findUniqueOrThrow/findFirstOrThrow em vez de findOneOrFail).

// databases/prisma/prisma-03-joined-queries.ts
// Consultas com joins (`include`) em [dbschool]. Usa exatamente o mesmo
// exemplo de databases/typeorm/typeorm-03-joined-queries.ts — compare os
// dois arquivos: a lógica é idêntica, só muda a API (`include`
// em vez de `relations`, `findUniqueOrThrow`/`findFirstOrThrow` em vez 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 {
  // aluno por id, com sua turma (join explícito via `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}"}`);

  // os alunos da mesma turma (nova consulta, com seu próprio 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}"}`);
  }

  // um aluno pelo sobrenome
  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}"}`);

  // as notas de um aluno, com a disciplina de cada nota — `include` aninhado,
  // equivalente ao `relations: { grades: { subject: true } }` do 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}"}`);
  }

  // os alunos de uma turma, pelo nome da turma
  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}"}`);
    }
  }

  // as notas de uma disciplina, pelo nome da disciplina
  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();
}

Vamos comentar este código:

  • linha 44: [include: { grades: { include: { subject: true } } }] : um include aninhado, equivalente a relations: { grades: { subject: true } } no TypeORM: busca, em uma única consulta, as notas do aluno e, para cada uma delas, sua disciplina.

Depois de executado (npx tsx .\databases\prisma\prisma-03-joined-queries.ts), este script produz:

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: os valores numéricos acima aparecem sem zeros decimais à direita (10 em vez de 10.00) quando interpolados em uma string, ao contrário da saída do script [typeorm-03]; um sinal visível de que grade.value não é mais uma string, como ocorre com o TypeORM (veja o script seguinte).

7.3.5. script [prisma-04-stats]

Calcula, para um determinado aluno, sua média das notas ponderada pelos coeficientes das disciplinas, bem como suas notas mínima e máxima. Usa o mesmo exemplo de typeorm-04-stats.ts.

// databases/prisma/prisma-04-stats.ts
// Calcula, para um determinado aluno, sua média ponderada pelos coeficientes das
// disciplinas, bem como sua nota mínima e máxima. Usa o mesmo exemplo de
// databases/typeorm/typeorm-04-stats.ts.
//
// Armadilha a conhecer, diferente da do TypeORM: o Prisma não retorna
// as colunas `Decimal` (aqui `grade.value` e `subject.coefficient`) como
// strings, mas como instâncias da classe `Prisma.Decimal`
// (fornecida pela biblioteca decimal.js), para não perder nenhuma
// precisão decimal. `typeof grade.value` é `'object'`, nem `'number'`
// nem `'string'`. Um cálculo como `grade.value * subject.coefficient`
// funcionaria quase por acaso (`Decimal` redefine `valueOf`), mas
// a boa prática — e a usada abaixo — é chamar
// `.toNumber()` explicitamente antes de qualquer cálculo em ponto flutuante.
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 as estatísticas (média ponderada, mínimo, máximo) de um aluno
async function studentStats(studentId: number): Promise<void> {
  // uma única consulta, com dois níveis de join (notas e depois a disciplina de
  // cada nota) para obter o coeficiente de cada disciplina
  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) {
    // conversão explícita: `grade.value` e `grade.subject.coefficient`
    // são valores `Prisma.Decimal`, não 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 {
  // aluno id=11: notas disciplina1=10 (coef 1.0), disciplina2=6 (coef 2.0)
  // média ponderada = (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();
}

Vamos comentar este código:

  • linha 48: [const value = grade.value.toNumber(); const coefficient = grade.subject.coefficient.toNumber();] : uma armadilha a observar, diferente da do TypeORM: o Prisma não retorna as colunas Decimal como strings, mas como instâncias da classe Prisma.Decimal (fornecida pela biblioteca decimal.js), para não perder nenhuma precisão decimal; typeof grade.value retorna 'object', e não 'number' nem 'string'. A boa prática é chamar explicitamente .toNumber() antes de qualquer cálculo em ponto flutuante; um cálculo direto como grade.value * subject.coefficient funcionaria quase por acaso (Decimal redefine valueOf), mas ainda assim é uma prática a evitar.

Depois de executado (npx tsx .\databases\prisma\prisma-04-stats.ts), este script produz:

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. Conclusão

Com o mesmo exemplo, o TypeORM e o Prisma produzem código de extensão e legibilidade comparáveis; as diferenças são principalmente de estilo: classes decoradas e um Repository no TypeORM (mais parecido com o SQLAlchemy e o Spring Data JPA), e um esquema declarativo separado e um cliente totalmente gerado no Prisma (mais parecido, em espírito, com uma ferramenta como o Alembic combinada com um gerador de código). Ambos evitam escrever SQL e ambos compartilham a mesma escolha de projeto, nenhum lazy loading implícito das relações, o que os distingue do SQLAlchemy. A escolha entre os dois, em um projeto real, depende principalmente do ecossistema (Prisma Studio, migrações do Prisma etc.) e das preferências da equipe.