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:
- In the root folder of your project (
./.env
) - From the same folder as the schema specified by the
--schema
argument - From the same folder as the schema taken from
"prisma": {"schema": "/path/to/schema.prisma"}
inpackage.json
- 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/.envConflicting env vars:DATABASE_URLWe 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:
Command | Schema 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/test2DATABASE_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.prismadatasource 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 variablesconsole.log(`The connection URL is ${process.env.DATABASE_URL}`)