> Fetch the complete documentation index at: https://wasp.sh/llms.txt
---

# Entities

Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.

Wasp uses the excellent [Prisma ORM](https://www.prisma.io/) to implement all database functionality and occasionally enhances it with a thin abstraction layer. This means that you use the `schema.prisma` file to define your database models and relationships. Wasp understands the Prisma schema file and picks up all the models you define there. You can read more about this in the [Prisma Schema File](https://wasp.sh/docs/data-model/prisma-file) section of the docs.

In your project, you'll find a `schema.prisma` file in the root directory:

```
.
├── main.wasp.ts
...
├── package.json
├── public
├── schema.prisma
├── src
├── tsconfig.json
├── tsconfig.src.json
├── tsconfig.wasp.json
└── vite.config.ts
```

Prisma uses the *Prisma Schema Language*, a simple definition language explicitly created for defining models. The language is declarative and very intuitive. We'll also go through an example later in the text, so there's no need to go and thoroughly learn it right away. Still, if you're curious, look no further than Prisma's official documentation:

- [Basic intro and examples](https://www.prisma.io/docs/orm/prisma-schema/overview)
- [A more exhaustive language specification](https://www.prisma.io/docs/orm/reference/prisma-schema-reference)

## Defining an Entity

A Prisma `model` declaration in the `schema.prisma` file represents a Wasp Entity.

Entity vs Model

You might wonder why we distinguish between a **Wasp Entity** and a **Prisma model** if they're essentially the same thing right now.

While defining a Prisma model is currently the only way to create an Entity in Wasp, the Entity concept is a higher-level abstraction. We plan to expand on Entities in the future, both in terms of how you can define them and what you can do with them.

So, think of an Entity as a Wasp concept and a model as a Prisma concept. For now, all Prisma models are Entities and vice versa, but this relationship might evolve as Wasp grows.

Here's how you could define an Entity that represents a Task:

```prisma title="schema.prisma"
model Task {
  id          String  @id @default(uuid())
  description String
  isDone      Boolean @default(false)
}
```

The above Prisma `model` definition tells Wasp to create a table for storing Tasks where each task has three fields (i.e., the `tasks` table has three columns):

- `id` - A string value serving as a primary key. The database automatically generates it by generating a random unique ID.
- `description` - A string value for storing the task's description.
- `isDone` - A boolean value indicating the task's completion status. If you don't set it when creating a new task, the database sets it to `false` by default.

Wasp also exposes a type for working with the created Entity. You can import and use it like this:

```ts
import { Task } from "wasp/entities"

const task: Task = { ... }

// You can also define functions for working with entities
function getInfoMessage(task: Task): string {
  const isDoneText = task.isDone ? "is done" : "is not done"
  return `Task '${task.description}' is ${isDoneText}.`
}
```

Using the `Task` type in `getInfoMessage`'s definition connects the argument's type with the `Task` entity.

This coupling removes duplication and ensures the function keeps the correct signature even if you change the entity. Of course, the function might throw type errors depending on how you change it, but that's precisely what you want!

Entity types are available everywhere, including the client code:

```ts
import { Task } from "wasp/entities"

export function ExamplePage() {
  const task: Task = {
    id: "some-uuid-1234",
    description: "Some random task",
    isDone: false,
  }
  return <div>{task.description}</div>
}
```

The mentioned type safety mechanisms also apply here: changing the task entity in our `schema.prisma` file changes the imported type, which might throw a type error and warn us that our task definition is outdated.

You'll learn even more about Entity types when you start using [them with operations](#using-entities-in-operations).

### Working with Entities

Let's see how you can define and work with Wasp Entities:

1. Create/update some Entities in the `schema.prisma` file.
2. Run `wasp db migrate-dev`. This command syncs the database model with the Entity definitions the `schema.prisma` file. It does this by creating migration scripts.
3. Migration scripts are automatically placed in the `migrations/` folder. Make sure to commit this folder into version control.
4. Use Wasp's JavaScript API to work with the database when implementing Operations (we'll cover this in detail when we talk about [operations](https://wasp.sh/docs/data-model/operations/overview)).

#### Using Entities in Operations

Most of the time, you will be working with Entities within the context of [Operations (Queries & Actions)](https://wasp.sh/docs/data-model/operations/overview). We'll see how that's done on the next page.

#### Using Entities directly

If you need more control, you can directly interact with Entities by importing and using the [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client/crud). We recommend sticking with conventional Wasp-provided mechanisms, only resorting to directly using the Prisma client only if you need a feature Wasp doesn't provide.

You can only use the Prisma Client in your Wasp server code. You can import it like this:

```ts
import { prisma } from "wasp/server"

prisma.task.create({
    description: "Read the Entities doc",
    isDone: true // almost :)
})
```

:::note[Available Prisma features in the client]
While the Prisma Client is not available in your client code, you can still import Prisma there, for accessing type definitions (notably, `enum`s).

You can see more information in the overview of [supported Prisma Schema features](https://wasp.sh/docs/data-model/prisma-file#the-enum-blocks).
:::

### Next steps

Now that we've seen how to define Entities that represent Wasp's core data model, we'll see how to make the most of them in other parts of Wasp. Keep reading to learn all about Wasp Operations!