1. O que é e para que serve?

Mikro-ORM é uma biblioteca moderna de mapeamento objeto-relacional (ORM) para TypeScript e JavaScript (Node.js) que implementa os padrões Identity Map e Unit of Work. Diferente de ORMs clássicos como TypeORM ou Sequelize, o Mikro-ORM é inspirado no Doctrine (PHP) e Hibernate (Java), oferecendo um gerenciamento mais previsível do estado das entidades e sua sincronização com o banco de dados.

Para que serve? Em aplicações web típicas, desenvolvedores frequentemente enfrentam o problema de "dados sujos", quando o mesmo registro é carregado duas vezes em partes diferentes do código, gerando conflitos ao salvar. O Mikro-ORM resolve isso com o Identity Map: para cada chave primária, existe exatamente uma instância da entidade dentro de um mesmo contexto (EntityManager). Isso garante que você sempre trabalhe com a versão mais atual do objeto, e todas as alterações são rastreadas automaticamente.

A biblioteca suporta diversos bancos de dados (PostgreSQL, MySQL, SQLite, MongoDB, MariaDB) e oferece ferramentas poderosas: migrations, suporte nativo a transações, operações em cascata, carregamento de relacionamentos (eager/lazy), validador de esquemas integrado e gerador de entidades a partir de bancos existentes. O Mikro-ORM é ideal para modelos de domínio complexos e arquiteturas de microsserviços onde a consistência dos dados é essencial.

2. Instalação

Para instalar o Mikro-ORM e o driver necessário do banco de dados, execute o comando via npm (ou yarn/pnpm):

# Instalação do núcleo da biblioteca
npm install @mikro-orm/core

# Instalação do driver para seu banco (escolha um):
npm install @mikro-orm/sqlite    # SQLite
npm install @mikro-orm/postgresql # PostgreSQL
npm install @mikro-orm/mysql      # MySQL / MariaDB
npm install @mikro-orm/mongodb    # MongoDB

# Adicional: CLI para migrations e geração de esquemas
npm install @mikro-orm/cli
npm install @mikro-orm/migrations  # para migrations

Também é recomendado instalar o reflect-metadata para o funcionamento dos decoradores:

npm install reflect-metadata

Adicione ao tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2021",
    "module": "commonjs"
  }
}

3. Início rápido — exemplo mínimo funcional

Vamos criar uma aplicação simples com SQLite e uma entidade User.

Passo 1. Definindo a entidade (entities/User.ts):

import { Entity, PrimaryKey, Property } from '@mikro-orm/core';

@Entity()
export class User {
  @PrimaryKey()
  id!: number;

  @Property()
  name!: string;

  @Property()
  email!: string;

  @Property()
  createdAt: Date = new Date();
}

Passo 2. Configurando o Mikro-ORM (index.ts):

import 'reflect-metadata';
import { MikroORM } from '@mikro-orm/core';
import { SqliteDriver } from '@mikro-orm/sqlite';
import { User } from './entities/User';

async function main() {
  const orm = await MikroORM.init({
    entities: [User],
    dbName: 'test.db',
    driver: SqliteDriver,
    debug: true, // logs das consultas SQL
  });

  // Criando o esquema (em modo dev)
  await orm.getSchemaGenerator().createSchema();

  // Obtendo o EntityManager
  const em = orm.em.fork();

  // Criando um usuário
  const user = em.create(User, {
    name: 'João',
    email: 'joao@example.com',
  });
  await em.flush(); // salvando no banco

  // Lendo o usuário
  const found = await em.findOne(User, { email: 'joao@example.com' });
  console.log('Encontrado:', found);

  // Atualizando
  found!.name = 'Pedro';