Prisma Upgrade V7 Agent Skill

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

10. 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.