Banco de Dados5 min de leitura

Domínio Relacional no TypeORM: Eager Loading, Cascades e JoinTables

Como modelar relacionamentos complexos corretamente: OneToMany vs ManyToOne, o perigo do eager: true, como customizar a JoinTable em relacionamentos ManyToMany e a diferença entre cascade: insert e cascade: update.

12 de agosto de 2026

O verdadeiro poder dos bancos de dados SQL está nas relações (Foreign Keys). Mas mapear a teoria relacional para o paradigma de Orientação a Objetos no Node.js tem suas armadilhas. Entender exatamente de qual lado declarar as chaves e quando delegar o carregamento dos relacionamentos salva a aplicação do temido gargalo de N+1 queries.

1. O Lado Dono da Chave (ManyToOne / OneToMany)

Em um relacionamento 'Um para Muitos' (ex: Um Usuário tem Muitos Pedidos), a tabela do 'Muitos' sempre hospeda a chave estrangeira (o Pedido tem um user_id). Por isso, no TypeORM, o lado que usa @ManyToOne obrigatoriamente usa o @JoinColumn. A simetria é importante: Order declara @ManyToOne, User declara @OneToMany apontando de volta para order.user. Sem o lado @OneToMany, o TypeORM não consegue navegar a relação inversa.

Order.ts (O Lado 'Muitos')

1import { Entity, Column, PrimaryGeneratedColumn, ManyToOne, JoinColumn } from 'typeorm';
import { Entity, Column, PrimaryGeneratedColumn, ManyToOne, JoinColumn } from 'typeorm';
2import { User } from './User';
import { User } from './User';
3

4@Entity('orders')
@Entity('orders')
5export class Order {
export class Order {
6  @PrimaryGeneratedColumn('uuid')
  @PrimaryGeneratedColumn('uuid')
7  id: string;
  id: string;
8

9  @Column()
  @Column()
10  userId: string; // Fica visível para queries diretas e inserts rápidos
  userId: string; // Fica visível para queries diretas e inserts rápidos
11

12  // O relacionamento espelho
  // O relacionamento espelho
13  @ManyToOne(() => User, user => user.orders)
  @ManyToOne(() => User, user => user.orders)
14  @JoinColumn({ name: 'userId' }) // Define qual coluna guarda o ID no banco
  @JoinColumn({ name: 'userId' }) // Define qual coluna guarda o ID no banco
15  user: User;
  user: User;
16}
}

User.ts (O Lado 'Um')

1import { Entity, PrimaryGeneratedColumn, OneToMany } from 'typeorm';
import { Entity, PrimaryGeneratedColumn, OneToMany } from 'typeorm';
2import { Order } from './Order';
import { Order } from './Order';
3

4@Entity('users')
@Entity('users')
5export class User {
export class User {
6  @PrimaryGeneratedColumn('uuid')
  @PrimaryGeneratedColumn('uuid')
7  id: string;
  id: string;
8

9  // Aqui NÃO VAI JoinColumn. O TypeORM apenas sabe que a relação
  // Aqui NÃO VAI JoinColumn. O TypeORM apenas sabe que a relação
10  // reversa se chama 'user' dentro da classe Order.
  // reversa se chama 'user' dentro da classe Order.
11  @OneToMany(() => Order, order => order.user)
  @OneToMany(() => Order, order => order.user)
12  orders: Array<Order>;
  orders: Array<Order>;
13}
}

Fuja do `eager: true`: Se você colocar @OneToMany(..., { eager: true }) no User, toda vez que fizer um .findOneBy({ id }), o TypeORM secretamente fará um LEFT JOIN para puxar os pedidos. Se você tiver mil pedidos, o banco trará uma carga massiva de dados silenciosamente. Use relações explícitas via relations: ['orders'] no seu Repository.

2. Tabelas Pivô Nativas (ManyToMany)

Em um relacionamento Muitos-para-Muitos (ex: Produto pode estar em muitas Categorias e uma Categoria pode ter muitos Produtos), o banco de dados usa uma tabela pivot (ou join table) para representar as associações. O TypeORM cria e gerencia essa tabela automaticamente — mas você pode customizá-la se precisar de colunas extras na associação (ex: data de adição, prioridade).

Relações Muito para Muitos exigem uma tabela intermediária no SQL. Se um Produto pertence a várias Categorias e vice-versa, o TypeORM abstrai essa tabela pivô com o @JoinTable. Apenas um lado do relacionamento (você escolhe qual) recebe essa anotação.

Product.ts

1import { Entity, PrimaryGeneratedColumn, ManyToMany, JoinTable } from 'typeorm';
import { Entity, PrimaryGeneratedColumn, ManyToMany, JoinTable } from 'typeorm';
2import { Category } from './Category';
import { Category } from './Category';
3

4@Entity('products')
@Entity('products')
5export class Product {
export class Product {
6  @PrimaryGeneratedColumn('uuid')
  @PrimaryGeneratedColumn('uuid')
7  id: string;
  id: string;
8

9  @ManyToMany(() => Category)
  @ManyToMany(() => Category)
10  @JoinTable({
  @JoinTable({
11    name: 'products_categories', // Nome da tabela pivô no banco
    name: 'products_categories', // Nome da tabela pivô no banco
12    joinColumn: {
    joinColumn: {
13      name: 'product_id', // Como se chama o ID do produto lá
      name: 'product_id', // Como se chama o ID do produto lá
14      referencedColumnName: 'id'
      referencedColumnName: 'id'
15    },
    },
16    inverseJoinColumn: {
    inverseJoinColumn: {
17      name: 'category_id', // Como se chama o ID da categoria lá
      name: 'category_id', // Como se chama o ID da categoria lá
18      referencedColumnName: 'id'
      referencedColumnName: 'id'
19    }
    }
20  })
  })
21  categories: Array<Category>;
  categories: Array<Category>;
22}
}

3. O Poder (e Risco) dos Cascades

Se configurarmos { cascade: ['insert'] }, o TypeORM permite criar a árvore inteira de dados em um único .save().

Exemplo de Cascade

1// Se o relacionamento categorias estiver com cascade: ['insert']
// Se o relacionamento categorias estiver com cascade: ['insert']
2// Você pode salvar o Produto e criar Categorias novas na mesma transação
// Você pode salvar o Produto e criar Categorias novas na mesma transação
3const product = productRepo.create({
const product = productRepo.create({
4  name: 'Notebook',
  name: 'Notebook',
5  categories: [
  categories: [
6    { name: 'Eletrônicos' }, // Não tem ID, será um INSERT
    { name: 'Eletrônicos' }, // Não tem ID, será um INSERT
7    { id: 'uuid-existente' } // Tem ID, apenas vinculará na tabela pivô
    { id: 'uuid-existente' } // Tem ID, apenas vinculará na tabela pivô
8  ]
  ]
9});
});
10

11await productRepo.save(product);
await productRepo.save(product);

Conclusão

O TypeORM tira todo o peso de escrever queries complexas de junção, mas essa abstração cobra um preço: se você errar a direção do JoinColumn ou abusar do Eager Loading, a performance do sistema sofrerá sem que você veja os comandos SQL rodando de fundo. Mantenha os mapeamentos explícitos e faça queries focadas.