3.7. Data Models

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. It's created in a module.

How to Create a Data Model?#

Steps Summary
  1. Create a data model in a module.
  2. Create migration for the data model.
  3. Run migration to add the data model's table in the database.

A data model is created in a TypeScript or JavaScript file under a module's models directory. It's defined using the model utility imported from @medusajs/utils.

For example, create the file src/modules/hello/models/my-custom.ts with the following content:

1import { model } from "@medusajs/utils"2
3const MyCustom = model.define("my_custom", {4  id: model.id().primaryKey(),5  name: model.text(),6})7
8export default MyCustom

You define a data model using the model's define method. It accepts two parameters:

  1. The first one is the name of the data model's table in the database. It should be in snake-case form.
  2. The second is an object, which is the data model's schema. The schema's properties are defined using the model's methods.

The example above defines the data model MyCustom with the properties id and name.

Create a Migration#

A migration defines changes to be made in the database, such as create or update tables.

A migration is a class created in a TypeScript or JavaScript file under a module's migrations directory. It has two methods:

  • The up method reflects changes on the database.
  • The down method reverts the changes made in the up method.
Generate Migration

For example:

1import { Migration } from "@mikro-orm/migrations"2
3export class Migration20240702105919 extends Migration {4
5  async up(): Promise<void> {6    this.addSql("create table if not exists \"my_custom\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"my_custom_pkey\" primary key (\"id\"));")7  }8
9  async down(): Promise<void> {10    this.addSql("drop table if exists \"my_custom\" cascade;")11  }12

In the up method, you create the table my_custom and define its columns. In the down method, you drop the table.


The queries performed in each of the methods use PostgreSQL syntax.

Run Migration#

To reflect the changes in the migration, run the migration command:

npx medusa migrations run

If ran successfully, the my_custom table will be created in the database.

When to Use Data Models#

Use data models when
  • You want to store data related to your customization in the database.
Don't use data models if
  • 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.
Was this chapter helpful?