Prisma Schema Guide

A Comprehensive Guide to the Prisma Schema Language

This interactive guide will walk you through the entire Prisma Schema Language (PSL). Prisma is a next-generation ORM that makes database access easy with an intuitive data model. At its core is the PSL, a declarative language used to define your database schema and data models. This single file becomes the source of truth for your database structure and your application's models. Use the navigation on the left to explore the core concepts.

1. Prisma Schema Fundamentals

A schema.prisma file is composed of three main building blocks: datasource, generator, and model. These blocks work together to configure your database connection, specify what code to generate, and define your application's data structures. Explore the cards below to understand each component.

// schema.prisma

// 1. Datasource: Specifies your database connection.
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// 2. Generator: Specifies what clients to generate.
generator client {
  provider = "prisma-client-js"
}

// 3. Data Model: Defines your application models.
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

2. Defining Models

A model is defined using the model keyword, followed by its name. Inside, you define the model's fields using a name, a type, and optional attributes and type modifiers. This section covers the essential types you can use to build your models.

Scalar Types

Prisma supports a set of scalar types that map to the underlying database types. These are the fundamental building blocks for your model fields.

Enums & Type Modifiers

You can further refine your model fields using enums to restrict values and type modifiers to indicate optionality or lists.

enum Role {
  USER
  ADMIN
}

model User {
  id   Int  @id
  role Role @default(USER)
}

model Post {
  id   Int      @id
  bio  String?  // Optional field
  tags String[] // List of strings
}

3. Attributes

Attributes modify the behavior of fields or entire model blocks. Field attributes start with @ and apply to a single field. Block attributes start with @@ and apply to the whole model, often referencing multiple fields to define composite keys or indexes.

Field Attributes (@)

These are applied to a single field to define its behavior, such as making it a primary key, setting a default value, or ensuring its values are unique.

• @id: Marks a field as the primary key.
• @default(...): Specifies a default value. Examples: autoincrement(), uuid(), now().
• @unique: Enforces a unique constraint on the field.
• @updatedAt: Automatically updates a DateTime field on record updates.
• @relation(...): Defines a relationship.
• @map(...): Maps a field to a different database column name.
• @db.*: Specifies a native database type.

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  firstName String   @map("first_name")
}

Block Attributes (@@)

These are applied at the model level and are essential for defining constraints or indexes that span multiple fields.

• @@id([...]): Defines a composite (multi-field) primary key.
• @@unique([...]): Defines a composite unique constraint.
• @@index([...]): Defines a database index on one or more fields.
• @@map(...): Maps the model to a different database table name.

model UserProfile {
  userId    Int
  photoUrl  String
  firstName String
  lastName  String

  @@id([userId, photoUrl])
  @@unique([firstName, lastName])
  @@index([userId])
  @@map("user_profiles")
}

4. Visualizing Relations

Relations define how models are connected. A clear understanding of relationships is fundamental to good data modeling. Use the tabs below to explore visual diagrams and the corresponding Prisma schema for each major relation type.

model User {
  id      Int      @id @default(autoincrement())
  profile Profile?
}

model Profile {
  id     Int    @id @default(autoincrement())
  bio    String
  user   User   @relation(fields: [userId], references: [id])
  userId Int    @unique // The @unique is crucial for 1-1
}

model User {
  id    Int    @id @default(autoincrement())
  posts Post[] // Relation field is a list
}

model Post {
  id        Int    @id @default(autoincrement())
  title     String
  author    User   @relation(fields: [authorId], references: [id])
  authorId  Int    // Foreign key
}

model Post {
  id         Int        @id @default(autoincrement())
  title      String
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  name  String
  posts Post[]
}

// A user can follow many other users,
// and can be followed by many other users.
model User {
  id          Int      @id @default(autoincrement())
  name        String
  followedBy  User[]   @relation("UserFollows")
  following   User[]   @relation("UserFollows")
}

5. Native Database Types

While Prisma's scalar types provide a convenient abstraction, you sometimes need to use a specific data type from your database (e.g., VARCHAR(255) instead of the generic String). You can do this with the @db.* attribute. Select a database provider below to see some common examples.

6. Integrating Prisma with Express.js

This guide provides a step-by-step walkthrough for setting up a new Node.js project with Express and Prisma. Follow the steps in the accordion below to build a simple API that can create and retrieve users from your database.

7. Helpful Resources

The Prisma ecosystem is well-documented. For more in-depth information, advanced topics, and API references, check out the official resources below.