How to Create an Entity

In this document, you’ll learn how you can create a custom Entity.

Step 1: Create the Entity

To create an entity, create a TypeScript file in src/models. For example, here’s a Post entity defined in the file src/models/post.ts:

src/models/post.ts

import { 
  BeforeInsert, 
  Column, 
  Entity, 
  PrimaryColumn,
} from "typeorm"
import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"

@Entity()
export class Post extends BaseEntity {
  @Column({ type: "varchar" })
  title: string | null

  @BeforeInsert()
  private beforeInsert(): void {
    this.id = generateEntityId(this.id, "post")
  }
}

This entity has one column title defined. However, since it extends BaseEntity it will also have the id, created_at, and updated_at columns.

Medusa’s core entities all have the following format for IDs: <PREFIX>_<RANDOM>. For example, an order might have the ID order_01G35WVGY4D1JCA4TPGVXPGCQM.

To generate an ID for your entity that matches the IDs generated for Medusa’s core entities, you should add a BeforeInsert event handler. Then, inside that handler use Medusa’s utility function generateEntityId to generate the ID. It accepts the ID as a first parameter and the prefix as a second parameter. The Post entity IDs will be of the format post_<RANDOM>.

You can learn more about what decorators and column types you can use in Typeorm’s documentation.

Soft-Deletable Entities

If you want the entity to also be soft deletable then it should extend SoftDeletableEntity instead:

import { SoftDeletableEntity } from "@medusajs/medusa"

@Entity()
export class Post extends SoftDeletableEntity {
  // ...
}

Adding Relations

Your entity may be related to another entity. You can showcase the relation with Typeorm's relation decorators.

For example, you can create another entity Author and add a ManyToOne relation to it from the Post, and a OneToMany relation from the Author to the Post:

src/models/post.ts
src/services/author.ts

import { 
  BeforeInsert, 
  Column, 
  Entity,
  JoinColumn,
  ManyToOne, 
} from "typeorm"
import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"
import { Author } from "./author"

@Entity()
export class Post extends BaseEntity {
  @Column({ type: "varchar" })
  title: string | null

  @Column({ type: "varchar" })
  author_id: string

  @ManyToOne(() => Author, (author) => author.posts)
  @JoinColumn({ name: "author_id" })
  author: Author

  @BeforeInsert()
  private beforeInsert(): void {
    this.id = generateEntityId(this.id, "post")
  }
}

import { BaseEntity, generateEntityId } from "@medusajs/medusa"
import { 
  BeforeInsert,
  Column,
  Entity,
  OneToMany,
} from "typeorm"
import { Post } from "./post"

@Entity()
export class Author extends BaseEntity {
  @Column({ type: "varchar" })
  name: string

  @Column({ type: "varchar", nullable: true })
  image?: string

  @OneToMany(() => Post, (post) => post.author)
  posts: Post[]

  @BeforeInsert()
  private beforeInsert(): void {
    this.id = generateEntityId(this.id, "auth")
  }
}

Adding these relations allows you to later on expand these relations when retrieving records of this entity with repositories.

Step 2: Create a Migration

Additionally, you must create a migration for your entity. Migrations are used to update the database schema with new tables or changes to existing tables.

You can learn more about Migrations, how to create or generate them, and how to run them in the Migration documentation.

Step 3: Create a Repository

An repository is required for every entity you create. They provide methods to access and modify an entity's records, and they're used by other resources such as services or endpoints to perform those functionalities.

To learn how to create a repository, refer to the Repositories documentation.

(Optional) Step 4: Run Migrations

Before you start using your entity, make sure to run the migrations that reflect the entity on your database schema. If you've already ran migrations, you can skip this step.

To run migrations, run the build command that transpiles your code:

npm
Yarn
pnpm

npm run build

yarn build

pnpm run build

Then, run the migration command:

npx medusa migrations run

You should see that your migration have executed.

Advanced Entity Definitions

With entities, you can create relationships, index keys, and more. As Medusa uses Typeorm, you can learn about using these functionalities through Typeorm's documentation.

How to Create an Entity

Step 1: Create the Entity​

Soft-Deletable Entities​

Adding Relations​

Step 2: Create a Migration​

Step 3: Create a Repository​

(Optional) Step 4: Run Migrations​

Advanced Entity Definitions​

See Also​