First install the module via
npm and do not forget to install the
driver package as well:
Since v4, you should install the driver package, but not the db connector itself, e.g. install
@mikro-orm/sqlite, but not
sqlite3as that is already included in the driver package.
Next you will need to enable support for decorators
as well as
MikroORM.init as part of bootstrapping your app:
Read more about all the possible configuration options in Advanced Configuration section.
If you are experiencing problems with folder based discovery, try using
CLI command to check what paths are actually being used.
Since v4, you can also use file globs, like
You can pass additional options to the underlying driver (e.g.
driverOptions. The object will be deeply merged, overriding all internally used options.
Your entities will most probably contain circular dependencies (e.g. if you use bi-directional relationship). While this is fine, there might be issues caused by wrong order of entities during discovery, especially when you are using the folder based way.
The errors caused by circular dependencies are usually similar to this one:
If you encounter this, you have basically two options:
- Use entity references in
entitiesarray to have control over the order of discovery. You might need to play with the actual order you provide here, or possibly with the order of import statements.
- Use strings instead of references (e.g.
@OneToMany('Book', 'author')). The downside here is that you will lose the typechecking capabilities of the decorators.
In v4 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
Read more about the differences in Metadata Providers section.
It is important that
entitieswill point to the compiled JS files, and
entitiesTswill point to the TS source files. You should not mix those.
ts-morphdiscovery to work in production, we need to deploy
.d.tsdeclaration files. Be sure to enable
You can also use different metadata provider or even write custom one:
EntitySchemais another way to define your entities, which is better suited than using
Then you will need to fork Entity Manager for each request so their identity maps will not
collide. To do so, use the
nexthandler needs to be awaited (like in Koa), use
RequestContext.createAsync()instead.app.use((ctx, next) => RequestContext.createAsync(orm.em, next));
More info about
RequestContext is described here.
MikroORM ships with a number of command line tools that are very helpful during development,
EntityGenerator. You can call this command from the NPM binary
directory or use
To work with the CLI, first install
@mikro-orm/clipackage locally. The version needs to be aligned with the
For CLI to be able to access your database, you will need to create
mikro-orm.config.js file that
exports your ORM configuration. TypeScript is also supported, just enable
useTsNode flag in your
package.json file. There you can also set up array of possible paths to
as well as use different file name:
Do not forget to install
useTsNodeis used only when executing the CLI, it is not respected when running your app.
MikroORM will always try to load the first available config file, based on the
configPaths. This means that if you specify the first item as the TS
config, but you do not have
ts-node enabled and installed, it will fail to
When we have
useTsNode disabled and
ts-node is not already registered and detected,
TS config files will be ignored.
Once you have the CLI config properly set up, you can omit the
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
You can also use different names for this file, simply rename it in the
configPathsarray your in
package.json. You can also use
MIKRO_ORM_CLIenvironment variable with the path to override
Now you should be able to start using the CLI. All available commands are listed in the CLI help:
To verify your setup, you can use
mikro-orm debug command.
When you have CLI config properly set up, you can omit the
optionsparameter when calling
Note: When importing a dump file you need
multipleStatements: truein your configuration. Please check the configuration documentation for more information.
Now you can start defining your entities.