## TL;DR
`prisma migrate dev` needs a `url` on the `datasource` block, and the common setup reads it from an env var that isnt set in your shell. Add `url = env("DATABASE_URL")` to the datasource block in schema.prisma and export DATABASE_URL in the same terminal before running migrate dev.

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

## Use this when
- `prisma migrate dev` exits immediately with the datasource.url error
- The schema has a datasource block but no `url =` line
- An agent scaffolded the Prisma project and skipped the env wiring

## Not for this skill when
- The url is set but the DB refuses the connection (thats a connection-string problem)
- `migrate dev` fails later on a migration conflict or drift warning
- The error appears for `migrate deploy` (same fix shape, but deploy reads env differently in CI)

## Steps

1. Open schema.prisma and confirm the datasource block is missing its url:

```prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```
Expected output: if the `url` line is absent, add it exactly as shown. Do not hardcode a connection string here, use the env lookup.

2. Set DATABASE_URL in the terminal where you run Prisma. A `.env` file in the project root works for the CLI:

Add this line to the `.env` file in your project root:

```text
DATABASE_URL="postgresql://YOUR_USER@YOUR_HOST:5432/YOUR_DB"
```

Then confirm it is there:

```bash
cat .env
```
Expected output: the `.env` file contains the DATABASE_URL line. Use your real user, host, and database name; keep any credential out of the schema file itself.

3. Verify the env var is visible to the Prisma CLI, then run migrate dev:

```bash
npx prisma validate
npx prisma migrate dev --name init
```
Expected output: `validate` prints "The schema at prisma/schema.prisma is valid", and migrate dev creates the migration instead of the datasource.url error.

4. If the error persists with `.env` present, the env file isnt being loaded: Prisma CLI loads `.env` from the project root (or the schema dir in older versions). Move the schema reference explicitly:

```bash
npx prisma migrate dev --schema=./prisma/schema.prisma --name init
```
Expected output: the migration proceeds. Newer Prisma versions also support dotenv path flags if your env file lives elsewhere.

## Variant phrasings

### same error when running migrate deploy in CI
`migrate deploy` doesnt read `.env` files the same way; export DATABASE_URL in the CI job environment instead of relying on a file.

### error after switching providers
Each provider needs its own url format. A postgres URL in a mysql datasource still fails later at connect time, so match the URL scheme to `provider`.

## Why it happens
Prisma separates config (schema.prisma) from secrets (env vars). The datasource block must declare where the URL comes from even when the value is injected at runtime. Agents and templates often generate a schema without the `url = env(...)` line, or the developer runs the CLI in a shell where DATABASE_URL was never exported, so the CLI reports the property missing rather than the value being wrong.

## Edge cases
- Multiple schemas in a monorepo: each schema.prisma needs its own datasource block with url.
- `prisma db push` needs the same url; it wont error the same way but will fail to connect.
- On Prisma 5+, `datasource.url` can also come from a `prisma.config.ts`; mixing both files confuses the resolution, so pick one.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jEKAXfYUS_KV0TQiK3Qbkw