Environment variables

An environment variable is a key value pair of string data stored on your machine's local environment.

Traditionally 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 install Prisma for the first time 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 there are put into the system's environment, 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 prisma.schema 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 introspect 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 can be expanded using the format specified by dotenv-expand. This is useful when dealing with PaaS or similar products. such as Heroku):

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

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
DATABASE_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 introspect), 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