docs: add mapped enums breaking change to Prisma 7 upgrade guide

[AmanVarshney01]

Summary by CodeRabbit

• Documentation
  • Added upgrade guidance explaining Prisma v7 behavior change for generated TypeScript enum values with mapped enums, including before/after examples, migration steps, and temporary workarounds for a known runtime issue.
  • Added a delivery/prompts note and checklist item to surface a mapped-enum warning where applicable.
  • Clarified enum mapping behavior in reference docs; warning appears in multiple places to improve discoverability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds documentation across multiple docs pages and an AI prompt: documents that Prisma v7 emits TypeScript enum values from @map (database) values, notes a known runtime bug with mapped enum values, provides examples, migration steps, and temporary workarounds; the migration guide section was inserted twice.

Changes

Cohort / File(s)	Summary
Migration guide updates content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx	Inserts a "Mapped enum values in generated TypeScript" section (added in two locations) explaining that v7 generates enum values from @map, showing before/after examples, listing migration steps, and suggesting temporary workarounds (use schema-name string literals or remove @map).
Schema mapping docs content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx, content/200-orm/500-reference/100-prisma-schema-reference.mdx	Adds explanations that @@map maps enum names and @map maps enum values; documents that generated TypeScript uses mapped strings, includes example output and a warning about the known runtime bug.
AI prompt / guidance content/900-ai/prompts/prisma-7.mdx	Adds a "Mapped Enum Breaking Change" guidance block with v6 vs v7 examples, notes the runtime bug, and appends a deliverable bullet: "Mapped enum breaking change warning (if applicable)."

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Check duplicated insertion in the migration guide — consolidate or confirm intentional duplication.
• Verify the before/after TypeScript examples precisely match generator output for v7.
• Confirm wording consistency across migration guide, schema docs, and AI prompt, and that the workaround instructions are clear.

Possibly related issues

• Enum values use @map value instead of enum name in Prisma 7.x (regression from 6.x) prisma#28843 — Describes the same regression where v7 generates TypeScript enum values from @map; this PR adds documentation and warnings about that behavior.
• [Docs] Prisma 7 migration guide does not contain any mention of the v7 mapped enums breaking change prisma#28930 — Requests documenting the mapped-enum breaking change; the changes here implement that documentation and guidance.

Possibly related PRs

• docs(): add v7 migration guide #7249 — Edits the Prisma v7 migration docs with similar mapped-enum content and likely overlaps with the added sections in the migration guide.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding documentation about mapped enums breaking changes to the Prisma 7 upgrade guide, which is reflected across four documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

Dangerous URL check

No absolute URLs to prisma.io/docs found.
No local URLs found.

[github-actions]

original	preview
content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx	content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx
content/200-orm/500-reference/100-prisma-schema-reference.mdx	content/200-orm/500-reference/100-prisma-schema-reference.mdx
content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx	content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx
content/900-ai/prompts/prisma-7.mdx	content/900-ai/prompts/prisma-7.mdx

[github-actions]

Redirect check

This PR probably requires the following redirects to be added to static/_redirects:

• This PR does not change any pages in a way that would require a redirect.

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2241
⏳ Timeouts	0
🔀 Redirected	7
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	ed2b69d
Status:	✅  Deploy successful!
Preview URL:	https://19f2c26f.docs-51g.pages.dev
Branch Preview URL:	https://dr-6654-ensure-documentation.docs-51g.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx (1)

345-409: Well-structured documentation with appropriate warning placement.

The section effectively communicates the breaking change with:

• Prominent warning block about the known bug
• Clear before/after code examples
• Practical workarounds

The content is consistent with the AI prompt documentation (content/900-ai/prompts/prisma-7.mdx), which is important for maintaining coherent guidance across the docs.

One optional enhancement: Consider briefly explaining why this change was made (e.g., "to better align generated types with actual database values") to help users understand the long-term benefit despite the current bug.

Optional: Add context for the change rationale

After line 353, you could optionally add:

 In Prisma ORM v7, the generated TypeScript enum values now use the `@map` values instead of the schema names. This is a breaking change from v6.
+
+This change aligns the generated TypeScript enum values with the actual values stored in your database, making the generated code more intuitive when working with database queries and results.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a4bbbe7 and 0546ac0.

📒 Files selected for processing (2)

• content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx (1 hunks)
• content/900-ai/prompts/prisma-7.mdx (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Check internal links
• GitHub Check: Cloudflare Pages

🔇 Additional comments (2)

content/900-ai/prompts/prisma-7.mdx (2)

372-372: Good addition to the deliverables checklist.

Including the mapped enum warning in the deliverables list ensures AI assistants will check for and communicate this breaking change when applicable.

---

305-360: Verify GitHub issue #28591 and its current status before relying on this documentation.

The section effectively documents the mapped enum breaking change with clear before/after examples and identifies the known bug. However, GitHub issue #28591 exists but the documentation should note its current resolution status—whether it remains unfixed, has a timeline for resolution, or if users should be aware of any updates to the workarounds since v7.2.0.

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2245
⏳ Timeouts	0
🔀 Redirected	2
👻 Excluded	24
❓ Unknown	0
🚫 Errors	5
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/300-upgrade-guides/800-upgrade-from-prisma-1/06-upgrading-prisma-binding-to-sdl-first.mdx

• [ERROR] https://v1.prisma.io/docs/1.20/data-model-and-migrations/data-model-knul/#a-note-on-the-application-schema | Error (cached)

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2242
⏳ Timeouts	0
🔀 Redirected	6
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2244
⏳ Timeouts	0
🔀 Redirected	4
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2240
⏳ Timeouts	0
🔀 Redirected	8
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2244
⏳ Timeouts	0
🔀 Redirected	4
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[github-actions]

🍈 Lychee Link Check Report

Note: Links are cached for 5 minutes. Failed links (timeouts, rate limits) are retried in a second run with longer timeout.

📊 Results Overview

Status	Count
🔍 Total	2277
✅ Successful	2242
⏳ Timeouts	0
🔀 Redirected	6
👻 Excluded	24
❓ Unknown	0
🚫 Errors	4
⛔ Unsupported	1

Errors per input

Errors in 200-orm/800-more/350-ai-tools/100-cursor.mdx

• [500] https://docs.cursor.com/context/ | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/@-files | Rejected status code (this depends on your "accept" configuration): Internal Server Error
• [500] https://docs.cursor.com/context/@-symbols/basic | Rejected status code (this depends on your "accept" configuration): Internal Server Error

Errors in 800-guides/380-vercel-app-deployment.mdx

• [500] https://vercel.com/docs/rest-api | Rejected status code (this depends on your "accept" configuration): Internal Server Error

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

content/200-orm/500-reference/100-prisma-schema-reference.mdx (1)

2725-2740: Consider document structure: v7-specific behavior within general attribute docs.

The content accurately documents the v7 mapped enum behavior and includes an appropriate warning about the runtime bug. The code example is correct, and the cross-reference to the upgrade guide is helpful.

However, this v7-specific breaking change documentation is embedded within the general @map attribute reference documentation. This placement might create confusion for users in two scenarios:

1. Users still on v6 reading about @map who don't need v7 migration information yet
2. Users searching for general @map behavior who encounter version-specific migration content

Consider adding a version indicator in the heading or structuring this as a versioned callout (e.g., "In Prisma ORM v7:") to make it clear this is version-specific behavior rather than general @map attribute documentation.

The warning about the known bug is appropriately worded and links to the right resources.

content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx (1)

395-427: Clarify trade-offs between the two workaround approaches.

The section provides two valid workarounds, but doesn't explicitly guide users on when to choose one over the other. Consider adding a brief comparison to help users make an informed decision:

• Workaround 1 (string literal with as any): Maintains your existing database schema but requires type assertions throughout your codebase. Use this if you need to preserve the exact database enum values (e.g., for compatibility with existing data or external systems).

• Workaround 2 (removing @map): Cleaner TypeScript but requires a database migration to change enum values. Use this if you can safely migrate your database and prefer type-safe code without assertions.

Additionally, the first workaround might trigger TypeScript linting rules against any types. Consider mentioning an alternative using type assertions:

await prisma.suggestion.create({
  data: {
    status: "PENDING" as unknown as SuggestionStatus.PENDING,
  },
});

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a9cd25 and ed2b69d.

📒 Files selected for processing (4)

• content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx (1 hunks)
• content/200-orm/500-reference/100-prisma-schema-reference.mdx (1 hunks)
• content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx (1 hunks)
• content/900-ai/prompts/prisma-7.mdx (2 hunks)

✅ Files skipped from review due to trivial changes (1)

• content/200-orm/100-prisma-schema/20-data-model/50-database-mapping.mdx

🚧 Files skipped from review as they are similar to previous changes (1)

• content/900-ai/prompts/prisma-7.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Check internal links
• GitHub Check: Cloudflare Pages

🔇 Additional comments (2)

content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx (2)

345-351: LGTM: Clear warning about runtime bug.

The section heading clearly identifies the breaking change, and the warning is appropriately prominent. The explanation of the mismatch between TypeScript types (expecting mapped values) and the Prisma Client engine (expecting schema names) helps users understand the root cause of runtime errors.

The GitHub issue link provides transparency and allows users to track resolution progress.

---

353-389: Excellent before/after comparison demonstrates the breaking change.

The side-by-side comparison using the same SuggestionStatus enum makes the breaking change immediately clear. Showing that SuggestionStatus.PENDING changes from "PENDING" (v6) to "pending" (v7) effectively illustrates the impact.

The consistent use of the same schema example in both sections allows readers to focus on the difference in generated output rather than understanding different schemas.