154673f3d8
* docs: changes based on DX changes * remove fields no longer needed * remove unnecessary parameters * fixes to authenticate middleware usage * add highlight to migrations config * change configuration to http * added missing remote link docs * fix name in sidebar * added notification module docs + updated file module docs * add vale exceptions * fix vale errors * added docs on custom cli scripts
148 lines
4.5 KiB
Plaintext
148 lines
4.5 KiB
Plaintext
export const metadata = {
|
||
title: `${pageNumber} Data Models`,
|
||
}
|
||
|
||
# {metadata.title}
|
||
|
||
In this chapter, you’ll learn what data models are and how to create a data model.
|
||
|
||
## What is a Data Model?
|
||
|
||
A data model is a class that represents a table in the database. A data model is created in a module. You can then create a service that manages that data model.
|
||
|
||
Data models are based on [MikroORM](https://mikro-orm.io/docs/quick-start). So, you can use its decorators, types, and utilities when creating a model.
|
||
|
||
---
|
||
|
||
## How to Create a Data Model
|
||
|
||
<Note title="Steps Summary">
|
||
|
||
1. Create data model class in a module.
|
||
2. Generate migration for the data model.
|
||
3. Add migration scripts to the module's definition.
|
||
4. Run migration to add table for data model in the database.
|
||
|
||
</Note>
|
||
|
||
A data model is a class created in a TypeScript or JavaScript file under a module's `models` directory.
|
||
|
||
For example, create the file `src/modules/hello/models/my-custom.ts` with the following content:
|
||
|
||
```ts title="src/modules/hello/models/my-custom.ts"
|
||
import { BaseEntity } from "@medusajs/utils"
|
||
import {
|
||
Entity,
|
||
PrimaryKey,
|
||
Property,
|
||
} from "@mikro-orm/core"
|
||
|
||
@Entity()
|
||
export class MyCustom extends BaseEntity {
|
||
@PrimaryKey({ columnType: "text" })
|
||
id!: string
|
||
|
||
@Property({ columnType: "text" })
|
||
name: string
|
||
}
|
||
```
|
||
|
||
This defines a new data model `MyCustom` with the fields `id` and `name`. Data models extend the `BaseEntity` class imported from `@medusajs/utils`.
|
||
|
||
### Create a Migration
|
||
|
||
After creating the data model, you must create a migration that creates a table in your database for this data model.
|
||
|
||
A migration is a class created in a TypeScript or JavaScript file under a module's `migrations` directory. It implements an `up` and `down` method, where the `up` method reflects changes on the database, and the `down` method reverts the changes from the database.
|
||
|
||
<Details summaryContent="Generate with MikroORM">
|
||
MikroORM provides a CLI tool that helps you generate migrations. To use it:
|
||
|
||
1. Create the file `src/modules/hello/mikro-orm.config.dev.ts` with the following content:
|
||
|
||
```ts highlights={[["8", "hello", "The module's name."]]}
|
||
import path from "path"
|
||
import { TSMigrationGenerator } from "@medusajs/utils"
|
||
import { MyCustom } from "./models/my-custom"
|
||
|
||
module.exports = {
|
||
entities: [MyCustom],
|
||
schema: "public",
|
||
clientUrl: "postgres://postgres@localhost/medusa-hello",
|
||
type: "postgresql",
|
||
migrations: {
|
||
path: path.join(__dirname, "migrations"),
|
||
generator: TSMigrationGenerator,
|
||
},
|
||
}
|
||
```
|
||
|
||
2. Run the following command in the root directory of your Medusa application:
|
||
|
||
```bash
|
||
npx cross-env MIKRO_ORM_CLI=./src/modules/hello/mikro-orm.config.dev.ts mikro-orm migration:create
|
||
```
|
||
|
||
<Note title="Tip">
|
||
|
||
Add this command as a script in `package.json` for easy usage in the future. Use this command whenever you want to generate a new migration in your module.
|
||
|
||
</Note>
|
||
|
||
After running the command, a new file is created under the `src/modules/hello/migrations` directory. This file holds `up` and `down` methods that define the actions to execute when running and reverting the migration respectively.
|
||
|
||
</Details>
|
||
|
||
For example:
|
||
|
||
```ts title="src/modules/migrations/Migration20240429090012.ts"
|
||
import { Migration } from "@mikro-orm/migrations"
|
||
|
||
export class Migration20240429090012 extends Migration {
|
||
|
||
async up(): Promise<void> {
|
||
this.addSql("create table if not exists \"my_custom\" (\"id\" varchar(255) not null, \"name\" text not null, constraint \"my_custom_pkey\" primary key (\"id\"));")
|
||
}
|
||
|
||
async down(): Promise<void> {
|
||
this.addSql("drop table if exists \"my_custom\" cascade;")
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
In the `up` method, you create the table `my_custom` and define its columns. In the `down` method, you drop the table.
|
||
|
||
<Note title="Tip">
|
||
|
||
The queries performed in each of the methods use PostgreSQL syntax.
|
||
|
||
</Note>
|
||
|
||
### Run Migration
|
||
|
||
To reflect the changes in the migration, transpile your source files using the `build` command, then run the `migration` command:
|
||
|
||
```bash npm2yarn
|
||
npm run build
|
||
npx medusa migrations run
|
||
```
|
||
|
||
If ran successfully, the `my_custom` table will be created in the database.
|
||
|
||
---
|
||
|
||
## When to Use Data Models
|
||
|
||
<Note title="Use data models when" type="success">
|
||
|
||
- You want to store data related to your customization in the database.
|
||
|
||
</Note>
|
||
|
||
<Note title="Don't use data models if" type="error">
|
||
|
||
- You want to store simple key-value pairs related to an existing data model. Instead, use the `metadata` field that most existing models have, which is an object of custom key-value pairs.
|
||
|
||
</Note>
|