Environment variables

Environment variables are project configuration that gets injected into your deployments. You scope each one to production, to preview, or to a single preview branch. This is also how you connect your app to a database: set its connection string as a variable like DATABASE_URL.

There are three layers:

1. Production variables: used by production deploys.
2. Preview variables: used by every preview deploy.
3. Branch overrides: replace a preview value for one specific branch.

How a deploy composes its environment variablesStep 1 of 3

Your default branch deploys as production, and resolves to the production variables only. Nothing else is mixed in.

A preview deploy gets the preview variables, with any branch overrides layered on top. Overrides help when one branch needs a different API key, database URL, or feature flag than the rest.

Values are resolved at deploy time and baked into the deployment. Changing a variable doesn't touch deployments that already exist and doesn't trigger a redeploy. The new value applies the next time you deploy.

Pass KEY=value and a role or branch:

bunx prisma project env add DATABASE_URL=postgresql://example --role production

bunx prisma project env add DATABASE_URL=postgresql://preview --role preview

bunx prisma project env add FEATURE_FLAG=enabled --branch feature/search

pnpm prisma project env add DATABASE_URL=postgresql://example --role production
pnpm prisma project env add DATABASE_URL=postgresql://preview --role preview
pnpm prisma project env add FEATURE_FLAG=enabled --branch feature/search

yarn prisma project env add DATABASE_URL=postgresql://example --role production
yarn prisma project env add DATABASE_URL=postgresql://preview --role preview
yarn prisma project env add FEATURE_FLAG=enabled --branch feature/search

npx prisma project env add DATABASE_URL=postgresql://example --role production
npx prisma project env add DATABASE_URL=postgresql://preview --role preview
npx prisma project env add FEATURE_FLAG=enabled --branch feature/search

To keep a secret out of your shell history, pass just the key and let the CLI read it from your environment:

DATABASE_URL=postgresql://example npx prisma project env add DATABASE_URL --role production

To import many variables at once, pass a dotenv file with --file instead of a KEY=value argument (one or the other, not both). It works for add and update:

bunx prisma project env add --file .env.production --role production

pnpm prisma project env add --file .env.production --role production

yarn prisma project env add --file .env.production --role production

npx prisma project env add --file .env.production --role production

To give your app a database, set its connection string per scope, then redeploy. Use a different database per scope if you want preview deployments isolated from production data.

bunx prisma project env list --role production

bunx prisma project env list --branch feature/search

bunx prisma project env update DATABASE_URL=postgresql://new --role production

bunx prisma project env delete DATABASE_URL --role preview

pnpm prisma project env list --role production
pnpm prisma project env list --branch feature/search
pnpm prisma project env update DATABASE_URL=postgresql://new --role production
pnpm prisma project env delete DATABASE_URL --role preview

yarn prisma project env list --role production
yarn prisma project env list --branch feature/search
yarn prisma project env update DATABASE_URL=postgresql://new --role production
yarn prisma project env delete DATABASE_URL --role preview

npx prisma project env list --role production
npx prisma project env list --branch feature/search
npx prisma project env update DATABASE_URL=postgresql://new --role production
npx prisma project env delete DATABASE_URL --role preview

list --role shows names and metadata, never values. list --branch shows the variables a deploy of that branch would receive. rm works as an alias for remove.

add never overwrites: it fails if the key already exists in that scope, so use update to change a value. Every project env subcommand also accepts --project <id-or-name> to target a project other than the linked one.

Once you save a variable, its value is encrypted at rest and never returned: not by the CLI, the API, or the Console. In practice:

• project env list shows keys and metadata, not values.
• There's no command to pull values into a local .env.
• To rotate a secret, project env update it and redeploy.
• To confirm an app sees a value, redeploy and check its behavior or logs.

Keep your own copy of every value in a secret manager. Treat Prisma as the place values are injected, not a store you read back from.

• Keys must match [A-Z_][A-Z0-9_]*, up to 256 characters.
• Values must be non-empty, up to 8 KB.
• Production variables can't be branch-scoped: use --role production for production, and --branch <name> only for preview overrides.

Add --json so the output is machine-readable, and --no-interactive so the CLI fails with an error code instead of waiting on a prompt:

bunx prisma project env list --role preview --json --no-interactive

pnpm prisma project env list --role preview --json --no-interactive

yarn prisma project env list --role preview --json --no-interactive

npx prisma project env list --role preview --json --no-interactive

Don't build anything that depends on reading a value back. Pass the source value in from your own secret store, and let Prisma inject it at deploy time.

• Deployments: redeploy to apply new values.
• Branching: how preview branches work.