Kurs NestJS · Moduł 3: TypeORM i bazy danych

Bazy danych i TypeORM - skarbiec imperium

6 min czytania ·
W tej lekcji12

Witaj z powrotem w systemie, młody legionisto! Consul Caesar.js ma dla Ciebie nowe wyzwanie. Dotychczas nauczyłeś się budować potężne fortyfikacje z NestJS, ale każde prawdziwe imperium potrzebuje miejsca do przechowywania swoich tributów. Czas nauczyć się zarządzania skarbcem - bazami danych!

Czym jest baza danych dla imperium?

Podobnie jak Rzymianie przechowują swoje tributy w bezpiecznych skarbcach w Forum Romanum, aplikacje muszą gdzieś bezpiecznie przechowywać swoje dane. Baza danych to nasz cyfrowy skarbiec, który:

  • Przechowuje tributy - dane aplikacji jak informacje o obywatelach, zamówienia, produkty
  • Zabezpiecza przed stratą - zapewnia trwałość i integralność danych
  • Umożliwia szybkie wyszukiwanie - jak rejestr skarbca pokazujący dokładne lokalizacje
  • Kontroluje dostęp - tylko uprawnieni legionariusze mogą sięgać po tributy

Rodzaje baz danych - różne typy skarbców

Relacyjne bazy danych (SQL)

To jak zorganizowane magazyny z dokładnie opisanymi przegródkami:

-- Tabela legionariuszy
CREATE TABLE legionaries (
 id SERIAL PRIMARY KEY,
 name VARCHAR(100) NOT NULL,
 cohort VARCHAR(100),
 tribute_count INTEGER DEFAULT 0
);

-- Tabela tributów
CREATE TABLE tributes (
 id SERIAL PRIMARY KEY,
 name VARCHAR(100) NOT NULL,
 value DECIMAL(10,2),
 legionary_id INTEGER REFERENCES legionaries(id)
);

NoSQL bazy danych

To jak elastyczne worki na tributy, gdzie można trzymać różne rzeczy:

// MongoDB document
{
 _id: ObjectId("..."),
 name: "Marcus Aurelius",
 cohort: "Legio X Equestris",
 tributes: [
 { name: "Golden Coin", value: 100 },
 { name: "Diamond Ring", value: 500 }
 ],
 officers: {
 optio: "Gaius",
 signifer: "Marcus"
 }
}

TypeORM - magiczny system zarządzania skarbcem

TypeORM to potężne narzędzie, które pozwala nam łatwo zarządzać bazami danych w TypeScript. To jak system zarządzania skarbcem imperium, który automatycznie tłumaczy nasze żądania na język zrozumiały dla bazy danych.

Instalacja TypeORM w aplikacji

npm install @nestjs/typeorm typeorm pg
npm install --save-dev @types/pg

Konfiguracja połączenia ze skarbcem

// app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
 imports: [
 TypeOrmModule.forRoot({
 type: 'postgres',
 host: 'localhost',
 port: 5432,
 username: 'consul',
 password: 'imperium123',
 database: 'roman_empire',
 entities: [__dirname + '/**/*.entity{.ts,.js}'],
 synchronize: true, // Tylko podczas rozwoju!
 }),
 ],
})
export class AppModule {}

Pierwsza entity - rejestr tributów

Entity to jak szczegółowy rejestr pokazujący, jak wygląda konkretny tribut w naszym skarbcu:

// tribute.entity.ts
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';

@Entity('tributes')
export class Tribute {
 @PrimaryGeneratedColumn()
 id: number;

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

 @Column('decimal', { precision: 10, scale: 2 })
 value: number;

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

 @Column({ default: 'unknown' })
 location: string;

 @CreateDateColumn()
 collectedAt: Date;

 @Column({ default: false })
 isCursed: boolean;
}

Dekoratory TypeORM - instrukcje dla skarbnika

  • @Entity() - oznacza, że to jest rejestr tributów (tabela)
  • @PrimaryGeneratedColumn() - unikalny numer tributu (klucz główny)
  • @Column() - opis właściwości tributu (kolumna)
  • @CreateDateColumn() - automatycznie zapisuje datę pobrania
  • @UpdateDateColumn() - automatycznie aktualizuje datę modyfikacji

Podstawowe operacje na tributach

Tworzenie nowego tributu

// tribute.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { Tribute } from './tribute.entity';

@Injectable()
export class TributeService {
 constructor(
 @InjectRepository(Tribute)
 private tributeRepository: Repository<Tribute>,
 ) {}

 async addTribute(tributeData: Partial<Tribute>): Promise<Tribute> {
 const newTribute = this.tributeRepository.create(tributeData);
 return await this.tributeRepository.save(newTribute);
 }

 async findAllTributes(): Promise<Tribute[]> {
 return await this.tributeRepository.find();
 }

 async findTributeById(id: number): Promise<Tribute> {
 return await this.tributeRepository.findOne({ where: { id } });
 }

 async updateTribute(id: number, updateData: Partial<Tribute>): Promise<Tribute> {
 await this.tributeRepository.update(id, updateData);
 return this.findTributeById(id);
 }

 async removeTribute(id: number): Promise<void> {
 await this.tributeRepository.delete(id);
 }
}

Typy kolumn - różne rodzaje tributów

@Entity()
export class DetailedTribute {
 @PrimaryGeneratedColumn()
 id: number;

 // Tekst - nazwa tributu
 @Column('varchar', { length: 200 })
 name: string;

 // Liczby całkowite - ilość
 @Column('int')
 quantity: number;

 // Liczby dziesiętne - wartość
 @Column('decimal', { precision: 10, scale: 2 })
 value: number;

 // Wartości logiczne - czy przeklęty
 @Column('boolean', { default: false })
 isCursed: boolean;

 // Data - kiedy pobrany
 @Column('date')
 collectionDate: Date;

 // Tekst długi - historia tributu
 @Column('text')
 history: string;

 // JSON - szczegóły
 @Column('json')
 details: {
 material: string;
 origin: string;
 previousOwners: string[];
 };
}

Walidacja danych - sprawdzanie jakości tributów

import { IsNotEmpty, IsPositive, IsOptional, Length } from 'class-validator';

export class CreateTributeDto {
 @IsNotEmpty({ message: 'Każdy tribut musi mieć nazwę!' })
 @Length(3, 100, { message: 'Nazwa musi mieć od 3 do 100 znaków' })
 name: string;

 @IsPositive({ message: 'Wartość tributu musi być większa od zera' })
 value: number;

 @IsOptional()
 @Length(0, 500)
 description?: string;

 @IsOptional()
 location?: string;
}

Konfiguracja modułu tributów

// tribute.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { TributeService } from './tribute.service';
import { TributesController } from './tributes.controller';
import { Tribute } from './tribute.entity';

@Module({
 imports: [TypeOrmModule.forFeature([Tribute])],
 controllers: [TributesController],
 providers: [TributeService],
 exports: [TributeService],
})
export class TributeModule {}

Kontroler zasobów

// tributes.controller.ts
import { Controller, Get, Post, Put, Delete, Body, Param } from '@nestjs/common';
import { TributeService } from './tribute.service';
import { CreateTributeDto } from './dto/create-tribute.dto';

@Controller('tributes')
export class TributesController {
 constructor(private readonly tributeService: TributeService) {}

 @Post()
 async addTribute(@Body() createTributeDto: CreateTributeDto) {
 return await this.tributeService.addTribute(createTributeDto);
 }

 @Get()
 async getAllTributes() {
 return await this.tributeService.findAllTributes();
 }

 @Get(':id')
 async getTribute(@Param('id') id: string) {
 return await this.tributeService.findTributeById(+id);
 }

 @Put(':id')
 async updateTribute(
 @Param('id') id: string,
 @Body() updateData: Partial<CreateTributeDto>
 ) {
 return await this.tributeService.updateTribute(+id, updateData);
 }

 @Delete(':id')
 async removeTribute(@Param('id') id: string) {
 await this.tributeService.removeTribute(+id);
 return { message: 'Tribut został usunięty ze skarbca!' };
 }
}

Obsługa błędów - ochrona przed klątwami

import { NotFoundException, BadRequestException } from '@nestjs/common';

@Injectable()
export class TributeService {
 //
 async findTributeById(id: number): Promise<Tribute> {
 if (id <= 0) {
 throw new BadRequestException('ID tributu musi być większe od zera');
 }

 const tribute = await this.tributeRepository.findOne({ where: { id } });

 if (!tribute) {
 throw new NotFoundException(`Tribut o ID ${id} nie został znaleziony w skarbcu`);
 }

 return tribute;
 }

 async removeTribute(id: number): Promise<void> {
 const tribute = await this.findTributeById(id);

 if (tribute.isCursed) {
 throw new BadRequestException('Nie można usunąć przeklętego tributu!');
 }

 await this.tributeRepository.delete(id);
 }
}

Praktyczne ćwiczenie

Teraz gdy już znasz podstawy, czas na własne eksperymenty! Spróbuj stworzyć własną entity dla legionariuszy:

// Twój kod tutaj
@Entity('legionaries')
export class Legionary {
 // Dodaj właściwości:
 // - id (auto-generowane)
 // - name (tekst, wymagane)
 // - cohort (tekst, opcjonalne)
 // - tributeCount (liczba, domyślnie 0)
 // - joinedAt (data dołączenia)
 // - isActive (czy aktywny, domyślnie true)
}

Podsumowanie

Gratulacje! Nauczyłeś się podstaw zarządzania skarbcem danych. Teraz umiesz:

Konfigurować TypeORM w aplikacji NestJS Tworzyć entity - rejestry swoich tributów Wykonywać podstawowe operacje CRUD na danych Walidować dane przed zapisem do skarbca Obsługiwać błędy i chronić przed klątwami

W następnych lekcjach poznasz zaawansowane techniki jak relacje między tabelami, migracje i zaawansowane zapytania. Consul Caesar.js jest dumny z Twoich postępów!

Kod do tej lekcji: src/database-intro.ts
// Bazy danych i TypeORM - Skarbiec Imperium
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

console.log("TypeORM - system zarzadzania skarbcem imperium!");

// ===========================================
// 1. Podstawowa encja (Entity) - mapa tributu
// ===========================================

@Entity('legionaries')
export class Legionary {
  @PrimaryGeneratedColumn()
  id: number;

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

  @Column()
  rank: string;

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

  @Column()
  legion: string;
}

// ===========================================
// 2. Konfiguracja polaczenia z baza danych
// ===========================================

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'imperium',
      password: 'roma_aeterna',
      database: 'imperium_db',
      entities: [Legionary],
      synchronize: true, // Tylko w development!
    }),
    TypeOrmModule.forFeature([Legionary]),
  ],
})
export class DatabaseModule {}

// ===========================================
// 3. Rodzaje baz danych - typy skarbcow
// ===========================================

// Relacyjne (SQL):
// - PostgreSQL - najpopularniejsza, ACID, relacje
// - MySQL/MariaDB - szybka, popularna
// - SQLite - lekka, plikowa

// Nierelacyjne (NoSQL):
// - MongoDB - dokumentowa (JSON-like)
// - Redis - klucz-wartosc, cache
// - Cassandra - kolumnowa, big data

// ===========================================
// 4. ORM vs surowe zapytania SQL
// ===========================================

// ORM (Object-Relational Mapping):
// - Piszemy TypeScript zamiast SQL
// - Automatyczne mapowanie obiektow na tabele
// - Bezpieczenstwo typow
// - Latwiejsze migracje

// Surowe SQL:
// const result = await connection.query(
//   'SELECT * FROM legionaries WHERE rank = $1',
//   ['Centurio']
// );

// TypeORM:
// const result = await legionaryRepo.find({
//   where: { rank: 'Centurio' }
// });

console.log("\n=== PODSUMOWANIE ===");
console.log("TypeORM - ORM dla TypeScript/JavaScript");
console.log("@Entity - dekorator definiujacy tabele");
console.log("@Column - dekorator definiujacy kolumne");
console.log("@PrimaryGeneratedColumn - klucz glowny auto-increment");
console.log("TypeOrmModule.forRoot() - konfiguracja polaczenia");
console.log("TypeOrmModule.forFeature() - rejestracja repozytoriow");

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. Czym jest TypeORM?

  2. 2. Co oznacza dekorator @Entity() nad klasą TypeScript?

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

Zadania praktyczne w grze

  • Edytor kodu

    Napisz encję Legionary z @Entity(), @PrimaryGeneratedColumn(), @Column() name i @Column() rank

  • Klikanie w kolejności

    Ułóż elementy definicji encji TypeORM w prawidłowej kolejności:

  • Edytor kodu

    Napisz konfigurację TypeOrmModule.forRoot() z type: 'postgres', host, port, username, password i database

  1. PytanieCzym jest TypeORM
  2. PytanieDekorator @Entity
  3. Zadanie z kodemPierwsza encja TypeORM
  4. Kliknij w kolejnościDefinicja encji TypeORM
  5. PytanieKonfiguracja TypeORM w NestJS
  6. Zadanie z kodemKonfiguracja połączenia z bazą danych

Przydatne artykuły