Prisma Upgrade V7

# Upgrade to Prisma ORM 7

Complete guide for migrating from Prisma ORM v6 to v7. This upgrade introduces significant breaking changes around the new `prisma-client` generator, driver adapters, `prisma.config.ts`, explicit environment loading, and generated client entrypoints.

## When to Apply

Reference this skill when: - Upgrading from Prisma v6 to v7 - Updating to the `prisma-client` generator - Setting up driver adapters - Configuring `prisma.config.ts` - Fixing import errors after upgrade

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Schema Migration | CRITICAL | `schema-changes` | | 2 | Database Connectivity | CRITICAL | `driver-adapters` | | 3 | Module System | CRITICAL | `esm-support` | | 4 | Config and Env | HIGH | `prisma-config`, `env-variables` | | 5 | Removed Features | HIGH | `removed-features` | | 6 | Accelerate | HIGH | `accelerate-users` |

## Quick Reference

- `schema-changes` - generator migration, required output paths, generated entrypoints, and `Prisma.validator` replacement - `driver-adapters` - required adapter installation for SQL providers, pool differences, and Prisma Postgres adapter choices - `esm-support` - ESM-first setup plus CommonJS fallback with `moduleFormat = "cjs"` - `prisma-config` - creating and using `prisma.config.ts` - `env-variables` - explicit environment loading - `removed-features` - removed middleware, metrics, and legacy CLI behavior - `accelerate-users` - migration notes for Accelerate users

## Using MongoDB? This guide does not apply

Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a project with `provider = "mongodb"` — see the `prisma-mongodb-upgrade` skill for the actual decision (stay on v6 deliberately vs migrate to Prisma Next).

## Important Notes

- **MongoDB projects should stay on Prisma 6.x or migrate to Prisma Next** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`) - **Node.js 20.19.0+** required - **TypeScript 5.4.0+** required - **Latest stable Prisma ORM version**: `7.6.0`

## Upgrade Steps Overview

1. Update packages to v7 2. Choose your module format (`esm` by default, `cjs` if needed) 3. Update TypeScript configuration 4. Update the schema generator block 5. Create `prisma.config.ts` 6. Install and configure a driver adapter for SQL providers 7. Update Prisma Client imports 8. Update client instantiation 9. Replace deprecated helper patterns like `Prisma.validator` 10. Run `prisma generate` and test

## Quick Upgrade Commands

```bash # Update packages npm install @prisma/client@7 npm install -D prisma@7

# Install a driver adapter (PostgreSQL or Prisma Postgres via direct TCP) npm install @prisma/adapter-pg pg

# Install dotenv for env loading npm install dotenv

# Regenerate client npx prisma generate ```

## Breaking Changes Summary

| Change | v6 | v7 | |--------|----|----| | Module format | Implicit / mixed | ESM-first, `moduleFormat = "cjs"` supported | | Generator provider | `prisma-client-js` | `prisma-client` is the default, while `prisma-client-js` still exists for legacy setups | | Output path | Auto (node_modules) | Required explicit | | Driver adapters | Optional | Required for SQL providers | | Config file | `.env` + schema | `prisma.config.ts` | | Env loading | Automatic | Manual (dotenv) | | Generated entrypoints | Single package export | `client`, `browser`, `models`, `enums` entrypoints | | Type-safe query fragments | `Prisma.validator()` | TypeScript `satisfies` | | Middleware | `$use()` | Client Extensions | | Metrics | Preview feature | Removed |

## Rule Files

Detailed migration guides for each breaking change:

``` references/esm-support.md - ESM and CommonJS configuration references/schema-changes.md - Generator, output, imports, and generated entrypoints references/driver-adapters.md - Required driver adapter setup references/prisma-config.md - New configuration file references/env-variables.md - Environment variable loading references/removed-features.md - Middleware, metrics, and CLI flags references/accelerate-users.md - Special handling for Accelerate ```

## Step-by-Step Migration

### 1. Update package.json for ESM-first projects

```json { "type": "module" } ```

If you need to stay on CommonJS, keep your app as CJS and set `moduleFormat = "cjs"` in the generator block instead of forcing ESM.

### 2. Update tsconfig.json

```json { "compilerOptions": { "module": "ESNext", "moduleResolution": "bundler", "target": "ES2023", "strict": true, "esModuleInterop": true } } ```

### 3. Update schema.prisma

```prisma // Before (v6) generator client { provider = "prisma-client-js" }

// After (v7) generator client { provider = "prisma-client" output = "../generated/prisma" // Optional if you need CommonJS: // moduleFormat = "cjs" } ```

### 4. Create prisma.config.ts

```typescript import 'dotenv/config'