Introduction to MikroORM with PostgreSQL

May 23, 2022

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. We can use the same docker-compose.yml file we’ve created when setting up PostgreSQL with TypeORM.

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.

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.

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

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 { Options } from "@mikro-orm/core"
import { ConfigService } from "@nestjs/config"
 
import PostEntity from "./posts/post.entity"
 
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.