7. Acesso a bancos de dados

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

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:

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

| # 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:
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:
| 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.