Environment variables

An environment variable is a key value pair of string data that is stored on your machine's local environment. Refer to our Environment variables reference documentation for specific details.

Typically the name of the variable is uppercase, this is then followed by an equals sign then the value of the variable:

MY_VALUE=prisma

The environment variable belongs to the environment where a process is running.

Taking the TEMP environment variable as an example, one can query its value to find where to store temporary files. This is a system environment variable and can be queried by any process or application running on the machine.

How does Prisma use environment variables?

Prisma always reads environment variables from the system's environment.

When you initialize Prisma in your project with prisma init, it creates a convenience .env file for you to set your connection url as an environment variable. When you use Prisma CLI or Prisma Client, the .env file content and the variables defined in it are added to the process.env object, where Prisma can read it and use it.

Looking to use more than one .env file? See Using multiple .env files for information on how to setup and use multiple .env files in your application.

Using .env files

Prisma creates a default .env file at your projects root. You can choose to replace this file or create a new one in the prisma folder, or if you choose to relocate your schema.prisma file, alongside that.

.env file locations

The Prisma CLI looks for .env files, in order, in the following locations:

  1. In the root folder of your project (./.env)
  2. From the same folder as the schema specified by the --schema argument
  3. From the same folder as the schema taken from "prisma": {"schema": "/path/to/schema.prisma"} in package.json
  4. From the ./prisma folder

If a .env file is located in step #1, but additional, clashing .env variables are located in steps #2 - 4, the CLI will throw an error. For example, if you specify a DATABASE_URL variable in two different .env files, you will get the following error:

Error: There is a conflict between env vars in .env and prisma/.env
Conflicting env vars:
DATABASE_URL
We suggest to move the contents of prisma/.env to .env to consolidate your env vars.

The following table describes where the Prisma CLI looks for the .env file:

CommandSchema file location.env file locations checked, in order
prisma [command]./prisma/schema.prisma./.env
./prisma/.env
prisma [command] --schema=./a/b/schema.prisma./a/b/schema.prisma./.env
./a/b/.env
./prisma/.env
prisma [command]"prisma": {"schema": "/path/to/schema.prisma"}.env
./path/to/schema/.env
./prisma/.env
prisma [command]No schema (for example, when running prisma db pull in an empty directory)./.env
./prisma/.env

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

Do not commit your .env files into version control!

Refer to the dotenv documentation for information about what happens if an environment variable is defined in two places.

Expanding variables

Variables stored in .env files can be expanded using the format specified by dotenv-expand.

.env
1DATABASE_URL=postgresql://test:test@localhost:5432/test
2DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=public

This will make the environment variable DATABASE_URL_WITH_SCHEMA with value postgresql://test:test@localhost:5432/test?schema=public available for Prisma.

You can also use environment variables in the expansion that are set outside of the .env file, for example a database URL that is set on a PaaS like Heroku or similar:

$# environment variable already set in the environment of the system
$export DATABASE_URL=postgresql://test:test@localhost:5432/test
.env
1DATABASE_URL_WITH_SCHEMA=${DATABASE_URL}?schema=foo

This will make the environment variable DATABASE_URL_WITH_SCHEMA with value postgresql://test:test@localhost:5432/test?schema=foo available for Prisma.

Example: Set the DATABASE_URL environment variable in an .env file

It is common to load your database connection URL from an environment variable:

// schema.prisma
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}

You can set the DATABASE_URL in your .env file:

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

When you run a command that needs access to the database defined via the datasource block (for example, prisma db pull), the Prisma CLI automatically loads the DATABASE_URL environment variables from the .env file and makes it available to the CLI.

Using environment variables in your code

If you want environment variables to be evaluated at runtime, you need to load them manually in your application code (for example, by using dotenv):

import * as dotenv from 'dotenv'
dotenv.config() // Load the environment variables
console.log(`The connection URL is ${process.env.DATABASE_URL}`)
Edit this page on GitHub