Institute of Information Science - University of Miskolc

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== TypeORM ======

A TypeORM egy objektum-relációs leképező eszköz, aminek segítségével TypeScript osztályokat különböző adatbázisokkal tudjuk anélkül használni, hogy konkrét adatbázis-kezelő specifikus parancsokat használnánk (TypeORM segítségével nem csak relációs adatbázist lehet kezelni, hanem NoSQL-t – pl. MongoDB-t – is).

Használatát egy példán keresztül érdemes megismerni.

===== Globális függőségek telepítése =====

A következő parancsot egyszer kell futtatni, ennek hatására rendszer szinten települnek a szükséges csomagok:

<sxh bash>
npm install -g typeorm@0.3.27
</sxh>

===== Adatbázis létrehozása =====

  * Indítsuk el a WAMPServer szoftvercsomagot, mely tartalmazza a MySQL adatbázist és a PHPMyAdmin klienst.
  * Jelentkezzünk be a PHPMyAdmin-ba a következő címen: http://localhost/phpmyadmin (felhasználónév ''root'', jelszót nem kell megadni).
  * Ezután a felület baloldalán megjelennek a MySQL-ben létrehozott adatbázisok. Új adatbázis hozzáadásához kattintsunk az „Új” gombra.
  * Adatbázisunk neve legyen ''infrend_typeorm'', karakterkészletként használjuk a ''utf8mb4_hungarian_ci'' lehetőséget.
  * Ha az adatbázist sikeresen létrehoztuk, az megjelenik a baloldali menüben. Erre kattintva a későbbiekben ellenőrizni tudjuk a TypeORM által végrehajtott műveletek eredményét.

===== Projekt inicializálás =====

  * Meglévő projektbe történő telepítéskor [[https://typeorm.io/docs/getting-started#installation|ezt az útmutatót]] érdemes követni.
  * Új, MySQL alapú projekt létrehozásakor elég ezt a parancsot futtatni: ''npx typeorm init %%--%%name typeorm-tutorial %%--%%database mysql''

===== Projekt struktúra =====

A projektben a következő fájlstruktúra jött létre:

<sxh>
.
├── package.json
├── package-lock.json
├── README.md
├── src
│   ├── data-source.ts
│   ├── entity
│   │   └── User.ts
│   ├── migration
│   └── index.ts
└── tsconfig.json
</sxh>

Nézzünk bele a létrejött fájlok tartalmába!

  * ''data-source.ts'': A TypeORM konfigurációs fájlja.
  * ''entity'': Ez a könyvtár tartalmazza az adatbázis modelleket.
  * ''migration'': Ez a könyvtár tartalmazza az adatbázis migrációs szkripteket. Ez elsősorban éles rendszerek fejlesztésekor szükséges, mert minden DB módosításnál ebben lesznek megadva azok az adatbázis-specifikus parancsok, amik megvalósítják a konkrét struktúrákat és/vagy azok változtatását.
  * ''index.ts'': Az alkalmazás belépési pontja, ez a .ts fájl indul el futtatáskor.
  * ''tsconfig.json'': A TypeScript compiler beállításai.

Nyissuk meg a ''data-source.ts''-t, és módosítsuk a beállításokat az alábbiak szerint:

<sxh ts>
import "reflect-metadata"
import { DataSource } from "typeorm"
import { User } from "./entity/User"

export const AppDataSource = new DataSource({
    type: "mysql",
    host: "localhost",
    port: 3306,
    username: "root",
    password: undefined, // in case of using a password, set it to a string
    database: "infrend_typeorm",
    synchronize: true,
    logging: true,
    entities: [User],
    migrations: [],
    subscribers: [],
});
</sxh>

===== Projekt indítása =====

Futtassuk az ''npm start'' parancsot!

Ha hiba nélkül lefutott, akkor a PHPMyAdmin felületén megtekinthetjük a létrejött 1 sort az adatbázisban.

===== Entitások és relációk =====

A tábláink gyakran kapcsolatban vannak egymással. Három alap relációt különböztetünk meg:

  * **One-to-One**: 1:1 reláció, ahol két táblát úgy kapcsolunk össze, hogy 1 rekord csak 1 másik rekordnak felelhet meg egy másik táblában. Például ha az //Országok// és a //Fővárosok// táblákat tekintjük, egy országnak egy fővárosa lehet és minden főváros csak egy országnak lehet a fővárosa.
  * **One-to-Many**: 1:N reláció, ahol 1 rekord több másik táblabeli rekorddal is össze lehet kapcsolva. Példaként tekintsük a //Kutyák// és //Gazdák// táblát, ahol 1 kutyának csak 1 gazdája van, de egy gazdának több kutyája is lehet.
  * **Many-to-Many**: N:M reláció, ahol 1 rekord több másik táblabeli rekorddal is össze lehet kapcsolva, és ez fordítva is teljesül. Ilyen pl. a //Felhasználók// és //Szerepkörök// tábla, ahol egy felhasználónak több szerepköre is lehet és egy szerepkör több felhasználóhoz is tartozhat.

===== One-to-Many példa =====

Adjunk hozzá két entitást az ''src/entity/'' mappához, ''Dog.ts'' és ''Owner.ts'' elnevezéssel!

Az 1:N relációt mindkét osztályban jelölnünk kell, a ''ManyToOne'' és ''OneToMany'' dekorátorokkal.

<sxh ts>
// Dog.ts
import { Entity, PrimaryGeneratedColumn, Column, ManyToOne } from "typeorm";
import { Owner } from "./Owner";

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

    @Column()
    name: string;

    @ManyToOne(type => Owner, owner => owner.dogs)
    owner: Owner;
}
</sxh>

Az osztály ''owner'' adattagja feletti dekorátor jelzi, hogy „több kutyának egy tulajdonosa is lehet”. Az első paraméter jelzi, hogy a reláció az ''Owner'' osztályra mutat. A második paraméter jelzi, hogy az ''Owner'' osztályban a ''dogs'' adattaggal lesz összekapcsolva.

<sxh ts>
// Owner.ts
import {Entity, PrimaryGeneratedColumn, Column, OneToMany} from "typeorm";
import { Dog } from "./Dog";

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

    @Column()
    name: string;

    @OneToMany(type => Dog, dog => dog.owner)
    dogs: Dog[];
}
</sxh>

Az ''Owner'' osztály ''dogs'' adattagja feletti dekorátor jelzi, hogy „egy gazdának több kutyája is lehet”. Az első paraméter jelzi, hogy a reláció a ''Dog'' osztályra mutat. A második paraméter jelzi, hogy a ''Dog'' osztályban az ''owner'' adattaggal lesz összekapcsolva.

Módosítsuk a ''data-source.ts'' fájlt, az ''entities'' tömbhöz adjuk hozzá az új entitásokat: ''entities: [Dog, Owner]''.

Módosítsuk továbbá az ''index.ts'' fájlt!

<sxh ts>
import { AppDataSource } from "./data-source"
import { Dog } from "./entity/Dog";
import { Owner } from "./entity/Owner";

AppDataSource.initialize().then(async () => {
    const dog1 = new Dog();
    dog1.name = 'Bodri';

    const dog2 = new Dog();
    dog2.name = 'Buksi';

    const owner = new Owner();
    owner.name = "Kovács Lajos";
    owner.dogs = [ dog1, dog2 ];

    await AppDataSource.manager.save(owner);
    console.log("Owner is saved.");

    AppDataSource.destroy();
}).catch(error => {
    console.log(error);
    AppDataSource.destroy();
});
</sxh>

Futtassuk le a kódot (''npm start''), és nézzük meg, hogy mi jött létre az adatbázisban!

Látható, hogy az ORM rendszer létrehozta a táblákat, a ''dog'' táblában az ''owner''-re mutató id-vel. Láthatjuk még azt is, hogy az ''owner'' táblában 1 sor van, de a ''dog'' táblában nem jött létre semmi.

Azért, hogy létrejöjjenek a kutyákhoz tartozó rekordok is, az ''Owner.ts''-ben módosítsuk az 1:N relációt leíró dekorátort:

<sxh ts>
@OneToMany(type => Dog, dog => dog.owner, { cascade: true })
</sxh>

A ''cascade: true'' engedélyezi, hogy a gazda létrehozásakor a kutya is létrejöjjön. Mi történik viszont törlés esetén, ha egy gazdát törlünk? Próbáljuk ki!

Az ''index.ts''-ben a save() után rögtön tegyük be a következő sort, és futtassuk újra az alkalmazást (''npm start''):

<sxh ts>
await AppDataSource.manager.remove(owner);
</sxh>

A kapott hibaüzenet azt jelenti, hogy a TypeORM nem tudja letörölni a gazdát, mert a ''dog'' táblában van olyan idegen kulcs, ami a törlendő gazdára mutat.

<sxh>
Cannot delete or update a parent row: a foreign key constraint fails (`infrend_typeorm`.`dog`, CONSTRAINT `FK_2cd931b431fa086ee81e43ec5da` FOREIGN KEY (`ownerId`) REFERENCES `owner` (`id`) ON DELETE NO ACTION ON UPDATE NO ACTION)
</sxh>

A problémát megoldhatjuk úgy, hogy a kutyák tulajdonosát a törlés előtt ''null''-ra állítjuk, de az alábbi módon beállítható az is, hogy a gazdával együtt a kutyák is törlésre kerüljenek (azaz „kaszkádolt törlés” történjen):

<sxh ts>
// Dog.ts

@ManyToOne(type => Owner, owner => owner.dogs, { onDelete: 'CASCADE' })
owner: Owner;
</sxh>

===== Many-to-Many példa =====

Az ORM-ek erőssége akkor válik érezhetőbbé, ha több-több reláció esetén kapcsolótáblát is létre kell hoznunk.

Klasszikus példa a //Felhasználó<->Szerepkör// reláció.

Az ''src/entity'' mappában hozzuk létre a ''Role.ts'' fájlt a következő tartalommal:

<sxh ts>
import {Entity, PrimaryGeneratedColumn, Column} from "typeorm";

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

    @Column()
    name: string;
}
</sxh>

Hozzuk létre a ''User.ts'' fájlt is!

<sxh ts>
import { Entity, PrimaryGeneratedColumn, Column, ManyToMany, JoinTable } from "typeorm";
import { Role } from "./Role";

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

    @Column()
    name: string;

    @ManyToMany(type => Role, { cascade: true })
    @JoinTable()
    roles: Role[];
}
</sxh>

A fenti kódban látható, hogyan lehet több-több kapcsolatot létrehozni. A ''User'' osztály esetében most rögtön ''cascade'' típusú kapcsolatot definiáltunk a szerepkörökre nézve. A ''@JoinTable()'' dekorátor a reláció „tulajdonos” oldalát jelzi, amely kezeli a kapcsolat mentését. Ez azt jelenti, hogy ebben az esetben a felhasználóhoz rendelt szerepkörök mentése megfelelően működik, azonban ha egy szerepkörhöz szeretnénk felhasználókat rendelni, az önmagában nem elegendő — a kapcsolatot a ''User'' oldalon kell kezelni.

Az újonnan létrehozott entitásokra hivatkozzunk a ''data-source.ts'' fájl megfelelő pontján: ''entities: [User, Role, Dog, Owner]''.

Ezt követően írjuk át az ''index.ts'' fájl tartalmát a következőre:

<sxh ts>
import { AppDataSource } from "./data-source"
import { Role } from "./entity/Role";
import { User } from "./entity/User";
 
AppDataSource.initialize().then(async () => {
    const adminRole = new Role();
    adminRole.name = "admin";
 
    const userRole = new Role();
    userRole.name = "user";
 
    const user1 = new User();
    user1.name = "user1";
    user1.roles = [adminRole, userRole];
 
    const user2 = new User();
    user2.name = "user2";
    user2.roles = [adminRole];
 
    await AppDataSource.manager.save([user1, user2]);
    console.log("Users are saved.");
 
    AppDataSource.destroy();
}).catch(error => {
    console.log(error);
    AppDataSource.destroy();
});
</sxh>

Futtassuk a kódot (''npm start''), majd a PHPMyAdmin felületén ellenőrizzük, hogy mi történt az adatbázisban:

Létrejött egy ''user'' és egy ''role'' tábla a felhasználók és a szerepkörök tárolásához, valamint létrejött egy ''user_roles_role'' elnevezésű kapcsolótábla is, mely a több-több kapcsolatot valósítja meg az entitások között.