Kurs NestJS · Moduł 3: TypeORM i bazy danych
Transakcje - bezpieczne operacje na tributach
W tej lekcji6
Legionista Marek przekazuje złoty puchar Gajuszowi. W kodzie to dwie operacje: odjąć puchar z inwentarza Marka, dopisać go Gajuszowi. Wykonujesz pierwszą, a w tej samej chwili pada serwer bazy. Rezultat? Puchar zniknął ze skarbca Imperium. Nie ma go u Marka, nie dotarł do Gajusza - wyparował między dwoma zapisami.
Skarbiec nie może sobie na to pozwolić. Potrzebujemy sposobu, by powiedzieć bazie: "te dwie operacje to jeden rozkaz - wykonaj obie albo żadnej". Tym sposobem jest transakcja.
Atomowość i reszta ACID
Właściwość, której szukamy, nazywa się atomowość (ang. atomicity) - transakcja jest niepodzielna jak atom: nie da się jej wykonać w połowie. To pierwsza litera skrótu ACID, którym opisuje się gwarancje transakcji:
- Atomicity - atomowość: albo wszystkie operacje, albo żadna,
- Consistency - spójność: baza przechodzi z jednego poprawnego stanu w drugi, nigdy nie zostaje w połowie,
- Isolation - izolacja: równolegle działające transakcje nie podglądają swoich niedokończonych zmian,
- Durability - trwałość: po zatwierdzeniu zmiany przetrwają nawet awarię zasilania.
Zapamiętaj przede wszystkim to A - reszta z niego wynika i to o nie chodzi w naszym pucharze.
Cykl życia transakcji
Każda transakcja przechodzi tę samą drogę, niezależnie od bazy i języka. Najpierw BEGIN - ogłaszamy początek i od tej chwili baza zapisuje zmiany na boku, jako nietrwałe. Potem wykonujemy operacje - nasze dwa zapisy. Następnie sprawdzamy, czy wszystko się udało. I na końcu jedna z dwóch dróg: COMMIT zatwierdza całość i dopiero teraz zmiany stają się trwałe, albo ROLLBACK cofa wszystko, jakby transakcji nigdy nie było.
Ten schemat - rozpocznij, wykonaj, zweryfikuj, zatwierdź lub cofnij - warto mieć w głowie, zanim spojrzymy na kod. Cała reszta lekcji to dwa sposoby zapisania go w TypeORM.
Sposób pierwszy: transakcja zarządzana
Najprostszy wariant to dataSource.transaction(). Podajesz funkcję, a TypeORM sam otwiera transakcję przed jej wywołaniem i zamyka po zakończeniu:
await this.dataSource.transaction(async (manager) => {
await manager.update(Tribute, tributeId, { legionariusze: { id: toLegionaryId } });
await manager.increment(Legionary, { id: toLegionaryId }, 'tributeCount', 1);
await manager.decrement(Legionary, { id: fromLegionaryId }, 'tributeCount', 1);
});Funkcja dostaje jeden argument: manager - odpowiednik repozytorium, ale przypisany do tej konkretnej transakcji. To najważniejszy szczegół tego kodu: wszystkie operacje muszą przechodzić przez manager. Gdybyś w środku sięgnął po zwykłe this.tributeRepository.save(...), ten zapis poszedłby poza transakcją - i nie cofnąłby się przy błędzie.
A skąd baza wie, czy zatwierdzić, czy cofnąć? Z wyjątku. Jeśli funkcja dobiegnie do końca spokojnie, TypeORM wykonuje COMMIT. Jeśli cokolwiek w środku rzuci wyjątek - robi ROLLBACK i przekazuje wyjątek dalej. Nie piszesz ani jednej linii obsługi - i to polecam jako domyślny wybór.
Sposób drugi: QueryRunner, czyli pełna kontrola
Czasem potrzebujesz sterować transakcją ręcznie - na przykład wykonać coś między operacjami albo zareagować na konkretny błąd. Wtedy sięgasz po QueryRunner: obiekt reprezentujący jedno, wyłączne połączenie z bazą, na którym sam wywołujesz kolejne etapy.
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
await queryRunner.manager.update(Tribute, tributeId, {
legionariusze: { id: toLegionaryId },
});
await queryRunner.manager.increment(
Legionary, { id: toLegionaryId }, 'tributeCount', 1,
);
await queryRunner.commitTransaction();
} catch (error) {
await queryRunner.rollbackTransaction();
throw error;
} finally {
await queryRunner.release();
}Prześledźmy ten kod krok po kroku, bo każda linia odpowiada jednemu etapowi cyklu, który poznałeś wyżej. createQueryRunner() tworzy obiekt, connect() rezerwuje dla niego połączenie z puli, a startTransaction() to nasz BEGIN. Operacje wykonujemy przez queryRunner.manager - znów ten sam warunek co poprzednio: tylko to, co przejdzie przez menedżera tego runnera, należy do transakcji. Blok try kończy się commitTransaction(), a catch wywołuje rollbackTransaction() i rzuca wyjątek dalej, żeby warstwa wyżej wiedziała, że transfer się nie udał.
Najważniejsza jest ostatnia część. release() musi stać w finally, bo połączenie trzeba zwrócić do puli w każdym scenariuszu - i po sukcesie, i po błędzie. Pominięcie tego nie zepsuje pojedynczego transferu; skutek pojawi się później, gdy pula wyczerpie się z wolnych połączeń i cała aplikacja stanie. To najczęstszy błąd przy ręcznych transakcjach.
Zwróć też uwagę, czego release() nie robi: nie zatwierdza ani nie cofa niczego. Jeśli zwolnisz runnera bez commitu, transakcja zostanie wycofana - zwolnienie połączenia to nie zapisanie zmian.
Izolacja - transakcje obok siebie
Została nam litera I z ACID. Gdy dwie transakcje działają równocześnie, baza musi zdecydować, ile jedna widzi z niedokończonej pracy drugiej. Poziom tego odgrodzenia podajesz jako argument:
await queryRunner.startTransaction('SERIALIZABLE');Domyślny poziom to zwykle 'READ COMMITTED' - widzisz tylko zmiany już zatwierdzone przez innych. 'SERIALIZABLE' to poziom najostrzejszy: transakcje wykonują się tak, jakby stały w kolejce, jedna po drugiej. Daje najsilniejsze gwarancje, ale kosztem przepustowości - baza częściej każe którejś transakcji się wycofać i spróbować ponownie. Dlatego poziom podnosimy świadomie i tylko tam, gdzie naprawdę trzeba, na przykład przy operacjach na saldzie skarbca.
Podsumowanie
Puchar Marka nie zginie już nigdy w połowie drogi:
- transakcja to grupa operacji wykonywana atomowo - albo wszystkie, albo żadna,
- skrót ACID opisuje jej gwarancje, a litera A to właśnie atomowość,
- cykl życia jest zawsze ten sam: BEGIN, operacje, weryfikacja, COMMIT albo ROLLBACK,
dataSource.transaction(async manager => {...})prowadzi ten cykl za Ciebie: wyjście bez wyjątku to COMMIT, wyjątek to ROLLBACK,- QueryRunner daje pełną kontrolę:
createQueryRunner,connect,startTransaction, a potemcommitTransactionwtry,rollbackTransactionwcatchireleasewfinally, - w obu wariantach operacje muszą iść przez
managertransakcji - zwykłe repozytorium działa poza nią, - poziom izolacji decyduje, ile transakcje widzą nawzajem ze swojej niedokończonej pracy.
W następnej lekcji poznasz seedery - kwatermistrzów, którzy wyposażą świeżą bazę w dane startowe. A na razie zapamiętaj: transakcja to jeden rozkaz złożony z wielu ruchów - baza wykona go w całości albo udając, że nigdy go nie usłyszała, nie zrobi nic.
Kod do tej lekcji: src/transactions.ts
// Transakcje - Bezpieczne Operacje na Tributach
import { Injectable } from '@nestjs/common';
import { DataSource, QueryRunner, EntityManager } from 'typeorm';
console.log("Transakcje - atomowe operacje na danych imperium!");
// ===========================================
// 1. Transakcja z QueryRunner
// ===========================================
@Injectable()
export class TributeTransferService {
constructor(private dataSource: DataSource) {}
async transferTribute(
fromProvince: string,
toProvince: string,
amount: number,
): Promise<void> {
// Utworz QueryRunner
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
// Odejmij z prowincji zrodlowej
await queryRunner.query(
'UPDATE provinciae SET tribute = tribute - $1 WHERE name = $2',
[amount, fromProvince],
);
// Dodaj do prowincji docelowej
await queryRunner.query(
'UPDATE provinciae SET tribute = tribute + $1 WHERE name = $2',
[amount, toProvince],
);
// Zatwierdz transakcje
await queryRunner.commitTransaction();
console.log('Transfer zakonczony: ' + amount + ' z ' + fromProvince + ' do ' + toProvince);
} catch (error) {
// Cofnij w razie bledu
await queryRunner.rollbackTransaction();
console.error('Transfer anulowany: ' + error.message);
throw error;
} finally {
// Zwolnij polaczenie
await queryRunner.release();
}
}
}
// ===========================================
// 2. Transakcja z EntityManager
// ===========================================
@Injectable()
export class PromotionService {
constructor(private dataSource: DataSource) {}
async promoteLegionary(
legionaryId: number,
newRank: string,
) {
return this.dataSource.transaction(async (manager: EntityManager) => {
// Znajdz legioniste
const legionary = await manager.findOneBy('Legionary', {
id: legionaryId,
});
if (!legionary) {
throw new Error('Legionary non inventus!');
}
const oldRank = legionary.rank;
// Zaktualizuj range i doswiadczenie
legionary.rank = newRank;
legionary.experience += 1;
await manager.save('Legionary', legionary);
// Zapisz historie awansu
await manager.save('PromotionHistory', {
legionaryId,
oldRank,
newRank,
date: new Date(),
});
console.log('Awans: ' + oldRank + ' -> ' + newRank);
return legionary;
});
}
}
// ===========================================
// 3. Wlasciwosci ACID
// ===========================================
// Atomicity - wszystko albo nic
// Consistency - dane zawsze spojne
// Isolation - transakcje nie koliduja
// Durability - zatwierdzone = trwale
console.log("\n=== PODSUMOWANIE TRANSAKCJI ===");
console.log("QueryRunner: connect -> startTransaction -> commit/rollback -> release");
console.log("dataSource.transaction(manager => {...}) - prostsza skladnia");
console.log("ACID - atomowosc, spojnosc, izolacja, trwalosc");
console.log("try/catch/finally - zawsze obsluz bledy!");
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Czym jest transakcja bazodanowa?
2. Co oznacza litera 'A' w skrócie ACID opisującym właściwości transakcji?
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj etapy cyklu życia transakcji bazodanowej:
- Edytor kodu
Stwórz metodę transferTributes, która używa queryRunner.startTransaction(), wykonuje dwa zapisy i commituje (lub rollbackuje przy błędzie)
- Klikanie w kolejności
Ułóż elementy kodu transakcji z QueryRunner w prawidłowej kolejności:
- Układanie w poziomie
Ułóż elementy rozpoczęcia transakcji w prawidłowej kolejności:
- Edytor kodu
Napisz metodę serwisu używającą dataSource.transaction(async manager => { ... }), która tworzy tribute i aktualizuje prowincję