Overview

The Prisma schema file (short: schema file, Prisma schema or schema) is the main configuration file for your Prisma setup. It is typically called schema.prisma and consists of the following parts:

  • Data sources: Specify the details of the data sources Prisma should connect to (e.g. a PostgreSQL database)
  • Generators: Specifies what clients should be generated based on the data model (e.g. Prisma Client)
  • Data model definition: Specifies your application models (the shape of the data per data source) and their relations

Whenever a prisma command is invoked, the CLI typically reads some information from the schema file, e.g.:

  • prisma generate: Reads all above mentioned information from the Prisma schema to generate the correct data source client code (e.g. Prisma Client).
  • prisma migrate save --experimental: Reads the data sources and data model definition to create a new migration.

You can also use environment variables inside the schema file to provide configuration options when a CLI command is invoked.

Example

Here is an example for a Prisma schema file that specifies a data source (PostgreSQL), a generator (Prisma Client) and a data model definition with two models (with one relation) and one enum:

1datasource postgresql {
2 url = env("DATABASE_URL")
3 provider = "postgresql"
4}
5
6generator client {
7 provider = "prisma-client-js"
8}
9
10model User {
11 id Int @id @default(autoincrement())
12 createdAt DateTime @default(now())
13 email String @unique
14 name String?
15 role Role @default(USER)
16 posts Post[]
17}
18
19model Post {
20 id Int @id @default(autoincrement())
21 createdAt DateTime @default(now())
22 updatedAt DateTime @updatedAt
23 published Boolean @default(false)
24 title String
25 author User? @relation(fields: [authorId], references: [id])
26 authorId Int?
27}
28
29enum Role {
30 USER
31 ADMIN
32}

Naming

The default name for the schema file is schema.prisma. When your schema file is named like this, the Prisma CLI will detect it automatically in the directory where you invoke the CLI command (or any of its subdirectories).

If the file is named differently, you can provide the --schema argument to the Prisma CLI with the path to the schema file, e.g.:

1prisma generate --schema ./database/myschema.prisma

Syntax

The schema file is written in Prisma Schema Language (PSL). You can find a full reference for PSL in the spec.

VS Code

Syntax highlighting for PSL is available via a VS Code extension (which also lets you auto-format the contents of your Prisma schema and indicates syntax errors with red squiggly lines). Learn more about setting up Prisma in your editor.

GitHub

PSL code snippets on GitHub can be rendered with syntax highlighting as well by using the .prisma file extension or annotating fenced code blocks in Markdown with prisma:

1```prisma
2model User {
3 id Int @id @default(autoincrement())
4 createdAt DateTime @default(now())
5 email String @unique
6 name String?
7}
8```

Using environment variables

You can use environment variables to provide configuration options when a CLI command is invoked. This can e.g. be helpful in order to:

  • Keep secrets out of the schema file
  • Improve portability of the schema file

Defining environment variables with the env function

Environment variables can be accessed using the env function:

1datasource postgresql {
2 provider = "postgresql"
3 url = env("DATABASE_URL")
4}

There are a few limitations with env at the moment:

  • It is not possible to use string concat operations (e.g. to construct your database connection string).
  • It is not possible to use environment variables for the provider argument in datasource and generator definitions.

Using .env files

For many developer tools, it has become a good practice to define environment variables using .env files.

Prisma provides native support for .env files if the .env file is located in the same directory as your Prisma schema file:

1.
2└── prisma
3 ├── .env
4 └── schema.prisma

This means any environment variables defined in that .env file will automatically be loaded when running a Prisma CLI command.

WARNING: Do not commit your .env files into version control.

For example, it is a common scenario to set your database connection URL via an environment variable:

1// schema.prisma
2datasource db {
3 provider = "postgresql"
4 url = env("DATABASE_URL")
5}

This requires the DATABASE_URL to be set in your .env file:

1# .env
2DATABASE_URL=postgresql://test:test@localhost:5432/test?schema=public

When running any command that needs to access the database defined via the datasource block (e.g. prisma introspect), the Prisma CLI automatically loads the DATABASE_URL environment variables from the .env file and makes it available to the CLI.

If you want environment variables to be evaluated at runtime, you need to load them manually in your application code, e.g. using dotenv:

1import * as dotenv from 'dotenv'
2
3dotenv.config() // load the environment variables
4console.log(`The connection URL is ${process.env.DATABASE_URL}`)

Use multiple .env files or .env files outside the prisma folder

To use multiple .env files:

  1. Install dotenv-cli:

    1npm install -g dotenv-cli
  2. Create a file - for example, .env3 - in your project's root folder.

  3. To use the .env3 file, you can either:

    • Include a reference to dotenv at the top of your project's entry file.
    1import { config } from 'dotenv'
    2config({ path: '.env3' })
    • Use dotenv when you run any Prisma command and specify which .env file to use. The following example uses a file named .env3:
    1dotenv -e .env3 npx prisma introspect

Comments

There are two types of comments that are supported in the schema file:

  • // comment: This comment is for the reader's clarity and is not present in the abstract syntax tree (AST) of the schema file.
  • /// comment: These comments will show up in the abstract syntax tree (AST) of the schema file, either as descriptions to AST nodes or as free-floating comments. Tools can then use these comments to provide additional information.

Here are some different examples:

1 /// This comment will get attached to the `User` node in the AST
2 model User {
3 /// This comment will get attached to the `id` node in the AST
4 id Int @default(autoincrement())
5 // This comment is just for you
6 weight Float /// This comment gets attached to the `weight` node
7 }
8
9 // This comment is just for you. It will not
10 // show up in the AST.
11
12 /// This is a free-floating comment that will show up
13 /// in the AST as a `Comment` node, but is not attached
14 /// to any other node. We can use these for documentation
15 /// in the same way that godoc.org works.
16
17 model Customer {}

Auto formatting

Similar to tools like gofmt and prettier, PSL syntax ships with a formatter for .prisma files. The formatter can be enabled in the VS Code extension.

Like gofmt and unlike prettier, there are no options for configuration here. There is exactly one way to format a prisma file.

Learn more about the formatting rules in the spec.

In this section

Edit this page on Github