Introduction to MikroORM with PostgreSQL

So far, in this series, we’ve used a few different solutions for managing databases. To work with MongoDB, we’ve used Mongoose. To manage a PostgreSQL database, we’ve utilized TypeORM and Prisma. This article looks into another Object-relational mapping (ORM) library called MikroORM. By having a broad perspective on what’s available, we can choose the library that fits our needs the most. You can find all of the code from this article in this repository. Setting up MikroORM and PostgreSQL The most straightforward way to use PostgreSQL in our project is to use Docker. In the second part of this series, we set up PostgreSQL and TypeORM. Therefore, we can use the same docker-compose.yml file we created back then. docker-compose.yml version: "3" services: postgres: container_name: nestjs-postgres image: postgres:latest ports: - "5432:5432" volumes: - /data/postgres:/data/postgres env_file: - docker.env networks: - postgres pgadmin: links: - postgres:postgres container_name: nestjs-pgadmin image: dpage/pgadmin4 ports: - "8080:80" volumes: - /data/pgadmin:/root/.pgadmin env_file: - docker.env networks: - postgres networks: postgres: driver: bridgeAlso, we need to create a file that contains the variables our docker container needs. docker.env POSTGRES_USER=admin POSTGRES_PASSWORD=admin POSTGRES_DB=nestjs PGADMIN_DEFAULT_EMAIL=admin@admin.com PGADMIN_DEFAULT_PASSWORD=admin Connecting to the database To be able to connect to the database, we need to establish a set of environment variables our NestJS application will use. app.module.ts import { Module } from '@nestjs/common'; import { ConfigModule } from '@nestjs/config'; import * as Joi from 'joi'; @Module({ imports: [ ConfigModule.forRoot({ validationSchema: Joi.object({ POSTGRES_HOST: Joi.string().required(), POSTGRES_PORT: Joi.number().required(), POSTGRES_USER: Joi.string().required(), POSTGRES_PASSWORD: Joi.string().required(), POSTGRES_DB: Joi.string().required(), }), }), ], controllers: [], providers: [], }) export class AppModule {}We also need to create a file that contains the values for the variables we’ve defined above. .env POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_USER=admin POSTGRES_PASSWORD=admin POSTGRES_DB=nestjsIn this series, we use PostgreSQL. Because of that, we need the @mikroorm/postgresql package, among others.npm install @mikro-orm/core @mikro-orm/nestjs @mikro-orm/postgresqlWith all of the above, we can create our DatabaseModule that establishes a connection to the database. DatabaseModule.ts import { Module } from '@nestjs/common'; import { ConfigModule, ConfigService } from '@nestjs/config'; import { MikroOrmModule } from '@mikro-orm/nestjs'; @Module({ imports: [ MikroOrmModule.forRootAsync({ imports: [ConfigModule], inject: [ConfigService], useFactory: (configService: ConfigService) => ({ dbName: configService.get('POSTGRES_DB'), user: configService.get('POSTGRES_USER'), password: configService.get('POSTGRES_PASSWORD'), host: configService.get('POSTGRES_HOST'), port: configService.get('POSTGRES_PORT'), type: 'postgresql', autoLoadEntities: true, }), }), ], }) export class DatabaseModule {} Don’t forget to import the DatabaseModule in the AppModule. Defining a basic entity Thanks to using the autoLoadEntities property, MikroORM loads the entities we define. First, let’s create an elementary entity for a post. To do that, we can use a set of decorators provided by the @mikro-orm/core package. post.entity.ts import { Entity, Property, PrimaryKey } from '@mikro-orm/core'; @Entity() class PostEntity { @PrimaryKey() id: number; @Property() title: string; @Property() content: string; } export default PostEntity;For MikroORM to detect the above entity, we need to register it in the module. posts.module.ts import { Module } from '@nestjs/common'; import { PostsService } from './posts.service'; import PostsController from './posts.controller'; import { MikroOrmModule } from '@mikro-orm/nestjs'; import PostEntity from './post.entity'; @Module({ imports: [MikroOrmModule.forFeature([PostEntity])], controllers: [PostsController], providers: [PostsService], }) export class PostsModule {} Interacting with the entities The above file mentions the PostsController and PostsService. Let’s start by creating the latter. posts.service.ts import { Injectable } from '@nestjs/common'; import { InjectRepository } from '@mikro-orm/nestjs'; import { EntityRepository } from '@mikro-orm/core'; import PostEntity from './post.entity'; @Injectable() export class PostsService { constructor( @InjectRepository(PostEntity) private readonly postRepository: EntityRepository, ) {} }MikroORM uses a widespread repository pattern. We can easily create, modify, fetch, and delete entities with it. Getting all entities To get a whole list of entities from our database, we can use the findAll method.getPosts() { return this.postRepository.findAll(); } Getting an entity with a given id Besides the above, we also have the findOne method. If we provide it with the correct argument, we can fetch a post with a given id.async getPostById(id: number) { const post = await this.postRepository.findOne({ id, }); if (!post) { throw new PostNotFoundException(id); } return post; } We could also use the above method to find a post with a particular title, for example. We use the PostNotFoundException, which is a custom exception. postNotFound.exception.ts import { NotFoundException } from '@nestjs/common'; class PostNotFoundException extends NotFoundException { constructor(postId: number) { super(`Post with id ${postId} not found`); } } export default PostNotFoundException;MikroORM uses the Identity Map pattern to track the data. Whenever we fetch an entity from the database, MikroORM keeps its reference. This allows for a bunch of optimizations. For example, fetching a post with the same id twice returns the same instance and runs only one SELECT query.const firstPost = await this.postRepository.findOne({ id: 1 }); const secondPost = await this.postRepository.findOne({ id: 1 }); console.log(firstPost === secondPost); // true Creating an entity MikroORM handles transactions automatically and aims to batch as many of our queries as possible. Because of that, we need to tell MikroORM to persist changes to the database explicitly. If you want to know more about transactions, check out API with NestJS #15. Defining transactions with PostgreSQL and TypeORM const newPost = await this.postRepository.create(post); newPost.persist();We call the persist method to mark the entity as something we want to synchronize with the database. When we later call the flush() method, MikroORM stores all of the changes we’ve marked with the persist method to the database.await this.postRepository.flush();We can combine both of the above actions by using the persistAndFlush method.async createPost(post: CreatePostDto) { const newPost = await this.postRepository.create(post); await this.postRepository.persistAndFlush(newPost); return newPost; } Editing an entity To modify an entity, we can get it from the database and modify it. Then, when we flush all of the changes, MikroORM persists them in the database.async updatePost(id: number, post: UpdatePostDto) { const existingPost = await this.getPostById(id); existingPost.content = post.content; existingPost.title = post.title; await this.postRepository.persistAndFlush(existingPost); return existingPost; }We can simplify the above code by using the wrap function provided by MikroORM. It allows us to use various helpers, such as assign.async updatePost(id: number, post: UpdatePostDto) { const existingPost = await this.getPostById(id); wrap(existingPost).assign(post); await this.postRepository.persistAndFlush(existingPost); return existingPost; } By default, assign does not merge objects recursively. To achieve that, we would need to use wrap(existingPost).assign(post, { mergeObjects: true }) instead. Please notice that using assign allows us to implement the PATCH method, not PUT. The above is because it won’t remove properties if we don’t explicitly set them as null. Removing an entity We need to mark the entity for removal and flush the changes to remove an entity.async deletePost(id: number) { const post = await this.getPostById(id); this.postRepository.remove(post); return this.postRepository.flush(); }We can simplify the above function by using the removeAndFlush method.async deletePost(id: number) { const post = await this.getPostById(id); return this.postRepository.removeAndFlush(post); } Putting all of the features together When we incorporate all of the above features into our service, it looks like that: posts.service.ts import { Injectable } from '@nestjs/common'; import { InjectRepository } from '@mikro-orm/nestjs'; import { EntityRepository, wrap } from '@mikro-orm/core'; import PostEntity from './post.entity'; import PostNotFoundException from './exceptions/postNotFound.exception'; import CreatePostDto from './dto/createPost.dto'; import UpdatePostDto from './dto/updatePost.dto'; @Injectable() export class PostsService { constructor( @InjectRepository(PostEntity) private readonly postRepository: EntityRepository, ) {} getPosts() { return this.postRepository.findAll(); } async getPostById(id: number) { const post = await this.postRepository.findOne({ id, }); if (!post) { throw new PostNotFoundException(id); } return post; }