## TL;DR
`prisma migrate deploy` runs in non-interactive environments where `.env` files are often absent or ignored, so the datasource `url` resolves to nothing. Fix it by exporting DATABASE_URL as a real environment variable in the deploy job (not just a `.env` file), and keep `url = env("DATABASE_URL")` in the datasource block.

```text
error: the datasource.url property is required in your prisma config file when using prisma migrate deploy.
```

## Use this when
- `migrate dev` works locally but `migrate deploy` fails in CI or Docker with this error
- The deploy job relies on a `.env` file that isnt shipped into the container
- An agent wrote the deploy step without wiring the database URL into the environment

## Not for this skill when
- The url is set and the failure is about drift, failed migrations, or the shadow database
- The connection is refused or times out (the url is present but wrong)
- You are running `migrate dev` locally (thats the local-env variant of this error)

## Steps

1. Confirm the schema declares the url via env, not hardcoded:

```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```
Expected output: the `url` line exists. If it is missing entirely, add it; the CLI validates the property before it ever reads the value.

2. Export DATABASE_URL in the deploy environment. In a CI job:

```yaml
env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
```
Expected output: the secret is injected as an environment variable for the job step. `migrate deploy` prefers real env vars over `.env` files, which is why local dev works and CI fails.

3. In Docker, pass it at container run time rather than baking it into the image:

```bash
docker run --env-file ./deploy.env myapp npx prisma migrate deploy
```
Expected output: the container sees DATABASE_URL and deploy runs. Baking the URL into the image leaks a credential into the layer history, so dont.

4. Verify the variable is visible to the exact command you run, then deploy:

```bash
printenv DATABASE_URL | head -c 20
npx prisma migrate deploy
```
Expected output: the first command prints the start of the URL (proving visibility), and deploy applies pending migrations instead of the datasource.url error.

## Variant phrasings

### deploy fails but only in a specific stage
One stage exports the variable and another doesnt. Diff the env blocks across stages; the fix is per-stage, not global.

### same error with prisma.config.ts
If you moved config to `prisma.config.ts`, make sure it also provides the datasource url or env wiring. Mixed config files confuse resolution, so consolidate on one.

## Why it happens
`migrate dev` is a local command that happily reads `.env` from your project dir. `migrate deploy` is designed for production pipelines where `.env` files are typically absent (or intentionally excluded), so the url property resolves to nothing and the CLI reports it as missing rather than wrong. The asymmetry between dev and deploy environments is what makes this error show up only at deploy time.

## Edge cases
- Some platforms strip env vars between build and run phases; set it in the run phase.
- A trailing newline in the secret value breaks the URL silently; trim it when injecting.
- Preview deployments need their own database URL; pointing them at production is a data-loss accident waiting to happen.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ko2-KSA-C_wN1Ts0sh-JeQ