prisma-upgrade-v7

SKILL.md

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

Update packages to v7

Choose your module format (esm by default, cjs if needed)

Update TypeScript configuration

Update the schema generator block

Create prisma.config.ts

Install and configure a driver adapter for SQL providers

Update Prisma Client imports

Update client instantiation

Replace deprecated helper patterns like Prisma.validator

Run prisma generate and test

Quick Upgrade Commands

# 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

{
  "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

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

3. Update schema.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

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

5. Install a driver adapter (SQL providers only)

# PostgreSQL
npm install @prisma/adapter-pg pg

# MySQL
npm install @prisma/adapter-mariadb mariadb

# SQLite
npm install @prisma/adapter-better-sqlite3 better-sqlite3

# Prisma Postgres in standard Node.js apps (recommended)
npm install @prisma/adapter-pg pg

# Prisma Postgres serverless driver (edge/serverless)
npm install @prisma/adapter-ppg @prisma/ppg

# Neon
npm install @prisma/adapter-neon

MongoDB does not have a SQL @prisma/adapter-* package in the published Prisma 7.6.0 packages. If you're upgrading a MongoDB project, stop and keep that project on the latest Prisma 6.x release instead of following the standard Prisma 7 migration path.

6. Update client instantiation

// Before (v6)
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

// After (v7)
import { PrismaClient } from '../generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL
})

const prisma = new PrismaClient({ adapter })

7. Replace Prisma.validator with satisfies

import { Prisma } from '../generated/prisma/client'

const userSelect = {
  id: true,
  email: true,
  name: true,
} satisfies Prisma.UserSelect

8. Run migrations and generate

npx prisma generate
npx prisma migrate dev  # if needed

Troubleshooting

"Cannot find module" errors

Check that the generator output path matches your import path

Ensure prisma generate ran successfully

SSL certificate errors

Add ssl: { rejectUnauthorized: false } to the adapter config if you need to preserve old behavior

Or configure your certificates properly with NODE_EXTRA_CA_CERTS / OpenSSL CA settings

Connection timeout issues

Driver adapters use the underlying driver's defaults, which differ from v6

Configure pool settings explicitly on the adapter if needed

Resources

Official v7 Upgrade Guide

Driver Adapters Documentation

Prisma Config Reference

How to Use

Follow references/schema-changes.md and references/driver-adapters.md first, then apply the remaining reference files based on your project setup.
1f