# Source: https://mikro-orm.io/docs/usage-with-nestjs.md

# Using MikroORM with NestJS framework

## Installation[​](#installation "Direct link to Installation")

Easiest way to integrate MikroORM to Nest is via [`@mikro-orm/nestjs` module](https://github.com/mikro-orm/nestjs). Simply install it next to Nest, MikroORM and underlying driver:

```
$ yarn add @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mongodb     # for mongo
$ yarn add @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mysql       # for mysql/mariadb
$ yarn add @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mariadb     # for mysql/mariadb
$ yarn add @mikro-orm/core @mikro-orm/nestjs @mikro-orm/postgresql  # for postgresql
$ yarn add @mikro-orm/core @mikro-orm/nestjs @mikro-orm/sqlite      # for sqlite
```

or

```
$ npm i -s @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mongodb     # for mongo
$ npm i -s @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mysql       # for mysql/mariadb
$ npm i -s @mikro-orm/core @mikro-orm/nestjs @mikro-orm/mariadb     # for mysql/mariadb
$ npm i -s @mikro-orm/core @mikro-orm/nestjs @mikro-orm/postgresql  # for postgresql
$ npm i -s @mikro-orm/core @mikro-orm/nestjs @mikro-orm/sqlite      # for sqlite
```

Once the installation process is completed, we can import the `MikroOrmModule` into the root `AppModule`.

```
@Module({
  imports: [
    MikroOrmModule.forRoot({
      entities: ['./dist/entities'],
      entitiesTs: ['./src/entities'],
      dbName: 'my-db-name.sqlite3',
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

The `forRoot()` method accepts the same configuration object as `init()` from the MikroORM package. Check [this page](https://mikro-orm.io/docs/configuration.md) for the complete configuration documentation.

Alternatively we can [configure the CLI](https://mikro-orm.io/docs/quick-start.md#setting-up-the-commandline-tool) by creating a configuration file `mikro-orm.config.ts` and then call the `forRoot()` without any arguments. This won't work when you use a build tools that use tree shaking.

```
@Module({
  imports: [
    MikroOrmModule.forRoot(),
  ],
  ...
})
export class AppModule {}
```

Afterward, the `EntityManager` will be available to inject across entire project (without importing any module elsewhere).

```
import { MikroORM } from '@mikro-orm/core';
import { EntityManager } from '@mikro-orm/mysql'; // Import EntityManager from your driver package or `@mikro-orm/knex`

@Injectable()
export class MyService {

  constructor(private readonly orm: MikroORM,
              private readonly em: EntityManager) {
  }

}
```

> Notice that the `EntityManager` is imported from the `@mikro-orm/driver` package, where driver is `mysql`, `sqlite`, `postgres` or whatever driver you are using.
>
> In case you have `@mikro-orm/knex` installed as a dependency, you can also import the `EntityManager` from there.

## Repositories[​](#repositories "Direct link to Repositories")

MikroORM supports the repository design pattern. For every entity we can create a repository. Read the complete [documentation on repositories here](https://mikro-orm.io/docs/repositories.md). To define which repositories shall be registered in the current scope you can use the `forFeature()` method. For example, in this way:

> You should **not** register your base entities via `forFeature()`, as there are no repositories for those. On the other hand, base entities need to be part of the list in `forRoot()` (or in the ORM config in general).

```
// photo.module.ts

@Module({
  imports: [MikroOrmModule.forFeature([Photo])],
  providers: [PhotoService],
  controllers: [PhotoController],
})
export class PhotoModule {}
```

and import it into the root `AppModule`:

```
// app.module.ts
@Module({
  imports: [MikroOrmModule.forRoot(...), PhotoModule],
})
export class AppModule {}
```

In this way we can inject the `PhotoRepository` to the `PhotoService` using the `@InjectRepository()` decorator:

```
@Injectable()
export class PhotoService {
  constructor(
    @InjectRepository(Photo)
    private readonly photoRepository: EntityRepository<Photo>
  ) {}

  // ...
}
```

## Using custom repositories[​](#using-custom-repositories "Direct link to Using custom repositories")

When using custom repositories, we can get around the need for `@InjectRepository()` decorator by naming our repositories the same way as `getRepositoryToken()` method do:

```
export const getRepositoryToken = <T> (entity: EntityName<T>) => `${Utils.className(entity)}Repository`;
```

In other words, as long as we name the repository same was as the entity is called, appending `Repository` suffix, the repository will be registered automatically in the Nest.js DI container.

`**./author.entity.ts**`

```
@Entity({ repository: () => AuthorRepository })
export class Author {

  // to allow inference in `em.getRepository()`
  [EntityRepositoryType]?: AuthorRepository;

}
```

`**./author.repository.ts**`

```
import { EntityRepository } from '@mikro-orm/mysql'; // Import EntityManager from your driver package or `@mikro-orm/knex`

export class AuthorRepository extends EntityRepository<Author> {

  // your custom methods...

}
```

As the custom repository name is the same as what `getRepositoryToken()` would return, we do not need the `@InjectRepository()` decorator anymore:

```
@Injectable()
export class MyService {

  constructor(private readonly repo: AuthorRepository) { }

}
```

## Load entities automatically[​](#load-entities-automatically "Direct link to Load entities automatically")

> `autoLoadEntities` option was added in v4.1.0

Manually adding entities to the entities array of the connection options can be tedious. In addition, referencing entities from the root module breaks application domain boundaries and causes leaking implementation details to other parts of the application. To solve this issue, static glob paths can be used.

Note, however, that glob paths are not supported by webpack, so if you are building your application within a monorepo, you won't be able to use them. To address this issue, an alternative solution is provided. To automatically load entities, set the `autoLoadEntities` property of the configuration object (passed into the `forRoot()` method) to `true`, as shown below:

```
@Module({
  imports: [
    MikroOrmModule.forRoot({
      // ...
      autoLoadEntities: true,
    }),
  ],
})
export class AppModule {}
```

With that option specified, every entity registered through the `forFeature()` method will be automatically added to the entities array of the configuration object.

> Note that entities that aren't registered through the `forFeature()` method, but are only referenced from the entity (via a relationship), won't be included by way of the `autoLoadEntities` setting.

> Using `autoLoadEntities` also has no effect on the MikroORM CLI - for that we still need CLI config with the full list of entities. On the other hand, we can use globs there, as the CLI won't go through webpack.

## Request scoped handlers in queues[​](#request-scoped-handlers-in-queues "Direct link to Request scoped handlers in queues")

> `@CreateRequestContext()` decorator is available in `@mikro-orm/core` package.

> Before v6, `@CreateRequestContext()` was called `@UseRequestContext()`.

As mentioned in the [docs](https://mikro-orm.io/docs/identity-map.md), we need a clean state for each request. That is handled automatically thanks to the `RequestContext` helper registered via middleware.

But middlewares are executed only for regular HTTP request handles, what if we need a request scoped method outside of that? One example of that is queue handlers or scheduled tasks.

We can use the `@CreateRequestContext()` decorator. It requires you to first inject the `MikroORM` instance to current context, it will be then used to create the context for you. Under the hood, the decorator will register new request context for your method and execute it inside the context.

> `@CreateRequestContext()` should be used only on the top level methods. It should not be nested - a method decorated with it should not call another method that is also decorated with it.

```
@Controller()
export class MyService {

  constructor(private readonly orm: MikroORM) { }

  @CreateRequestContext()
  async doSomething() {
    // this will be executed in a separate context
  }

}
```

Alternatively you can provide a callback that will return the `MikroORM` instance.

```
import { DI } from '..';

export class MyService {

  @CreateRequestContext(() => DI.orm)
  async doSomething() {
    // this will be executed in a separate context
  }

}
```

Another thing to look out for how you combine them with other decorators. For example if you use it in combination with NestJS's "[BullJS queues module](https://docs.nestjs.com/techniques/queues)", a safe bet is to extract the part of the code that needs a clean [docs](https://mikro-orm.io/docs/identity-map.md), either in a new method or inject a separate service.

```
@Processor({
  name: 'example-queue',
})
export class MyConsumer {
  constructor(private readonly orm: MikroORM) { }

  @Process()
  async doSomething(job: Job<any>) {
    await this.doSomethingWithMikro();
  }

  @CreateRequestContext()
  async doSomethingWithMikro() {
    // this will be executed in a separate context
  }
}
```

As in this case, the `@Process()` decorator expects to receive an executable function, but if we add `@CreateRequestContext()` to the handler as well, if `@CreateRequestContext()` is executed before `@Process()`, the later will receive `void`.

## `@EnsureRequestContext()` decorator[​](#ensurerequestcontext-decorator "Direct link to ensurerequestcontext-decorator")

Sometimes you may prefer to just ensure the method is executed inside a request context, and reuse the existing context if available. You can use the `@EnsureRequestContext()` decorator here, it behaves exactly like the `@CreateRequestContext`, but only creates new context if necessary, reusing the existing one if possible.

## Request scoping when using GraphQL[​](#request-scoping-when-using-graphql "Direct link to Request scoping when using GraphQL")

The GraphQL module in NestJS uses `apollo-server-express` which enables `bodyparser` by default. ([source](https://github.com/mikro-orm/mikro-orm/issues/696#issuecomment-669846919)) As mentioned in "[RequestContext helper for DI containers](https://mikro-orm.io/docs/identity-map/#requestcontext-helper-for-di-containers)" this causes issues as the Middleware the NestJS MikroORM module installs needs to be loaded after `bodyparser`. At the same time make sure to disable body-parser in NestJs itself as well.

This can be done by adding bodyparser to your main.ts file

```
import { NestFactory } from '@nestjs/core';
import express from 'express';
async function bootstrap() {
  const app = await NestFactory.create(AppModule,{ bodyParser: false });
  app.use(express.json());
  await app.listen(5555);
}
```

And at the same time disabling the bodyparser in the GraphQL Module

```
@Module({
  imports: [
    GraphQLModule.forRoot({
      bodyParserConfig: false,
    }),
  ],
})
```

## App shutdown and cleanup[​](#app-shutdown-and-cleanup "Direct link to App shutdown and cleanup")

By default, NestJS does not listen for system process termination signals (for example SIGTERM). Because of this, the MikroORM shutdown logic will never execute if the process is terminated, which could lead to database connections remaining open and consuming resources. To enable this, the `enableShutdownHooks` function needs to be called when starting up the application.

```
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Starts listening for shutdown hooks
  app.enableShutdownHooks();

  await app.listen(3000);
}
```

More information about [enableShutdownHooks](https://docs.nestjs.com/fundamentals/lifecycle-events#application-shutdown)

## Multiple Database Connections[​](#multiple-database-connections "Direct link to Multiple Database Connections")

You can define multiple database connections by registering multiple `MikroOrmModule` and setting their `contextName`. If you want to use middleware request context you must disable automatic middleware and register `MikroOrmModule` with `forMiddleware()` or use NestJS `Injection Scope`

```
@Module({
  imports: [
    MikroOrmModule.forRoot({
      contextName: 'db1',
      registerRequestContext: false, // disable automatic middleware
      ...
    }),
    MikroOrmModule.forRoot({
      contextName: 'db2',
      registerRequestContext: false, // disable automatic middleware
      ...
    }),
    MikroOrmModule.forMiddleware()
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

To access different `MikroORM`/`EntityManager` connections you have to use the new injection tokens `@InjectMikroORM()`/`@InjectEntityManager()` where you are required to pass the `contextName` in:

```
@Injectable()
export class MyService {

  constructor(@InjectMikroORM('db1') private readonly orm1: MikroORM,
              @InjectMikroORM('db2') private readonly orm2: MikroORM,
              @InjectEntityManager('db1') private readonly em1: EntityManager,
              @InjectEntityManager('db2') private readonly em2: EntityManager) { }

}
```

When defining your repositories with `forFeature()` method you will need to set which `contextName` you want it registered against:

```
// photo.module.ts

@Module({
  imports: [MikroOrmModule.forFeature([Photo], 'db1')],
  providers: [PhotoService],
  controllers: [PhotoController],
})
export class PhotoModule {}
```

When using the `@InjectRepository` decorator you will also need to pass the `contextName` you want to get it from:

```
@Injectable()
export class PhotoService {
  constructor(
    @InjectRepository(Photo, 'db1')
    private readonly photoRepository: EntityRepository<Photo>
  ) {}

  // ...

}
```

## Serialization caveat[​](#serialization-caveat "Direct link to Serialization caveat")

[NestJS built-in serialization](https://docs.nestjs.com/techniques/serialization) relies on [class-transformer](https://github.com/typestack/class-transformer). Since MikroORM wraps every single entity relation in a `Reference` or a `Collection` instance (for type-safety), this will make the built-in `ClassSerializerInterceptor` blind to any wrapped relations. In other words, if you return MikroORM entities from your HTTP or WebSocket handlers, all of their relations will NOT be serialized.

Luckily, MikroORM provides a [serialization API](https://mikro-orm.io/docs/serializing) which can be used in lieu of `ClassSerializerInterceptor`.

```
@Entity()
export class Book {
  @Property({ hidden: true })   // --> Equivalent of class-transformer's `@Exclude`
  hiddenField: number = Date.now();

  @Property({ persist: false }) // --> Will only exist in memory (and will be serialized). Similar to class-transformer's `@Expose()`
  count?: number;

  @ManyToOne({ serializer: value => value.name, serializedName: 'authorName' })   // Equivalent of class-transformer's `@Transform()`
  author: Author;
}
```

## Testing[​](#testing "Direct link to Testing")

The `@mikro-orm/nestjs` package exposes `getRepositoryToken()` function that returns prepared token based on a given entity to allow mocking the repository.

> If we register the provider only via `getRepositoryToken()`, we need to use the `@InjectRepository` decorator. To be able to use custom repository without this decorator, we need to register it with `provide: PhotoRepository`. `provide`:

```
@Module({
  providers: [
    PhotoService,
    // required for `@InjectRepository` decorator
    {
      provide: getRepositoryToken(Photo),
      useValue: mockedRepository,
    },

    // required for custom repositories if we don't want to use `@InjectRepository`
    {
      provide: PhotoRepository,
      useValue: mockedRepository,
    },
  ],
})
export class PhotoModule {}
```

## Using `EventSubscriber`[​](#using-eventsubscriber "Direct link to using-eventsubscriber")

Subscribers are normally registered only via the ORM config, but you can do so also dynamically via `EventManager.registerSubscriber()`. If you want your subscriber to use some dependencies from the Nest.js DI container, use the `@Injectable` decorator and register the subscriber manually in the constructor instead of passing it to the ORM config:

```
import { Injectable } from '@nestjs/common';
import { EntityName, EventArgs, EventSubscriber } from '@mikro-orm/core';

@Injectable()
export class AuthorSubscriber implements EventSubscriber<Author> {

  constructor(em: EntityManager) {
    em.getEventManager().registerSubscriber(this);
  }

  getSubscribedEntities(): EntityName<Author>[] {
    return [Author];
  }

  async afterCreate(args: EventArgs<Author>): Promise<void> {
    // ...
  }

  async afterUpdate(args: EventArgs<Author>): Promise<void> {
    // ...
  }

}
```

## GraphQL resolvers[​](#graphql-resolvers "Direct link to GraphQL resolvers")

MikroORM supports [dataloaders](https://mikro-orm.io/docs/dataloaders.md) natively since v6 for `Reference.load()` and `Collection.load()` methods.

```
@Resolver(() => Book)
class BookResolver {

  @ResolveField(() => Author)
  async author(@Parent() book: Book) {
    return book.author.load({ dataloader: true }); // can be also enabled globally
  }

}
```

## Example[​](#example "Direct link to Example")

A real world example of NestJS with MikroORM can be found [here](https://github.com/mikro-orm/nestjs-realworld-example-app)