docs: add mapped enums breaking change to Prisma 7 upgrade guide (#7401)

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

* Update content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx

Co-authored-by: Ankur Datta <[email protected]>

* Update content/200-orm/800-more/300-upgrade-guides/200-upgrading-versions/400-upgrading-to-prisma-7.mdx

Co-authored-by: Ankur Datta <[email protected]>

* Apply suggestion from @ankur-arch

Co-authored-by: Ankur Datta <[email protected]>

* Apply suggestion from @ankur-arch

Co-authored-by: Ankur Datta <[email protected]>

* Apply suggestion from @ankur-arch

Co-authored-by: Ankur Datta <[email protected]>

* update content with example

* update other pages for @Map

---------

Co-authored-by: Ankur Datta <[email protected]>

Author: AmanVarshney01

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

@@ -74,6 +74,38 @@ enum Type {
 }
 ```
 
+In this example:
+- `@@map("comment_source_enum")` maps the enum name `Type` to `comment_source_enum` in the database
+- `@map("comment_twitter")` maps the enum value `Twitter` to `comment_twitter` in the database
+
+#### Effect on generated TypeScript (Prisma ORM v7+)
+
+In Prisma ORM v7 and later, when you use `@map` on enum values, the generated TypeScript enum uses the **mapped values** instead of the schema names:
+
+```prisma
+enum Status {
+  PENDING  @map("pending")
+  APPROVED @map("approved")
+}
+```
+
+This generates the following TypeScript:
+
+```ts
+export const Status = {
+  PENDING: 'pending',
+  APPROVED: 'approved'
+} as const
+```
+
+This means `Status.PENDING` evaluates to `"pending"`, not `"PENDING"`.
+
+:::warning
+
+There is currently a known bug in Prisma ORM v7 where using mapped enum values with Prisma Client operations causes runtime errors. See the [Prisma 7 upgrade guide](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7#mapped-enum-values-in-generated-typescript) for workarounds and details.
+
+:::
+
 ## Constraint and index names
 
 You can optionally use the `map` argument to explicitly define the **underlying constraint and index names** in the Prisma schema for the attributes [`@id`](/orm/reference/prisma-schema-reference#id), [`@@id`](/orm/reference/prisma-schema-reference#id-1), [`@unique`](/orm/reference/prisma-schema-reference#unique), [`@@unique`](/orm/reference/prisma-schema-reference#unique-1), [`@@index`](/orm/reference/prisma-schema-reference#index) and [`@relation`](/orm/reference/prisma-schema-reference#relation). (This is available in Prisma ORM version [2.29.0](https://github.com/prisma/prisma/releases/tag/2.29.0) and later.)

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

@@ -2722,6 +2722,23 @@ enum Role {
 }
 ```
 
+In Prisma ORM v7 and later, the generated TypeScript enum uses the mapped values:
+
+```ts
+export const Role = {
+  ADMIN: 'admin',
+  CUSTOMER: 'CUSTOMER'
+} as const
+```
+
+This means `Role.ADMIN` evaluates to `"admin"`, not `"ADMIN"`.
+
+:::warning
+
+There is currently a known bug in Prisma ORM v7 where using mapped enum values with Prisma Client operations causes runtime errors. See the [Prisma 7 upgrade guide](/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7#mapped-enum-values-in-generated-typescript) for workarounds and details.
+
+:::
+
 ### `@@map`
 
 Maps the Prisma schema model name to a table (relational databases) or collection (MongoDB) with a different name, or an enum name to a different underlying enum in the database. If you do not use `@@map`, the model name matches the table (relational databases) or collection (MongoDB) name exactly.

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

@@ -342,6 +342,89 @@ async function main() {
 }
 ```
 
+### Mapped enum values in generated TypeScript
+
+:::warning
+
+There is currently a known bug where using mapped enum values with Prisma Client operations (like `create`, `update`, etc.) causes runtime errors. The generated TypeScript types expect the mapped values, but the Prisma Client engine expects the schema names. This issue is being tracked in [GitHub issue #28591](https://github.com/prisma/prisma/issues/28591). Until this is fixed, you need to use workarounds described below.
+
+:::
+
+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.
+
+#### Before Prisma ORM v6
+
+Given this Prisma schema:
+
+```prisma
+enum SuggestionStatus {
+  PENDING  @map("pending")
+  ACCEPTED @map("accepted")
+  REJECTED @map("rejected")
+}
+```
+
+In v6, the generated TypeScript enum would be:
+
+```ts
+export const SuggestionStatus = {
+  PENDING: 'PENDING',
+  ACCEPTED: 'ACCEPTED',
+  REJECTED: 'REJECTED'
+} as const
+```
+
+#### After Prisma ORM v7
+
+In v7, the same schema generates:
+
+```ts
+export const SuggestionStatus = {
+  PENDING: 'pending',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected'
+} as const
+```
+
+This means that `SuggestionStatus.PENDING` now evaluates to `"pending"` instead of `"PENDING"`.
+
+#### Migration steps
+
+If you're using mapped enums, you'll need to update any code that relies on the enum values being the schema names rather than the mapped values.
+
+##### Temporary workaround
+
+Until we resolve [the open issue](https://github.com/prisma/prisma/issues/28591), you need to use the schema name as a string literal instead of the generated enum value:
+
+```ts
+// This may cause a TypeScript error but works at runtime
+await prisma.suggestion.create({
+  data: {
+    status: "PENDING" as any, // Use schema name, not mapped value
+  },
+});
+```
+
+Alternatively, you can temporarily remove the `@map` directives from your enum values if you don't strictly need the database values to differ from the schema names:
+
+```prisma
+// Before: with @map directives
+enum SuggestionStatus {
+  PENDING  @map("pending")
+  ACCEPTED @map("accepted")
+  REJECTED @map("rejected")
+}
+
+// After: without @map directives
+enum SuggestionStatus {
+  PENDING
+  ACCEPTED
+  REJECTED
+}
+```
+
+With this change, both the schema names and the database values will be `PENDING`, `ACCEPTED`, and `REJECTED`, and the generated TypeScript enum will work correctly with Prisma Client operations.
+
 ### Client middleware has been removed
 
 The client middleware API has been removed. If possible, use [Client Extensions](/orm/prisma-client/client-extensions). 

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

@@ -302,6 +302,79 @@ Your project will be migrated accordingly using the appropriate adapter.
 
 ---
 
+## 11) Mapped Enum Breaking Change
+
+In Prisma v7, the generated TypeScript enum values now use `@map` values instead of schema names.
+
+### Example
+
+Given this schema:
+```prisma
+enum SuggestionStatus {
+  PENDING  @map("pending")
+  ACCEPTED @map("accepted")
+  REJECTED @map("rejected")
+}
+```
+
+**v6 generated enum:**
+```ts
+export const SuggestionStatus = {
+  PENDING: 'PENDING',
+  ACCEPTED: 'ACCEPTED',
+  REJECTED: 'REJECTED'
+} as const
+```
+
+**v7 generated enum:**
+```ts
+export const SuggestionStatus = {
+  PENDING: 'pending',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected'
+} as const
+```
+
+### Known Bug (as of v7.2.0)
+
+⚠️ **There is a known bug** where using mapped enum values with Prisma Client operations causes runtime errors. The TypeScript types expect mapped values, but the engine expects schema names. Track this at [GitHub #28591](https://github.com/prisma/prisma/issues/28591).
+
+### Temporary Workarounds
+
+1. **Use schema names as string literals** (causes TS error but works at runtime):
+   ```ts
+   await prisma.suggestion.create({
+     data: {
+       status: "PENDING" as any, // Use schema name, not mapped value
+     },
+   });
+   ```
+
+2. **Remove `@map` from enum values** temporarily if you don't strictly need different database values:
+   ```prisma
+   // Before: with @map directives
+   enum SuggestionStatus {
+     PENDING  @map("pending")
+     ACCEPTED @map("accepted")
+     REJECTED @map("rejected")
+   }
+
+   // After: without @map directives
+   enum SuggestionStatus {
+     PENDING
+     ACCEPTED
+     REJECTED
+   }
+   ```
+   With this change, both the schema names and the database values will be `PENDING`, `ACCEPTED`, and `REJECTED`.
+
+### Migration Action
+
+- Inform users about this breaking change if their schema uses `@map` on enum values.
+- Warn about the current bug and suggest workarounds until it's fixed.
+
+---
+
 ## Deliverables
 
 - A short **CHANGELOG** summary in the PR body:
@@ -312,5 +385,6 @@ Your project will be migrated accordingly using the appropriate adapter.
     - ESM/TS config updates
     - Seed script updates
     - No automatic removal of Accelerate
+    - Mapped enum breaking change warning (if applicable)
 
 ````