medusa-store/docs/content/development/entities/create.mdx

---
description: 'Learn how to create an entity in Medusa. This guide also explains how to create a repository and access and delete the entity.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# How to Create an Entity

In this document, you’ll learn how you can create a custom [Entity](./overview.mdx).

## 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`:

```ts title=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](https://typeorm.io/entities).

### Soft-Deletable Entities

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

```ts
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](https://typeorm.io/relations).

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`:

<Tabs groupId="files" isCodeTabs={true}>
<TabItem value="post" label="src/models/post.ts" default>

```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")
  }
}
```

</TabItem>
<TabItem value="author" label="src/services/author.ts">

```ts
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")
  }
}
```

</TabItem>
</Tabs>

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](./migrations/create.md).

---

## 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](./repositories.md) 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:

```bash npm2yarn
npm run build
```

Then, run the `migration` command:

```bash
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](https://typeorm.io/entities).

---

## See Also

- [How to use repositories](./repositories.md)
- [Extend an entity](./extend-entity.md)
- [Create a plugin](../plugins/create.mdx)