Installation & Usage
First install the module via yarn
or 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 notsqlite3
as that is already included in the driver package.
or
Next you will need to enable support for decorators
as well as esModuleInterop
in tsconfig.json
via:
Then call MikroORM.init
as part of bootstrapping your app:
Read more about all the possible configuration options in Advanced Configuration section.
We can also provide paths where you store your entities via entities
array. Internally
it uses globby
so we can use
globbing patterns,
including negative globs.
If you are experiencing problems with folder based discovery, try using mikro-orm debug
CLI command to check what paths are actually being used.
Since v4, you can also use file globs, like
./dist/app/**/entities/*.entity.js
.
You can pass additional options to the underlying driver (e.g.
mysql2
) viadriverOptions
. The object will be deeply merged, overriding all internally used options.
#
Possible issues with circular dependenciesYour 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
entities
array 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.
#
Entity Discovery in TypeScriptIn 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 @mikro-orm/reflection
.
Read more about the differences in Metadata Providers section.
It is important that
entities
will point to the compiled JS files, andentitiesTs
will point to the TS source files. You should not mix those.
For
ts-morph
discovery to work in production, we need to deploy.d.ts
declaration files. Be sure to enablecompilerOptions.declaration
in yourtsconfig.json
.
You can also use different metadata provider or even write custom one:
ReflectMetadataProvider
that usesreflect-metadata
instead ofts-morph
JavaScriptMetadataProvider
that allows you to manually provide the entity schema (mainly for Vanilla JS)
Using
EntitySchema
is another way to define your entities, which is better suited than usingJavaScriptMetadataProvider
.
#
Request ContextThen you will need to fork Entity Manager for each request so their identity maps will not
collide. To do so, use the RequestContext
helper:
If the
next
handler needs to be awaited (like in Koa), useRequestContext.createAsync()
instead.
More info about RequestContext
is described here.
#
Setting up the Commandline ToolMikroORM 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.
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 mikro-orm.config
file,
as well as use different file name:
Do not forget to install
ts-node
when enablinguseTsNode
flag.
MikroORM will always try to load the first available config file, based on the
order in 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
load it.
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.
You can also use different names for this file, simply rename it in the
configPaths
array your inpackage.json
. You can also useMIKRO_ORM_CLI
environment variable with the path to overrideconfigPaths
value.
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
options
parameter when callingMikroORM.init()
.
Note: When importing a dump file you need
multipleStatements: true
in your configuration. Please check the configuration documentation for more information.
Now you can start defining your entities.