The data model definition part of the Prisma schema defines your application models (also called Prisma models). Models:

  • Represent the entities of your application domain
  • Map to the tables in your database
  • Form the foundation of the queries available in the generated Prisma Client API
  • When used with TypeScript, Prisma Client provides generated type definitions for your models and any variations of them to make database access entirely type safe.

The following schema describes a blogging platform - the data model definition is highlighted:

datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
generator client {
provider = "prisma-client-js"
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
role Role @default(USER)
posts Post[]
profile Profile?
}
model Profile {
id Int @id @default(autoincrement())
bio String
user User @relation(fields: [userId], references: [id])
userId Int
}
model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId Int
categories Category[] @relation(references: [id])
}
model Category {
id Int @id @default(autoincrement())
name String
posts Post[] @relation(references: [id])
}
enum Role {
USER
ADMIN
}

The data model definition is made up of:

The corresponding database looks like this:

sample database

  • In PostgreSQL, a model maps to a table
  • In MySQL, a model maps to a table
  • In SQLite, a model maps to a table

Note: In the future there might be connectors for non-relational databases and other data sources. For example, for MongoDB a model would map to a collection, for a REST API it would map to a resource.

The following example uses the Prisma Client generated from this model to create a User record and three nested Post records, each with one or two nested Category records:

Query Example
Copy-Paste Example
const user = await prisma.user.create({
data: {
email: "ariadne@prisma.io",
name: "Ariadne",
posts: {
create: [
{
title: "My first day at Prisma",
categories: {
create: {
name: "Office",
},
},
},
{
title: "How to connect to a SQLite database",
categories: {
create: [{ name: "Databases" }, { name: "Tutorials" }],
},
},
],
},
},
});

Your data model reflects your application domain. For example:

  • In an e-commerce application you probably have models like Customer, Order, Item and Invoice.
  • In a social media application you probably have models like User, Post, Photo and Message.

Introspection and migration

There are two ways to define a data model:

  • Write the model manually and use Prisma Migrate: You can write your data model manually and map it to your database using Prisma Migrate (experimental). In this case, the data model is the single source of truth for the models of your application.
  • Generate the model via introspection: When you have an existing database or prefer migrating your database schema with SQL, you generate the data model by introspecting your database. In this case, the database schema is the single source of truth for the models of your application.

Note: Since Prisma Migrate is currently in an experimental state, the officially recommended way for using Prisma is the introspection-based approach.

Defining models

Models represent the entities of your application domain. Models are represented by model blocks and define a number of fields. In the example data model, User, Profile, Post and Category are models.

A blogging platform can be extended with the following models:

model Comment {
// Fields
}
model Tag {
// Fields
}

Mapping model names to tables

Prisma model naming conventions (singular form, PascalCase) do not always match table names in the database. A common approach for naming tables in databases is to use plural form and snake_case notation - for example: comments. When you introspect a database with a table named comments, the result Prisma model will look like this:

model comments {
// Fields
}

However, you can still adhere to the naming convention without renaming the underlying comments table in the database by using the @@map attribute:

model Comment {
// Fields
@@map(name: "comments")
}

With this model definition, Prisma automatically maps the Comment model to the comments table in the underlying database.

Note: You can also @map a column name or enum value, and @@map an enum.

@map and @@map allow you to tune the shape of your Prisma Client API by decoupling model and field names from table and column names in the underlying database.

Defining fields

The properties of a model are called fields. Fields map to columns and consist of:

The following table describes User model's fields from the sample schema:

NameTypeScalar vs RelationType modifierAttributes
idIntScalar-@id and @default(autoincrement())
emailStringScalar-@unique
nameStringScalar?-
roleRoleScalar (enum)-@default(USER)
postsPostRelation (Prisma-level field)?-
profileProfileRelation (Prisma-level field)[]-

Field types

A field's type determines its structure, and fits into one of two categories:

Scalar fields

The following example extends the Comment and Tag models with several scalar types. Some fields include attributes:

model Comment {
id Int @id @default(autoincrement())
title String
content String
}
model Tag {
name String @id
}

See complete list of scalar field types .

Unsupported types

When you introspect a database, unsupported types are commented out:

// This type is currently not supported
// mydata geometric?

Follow topic:native database types and topic:types for information about type support.

Relation fields

A relation field's type is another model - for example, a post (Post) can have multiple comments (Comment[]):

model Post {
id Int @id @default(autoincrement())
// Other fields
comments Comment[] // A post can have many comments
}
model Comment {
id Int
// Other fields
Post Post? @relation(fields: [postId], references: [id]) // A comment can have one post
postId Int?
}

Refer to the relations documentation for more examples and information about relationships between models.

Type modifiers

The type of a field can be modified by appending either of two modifiers:

  • [] Make a field a list
  • ? Make a field optional

Note: You cannot combine type modifiers - optional lists are not supported.

Lists

The following example includes a scalar list and a list of related models:

model Post {
id Int @id @default(autoincrement())
// Other fields
comments Comment[] // A list of comments
keywords String[] // A scalar list
}

Note: Scalar lists are only supported if the underlying database supports scalar lists.

Optional and mandatory fields

model Comment {
id Int @id @default(autoincrement())
title String
content? String
}
model Tag {
name String @id
}

When not annotating a field with the ? type modifier, the field will be required on every record of the model. This has effects on two levels:

  • Database: Required fields are represented via NOT NULL constraints in the underlying database.
  • Prisma Client: Prisma Client's generated TypeScript types that represent the models in your application code will also define these fields as required to ensure they always carry values at runtime.

Defining attributes

Attributes modify the behavior of fields or model blocks. The following example includes two field attributes (@unique and @default) and one block attribute (@@id):

model User {
firstName String
lastName String
email String @unique
isAdmin Boolean @default(false) // @default(value: false)
@@id([firstName, lastName])
}

Some attributes accept arguments - for example, @default accepts true or false:

isAdmin Boolean @default(false) // short form of @default(value: false)

See complete list of field and block attributes

Defining an ID field

An ID uniquely identifies individual records of a model. IDs can be defined by a single field using the @id attribute, or multiple fields using the @@id attribute.

In the following example, the User ID is represented by the id field:

model User {
id Int @id @default(autoincrement())
email String @unique
name String?
role Role @default(USER)
posts Post[]
profile Profile?
}

In the following example, the User ID is represented by a combination of the firstName and lastName fields:

model User {
firstName String
lastName String
email String @unique
isAdmin Boolean @default(false)
@@id([firstName, lastName])
}

Note: A model can only have one ID, and that ID can either be a single field or based on multiple fields.

Defining a unique field

You can add unique attributes to your models to be able to uniquely identify individual records of that model. Unique attributes can be defined on a single field using @unique attribute, or on multiple fields (also called composite or compound unique constraints) using the @@unique attribute.

In the following example, the value of the email field must be unique:

model User {
email String @unique // `email` can not be optional because it's the only unique field on the model
name String?
}

In the following example, a combination of authorId and title must be unique:

model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId Int
categories Category[] @relation(references: [id])
@@unique([authorId, title])
}

Defining a default value

You can define default values for scalar fields of your models using the @default attribute:

model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId Int
categories Category[] @relation(references: [id])
}

@default attributes typically represent DEFAULT values in the underlying database. However, functions like cuid() and uuid() are provided by Prisma's query engine and are therefore not "visible" in the underlying database schema.

Default values can be:

  • Static values that correspond to the field type, such as 5 (Int), Hello (String), or false (Boolean)
  • Functions, such as now() or uuid()

Defining an index

You can define indexes on one or multiple fields of your models via the @@index on a model. The following example defines a multi-column index based on the title and content field:

model Post {
id Int @id @default(autoincrement())
title String
content String?
@@index([title, content])
}

Defining enums

You can define enums in your data model if they're supported by the data source you use.

Enums are considered scalar types in the Prisma data model. They're therefore by default included as return values in Prisma Client queries.

Enums are defined via the enum block. For example, a User has a Role:

model User {
id Int @id @default(autoincrement())
email String @unique
name String?
role Role @default(USER)
}
enum Role {
USER
ADMIN
}

Using functions

The Prisma schema supports a number of functions . These can be used to specify default values on fields of a model.

For example, the default value of createdAt is now() :

model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
}

cuid() and uuid() are implemented by Prisma and therefore are not "visible" in the underlying database schema. You can still use them when using introspection by manually changing your Prisma schema and generating Prisma Client, in that case the values will be generated by Prisma's query engine

autoincrement(), now and dbgenerated() are always "implemented" on the database-level, meaning they manifest in the database schema and can be recognized through introspection.

Relations

Refer to the relations documentation for more examples and information about relationships between models.

Models in Prisma Client

Queries (CRUD)

Every model in the data model definition will result in a number of CRUD queries in the generated Prisma Client API:

  • findMany
  • findOne
  • create
  • update
  • upsert
  • delete
  • updateMany
  • deleteMany

The operations are accessible via a generated property on the Prisma Client instance. By default the name of the property is the lowercase form of the model name, e.g. user for a User model or post for a Post model.

Here is an example illustrating the use of a user property from the Prisma Client API:

const newUser = await prisma.user.create({
data: {
name: 'Alice',
},
})
const allUsers = await prisma.user.findMany()

Type definitions

Prisma Client not only provides a query API for models, it also generates type definitions that reflect your model structures. These are part of the generated @prisma/client node module in a file called index.d.ts.

When using TypeScript, these type definitions ensure that all your database queries are entirely type safe and validated at compile-time (even partial queries using select or include).

Even when using plain JavaScript, the type definitions are still included in the @prisma/client node module, enabling features like IntelliSense/autocompletion in your editor.

Note: The actual types are stored in the .prisma/client folder. @prisma/client/index.d.ts exports the contents of this folder.

For example, the type definition for the User model from above would look as follows:

export type User = {
id: number
email: string
name: string | null
role: string
}

Note that the relation fields posts and profile are not included in the type definition by default. However, if you need variations of the User type you can still define them using some of Prisma Client's generated helper types (in this case, these helper types would be called UserGetIncludePayload and UserGetSelectPayload).

Edit this page on Github