@mikro-orm/core

TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, PostgreSQL (including CockroachDB and PGlite), SQLite (including libSQL), MSSQL and Oracle databases.

Heavily inspired by Doctrine and Hibernate.

Quick Start

Install a driver package for your database:

npm install @mikro-orm/postgresql   # PostgreSQL
npm install @mikro-orm/pglite       # PGlite (embedded PostgreSQL in WASM)
npm install @mikro-orm/mysql        # MySQL
npm install @mikro-orm/mariadb      # MariaDB
npm install @mikro-orm/sqlite       # SQLite
npm install @mikro-orm/libsql       # libSQL / Turso
npm install @mikro-orm/mongodb      # MongoDB
npm install @mikro-orm/mssql        # MS SQL Server
npm install @mikro-orm/oracledb     # Oracle

If you use additional packages like @mikro-orm/cli, @mikro-orm/migrations, or @mikro-orm/entity-generator, install @mikro-orm/core explicitly as well. See the quick start guide for details.

Define Entities

The recommended way to define entities is using defineEntity with setClass:

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

const AuthorSchema = defineEntity({
  name: 'Author',
  properties: {
    id: p.integer().primary(),
    name: p.string(),
    email: p.string(),
    born: p.datetime().nullable(),
    books: () => p.oneToMany(Book).mappedBy('author'),
  },
});

export class Author extends AuthorSchema.class {}
AuthorSchema.setClass(Author);

const BookSchema = defineEntity({
  name: 'Book',
  properties: {
    id: p.integer().primary(),
    title: p.string(),
    author: () => p.manyToOne(Author).inversedBy('books'),
  },
});

export class Book extends BookSchema.class {}
BookSchema.setClass(Book);

You can also define entities using decorators or EntitySchema. See the defining entities guide for all options.

Initialize and Use

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

const orm = await MikroORM.init({
  entities: [Author, Book],
  dbName: 'my-db',
});

// Create new entities
const author = orm.em.create(Author, {
  name: 'Jon Snow',
  email: '[e-mail]',
});
const book = orm.em.create(Book, {
  title: 'My Life on The Wall',
  author,
});

// Flush persists all tracked changes in a single transaction
await orm.em.flush();

Querying

// Find with relations
const authors = await orm.em.findAll(Author, {
  populate: ['books'],
  orderBy: { name: 'asc' },
});

// Type-safe QueryBuilder
const qb = orm.em.createQueryBuilder(Author);
const result = await qb
  .select('*')
  .where({ books: { title: { $like: '%Wall%' } } })
  .getResult();

Request Context

In web applications, use RequestContext to isolate the identity map per request:

const app = express();

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

More info about RequestContext is described here.

Unit of Work

Unit of Work maintains a list of objects (entities) affected by a business transaction and coordinates the writing out of changes. (Martin Fowler)

When you call em.flush(), all computed changes are queried inside a database transaction. This means you can control transaction boundaries simply by making changes to your entities and calling flush() when ready.

const author = await em.findOneOrFail(Author, 1, {
  populate: ['books'],
});
author.name = 'Jon Snow II';
author.books.getItems().forEach(book => book.title += ' (2nd ed.)');
author.books.add(orm.em.create(Book, { title: 'New Book', author }));

// Flush computes change sets and executes them in a single transaction
await em.flush();

The above flush will execute:

begin;
update "author" set "name" = 'Jon Snow II' where "id" = 1;
update "book"
  set "title" = case
    when ("id" = 1) then 'My Life on The Wall (2nd ed.)'
    when ("id" = 2) then 'Another Book (2nd ed.)'
    else "title" end
  where "id" in (1, 2);
insert into "book" ("title", "author_id") values ('New Book', 1);
commit;

Core Features

• Clean and Simple Entity Definition — decorators, EntitySchema, or defineEntity
• Identity Map and Unit of Work — automatic change tracking
• Entity References and Collections
• QueryBuilder and Kysely Integration
• Transactions and Cascading
• Populating Relations and Loading Strategies
• Filters and Lifecycle Hooks
• Schema Generator and Migrations
• Entity Generator and Seeding
• Embeddables, Custom Types, and Serialization
• Composite and Foreign Keys as Primary Key
• Entity Constructors and Property Validation
• Modelling Relationships and Vanilla JS Support

Documentation

MikroORM documentation, included in this repo in the root directory, is built with Docusaurus and publicly hosted on GitHub Pages at https://mikro-orm.io.

There is also auto-generated CHANGELOG.md file based on commit messages (via semantic-release).

Example Integrations

You can find example integrations for some popular frameworks in the mikro-orm-examples repository:

TypeScript Examples

• Express + MongoDB
• Nest + MySQL
• RealWorld example app (Nest + MySQL)
• Koa + SQLite
• GraphQL + PostgreSQL
• Inversify + PostgreSQL
• NextJS + MySQL
• Accounts.js REST and GraphQL authentication + SQLite
• Nest + Shopify + PostgreSQL + GraphQL
• Elysia.js + libSQL + Bun
• Electron.js + PostgreSQL

JavaScript Examples

• Express + SQLite

Contributing

Contributions, issues and feature requests are welcome. Please read CONTRIBUTING.md for details on the process for submitting pull requests to us.

Authors

Martin Adámek

• Twitter: @B4nan
• Github: @b4nan

See also the list of contributors who participated in this project.

Show Your Support

Please star this repository if this project helped you!

If you'd like to support my open-source work, consider sponsoring me directly at github.com/sponsors/b4nan.

License

Copyright © 2018-present Martin Adámek.

This project is licensed under the MIT License - see the LICENSE file for details.

Similar packages

Other packages similar to @mikro-orm/core

typeorm

TypeORM is another ORM for TypeScript and JavaScript (ES7, ES6, ES5). It supports multiple databases like MySQL, PostgreSQL, MariaDB, SQLite, and more. TypeORM is known for its active community and extensive documentation. Compared to @mikro-orm/core, TypeORM offers a similar feature set but with a different API and some additional features like Active Record pattern support.

sequelize

Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite, and Microsoft SQL Server. It features solid transaction support, relations, eager and lazy loading, read replication, and more. Sequelize is widely used and has a large community. Compared to @mikro-orm/core, Sequelize is more mature and has broader database support but lacks some of the TypeScript-specific features.

objection

Objection.js is an ORM for Node.js that aims to stay as close to the relational database as possible. It is built on top of the SQL query builder Knex.js. Objection.js is known for its simplicity and flexibility. Compared to @mikro-orm/core, Objection.js provides a more lightweight and less opinionated approach to ORM, making it suitable for developers who prefer more control over their SQL queries.