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 (a TypeORM-mel nem csak relációs adatbázist lehet kezelni, hanem NoSQL-t is, pl. MongoDB-t).

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



==== Telepítés ====

Hozzunk létre egy projekt könyvtárat és belépve (cd /path/to/ORMExample/) adjuk ki a következő parancsokat:

Az első parancsnál minden kérdésre nyomjunk entert.

<code>
npm init
npm install typeorm@0.2.45 --save
</code>

Létrejön lokálisan a node_modules/ könyvtár és a package.json, valamint a package-lock.json fájlok.

Telepítsük a kiegészítőit:

<code>
npm install reflect-metadata --save
npm install @types/node --save
npm install typescript --save
npm link typescript
</code>

Telepítsük a választott adatbázis driver-ét:

<code>
npm install sqlite3 --save
</code>

===Kiegészítés===
Ha MySQL-t vagy MariaDB-t használunk:
<code>
npm install mysql --save
</code>

Ha PostgreSQL-t használunk:
<code>
npm install pg --save
</code>

Ha Microsoft SQL Servert használunk:
<code>
npm install mssql --save
</code>

Ha MongoDB-t használunk:
<code>
npm install mongodb --save
</code>



==== Projekt létrehozása ====

Adjuk ki a következő parancsot (a node_modules\.bin könyvtár gyűjti a végrehajtható állományokat, nézzük meg jelenleg mik vannak benne): 

<code>
.\node_modules\.bin\typeorm init
</code>

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

<code>
├──> src
│ ├──> entity
│ │ └──> User.ts
│ ├──> migration
│ └──> index.ts
├──> node_modules
├──> ormconfig.json
├──> package.json
├──> package-lock.json
└──> tsconfig.json 
</code>

  * **src** - a TypeScript forráskódot tartalmazza
  * **index.ts** - Az alkalmazás belépési pontja. Ez a .ts állomány indul el futtatáskor
  * **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 azért kell, mert minden DB szerkezeti módosításnál ebben lesznek megadva azok a DB specifikus parancsok amik megvalósítják a konkrét struktúrákat vagy azok változtatását
  * **node_modules** - a helyi modulok, az alkalmazás által használt minden komponens, amit letöltünk
  * **ormconfig.json** - TypeORM konfigurációs állománya
  * **tsconfig.json** - TypeScript compiler beállítások


Töltsük le az UwAmp elnevezésű hordozható WAMP szervert: https://www.uwamp.com/file/UwAmp.zip
Ezt ki kell csomagolni egy könyvtárba és elindítani az uwamp.exe-t.

Nyissuk meg az ormconfig.json-t, és módosítsuk a mysql elérést az alábbiak szerint:

<code>
{
   "type": "mysql",
   "host": "localhost",
   "port": 3306,
   "username": "root",
   "password": "root",
   "database": "teszt",
   "synchronize": true,
   "logging": false,
   "entities": [
      "src/entity/**/*.ts"
   ],
   "migrations": [
      "src/migration/**/*.ts"
   ],
   "subscribers": [
      "src/subscriber/**/*.ts"
   ],
   "cli": {
      "entitiesDir": "src/entity",
      "migrationsDir": "src/migration",
      "subscribersDir": "src/subscriber"
   }
}
</code>

Hozzunk létre a MySQL-ben egy "teszt" nevű adatbázist, nyissuk meg a http://localhost/phpmyadmin vagy http://localhost/mysql lapot:

  * alapértelmezett felhasználó: root
  * alapértelmezett jelszó: root

Futtassuk a következő parancsot:

<code>
npm start
</code> 

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

A folytatáshoz töröljük le a teszt adatbázisban létrejött táblát, majd az **ormconfig.json** fájlban a "synchronize" legyen false:

<code>
"synchronize": false,
</code> 

Futtassuk le még egyszer a **npm start** parancsot, most látható hogy a tábla nem jött létre.

==== Adatbázis migráció ====

Az adatbázis módosításainak nyomonkövetésére a migráció nyújt lehetőséget. Nyissuk meg a **package.json** fájlt és a "scripts" részt módosítsuk az alábbi módon:

<code>
"scripts": {
      "test": "echo \"Error: no test specified\" && exit 1",
      "start": "ts-node src/index.ts",
      "typeorm-migration-generate": "ts-node ./node_modules/typeorm/cli.js migration:generate -n ",
      "typeorm-migration-run": "ts-node ./node_modules/typeorm/cli.js migration:run",
      "typeorm-migration-revert": "ts-node ./node_modules/typeorm/cli.js migration:revert"
   },
</code>

Az adatbázis első változatát a következő paranccsal lehet létrehozni (a **user_tabla** egy szabadon választott név, ez azonosítja az első változatot):

<code>
npm run typeorm-migration-generate user_tabla
</code>

Az src/migration alkönyvtárban létrejött állomány tartalma ez lesz:

<code javascript>
import {MigrationInterface, QueryRunner} from "typeorm";

export class userTabla1615018618129 implements MigrationInterface {
    name = 'userTabla1615018618129'

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query("CREATE TABLE `user` (`id` int NOT NULL AUTO_INCREMENT, `firstName` varchar(255) NOT NULL, `lastName` varchar(255) NOT NULL, `age` int NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB");
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query("DROP TABLE `user`");
    }

}
</code>

A typeorm legenerálta a tábla létrehozásához és eldobásához szükséges két függvényt. Ezzel még nincs továbbra sem létrehozva a valódi tábla, ezért a következő paranccsal alkalmazzuk a migrációt.

<code>
npm run typeorm-migration-run
</code>

Ezzel létrejött a két tábla:

<code>
query: SELECT * FROM `INFORMATION_SCHEMA`.`COLUMNS` WHERE `TABLE_SCHEMA` = 'teszt' AND `TABLE_NAME` = 'migrations'
query: CREATE TABLE `teszt`.`migrations` (`id` int NOT NULL AUTO_INCREMENT, `timestamp` bigint NOT NULL, `name` varchar(255) NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: SELECT * FROM `teszt`.`migrations` `migrations`  ORDER BY `id` DESC
0 migrations are already loaded in the database.
1 migrations were found in the source code.
1 migrations are new migrations that needs to be executed.
query: START TRANSACTION
query: CREATE TABLE `user` (`id` int NOT NULL AUTO_INCREMENT, `firstName` varchar(255) NOT NULL, `lastName` varchar(255) NOT NULL, `age` int NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB
query: INSERT INTO `teszt`.`migrations`(`timestamp`, `name`) VALUES (?, ?) -- PARAMETERS: [1615018618129,"userTabla1615018618129"]
Migration userTabla1615018618129 has been executed successfully.
query: COMMIT
</code>

Mint látható, egy migrations nevű tábla is létrejött ami tartalmazza az aktuális db változat nevét. 

Módosítsuk a User.ts-t a src/entity könyvtárban. Adjuk hozzá egy email mezőt:

<code>
@Column()
email: string;
</code>

Ezután az index.ts-ben a 11. sor után szúrjunk be egy email címet:

<code>
user.email = 'eee@eee.com';
</code>

Majd **npm start** után természetesen hibát kapunk, mert nincs átvezetve a db-be a módosítás.

<code>
QueryFailedError: ER_BAD_FIELD_ERROR: Unknown column 'email' in 'field list'
</code>

Futtassuk a következő sort:
<code>
npm run typeorm-migration-generate user_email
</code>

Ezzel létrejön egy új fájl a src/migration/ könyvtárban.

<code javascript>
import {MigrationInterface, QueryRunner} from "typeorm";

export class userEmail1615054071901 implements MigrationInterface {
    name = 'userEmail1615054071901'

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query("ALTER TABLE `user` ADD `email` varchar(255) NOT NULL");
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query("ALTER TABLE `user` DROP COLUMN `email`");
    }
}
</code>

Ha nem akarunk minden módosításkor migrációt készíteni (a próbálgatási időszakban) akkor érdemes a ormconfig.json-ben visszaállítani a "synchronize": true-t. Tegyük is meg a következő példák előtt.

==== Entitások - Relációk ====

A gyakorlatban a tábláink kapcsolatban vannak egymással. Három alaprelációt különböztetünk meg:

  * //one-to-one// - egy az egy reláció, ahol két táblát úgy kapcsolunk össze, hogy 1 sor csak 1 sornak felelhet meg mindkét táblában. Ilyen ha pl. **Országok** és a **Fővárosok** táblákat tekintjük, mivel egy országnak egy egy adott fővárosa lehet és minden főváros csak 1 országnak lehet a fővárosa.
  * //one-to-many// - egy/több reláció, egy adott sor, több sorral is össze van kapcsolva. 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-one// - ugyanaz mint az előző csak fordított relációban.
  * //many-to-many// - több/több reláció, egy adott sor, több sorral is össze van kötve és fordítva. 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.

Az ORM-ek, így a TypeORM is a következő fogalmakat/módszereket használja a relációk használatánál.
  * //eager// - a forrás entitás betölti a relációkhoz tartozó összes adatot. Ez azt jelenti, hogy ha a kutyák és gazdákra gondolunk, akkor a gazda betöltésekor a kutyái is betöltődnek. Ez természetesen bonyolultabb relációknál is érvényes. Ezért kell kézzel megadni, mert nagyobb adatbázison nem feltétlenül akarjuk betölteni automatikusan a kapcsolt adatot. 
  * //cascade// - A cél entitás frissül vagy hozzáadódik automatikusan, ha a forrás változik. (példa alapján érthető lesz később)
  * //onDelete// - A cél entitás törlődik, ha a forrást törlik.


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

Adjunk hozzá két entitást a src/entity/ mappához: Dog.ts és Owner.ts

<code javascript>
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;
}
</code>

A //Dog.ts// **owner** adattagja feletti dekorátor jelzi, hogy "Több kutyának egy tulajdonosa lehet". Az első paraméter azt jelenti, hogy a reláció az **Owner** objektumra mutat. A második paraméter jelzi, hogy az **owner** osztályban a **dogs** adattaggal lesz összekapcsolva.

<code javascript>
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[];
}
</code>

Az //Owner.ts// **dogs** adattagja feletti dekorátor jelzi, hogy "Egy gazdának több kutyája lehet". Az első paraméter azt jelenti, hogy a reláció az **Dog** objektumra mutat. A második paraméter jelzi, hogy az **dog** osztályban az **owner** adattaggal lesz összekapcsolva.

Módosítsuk továbbá az index.ts-t.

<code javascript>
import "reflect-metadata";
import { createConnection } from "typeorm";
import { Dog } from "./entity/Dog";
import { Owner } from "./entity/Owner";

createConnection().then(async connection => {

    const owner = new Owner();
    owner.name = "owner1";
    
    const dog = new Dog();
    dog.name = 'Bodri';

    owner.dogs = [dog];

    await connection.manager.save(owner);

    console.log("done.");
}).catch(error => console.log(error));
</code>

Futtassuk le a kódot és nézzük meg 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öjjön a kutya is, az **Owner.ts**-ben módosítsuk a relációt:

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

A **cascade: true** engedélyezi, hogy a gazda létrehozásakor a kutya is létrejöjjön. Viszont mi történik 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 ezt a sort, és futtassuk az alkalmazást:

<code javascript>
await connection.manager.remove(owner);
</code>

A hibaüzenet azt jelenti, hogy nem tudja letörölni a gazdát, mert ekkor a kutya táblában olyan idegen kulcs maradna ami nem mutat egyetlen tulajdonosra sem.

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

Ezt megoldhatjuk úgy, hogy a kutya tulajdonosát null-ra állítjuk és utána törlünk, de automatikusan is az alábbi módon:

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

Azaz "kaszkádolt törlést" definiálunk a kapcsolatnál.




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

Az ORM-ek erőssége akkor lesz érezhetőbb, ha például a több-több reláció esetén a kapcsolótáblát is létrehozzuk.

Klasszikus példa a user-roles reláció.

Hozzuk létre a User.ts és Role.ts fájlokat a következő tartalommal:

<code javascript>
import {Entity, PrimaryGeneratedColumn, Column} from "typeorm";

@Entity()
export class Role {

    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    name: string;

}
</code>

Látható, hogy a Role.ts forrásában semmi újdonság nincs.

<code javascript>
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[];
}
</code>

A User.ts alapján látható hogyan lehet több-több kapcsolatot megadni, most rögtön cascade típusúra definiáltuk a kapcsolatot.

Nézzük a index.ts példát, majd futtassuk le a kódot (npm start). Előtte nem árt az adatbázist kipucolni, törölni az összes táblát.

<code javascript>
import "reflect-metadata";
import { createConnection } from "typeorm";
import { Role } from "./entity/Role";
import { User } from "./entity/User";

createConnection().then(async connection => {
    const roleAdmin = new Role();
    roleAdmin.name = "admin";

    const roleUser = new Role();
    roleUser.name = "user";

    const user = new User();
    user.name = "administrator";
    user.roles = [roleAdmin, roleUser];

    await connection.manager.save(user);

    console.log("done.");
}).catch(error => console.log(error));
</code>