docs: make the local Prisma Postgres migrate step work on every run

[ankur-arch]

Fixes #7886.

The Local Postgres page told readers to copy only DATABASE_URL from the prisma dev output, and its .env example showed a prisma+postgres:// URL that the command no longer prints.

• Step 1 now copies both DATABASE_URL and SHADOW_DATABASE_URL into .env and shows the matching datasource config with shadowDatabaseUrl.
• Step 2 gets a troubleshooting note for the P1017 failure tracked in Command prisma migrate dev gives P1017 against local PGlite orm#29366, with the _prisma_migrations workaround from that thread and db push as the alternative.

Validation

Tested with prisma 7.10.0 (prisma@prev) against a fresh npx prisma dev --name ... instance:

• With only DATABASE_URL: the first prisma migrate dev --name init succeeds; the second run fails with relation "User" already exists even though migrate status reports the database up to date.
• With SHADOW_DATABASE_URL wired to shadowDatabaseUrl: migrate dev --name init, a no-op migrate dev, and a follow-up migrate dev --name add-post all succeed.
• P1017 itself did not reproduce on 7.10.0 in two fresh attempts; the upstream issue is still open with reports through June, so the note stays conditional.
• check-ai-signs.sh clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated the local Prisma Postgres setup guide to use direct PostgreSQL connection strings for DATABASE_URL and SHADOW_DATABASE_URL.
  • Clarified how Prisma ORM and Prisma Migrate use these connection strings.
  • Added a prisma.config.ts configuration example.
  • Added troubleshooting guidance for fresh-instance P1017 migration failures, including database setup and an alternative prisma db push workflow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
blog	Ready	Preview	Sep 17, 2026 3:12pm UTC
docs	Ready	Preview	Sep 17, 2026 3:12pm UTC
eclipse	Ready	Preview	Sep 17, 2026 3:12pm UTC
site	Ready	Preview	Sep 17, 2026 3:12pm UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Essentials

Run ID: 70c756d5-c4bc-48d6-856e-6165007a3532

📥 Commits

Reviewing files that changed from the base of the PR and between d5027b7 and fe3ef94.

📒 Files selected for processing (1)

• apps/docs/content/docs/local-development/postgres.mdx

Included review availability: 3 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

Walkthrough

The local development guide now uses direct PostgreSQL URLs for Prisma ORM and Prisma Migrate. It also documents a fresh-instance P1017 workaround and an alternative prisma db push workflow.

Changes

Local Prisma Postgres documentation

Layer / File(s)	Summary
Direct PostgreSQL connection setup apps/docs/content/docs/local-development/postgres.mdx	The guide uses separate DATABASE_URL and SHADOW_DATABASE_URL values and adds the corresponding prisma.config.ts configuration.
Fresh-instance migration troubleshooting apps/docs/content/docs/local-development/postgres.mdx	The guide documents manual creation of _prisma_migrations after P1017 and provides prisma db push when migration files are not required.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other · Severity of issue fixed: Medium

Suggested reviewers: wmadden-electric

Merge Risk: ⚪ Minimal · up to fe3ef

The documented migration guidance is appropriately scoped for the reported local setup, with no confirmed issue blocking merge.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main documentation change: making the local Prisma Postgres migration step work on repeated runs.
Linked Issues check	✅ Passed	The changes satisfy issue #7886. Step 1 now copies both DATABASE_URL and SHADOW_DATABASE_URL, and prisma.config.ts maps the second variable to shadowDatabaseUrl. Step 2 documents the P1017 f…
Out of Scope Changes check	✅ Passed	The pull request changes only apps/docs/content/docs/local-development/postgres.mdx. The URL updates, Prisma configuration example, migration troubleshooting note, workaround, and alternative comman…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🍈 Lychee Link Check Report

7 links: ✅ 3 OK | 🚫 0 errors | 🔀 0 redirects | 👻 4 excluded

✅ All links are working!

---

Full Statistics Table

Status	Count
✅ Successful	3
🔀 Redirected	0
👻 Excluded	4
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0

[prisma-robot]

Review round 1 at d54aa58. One finding, fixed and pushed as fe3ef94 (plus a merge of current main).

Found

• The P1017 note linked https://github.com/prisma/prisma/issues/29366. The upstream repository has been renamed to prisma/orm, GitHub returns 404 for that URL, and that is the error in the Lychee report above. Changed the link and the shorthand to prisma/orm#29366; the new URL returns 200.

Verified, no change

• Reproduced the page's claims against a fresh npx prisma dev instance with prisma 7.10.0 (prisma@prev): with only DATABASE_URL, migrate dev --name init succeeds and the next migrate dev fails with P3006 / relation "User" already exists while migrate status reports up to date; with SHADOW_DATABASE_URL wired to shadowDatabaseUrl, init, a no-op run and --name add-post all succeed.
• The create-migrations-table.sql block matches the workaround in the upstream thread and Prisma's own _prisma_migrations DDL; npx prisma db execute --file applies it from prisma.config.ts without extra flags, and migrate dev --name init then succeeds. P1017 itself did not reproduce, so the conditional wording is right.
• The .env example now matches what prisma dev prints (lines 35-36 of the page). pnpm lint:links 0 errors, cspell and check-ai-signs.sh clean on the page. The six other github.com/prisma/prisma/... links in the docs are in the generated error-reference.mdx and still redirect, so nothing to do there.

Will re-read the new head cold next.

— reviewer

[prisma-robot]

Review clean at fe3ef94.

Cold re-read of the head, including my round-1 link fix. The PR changes one page, local-development/postgres.mdx: step 1 now copies both DATABASE_URL and SHADOW_DATABASE_URL from prisma dev (the .env example matches the command's real output instead of the old prisma+postgres:// URL) and shows the prisma.config.ts that wires shadowDatabaseUrl; step 2 gains a conditional note for the P1017 failure in prisma/orm#29366 with the _prisma_migrations DDL, db execute --file, and db push as the fallback. Fixes #7886.

Checked on this head: branch is level with main; pnpm lint:links 0 errors; cspell 0 issues; check-ai-signs.sh clean; both internal links resolve to existing pages with matching url: frontmatter; the prisma/orm issue URL returns 200 and the issue is still open; all CI checks green. The claims themselves were reproduced in round 1 against prisma 7.10.0 (no shadow URL: second migrate dev fails with relation "User" already exists; with it: init, no-op and a second migration pass; the SQL block plus db execute lets migrate dev proceed).

Risk: low. Docs-only, one page, additive, and every statement on it was verified against the CLI it documents.

One thing outside this PR: the page lives in the unversioned (Prisma 8) tree but documents the Prisma ORM 7 workflow end to end. On prisma@latest (8.0.0-rc.15) prisma dev is the Composer runtime (dev <entry>), prisma migrate and db execute do not exist, and Prisma 8 rejects the v7 defineConfig shape. That predates this PR (the page already ran migrate dev and linked /orm/v7/...), so I did not change it here; I proposed a builder task to make the page's version scope explicit and point Prisma 8 readers at /composer/local-development.

— reviewer