# Environment variables (/docs/compute/environment-variables)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Project configuration that gets injected into your deployments, scoped to production, preview, or a single branch.

Location: Compute > 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`.

## How it works [#how-it-works]

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.

<ConceptAnimation name="env-layers" />

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.

## Set a variable [#set-a-variable]

Pass `KEY=value` and a role or branch:

  

#### bun

```bash
bunx prisma@latest project env add DATABASE_URL=postgresql://example --role production
bunx prisma@latest project env add DATABASE_URL=postgresql://preview --role preview
bunx prisma@latest project env add FEATURE_FLAG=enabled --branch feature/search
```

#### pnpm

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

#### yarn

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

#### npm

```bash
npx prisma@latest project env add DATABASE_URL=postgresql://example --role production
npx prisma@latest project env add DATABASE_URL=postgresql://preview --role preview
npx prisma@latest 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:

```bash
DATABASE_URL=postgresql://example npx prisma@latest 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`:

  

#### bun

```bash
bunx prisma@latest project env add --file .env.production --role production
```

#### pnpm

```bash
pnpm dlx prisma@latest project env add --file .env.production --role production
```

#### yarn

```bash
yarn dlx prisma@latest project env add --file .env.production --role production
```

#### npm

```bash
npx prisma@latest project env add --file .env.production --role production
```

## Connect a database [#connect-a-database]

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.

> [!NOTE]
> Don't assume production data is copied into preview branches, and don't assume migrations run automatically on deploy. Run migrations yourself against the right database.

## List, update, remove [#list-update-remove]

  

#### bun

```bash
bunx prisma@latest project env list --role production
bunx prisma@latest project env list --branch feature/search
bunx prisma@latest project env update DATABASE_URL=postgresql://new --role production
bunx prisma@latest project env delete DATABASE_URL --role preview
```

#### pnpm

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

#### yarn

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

#### npm

```bash
npx prisma@latest project env list --role production
npx prisma@latest project env list --branch feature/search
npx prisma@latest project env update DATABASE_URL=postgresql://new --role production
npx prisma@latest 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.

## Values are write-only [#values-are-write-only]

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.

## Rules [#rules]

* 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.

## In CI and agents [#in-ci-and-agents]

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:

  

#### bun

```bash
bunx prisma@latest project env list --role preview --json --no-interactive
```

#### pnpm

```bash
pnpm dlx prisma@latest project env list --role preview --json --no-interactive
```

#### yarn

```bash
yarn dlx prisma@latest project env list --role preview --json --no-interactive
```

#### npm

```bash
npx prisma@latest 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.

## Next steps [#next-steps]

* [Deployments](https://www.prisma.io/docs/compute/deployments): redeploy to apply new values.
* [Branching](https://www.prisma.io/docs/compute/branching): how preview branches work.

## Related pages

- [`Alchemy`](https://www.prisma.io/docs/compute/alchemy): Provision Prisma Postgres and deploy applications to Prisma Compute in one TypeScript stack.
- [`Branching`](https://www.prisma.io/docs/compute/branching): Branches are isolated environments that map to your Git branches, so preview work never touches production.
- [`Deploy Button`](https://www.prisma.io/docs/compute/deploy-button): Add a Deploy with Prisma button that copies a public Composer repository and starts a Composer-managed deployment.
- [`Deploy on push`](https://www.prisma.io/docs/compute/deploy-on-push): Graduate a Composer app from manual deploys to a Git workflow, with production deploys on push and an isolated preview environment per branch.
- [`Deployments`](https://www.prisma.io/docs/compute/deployments): How deploys create service versions on Prisma Compute, and how to inspect, promote, roll back, start, and stop them.