Kurs NestJS · Moduł 3: TypeORM i bazy danych
Migracje i Entity - archiwum rzymskiego legionu
W tej lekcji6
Dodałeś do encji Legionary pole rank. U Ciebie działa - baza deweloperska sama dorobiła kolumnę. Wysyłasz kod, a nazajutrz przychodzi wiadomość od kolegi: aplikacja nie wstaje, bo w jego bazie kolumny rank nie ma. Na produkcji byłoby gorzej - tam nikt nie pozwoli bazie przebudowywać się samodzielnie, bo przy okazji potrafi skasować dane.
Problem jest ten sam co z kodem, zanim wymyślono git: zmiany w strukturze bazy nie mają historii. Nie wiadomo, kto co zmienił, w jakiej kolejności i jak to cofnąć. Rzymianie prowadzili na to archiwum - każda zmiana w rejestrze legionu zapisana jako osobny dokument z datą. W TypeORM ten dokument nazywa się migracją.
Czym jest migracja
Migracja to plik z jedną zmianą schematu bazy - dodaniem tabeli, kolumny, indeksu. Ma znacznik czasu w nazwie, więc migracje układają się w kolejność, a baza pamięta, które już wykonała. To wersjonowanie schematu: dokładnie to samo, co git robi z kodem, tylko dla struktury tabel.
Dzięki temu każdy kolega odpala u siebie te same migracje w tej samej kolejności i dostaje identyczną bazę. A na produkcji zmiana wchodzi świadomie, jednym poleceniem, a nie przez zgadywanie ORM-a. Dlatego synchronize: true - opcja, która pozwala TypeORM przebudowywać bazę pod encje - jest wygodna lokalnie, ale nigdy nie powinna trafić na produkcję.
Anatomia migracji: up i down
Migracja to klasa implementująca interfejs MigrationInterface z dwiema metodami:
import { MigrationInterface, QueryRunner } from 'typeorm';
export class CreateLegionaryTable1710000000000 implements MigrationInterface {
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
CREATE TABLE "legionary" (
"id" SERIAL PRIMARY KEY,
"name" character varying(100) NOT NULL,
"rank" character varying(50)
)
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP TABLE "legionary"`);
}
}Te dwie metody to droga tam i z powrotem. up() wprowadza zmianę - tu tworzy tabelę. down() ją cofa - usuwa tę samą tabelę. Zasada jest prosta: down() musi dokładnie odwracać to, co zrobiło up(). Dodałeś kolumnę w up? Usuń ją w down. Bez tego wycofanie migracji zostawi bazę w stanie, którego nikt nie przewidział.
Zwróć uwagę na argument obu metod: queryRunner. To ten sam obiekt, który poznasz jeszcze w lekcji o transakcjach - reprezentuje połączenie z bazą, na którym wykonujemy polecenia. Liczba w nazwie klasy (1710000000000) to znacznik czasu utworzenia; to po nim TypeORM ustala kolejność migracji, a nie po nazwie pliku.
Cykl pracy z migracjami
W codziennej pracy rzadko piszesz migracje ręcznie. Kolejność jest zawsze taka sama i warto ją zapamiętać jako cztery kroki:
1. Zmień encję - dodaj pole, zmień typ, usuń kolumnę. To jedyne miejsce, gdzie opisujesz, jak ma wyglądać baza.
2. Wygeneruj migrację poleceniem, które porówna encje ze stanem bazy i zapisze różnicę:
typeorm migration:generate -n AddRankToLegionary3. Uruchom migrację - dopiero teraz zmiana trafia do bazy:
typeorm migration:run4. Sprawdź wynik w bazie - czy kolumna jest, czy ma właściwy typ, czy dane ocalały.
Między krokiem drugim a trzecim jest miejsce, o którym łatwo zapomnieć: przeczytaj wygenerowany plik. Generator porównuje encje z bazą i czasem interpretuje zmianę inaczej, niż zamierzałeś - zamiast zmienić nazwę kolumny, potrafi usunąć starą i dodać nową, gubiąc po drodze wszystkie dane. Ten przegląd zajmuje pół minuty i to polecam jako nawyk.
generate a create - dwie różne komendy
Warto rozdzielić dwa polecenia o mylnie podobnych nazwach. migration:generate porównuje encje z bazą i wypełnia up() oraz down() za Ciebie - to komenda, której użyjesz w 95% przypadków. migration:create tworzy pusty szkielet migracji, który wypełniasz sam - przydaje się, gdy zmiana nie wynika z encji, na przykład przy przenoszeniu danych między kolumnami.
Gdy migracja okaże się błędna, cofasz ją jednym poleceniem:
typeorm migration:revertrevert wywołuje metodę down() ostatniej wykonanej migracji - jednej, nie wszystkich. Żeby cofnąć się o trzy kroki, wywołujesz je trzy razy. I tu widać, po co była ta dyscyplina przy pisaniu down(): cofnięcie zadziała dokładnie tak dobrze, jak dobrze opisałeś drogę powrotną.
Encja steruje migracją - opcje kolumn
Skoro migracje powstają z encji, to opcje kolumn są tak naprawdę instrukcjami dla generatora. Kilka z nich warto znać, bo wprost decydują o kształcie tabeli:
@Entity()
export class Tribute {
@PrimaryGeneratedColumn()
id: number;
@Column({ type: 'varchar', length: 100 })
name: string;
@Column({ type: 'decimal', precision: 10, scale: 2 })
value: number;
@Column({ default: false })
isCursed: boolean;
}@PrimaryGeneratedColumn() to klucz główny nadawany automatycznie przez bazę - nigdy nie ustawiasz go ręcznie. type: 'varchar' z length: 100 daje tekst o ograniczonej długości; próba zapisania dłuższej nazwy zostanie odrzucona przez bazę, a nie po cichu przycięta.
Najciekawszy jest decimal z parą precision i scale, bo ta para bywa myląca. precision to łączna liczba cyfr, a scale - ile z nich stoi po przecinku. Zapis precision: 10, scale: 2 oznacza więc osiem cyfr przed przecinkiem i dwie po nim, czyli wartości do 99 999 999,99. Dlaczego nie zwykły float? Bo liczby zmiennoprzecinkowe zaokrąglają - przy pieniądzach i wartościach tributów sumy przestałyby się zgadzać. decimal przechowuje dokładną wartość.
default: false wpisuje wartość domyślną do definicji kolumny w bazie - nowy tribut będzie nieprzeklęty, nawet jeśli kod tego pola nie poda.
Podsumowanie
Archiwum legionu prowadzi się samo, a Ty wiesz, jak je czytać:
- migracja to wersjonowanie schematu bazy - git dla struktury tabel,
synchronize: truebywa wygodne lokalnie, ale na produkcji potrafi skasować dane,- klasa migracji implementuje
MigrationInterface:up()wprowadza zmianę,down()musi ją dokładnie odwracać, - cykl pracy: zmień encję,
migration:generate, przeczytaj wygenerowany plik,migration:run, sprawdź bazę, generatewypełnia migrację z różnicy encji i bazy,createdaje pusty szkielet do napisania ręcznie,migration:revertcofa jedną, ostatnią migrację, wywołując jejdown(),- opcje kolumn sterują generatorem:
lengthogranicza tekst,decimalzprecisioniscaleprzechowuje dokładne kwoty,defaultwpisuje wartość domyślną do bazy.
W następnej lekcji połączymy tabele relacjami - bo legionista bez centuriona i tributu to wciąż samotny wpis w rejestrze. A na razie zapamiętaj: migracja to dokument w archiwum - opisuje jedną zmianę i drogę powrotną, dzięki czemu każda baza w Imperium może dojść do tego samego stanu.
Kod do tej lekcji: src/migrations.ts
// Migracje i Entity - Archiwum Rzymskiego Legionu
import { MigrationInterface, QueryRunner, Table, TableColumn } from 'typeorm';
console.log("Migracje - bezpieczna reorganizacja skarbca!");
// ===========================================
// 1. Tworzenie tabeli - pierwsza migracja
// ===========================================
export class CreateLegionaries1700000000000 implements MigrationInterface {
async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.createTable(
new Table({
name: 'legionaries',
columns: [
{
name: 'id',
type: 'integer',
isPrimary: true,
isGenerated: true,
generationStrategy: 'increment',
},
{ name: 'name', type: 'varchar', isNullable: false },
{ name: 'rank', type: 'varchar', isNullable: false },
{ name: 'experience', type: 'integer', default: '0' },
{ name: 'legion', type: 'varchar', isNullable: false },
{ name: 'created_at', type: 'timestamp', default: 'now()' },
],
}),
);
console.log('Tabela legionaries utworzona!');
}
async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.dropTable('legionaries');
console.log('Tabela legionaries usunieta!');
}
}
// ===========================================
// 2. Dodanie kolumny - kolejna migracja
// ===========================================
export class AddProvinceToLegionaries1700000001000 implements MigrationInterface {
async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.addColumn(
'legionaries',
new TableColumn({
name: 'province',
type: 'varchar',
isNullable: true,
default: "'Roma'",
}),
);
console.log('Dodano kolumne province!');
}
async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.dropColumn('legionaries', 'province');
}
}
// ===========================================
// 3. Komendy migracji
// ===========================================
// npx typeorm migration:generate -n CreateLegionaries
// npx typeorm migration:run // Wykonaj migracje
// npx typeorm migration:revert // Cofnij ostatnia
// npx typeorm migration:show // Pokaz status
// ===========================================
// 4. Konfiguracja migracji
// ===========================================
// ormconfig.ts / data-source.ts
// export const dataSource = new DataSource({
// type: 'postgres',
// host: 'localhost',
// port: 5432,
// migrations: ['src/migrations/*.ts'],
// migrationsTableName: 'typeorm_migrations',
// });
console.log("\n=== PODSUMOWANIE MIGRACJI ===");
console.log("up() - wykonuje zmiane (tworzenie tabeli, dodanie kolumny)");
console.log("down() - cofa zmiane (usuwanie tabeli, kolumny)");
console.log("migration:run - wykonuje oczekujace migracje");
console.log("migration:revert - cofa ostatnia migracje");
console.log("synchronize: true TYLKO w development!");
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. Do czego służą migracje w TypeORM?
2. Jaką komendą generujemy migrację na podstawie zmian w encjach TypeORM?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Stwórz migrację CreateLegionaryTable z metodą up() tworzącą tabelę i down() usuwającą ją
- Układanie w pionie
Uporządkuj kroki procesu migracji bazy danych od pierwszego do ostatniego:
- Klikanie w kolejności
Ułóż elementy komendy generowania migracji w prawidłowej kolejności:
- Edytor kodu
Napisz encję Tribute z @Column({ type: 'varchar', length: 100 }), @Column({ type: 'decimal', precision: 10, scale: 2 }) i @Column({ default: false })