Skip to main content
Version: 6.3

Quick Start

In this guide, you will learn how to quickly bootstrap a simple project using MikroORM. For a deeper dive, check out the Getting Started guide which follows.

If you prefer to take a peek at an existing project, there are several example repositories available.

Installation​

First install the module via package manager of your choice. Do not forget to install the database driver as well:

# for mongodb
npm install @mikro-orm/core @mikro-orm/mongodb

# for mysql (works with mariadb too)
npm install @mikro-orm/core @mikro-orm/mysql

# for mariadb (works with mysql too)
npm install @mikro-orm/core @mikro-orm/mariadb

# for postgresql (works with cockroachdb too)
npm install @mikro-orm/core @mikro-orm/postgresql

# for sqlite
npm install @mikro-orm/core @mikro-orm/sqlite

# for better-sqlite
npm install @mikro-orm/core @mikro-orm/better-sqlite

# for libsql/turso
npm install @mikro-orm/core @mikro-orm/libsql

# for mssql
npm install @mikro-orm/core @mikro-orm/mssql

Next you will need to enable support for decorators as well as esModuleInterop in tsconfig.json via:

The decorators are opt-in, if you use a different way to define your entity metadata like EntitySchema, you don't need to enable them.

"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"esModuleInterop": true

Then call MikroORM.init as part of bootstrapping your app:

To access driver specific methods like em.createQueryBuilder() you need to import the MikroORM/EntityManager/EntityRepository class from the driver package. Alternatively you can cast the orm.em to EntityManager exported from the driver package:

import { EntityManager } from '@mikro-orm/postgresql';
const em = orm.em as EntityManager;
const qb = em.createQueryBuilder(...);
import { MikroORM } from '@mikro-orm/postgresql'; // or any other driver package

const orm = await MikroORM.init({
  entities: ['./dist/entities'], // path to your JS entities (dist), relative to `baseDir`
  dbName: 'my-db-name',
});
console.log(orm.em); // access EntityManager via `em` property

You can read more about all the possible configuration options in Advanced Configuration section.

Folder-based discovery​

You can also provide paths where you store your entities via entities array. The paths are resolved via globby internally, so you can use globbing patterns, including negative globs.

const orm = await MikroORM.init({
  entities: ['./dist/app/**/*.entity.js'],
  entitiesTs: ['./src/app/**/*.entity.ts'],
  // ...
});

If you are experiencing problems with folder based discovery, try using mikro-orm debug CLI command to check what paths are actually being used.

Entity Discovery in TypeScript​

The default metadata provider is ReflectMetadataProvider. If you want to use ts-morph based discovery (that reads actual TS types via the compiler API), you need to install @mikro-orm/reflection package.

import { MikroORM } from '@mikro-orm/postgresql';
import { TsMorphMetadataProvider } from '@mikro-orm/reflection';

const orm = await MikroORM.init({
  metadataProvider: TsMorphMetadataProvider,
  // ...
});

Read more about the differences in Metadata Providers section.

import { MikroORM } from '@mikro-orm/postgresql';

const orm = await MikroORM.init({
  entities: ['./dist/entities/**/*.js'], // path to your JS entities (dist), relative to `baseDir`
  entitiesTs: ['./src/entities/**/*.ts'], // path to your TS entities (source), relative to `baseDir`
  // ...
});

It is important that entities will point to the compiled JS files, and entitiesTs will point to the TS source files. You should not mix those.

For ts-morph discovery to work in production, you need to deploy .d.ts declaration files. Be sure to enable compilerOptions.declaration in your tsconfig.json.

You can also use different the default ReflectMetadataProvider or even write custom one. Using EntitySchema is another way to define your entities and does not depend on the metadata providers at all.

import { MikroORM } from '@mikro-orm/postgresql';

const orm = await MikroORM.init({
  // default since v4, so not needed to specify explicitly
  metadataProvider: ReflectMetadataProvider,
  // ...
});

Synchronous initialization​

As opposed to the async MikroORM.init method, you can prefer to use synchronous variant initSync. This method has some limitations:

  • database connection will be established when you first interact with the database (or you can use orm.connect() explicitly)
  • no loading of the config file, options parameter is mandatory
  • no support for folder based discovery
  • no check for mismatched package versions

RequestContext helper​

Now you will need to fork entity manager for each request so their identity maps will not collide. To do so, use the RequestContext helper:

const app = express();

app.use((req, res, next) => {
  RequestContext.create(orm.em, next);
});

You should register this middleware as the last one just before request handlers and before any of your custom middleware that is using the ORM. There might be issues when you register it before request processing middleware like queryParser or bodyParser, so definitely register the context after them.

More info about RequestContext is described here.

Entity definition​

Now you can start defining your entities (in one of the entities folders). This is how a simple entity can look like:

./entities/Book.ts
@Entity()
export class Book {

  @PrimaryKey()
  id: bigint;

  @Property()
  title: string;

  @ManyToOne(() => Author)
  author: Author;

  @ManyToMany(() => BookTag)
  tags = new Collection<BookTag>(this);

  constructor(title: string, author: Author) {
    this.title = title;
    this.author = author;
  }

}

Or if you want to use UUID primary key:

./entities/Book.ts
import { v4 } from 'uuid';

@Entity()
export class Book {

  @PrimaryKey({ type: 'uuid' })
  uuid = v4();

  // ...

}

More information can be found in defining entities section in docs.

EntityManager​

When you have your entities defined, you can start using ORM either via EntityManager.

To save entity state to database, you need to persist it. Persist determines whether to use insert or update and computes appropriate change-set. Entity references that are not persisted yet (does not have identifier) will be cascade persisted automatically.

// use constructors in your entities for required parameters
const author = new Author('Jon Snow', 'snow@wall.st');
author.born = new Date();

const publisher = new Publisher('7K publisher');

const book1 = new Book('My Life on The Wall, part 1', author);
book1.publisher = publisher;
const book2 = new Book('My Life on The Wall, part 2', author);
book2.publisher = publisher;
const book3 = new Book('My Life on The Wall, part 3', author);
book3.publisher = publisher;

// just persist books, author and publisher will be automatically cascade persisted
await em.persist([book1, book2, book3]).flush();

To fetch entities from database you can use find() and findOne() of EntityManager:

const authors = em.find(Author, {});

for (const author of authors) {
  console.log(author); // instance of Author entity
  console.log(author.name); // Jon Snow

  for (const book of author.books) { // iterating books collection
    console.log(book); // instance of Book entity
    console.log(book.title); // My Life on The Wall, part 1/2/3
  }
}

Take a look at docs about working with EntityManager.

Setting up the Commandline Tool​

MikroORM ships with a number of command line tools that are very helpful during development, like SchemaGenerator and EntityGenerator. You can call this command from the NPM binary directory or use npx:

To work with the CLI, first install @mikro-orm/cli package locally. The version needs to be aligned with the @mikro-orm/core package.

# install the CLI package first!
$ yarn add @mikro-orm/cli

# manually
$ node node_modules/.bin/mikro-orm

# via npx
$ npx mikro-orm

# or via yarn
$ yarn mikro-orm

For CLI to be able to access your database, you will need to create mikro-orm.config.js file that exports your ORM configuration.

ORM configuration file can export the Promise, like: export default Promise.resolve({...});.

Since v6.3, the CLI will always try to use TS config file, even without explicitly enabling it via useTsNode flag in your package.json file. You can still use it to disable the TS support explicitly. Keep in mind that having ts-node installed is still required for the TS support to work. The useTsNode has effect only on the CLI. Alternatively, you can use the alwaysAllowTs option in your package.json file, which will enable checking the TS files even for your actual app and not just the CLI (in case you call MikroORM.init() without any parameters). This can be handly if you run your app via Bun.

You can also set up array of possible paths to mikro-orm.config.* file in the package.json, as well as use different file name. The package.json file can be located in the current working directory, or in one of its parent folders.

./package.json
{
  "name": "your-app",
  "dependencies": { ... },
  "mikro-orm": {
    "configPaths": [
      "./src/mikro-orm.config.ts",
      "./dist/mikro-orm.config.js"
    ]
  }
}

Another way to control these CLI-related settings is with the environment variables:

  • MIKRO_ORM_CLI_CONFIG: the path to ORM config file
  • MIKRO_ORM_CLI_USE_TS_NODE: register ts-node for TypeScript support
  • MIKRO_ORM_CLI_TS_CONFIG_PATH: path to the tsconfig.json (for ts-node)
  • MIKRO_ORM_CLI_ALWAYS_ALLOW_TS: enable .ts files to use without ts-node
  • MIKRO_ORM_CLI_VERBOSE: enable verbose logging (e.g. print queries used in seeder or schema diffing)

Alternatively, you can also specify the config path via --config option:

$ npx mikro-orm debug --config ./my-config.ts

The --config flag will be respected also when you run your app (as long as it is part of process.argv), not just when you use the CLI.

For the app support, this might introduce a conflict with other tools like jest that also support overriding the config path via --config argument, in those cases you can use the MIKRO_ORM_CONFIG_ARG_NAME environment variable to change the argument name to something else than config:

$ MIKRO_ORM_CONFIG_ARG_NAME=mikro-orm-config \
  npx mikro-orm debug --mikro-orm-config ./my-config.ts

jest does not allow unrecognised parameters, to run tests with a custom configuration you can use this together with MIKRO_ORM_CLI_CONFIG environment variable to point to a test config.

MikroORM will always try to load the first available config file, based on the order in configPaths. When you have useTsNode disabled or ts-node is not already registered nor detected, TS config files will be ignored.

Preferred way of creating to the configuration object is with the defineConfig helper. It will provide intellisense even in JavaScript files, without the need for type hints via jsdoc:

import { defineConfig } from '@mikro-orm/sqlite';

export default defineConfig({
  entities: [Author, Book, BookTag],
  dbName: 'my-db-name',
  // this is inferred as you import `defineConfig` from sqlite package
  // driver: SqliteDriver,
});

Using defineConfig also automatically infers the driver option for you if you import the helper from the driver package. This means you don't have to provide the driver option explicitly.

Alternatively, you can use the Options type:

./src/mikro-orm.config.ts
import { Options } from '@mikro-orm/sqlite';

const config: Options = {
  entities: [Author, Book, BookTag],
  dbName: 'my-db-name',
  driver: SqliteDriver,
};

export default config;

Once you have the CLI config properly set up, you can omit the MikroORM.init() options parameter, and the CLI config will be automatically used. This process may fail if you use bundlers that use tree shaking. As the config file is not referenced anywhere statically, it would not be compiled - for that the best approach is to provide the config explicitly:

import config from './mikro-orm.config';
const orm = await MikroORM.init(config);

Now you should be able to start using the CLI. All available commands are listed in the CLI help:

$ npx mikro-orm

Usage: mikro-orm <command> [options]

Commands:
  mikro-orm cache:clear             Clear metadata cache
  mikro-orm cache:generate          Generate metadata cache
  mikro-orm generate-entities       Generate entities based on current database
                                    schema
  mikro-orm database:create         Create your database if it does not exist
  mikro-orm database:import <file>  Imports the SQL file to the database
  mikro-orm seeder:run              Seed the database using the seeder class
  mikro-orm seeder:create <seeder>  Create a new seeder class
  mikro-orm schema:create           Create database schema based on current
                                    metadata
  mikro-orm schema:drop             Drop database schema based on current
                                    metadata
  mikro-orm schema:update           Update database schema based on current
                                    metadata
  mikro-orm schema:fresh            Drop and recreate database schema based on
                                    current metadata
  mikro-orm migration:create        Create new migration with current schema
                                    diff
  mikro-orm migration:up            Migrate up to the latest version
  mikro-orm migration:down          Migrate one step down
  mikro-orm migration:list          List all executed migrations
  mikro-orm migration:check         Check if migrations are needed. Useful for
                                    bash scripts.
  mikro-orm migration:pending       List all pending migrations
  mikro-orm migration:fresh         Clear the database and rerun all migrations
  mikro-orm debug                   Debug CLI configuration

Options:
      --config   Set path to the ORM configuration file                 [string]
  -v, --version  Show version number                                   [boolean]
  -h, --help     Show help                                             [boolean]

Examples:
  mikro-orm schema:update --run  Runs schema synchronization

To verify your setup, you can use mikro-orm debug command.

When you have CLI config properly set up, you can omit the options parameter when calling MikroORM.init().