API with NestJS #62. Introduction to MikroORM with PostgreSQL

May 23, 2022

This entry is part 62 of 121 in the API with NestJS

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: bridge

Also, 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=nestjs

In this series, we use PostgreSQL. Because of that, we need the @mikroorm/postgresql package, among others.

1	npm install @mikro-orm/core @mikro-orm/nestjs @mikro-orm/postgresql

With 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<PostEntity>,

) {}

}

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

1 2	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.

1	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<PostEntity>,

) {}

getPosts() {

return this.postRepository.findAll();

}

async getPostById(id: number) {

const post = await this.postRepository.findOne({

id,

});

if (!post) {

throw new PostNotFoundException(id);

}

return post;

}

async createPost(post: CreatePostDto) {

const newPost = await this.postRepository.create(post);

await this.postRepository.persistAndFlush(newPost);

return newPost;

}

async updatePost(id: number, post: UpdatePostDto) {

const existingPost = await this.getPostById(id);

wrap(existingPost).assign(post);

await this.postRepository.persistAndFlush(existingPost);

return existingPost;

}

async deletePost(id: number) {

const post = await this.getPostById(id);

return this.postRepository.removeAndFlush(post);

}

We also need a controller that uses our service.

posts.controller.ts

import {

Body,

Controller,

Delete,

Get,

Param,

Post,

Put,

} from '@nestjs/common';

import { PostsService } from './posts.service';

import FindOneParams from '../utils/findOneParams';

import CreatePostDto from './dto/createPost.dto';

import UpdatePostDto from './dto/updatePost.dto';

@Controller('posts')

export default class PostsController {

constructor(private readonly postsService: PostsService) {}

@Get()

async getPosts() {

return this.postsService.getPosts();

}

@Get(':id')

getPostById(@Param() { id }: FindOneParams) {

return this.postsService.getPostById(id);

}

@Post()

async createPost(@Body() post: CreatePostDto) {

return this.postsService.createPost(post);

}

@Put(':id')

async updatePost(

@Param() { id }: FindOneParams,

@Body() post: UpdatePostDto,

) {

return this.postsService.updatePost(id, post);

}

@Delete(':id')

async deletePost(@Param() { id }: FindOneParams) {

return this.postsService.deletePost(Number(id));

}

Synchronizing our entities schema with the database

Doing all of the above does not create a posts table in our database. To achieve that, we need to create a migration. We will need the MikroORM CLI and a dedicated @mikro-orm/cli package.

1	npm install @mikro-orm/cli @mikro-orm/migrations

The CLI needs a separate configuration. To provide it, let’s add the following to the package.json first:

package.json

"mikro-orm": {

"useTsNode": true,

"configPaths": [

"./src/mikro-orm.config.ts"

]

}

We also need to create the mikro-orm.config.ts file in the src directory.

mikro-orm.config.ts

import PostEntity from './posts/post.entity';

import { Options } from '@mikro-orm/core';

import { ConfigService } from '@nestjs/config';

const configService = new ConfigService();

const MikroOrmConfig: Options = {

entities: [PostEntity],

type: 'postgresql',

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'),

};

export default MikroOrmConfig;

Because the mikro-orm.config.ts is not a part of a NestJS application, we initialize the ConfigService manually.

When we run npx mikro-orm migration:create, MikroORM checks the difference between our entity schema definitions and the state of the database. If there is a difference, it generates migration files.

Migration20220522201347.ts

import { Migration } from '@mikro-orm/migrations';

export class Migration20220522201347 extends Migration {

async up(): Promise<void> {

this.addSql('create table "post_entity" ("id" serial primary key, "title" varchar(255) not null, "content" varchar(255) not null);');

}

async down(): Promise<void> {

this.addSql('drop table if exists "post_entity" cascade;');

}

When we run npx mikro-orm migration:up, MikroORM performs the above migrations to bring our database to the latest state.

MikroORM keeps track of all of the migrations in the mikro_orm_migrations table.

Summary

In this article, we’ve gone through using MikroORM with PostgreSQL and NestJS. It included learning how MikroORM works by implementing all of the Create, Read, Update and Delete (CRUD) operations. To do that, we had to understand how MikroORM works under the hood and how to synchronize changes with the database. We also learned the basics of migrations and created them using the MikroORM CLI.

Series Navigation<< API with NestJS #61. Dealing with circular dependenciesAPI with NestJS #63. Relationships with PostgreSQL and MikroORM >>