Skip to main content

.env files

Prisma ORM 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 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.

warning

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
DATABASE_URL=postgresql://test:test@localhost:5432/test
DATABASE_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 ORM.

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
DATABASE_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 ORM.

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 db pull), the Prisma CLI automatically loads the DATABASE_URL environment variables from the .env file and makes it available to the CLI.