Kurs NestJS · Moduł 3: TypeORM i bazy danych

Database Validation - kontrola jakości danych

6 min czytania ·
W tej lekcji8

Do skarbca trafił wczoraj legionista bez imienia. Dziś - dwa identyczne wpisy tego samego tributu. Konsul Caesar.js jest wściekły: przecież walidujemy dane w DTO! Owszem - ale walidacja w warstwie API chroni tylko jedną bramę. Dane wchodzą do bazy także innymi drogami: przez seeder, przez inny serwis, przez ręczne zapytanie administratora. Dlatego dojrzały system ustawia strażników warstwami: DTO sprawdza kształt żądania, serwis pilnuje reguł biznesowych, a baza danych jest ostatnią linią obrony - murem, którego nie obejdzie nikt. W tej lekcji budujemy właśnie ten mur.

Reguły wprost w kolumnach

Pierwsza linia muru to definicje kolumn. Dekorator @Column przyjmuje opcje, które baza zamieni na twarde ograniczenia:

@Entity()
export class Legionary {
  @Column({ length: 100, nullable: false })
  name: string;

  @Column({ unique: true })
  codeName: string;

  @Column({ type: 'int', default: 0 })
  tributeCount: number;

  @Column({ type: 'boolean', default: true })
  isActive: boolean;
}

Przeczytajmy te opcje jak rozkazy dla bazy. nullable: false to SQL-owe NOT NULL - rekord bez imienia zostanie odrzucony, zanim dotknie tabeli. unique: true zakłada ograniczenie unikalności: drugi legionista o tym samym codeName wywoła błąd bazy, nie cichy duplikat. default uzupełnia wartość, gdy jej nie podano - nowy legionista startuje z zerem tributów, bez pisania tego w kodzie. A type i length dobierają typ kolumny do danych: liczba całkowita dla licznika, tekst o ograniczonej długości dla imienia. Zauważ, że te reguły działają zawsze - niezależnie od tego, którą drogą dane wchodzą.

Indeksy - spis treści skarbca

Skoro codeName ma być unikalny, baza i tak zbudowała dla niego indeks. Ale indeks przyda się także tam, gdzie często szukamy, choć unikalności nie wymagamy - dekorator @Index zakładamy wtedy sami:

@Entity()
@Index(['rank', 'isActive'])
export class Legionary {
  @Index()
  @Column()
  lastName: string;
}

Indeks działa jak spis treści księgi inwentarzowej: zamiast kartkować całą tabelę, baza skacze prosto do właściwej strony. Pojedynczy @Index() nad kolumną przyspiesza wyszukiwanie po lastName; indeks złożony nad klasą - zapytania filtrujące jednocześnie po randze i aktywności. To najprostsza optymalizacja zapytań, jaką znasz z tej lekcji: zero zmian w kodzie serwisu, a zapytania z where po tych kolumnach przestają skanować całą tabelę. Cena jest jedna - każdy zapis musi zaktualizować także indeks - dlatego indeksujemy kolumny, po których naprawdę szukamy, a nie wszystkie.

Znaczniki czasu - kronika automatyczna

Kiedy rekord powstał? Kiedy go ostatnio zmieniano? Tych dwóch kolumn nie wypełniamy nigdy ręcznie:

@CreateDateColumn()
createdAt: Date;

@UpdateDateColumn()
updatedAt: Date;

@CreateDateColumn dostaje datę raz, przy tworzeniu rekordu, i już się nie zmienia. @UpdateDateColumn odświeża się przy każdym zapisie. Kronika prowadzi się sama - a Ty zyskujesz odpowiedź na pytanie "co się tu ostatnio działo", zanim ktokolwiek je zada.

Hooki encji - rytuał przed zapisem

Czasem przed zapisem trzeba coś dopilnować: przyciąć spacje, znormalizować wielkość liter, wyliczyć pole pochodne. Do tego służą hooki - metody encji oznaczone dekoratorem, które TypeORM wywoła sam w odpowiednim momencie:

@Entity()
export class Legionary {
  @Column()
  codeName: string;

  @BeforeInsert()
  @BeforeUpdate()
  normalizeCodeName() {
    this.codeName = this.codeName.trim().toLowerCase();
  }
}

@BeforeInsert odpala metodę tuż przed pierwszym zapisem rekordu, @BeforeUpdate - przed każdą aktualizacją. Tutaj oba dekoratory wiszą nad jedną metodą, więc normalizacja zadziała w obu sytuacjach: niezależnie od tego, jak niechlujnie wpisano codeName, do bazy trafi wersja przycięta i pisana małymi literami. Ważna granica: hook mieszka w encji i widzi tylko ją samą. Gdy potrzebujesz reagować na zapisy wielu encji w jednym miejscu (na przykład logować każdą zmianę w skarbcu), TypeORM oferuje subscribers - osobne klasy nasłuchujące zdarzeń całej bazy. Zapamiętaj podział: hook - rytuał jednej encji, subscriber - obserwator całego systemu.

Soft delete - wygnanie zamiast egzekucji

Rozkaz "usuń legionistę" bywa pochopny. Zwykłe delete kasuje rekord bezpowrotnie - a razem z nim historię tributów i powiązania. Dlatego dojrzałe systemy stosują soft delete: rekord dostaje znacznik usunięcia, ale fizycznie zostaje w tabeli. W TypeORM wystarczy jedna kolumna:

@Entity()
export class Legionary {
  @DeleteDateColumn()
  deletedAt: Date;
}

// usunięcie miękkie - ustawia deletedAt, rekord zostaje
await legionaryRepository.softDelete(legionaryId);

// przywrócenie - czyści deletedAt
await legionaryRepository.restore(legionaryId);

// znalezienie także usuniętych
const all = await legionaryRepository.find({ withDeleted: true });

Obecność @DeleteDateColumn zmienia zachowanie całego repozytorium: softDelete wpisuje datę do deletedAt, a każde zwykłe find zaczyna automatycznie pomijać rekordy z ustawioną datą - usunięty legionista znika z wyników, choć w tabeli wciąż jest. restore czyści znacznik i legionista wraca do służby. A gdy audytor chce zobaczyć wszystkich, także wygnanych - dodaje opcję withDeleted: true. Egzekucja stała się wygnaniem: odwracalnym i zostawiającym ślad.

Cascade - los rekordów powiązanych

Została ostatnia decyzja strażnika: co z tributami, gdy ich właściciel znika? Odpowiedź zapisujemy w definicji relacji:

@OneToMany(() => Tribute, (tribute) => tribute.legionariusze, {
  cascade: true,
})
tributes: Tribute[];

@ManyToOne(() => Legionary, { onDelete: 'CASCADE' })
legionariusze: Legionary;

To dwie różne kaskady i warto je rozróżniać. cascade: true działa przy zapisie: zapisując legionistę z nowymi tributami w tablicy, TypeORM zapisze i jego, i je - jednym ruchem. onDelete: 'CASCADE' działa przy usuwaniu, po stronie bazy: gdy legionista znika naprawdę, baza sama usuwa jego tributy, nie zostawiając rekordów-sierot. Alternatywy dla 'CASCADE' to między innymi 'SET NULL' - tribut zostaje, ale traci właściciela. Wybór należy do Ciebie - ale podejmij go świadomie, bo kaskada usuwania to najostrzejsze narzędzie w tej lekcji.

findAndCount - paginacja po stronie repozytorium

Na koniec spinamy kontrolę jakości z czymś, co znasz z lekcji o Query Builderze: podawaniem wyników porcjami. Repozytorium ma do tego gotową parę metod w jednej:

const [legionaries, total] = await legionaryRepository.findAndCount({
  where: { isActive: true },
  order: { name: 'ASC' },
  skip: (page - 1) * limit,
  take: limit,
});

findAndCount zwraca tablicę dwuelementową: listę wyników i łączną liczbę pasujących rekordów. Zapis const [legionaries, total] = ... to destrukturyzacja - rozpakowujemy parę do dwóch nazwanych zmiennych w jednej linii. Reszta wygląda jak zwykłe find: skip pomija poprzednie strony, take pobiera porcję. To repozytoryjny bliźniak getManyAndCount() z Query Buildera - prostszy zapis na prostsze przypadki, a gdy warunki się komplikują, wracasz do buildera.

Podsumowanie

Mur wokół skarbca stoi. Ułożyłeś go warstwami:

  • opcje @Column: nullable, unique, default, type i length - twarde reguły egzekwowane przez samą bazę,
  • @Index - spis treści dla kolumn, po których szukasz; przyspiesza odczyty kosztem zapisów,
  • @CreateDateColumn i @UpdateDateColumn - kronika prowadząca się sama,
  • @BeforeInsert i @BeforeUpdate - rytuał encji przed zapisem; subscribers - obserwator zdarzeń całej bazy,
  • @DeleteDateColumn z softDelete, restore i withDeleted - wygnanie zamiast egzekucji,
  • cascade przy zapisie i onDelete: 'CASCADE' przy usuwaniu - świadomy los rekordów powiązanych,
  • findAndCount z destrukturyzacją [wyniki, licznik] - paginacja bez Query Buildera.

Przed Tobą projekt kończący moduł: system inwentaryzacji tributów, w którym te strażnicze mechanizmy spotkają się w jednym kodzie. A na razie zapamiętaj: walidacja w DTO chroni bramę, ale to reguły w bazie są murem - działają zawsze, niezależnie od tego, którędy dane próbują wejść.

Kod do tej lekcji: src/database-validation.ts
// Database Validation - Kontrola Jakosci Danych
import {
  Entity, Column, PrimaryGeneratedColumn, Index,
  CreateDateColumn, UpdateDateColumn, DeleteDateColumn,
  Check, BeforeInsert, BeforeUpdate, AfterInsert,
} from 'typeorm';

console.log("Walidacja bazy danych - ostatnia linia obrony!");

// ===========================================
// 1. Constraints na kolumnach
// ===========================================

@Entity('tribute_records')
@Index(['provincia', 'year']) // Indeks zlozony
export class TributeRecord {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 100 })
  provincia: string;

  @Column({ type: 'decimal', precision: 12, scale: 2 })
  @Check('"amount" > 0') // Wartosc musi byc dodatnia
  amount: number;

  @Column({ type: 'int' })
  year: number;

  @Index() // Indeks na kolumnie
  @Column({ length: 100 })
  collector: string;

  @Column({ type: 'enum', enum: ['gold', 'silver', 'goods'], default: 'gold' })
  type: string;

  @CreateDateColumn()
  createdAt: Date;
}

// ===========================================
// 2. Entity hooks (lifecycle events)
// ===========================================

@Entity('centurions')
export class Centurion {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  rank: string;

  @Column({ default: 0 })
  experience: number;

  @Column({ nullable: true })
  slug: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @BeforeInsert()
  generateSlug() {
    if (this.name) {
      this.slug = this.name.toLowerCase().replace(/ /g, '-');
    }
  }

  @BeforeUpdate()
  validateExperience() {
    if (this.experience < 0) {
      this.experience = 0;
    }
  }

  @AfterInsert()
  logCreation() {
    console.log('Nowy centurion zaciagniety: ' + this.name);
  }
}

// ===========================================
// 3. Soft delete
// ===========================================

@Entity('decrees')
export class Decree {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 200 })
  title: string;

  @Column({ type: 'text' })
  content: string;

  @Column({ type: 'boolean', default: true })
  isActive: boolean;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @DeleteDateColumn() // Soft delete - nie usuwaj naprawde
  deletedAt: Date;
}

// Uzycie soft delete:
// await decreeRepo.softDelete(id);     // Ustawia deletedAt
// await decreeRepo.restore(id);        // Przywraca
// await decreeRepo.find();             // Pomija soft-deleted
// await decreeRepo.find({ withDeleted: true }); // Wszystkie

console.log("\n=== PODSUMOWANIE WALIDACJI DB ===");
console.log("@Check() - constrainty na poziomie bazy danych");
console.log("@Index() - indeksy przyspieszajace wyszukiwanie");
console.log("@BeforeInsert/@BeforeUpdate - hooki cyklu zycia");
console.log("@DeleteDateColumn - soft delete (nie usuwaj naprawde)");
console.log("unique: true - unikalnosc kolumny");

Hasła z dokumentacji w tej lekcji

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. Jak dodać walidację na poziomie encji w TypeORM z class-validator?

  2. 2. Jak oznaczyć kolumnę jako unikalną w encji TypeORM?

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

Zadania praktyczne w grze

  • Edytor kodu

    Napisz encję Province z @Index() na nazwie, @Column({ unique: true }) dla kodu i dekoratorami @IsString(), @Length(2, 100)

  • Układanie w pionie

    Uporządkuj warstwy walidacji danych od zewnętrznej do wewnętrznej:

  • Klikanie w kolejności

    Ułóż elementy definicji kolumny z wartością domyślną i NOT NULL:

  • Edytor kodu

    Napisz encję z @BeforeInsert() który ustawia createdAt na new Date() i @BeforeUpdate() który ustawia updatedAt

  • Układanie w poziomie

    Ułóż elementy dekoratora @Index dla encji z wieloma kolumnami:

  • Układanie w pionie

    Uporządkuj typy kolumn TypeORM od najprostszego do najbardziej złożonego:

  • Edytor kodu

    Napisz encję z @CreateDateColumn(), @UpdateDateColumn() i @DeleteDateColumn() dla soft delete

  • Klikanie w kolejności

    Ułóż elementy soft delete za pomocą repozytorium w prawidłowej kolejności:

  • Układanie w poziomie

    Ułóż elementy zapytania o rekordy włącznie z soft-deleted:

  • Układanie w pionie

    Uporządkuj techniki optymalizacji zapytań od najprostszej do najbardziej zaawansowanej:

  • Edytor kodu

    Napisz metodę findPaginated(page, limit), która używa findAndCount z skip i take do paginacji legionistów

  • Układanie w poziomie

    Ułóż elementy destrukturyzacji wyniku findAndCount:

  1. PytanieWalidacja na poziomie encji
  2. PytanieUnique constraint
  3. Zadanie z kodemEncja z walidacją i indeksami
  4. Ułóż w kolejnościWarstwy walidacji danych w NestJS
  5. Kliknij w kolejnościDefinicja kolumny z NOT NULL i default
  6. PytanieHook BeforeInsert
  7. Zadanie z kodemEntity hooks i subscribers
  8. Ułóż w kolejnościDekorator Index na encji
  9. Ułóż w kolejnościTypy kolumn od najprostszego do najbardziej złożonego
  10. PytanieSoft delete w TypeORM
  11. Zadanie z kodemEncja z soft delete i timestampami
  12. Kliknij w kolejnościSoft delete z repozytorium
  13. Ułóż w kolejnościOdzyskanie soft-deleted rekordów
  14. PytanieCascade w relacjach
  15. Ułóż w kolejnościOptymalizacja zapytań bazy danych
  16. Zadanie z kodemPaginacja wyników
  17. PytanieMetoda findAndCount
  18. Ułóż w kolejnościDestrukturyzacja findAndCount

Przydatne artykuły