# MikroORM Setup {#mikroorm-setup}


MikroORM is the **alternative ORM** in Ever Gauzy, providing stricter metadata validation, identity maps, and the Unit of Work pattern.


## Configuration {#configuration}



### Enabling MikroORM {#enabling-mikroorm}


```bash
# .env
DB_ORM=mikro-orm
```


### Connection Options {#connection-options}


MikroORM uses a similar database configuration to TypeORM:

```typescript
MikroOrmModule.forRootAsync({
  useFactory: (configService: ConfigService) => ({
    type: configService.get("DB_TYPE"),
    host: configService.get("DB_HOST"),
    port: configService.get("DB_PORT"),
    dbName: configService.get("DB_NAME"),
    user: configService.get("DB_USER"),
    password: configService.get("DB_PASS"),
    entities: [...coreEntities, ...pluginEntities],
    discovery: { disableDynamicFileAccess: true },
    allowGlobalContext: true,
  }),
});
```


## Key Differences from TypeORM {#key-differences-from-typeorm}


| Feature             | TypeORM                     | MikroORM                 |
| ------------------- | --------------------------- | ------------------------ |
| **Pattern**         | Active Record + Data Mapper | Unit of Work             |
| **Change Tracking** | Manual save                 | Automatic (Identity Map) |
| **Metadata**        | Decorators at runtime       | Stricter validation      |
| **Flushing**        | Immediate `save()`          | Batch `em.flush()`       |
| **Relations**       | Eager/lazy optional         | Reference wrappers       |
| **Entity Creation** | `repo.create()`             | `em.create()`            |


## Repository Pattern {#repository-pattern}



### MikroORM Repositories {#mikroorm-repositories}


```typescript
@Injectable()
export class MikroOrmEmployeeRepository extends MikroOrmBaseEntityRepository<Employee> {
  constructor(em: EntityManager) {
    super(em, Employee);
  }
}
```


### Using the EntityManager {#using-the-entitymanager}


```typescript
@Injectable()
export class EmployeeService {
  constructor(
    @InjectRepository(Employee)
    private readonly mikroOrmRepo: MikroOrmEmployeeRepository,
  ) {}

  async create(input: IEmployeeCreateInput): Promise<Employee> {
    const employee = this.mikroOrmRepo.create(input);
    await this.mikroOrmRepo.persistAndFlush(employee);
    return employee;
  }

  async findAll(): Promise<Employee[]> {
    return this.mikroOrmRepo.find(
      { isActive: true },
      { populate: ["user", "organization"] },
    );
  }
}
```


## Unit of Work {#unit-of-work}


MikroORM tracks entity changes automatically via the EntityManager's Identity Map:

```typescript
// Load entity
const employee = await em.findOne(Employee, id);

// Modify in memory
employee.firstName = "Updated";

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


## Stricter Metadata {#stricter-metadata}


MikroORM validates entity metadata more strictly than TypeORM:

- All relation properties must have proper type hints
- Unique constraint definitions must reference property names (not column names)
- Entity discovery validates all decorators at startup



> [!NOTE]
> This strictness catches many common bugs at startup rather than at runtime, making MikroORM a good choice for production environments.




## Known Considerations {#known-considerations}



### Conditional Decorator Application {#conditional-decorator-application}


Since Gauzy supports both ORMs, Multi-ORM decorators are **conditionally applied** based on the active ORM:

```typescript
// Only the MikroORM decorators are applied when DB_ORM=mikro-orm
// Only TypeORM decorators are applied when DB_ORM=typeorm
```

This prevents metadata conflicts. See [Custom Entity Fields Registration Issues](https://sourcey-gauzy.pages.dev/architecture/multi-orm-architecture/index.md) for more details on this pattern.


### PostgreSQL vs SQLite Behavior {#postgresql-vs-sqlite-behavior}


MikroORM's metadata validation is stricter with PostgreSQL than SQLite:

- PostgreSQL driver enforces all metadata constraints
- SQLite may silently ignore some constraints
- Always test with PostgreSQL for production deployments


## Related Pages {#related-pages}


- [Database Overview](https://sourcey-gauzy.pages.dev/database/database-overview/index.md) — general database info
- [TypeORM Setup](https://sourcey-gauzy.pages.dev/database/typeorm/index.md) — primary ORM
- [Multi-ORM Architecture](https://sourcey-gauzy.pages.dev/architecture/multi-orm-architecture/index.md) — Multi-ORM details
- [Multi-ORM Entities](https://sourcey-gauzy.pages.dev/database/multi-orm-entities/index.md) — entity patterns