Configuration
Entity Discovery
You can either provide array of entity instances via entities
, or let the ORM look up your entities in selected folders.
MikroORM.init({
entities: [Author, Book, Publisher, BookTag],
});
We can also use folder based discovery by providing list of paths to the entities we want to discover (globs are supported as well). This way we also need to specify entitiesTs
, where we point the paths to the TS source files instead of the JS compiled files (see more at Metadata Providers).
The
entitiesTs
option is used when running the app viats-node
, as the ORM needs to discover the TS files. Always specify this option if you use folder/file based discovery.
MikroORM.init({
entities: ['./dist/modules/users/entities', './dist/modules/projects/entities'],
entitiesTs: ['./src/modules/users/entities', './src/modules/projects/entities'],
// optionally you can override the base directory (defaults to `process.cwd()`)
baseDir: process.cwd(),
});
Be careful when overriding the
baseDir
with dynamic values like__dirname
, as you can end up with valid paths fromts-node
, but invalid paths fromnode
. Ideally you should keep the default ofprocess.cwd()
there to always have the same base path regardless of how you run the app.
By default, ReflectMetadataProvider
is used that leverages the reflect-metadata
. You can also use TsMorphMetadataProvider
by installing @mikro-orm/reflection
. This provider will analyse your entity source files (or .d.ts
type definition files). If you aim to use plain JavaScript instead of TypeScript, use EntitySchema
or the JavaScriptMetadataProvider
.
You can also implement your own metadata provider and use it instead. To do so, extend the
MetadataProvider
class.
import { MikroORM } from '@mikro-orm/core';
import { TsMorphMetadataProvider } from '@mikro-orm/reflection';
MikroORM.init({
metadataProvider: TsMorphMetadataProvider,
});
There are also some additional options how you can adjust the discovery process:
MikroORM.init({
discovery: {
warnWhenNoEntities: false, // by default, discovery throws when no entity is processed
requireEntitiesArray: true, // force usage of class references in `entities` instead of paths
alwaysAnalyseProperties: false, // do not analyse properties when not needed (with ts-morph)
},
});
If you disable
discovery.alwaysAnalyseProperties
option, you will need to explicitly providenullable
andwrappedReference
parameters (where applicable).
Read more about this in Metadata Providers sections.
Driver
To select driver, you can either use type
option, or provide the driver class reference.
type | driver name | dependency | note |
---|---|---|---|
mongo | MongoDriver | mongodb^3.3.4 | - |
mysql | MySqlDriver | mysql2^2.0.0 | compatible with MariaDB |
mariadb | MariaDbDriver | mariadb^2.0.0 | compatible with MySQL |
postgresql | PostgreSqlDriver | pg^7.0.0 | - |
sqlite | SqliteDriver | sqlite3^4.0.0 | - |
Driver and connection implementations are not directly exported from
@mikro-orm/core
module. You can import them from the driver packages (e.g.import { PostgreSqlDriver } from '@mikro-orm/postgresql'
).
You can pass additional options to the underlying driver (e.g.
mysql2
) viadriverOptions
. The object will be deeply merged, overriding all internally used options.
import { MySqlDriver } from '@mikro-orm/mysql';
MikroORM.init({
driver: MySqlDriver,
driverOptions: { connection: { timezone: '+02:00' } },
});
From v3.5.1 you can also set the timezone directly in the ORM configuration:
MikroORM.init({
type: 'mysql',
timezone: '+02:00',
});
Connection
Each platform (driver) provides default connection string, you can override it as a whole through clientUrl
, or partially through one of following options:
export interface ConnectionOptions {
dbName?: string;
name?: string; // for logging only (when replicas are used)
clientUrl?: string;
host?: string;
port?: number;
user?: string;
password?: string;
charset?: string;
multipleStatements?: boolean; // for mysql driver
pool?: PoolConfig; // provided by `knex`
}
Following table shows default client connection strings:
type | default connection url |
---|---|
mongo | mongodb://127.0.0.1:27017 |
mysql | mysql://root@127.0.0.1:3306 |
mariadb | mysql://root@127.0.0.1:3306 |
postgresql | postgresql://postgres@127.0.0.1:5432 |
To set up read replicas, you can use replicas
option. You can provide only those parts of the ConnectionOptions
interface, they will be used to override the master
connection options.
MikroORM.init({
type: 'mysql',
dbName: 'my_db_name',
user: 'write-user',
host: 'master.db.example.com',
port: 3306,
replicas: [
{ user: 'read-user-1', host: 'read-1.db.example.com', port: 3307 },
{ user: 'read-user-2', host: 'read-2.db.example.com', port: 3308 },
{ user: 'read-user-3', host: 'read-3.db.example.com', port: 3309 },
],
});
Read more about this in Installation and Read Connections sections.
Naming Strategy
When mapping your entities to database tables and columns, their names will be defined by naming strategy. There are 3 basic naming strategies you can choose from:
UnderscoreNamingStrategy
- default of all SQL driversMongoNamingStrategy
- default ofMongoDriver
EntityCaseNamingStrategy
- uses unchanged entity and property names
You can also define your own custom
NamingStrategy
implementation.
MikroORM.init({
namingStrategy: EntityCaseNamingStrategy,
});
Read more about this in Naming Strategy section.
Auto-join of 1:1 owners
By default, owning side of 1:1 relation will be auto-joined when you select the inverse side so we can have the reference to it. You can disable this behaviour via autoJoinOneToOneOwner
configuration toggle.
MikroORM.init({
autoJoinOneToOneOwner: false,
});
Propagation of 1:1 and m:1 owners
MikroORM defines getter and setter for every owning side of m:1 and 1:1 relation. This is then used for propagation of changes to the inverse side of bi-directional relations.
const author = new Author('n', 'e');
const book = new Book('t');
book.author = author;
console.log(author.books.contains(book)); // true
You can disable this behaviour via propagateToOneOwner
option.
MikroORM.init({
propagateToOneOwner: false,
});
Forcing UTC Timezone
Use forceUtcTimezone
option to force the Date
s to be saved in UTC in datetime columns without timezone. It works for MySQL (datetime
type) and PostgreSQL (timestamp
type). SQLite does this by default.
MikroORM.init({
forceUtcTimezone: true,
});
Mapping null
values to undefined
By default null
values from nullable database columns are hydrated as null
. Using forceUndefined
we can tell the ORM to convert those null
values to undefined
instead.
MikroORM.init({
forceUndefined: true,
});