Kurs NestJS · Moduł 3: TypeORM i bazy danych

Relacje w bazie danych - więzy legionu

5 min czytania ·
W tej lekcji5

Masz już tabelę legionistów i tabelę legionów. Każda z osobna trzyma się dobrze - ale skąd wiadomo, kto pod kim służy? Można by wpisać nazwę legionu w kolumnę tekstową przy każdym legioniście. Do pierwszej literówki: "Legio X Equestris" i "Legio X Equestriss" to dla bazy dwa różne legiony, a Ty właśnie rozbiłeś kohortę na dwie.

Rzymianie znali lepszy sposób. Legionista nie nosi przy sobie nazwy legionu - nosi jego numer. Jeden legion, jeden numer, wszyscy wskazują na ten sam wpis w rejestrze. To jest relacja: powiązanie oparte na identyfikatorze, a nie na przepisywanym tekście.

W tej lekcji poznasz trzy rodzaje takich więzów i nauczysz się je czytać ze strony kodu.

Jeden do wielu - legion i jego legioniści

Zacznijmy od najczęstszego układu. Legion ma wielu legionistów; legionista należy do jednego legionu. Ta relacja ma dwie strony i obie trzeba opisać - każdą w swojej encji:

@Entity()
export class Legion {
  @OneToMany(() => Legionary, (legionary) => legionary.legion)
  legionaries: Legionary[];
}

@Entity()
export class Legionary {
  @ManyToOne(() => Legion, (legion) => legion.legionaries)
  legion: Legion;
}

Kluczowa jest zasada, po której poznasz, gdzie co postawić: dekorator opisuje stronę, na której stoi. Legion jest "jednym", a ma "wielu" legionistów - więc w encji Legion stoi @OneToMany, a pole jest tablicą. Legionista jest jednym z "wielu" i należy do "jednego" legionu - w encji Legionary stoi @ManyToOne, a pole jest pojedyncze. Jeśli kiedykolwiek się zawahasz, przeczytaj zdanie od strony encji, którą właśnie piszesz: "legionista należy do jednego legionu" - i masz @ManyToOne.

Przyjrzyjmy się dwóm argumentom dekoratora, bo oba są obowiązkowe i oba mylą. Pierwszy, () => Legionary, wskazuje encję po drugiej stronie. Dlaczego funkcja, a nie sama nazwa klasy? Bo obie encje odwołują się do siebie nawzajem, a przy takim zapętleniu jedna z klas nie byłaby jeszcze zdefiniowana w chwili odczytu. Funkcja odracza to sięgnięcie do momentu, gdy obie już istnieją.

Drugi argument, (legionary) => legionary.legion, to strona odwrotna: wskazuje pole w tamtej encji, które opisuje tę samą relację. Dzięki niemu TypeORM wie, że Legion.legionaries i Legionary.legion to dwa końce jednego mostu, a nie dwie niezależne relacje.

A co dzieje się w bazie? Kolumna z identyfikatorem powstaje tylko po stronie @ManyToOne - w tabeli legionistów pojawi się legionId. Tabela legionów nie zmienia się wcale. To jest ten "numer noszony przy sobie": każdy legionista wskazuje na swój legion, a nie odwrotnie.

Wiele do wielu - legioniści i umiejętności

Drugi układ: legionista opanował wiele umiejętności, a każdą umiejętność opanowało wielu legionistów. Tu żadna ze stron nie może przechowywać identyfikatora - jedna kolumna nie pomieści listy.

@Entity()
export class Legionary {
  @ManyToMany(() => Skill)
  @JoinTable()
  skills: Skill[];
}

@Entity()
export class Skill {
  @ManyToMany(() => Legionary, (legionary) => legionary.skills)
  legionaries: Legionary[];
}

Rozwiązaniem jest osobna tabela pośrednia, w której jeden wiersz to jedna para: ten legionista zna tę umiejętność. Tworzy ją dla Ciebie dekorator @JoinTable() - i to jest szczegół, na którym potyka się najwięcej osób: @JoinTable() stawiamy tylko po jednej stronie, tej, którą uznajemy za właścicielkę relacji. Postawienie go po obu stronach kończy się dwiema tabelami pośrednimi opisującymi to samo. Postawienie po żadnej - błędem przy starcie aplikacji.

Zwróć uwagę, że @ManyToMany po stronie Legionary obywa się bez drugiego argumentu. Strona odwrotna jest opcjonalna: podajesz ją wtedy, gdy chcesz też z drugiej strony sięgać po powiązania - tu z umiejętności odczytać, kto ją posiadł.

Jeden do jednego - legionista i jego mapa

Trzeci układ jest najprostszy: legionista ma jedną osobistą mapę tributów, a mapa należy do jednego legionisty.

@Entity()
export class Legionary {
  @OneToOne(() => TributeMap)
  @JoinColumn()
  map: TributeMap;
}

Tu decyzję o tym, w której tabeli wyląduje kolumna z identyfikatorem, podejmujesz sam - wskazuje ją @JoinColumn(). Postawiony w encji Legionary sprawia, że to tabela legionistów dostanie kolumnę mapId. Nie myl go z @JoinTable() z poprzedniej sekcji: @JoinColumn wskazuje kolumnę w istniejącej tabeli, @JoinTable tworzy całą nową tabelę pośrednią.

Pobieranie relacji

Relacja opisana w encji nie znaczy, że dane przyjdą same. Domyślnie find() przynosi sam rekord, a pole relacji zostaje puste - i to celowo, bo inaczej pobranie jednego legionisty ciągnęłoby za sobą pół bazy. Powiązania dociągasz świadomie:

const legionaries = await this.legionaryRepo.find({
  relations: ['legion', 'skills'],
});

Klucz relations wylicza, co ma dojechać razem z rekordem. To jest jawne ładowanie i domyślny sposób pracy: w każdym zapytaniu decydujesz osobno, czego potrzebujesz.

Jest też wariant automatyczny. Dopisanie eager: true do relacji sprawia, że dociągnie się ona zawsze, bez proszenia:

@ManyToOne(() => Legion, (legion) => legion.legionaries, { eager: true })
legion: Legion;

Wygodne - i właśnie dlatego niebezpieczne. eager działa w każdym zapytaniu o legionistów, także tam, gdzie legion jest zupełnie niepotrzebny, i po cichu obciąża zapytania w całej aplikacji. Zauważ też, czego eager nie zmienia: to nadal jedno zapytanie z JOIN-em, tylko wykonywane zawsze zamiast na żądanie. Dlatego polecam trzymać się relations i sięgać po eager wyjątkowo - gdy relacja naprawdę jest potrzebna za każdym razem.

Podsumowanie

Legion trzyma się razem, a Ty umiesz opisać jego więzy:

  • relacja łączy tabele przez identyfikator, nie przez przepisywany tekst,
  • dekorator opisuje stronę, na której stoi: @OneToMany po stronie "jednego" (pole tablicowe), @ManyToOne po stronie "wielu" (pole pojedyncze),
  • pierwszy argument to funkcja () => Encja - odracza odczyt klasy, bo encje wskazują na siebie nawzajem,
  • drugi argument wskazuje stronę odwrotną, czyli drugi koniec tego samego mostu,
  • kolumna z identyfikatorem powstaje po stronie @ManyToOne,
  • @ManyToMany wymaga tabeli pośredniej: @JoinTable() tylko po jednej stronie,
  • @OneToOne z @JoinColumn() decyduje, w której tabeli wyląduje kolumna - @JoinColumn wskazuje kolumnę, @JoinTable tworzy nową tabelę,
  • relacje pobierasz jawnie przez relations: ['...']; eager: true robi to zawsze i dlatego stosuj go oszczędnie.

W następnej lekcji poznasz repozytoria - archiwistów, którzy sięgają po te dane w imieniu serwisów. A na razie zapamiętaj: relacja to numer noszony przy sobie - jeden wpis w rejestrze, na który wskazują wszyscy, zamiast nazwy przepisywanej przy każdym legioniście.

Kod do tej lekcji: src/relations.ts
// Relacje w Bazie Danych - Wiezy Miedzy Legionariuszami
import {
  Entity, Column, PrimaryGeneratedColumn,
  OneToMany, ManyToOne, ManyToMany,
  JoinColumn, JoinTable, OneToOne,
} from 'typeorm';

console.log("Relacje TypeORM - wiezi miedzy danymi imperium!");

// ===========================================
// 1. OneToMany / ManyToOne - Legion i Zolnierze
// ===========================================

@Entity('legions')
export class Legion {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  commander: string;

  @OneToMany(() => Soldier, soldier => soldier.legion)
  soldiers: Soldier[];
}

@Entity('soldiers')
export class Soldier {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  rank: string;

  @ManyToOne(() => Legion, legion => legion.soldiers)
  @JoinColumn({ name: 'legion_id' })
  legion: Legion;
}

// ===========================================
// 2. OneToOne - Legionista i Mapa
// ===========================================

@Entity('tribute_maps')
export class TributeMap {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  location: string;

  @Column()
  description: string;

  @OneToOne(() => Soldier)
  @JoinColumn()
  owner: Soldier;
}

// ===========================================
// 3. ManyToMany - Bitwy i Legiony
// ===========================================

@Entity('battles')
export class Battle {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  location: string;

  @ManyToMany(() => Legion)
  @JoinTable({
    name: 'battle_legions',
    joinColumn: { name: 'battle_id' },
    inverseJoinColumn: { name: 'legion_id' },
  })
  legions: Legion[];
}

// ===========================================
// 4. Ladowanie relacji (eager vs lazy)
// ===========================================

// Eager loading (automatyczne):
// @OneToMany(() => Soldier, s => s.legion, { eager: true })
// soldiers: Soldier[];

// Lazy loading (na zadanie):
// const legion = await legionRepo.findOne({
//   where: { id: 1 },
//   relations: ['soldiers'],
// });

// Kaskadowe operacje:
// @OneToMany(() => Soldier, s => s.legion, { cascade: true })
// soldiers: Soldier[];

console.log("\n=== PODSUMOWANIE RELACJI ===");
console.log("@OneToMany + @ManyToOne - jeden do wielu (legion -> zolnierze)");
console.log("@OneToOne - jeden do jednego (legionista -> mapa)");
console.log("@ManyToMany + @JoinTable - wiele do wielu (bitwy -> legiony)");
console.log("@JoinColumn - strona posiadajaca klucz obcy");
console.log("relations: ['x'] - ladowanie relacji w zapytaniu");

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co oznacza relacja @OneToMany w TypeORM?

  2. 2. Po której stronie relacji umieszcza się @ManyToOne?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Napisz encje Legion z @OneToMany(() => Legionary, ...) i Legionary z @ManyToOne(() => Legion, ...)

  • Układanie w poziomie

    Ułóż elementy deklaracji @OneToMany w prawidłowej kolejności:

  • Klikanie w kolejności

    Ułóż elementy konfiguracji eager loading relacji w prawidłowej kolejności:

  • Edytor kodu

    Napisz encję Legionary z @ManyToMany(() => Skill) i @JoinTable() oraz encję Skill z @ManyToMany(() => Legionary)

  1. PytanieRelacja OneToMany
  2. PytanieDekorator @ManyToOne
  3. Zadanie z kodemRelacja OneToMany i ManyToOne
  4. Ułóż w kolejnościDeklaracja relacji OneToMany
  5. PytanieRelacja ManyToMany
  6. Kliknij w kolejnościKonfiguracja eager loading
  7. Zadanie z kodemRelacja ManyToMany z JoinTable

Przydatne artykuły