prisma-upgrade-v7

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upgrade to Prisma ORM 7

升级至 Prisma ORM 7

Complete guide for migrating from Prisma ORM v6 to v7. This upgrade introduces significant breaking changes including ESM-only support, required driver adapters, and a new configuration system.

这是一份从 Prisma ORM v6 迁移至 v7 的完整指南。本次升级带来了多项重大变更，包括仅支持 ESM、强制要求驱动适配器，以及全新的配置系统。

When to Apply

适用场景

Reference this skill when:

Upgrading from Prisma v6 to v7
Switching from
```
prisma-client-js
```
to
```
prisma-client
```
Setting up driver adapters
Configuring
```
prisma.config.ts
```
Fixing import errors after upgrade

在以下场景中可参考本指南：

从 Prisma v6 升级至 v7
从
```
prisma-client-js
```
切换至
```
prisma-client
```
配置驱动适配器
配置
```
prisma.config.ts
```
修复升级后的导入错误

Important Notes

重要说明

MongoDB not yet supported in v7 - Continue using v6 for MongoDB
Node.js 20.19.0+ required
TypeScript 5.4.0+ required

v7 暂不支持 MongoDB - 如需使用 MongoDB 请继续使用 v6
要求 Node.js 20.19.0+
要求 TypeScript 5.4.0+

Upgrade Steps Overview

升级步骤概览

Update packages to v7
Configure ESM in package.json
Update TypeScript configuration
Update schema generator block
Create prisma.config.ts
Install and configure driver adapter
Update Prisma Client imports
Update client instantiation
Remove deprecated code (middleware, env vars)
Run generate and test

将包更新至 v7 版本
在 package.json 中配置 ESM
更新 TypeScript 配置
更新 schema 生成器块
创建 prisma.config.ts
安装并配置驱动适配器
更新 Prisma Client 导入路径
更新客户端实例化代码
移除已废弃代码（中间件、环境变量相关）
运行生成命令并测试

Quick Upgrade Commands

快速升级命令

bash

undefined

bash

undefined

Update packages

更新包

npm install @prisma/client@7 npm install -D prisma@7

Install driver adapter (PostgreSQL example)

安装驱动适配器（PostgreSQL 示例）

npm install @prisma/adapter-pg

Install dotenv for env loading

安装 dotenv 用于加载环境变量

npm install dotenv

Regenerate client

重新生成客户端

npx prisma generate

undefined

npx prisma generate

undefined

Breaking Changes Summary

重大变更汇总

Change	v6	v7
Module format	CommonJS	ESM only
Generator provider	`prisma-client-js`	`prisma-client`
Output path	Auto (node_modules)	Required explicit
Driver adapters	Optional	Required
Config file	`.env` + schema	`prisma.config.ts`
Env loading	Automatic	Manual (dotenv)
Middleware	`$use()`	Client Extensions
Metrics	Preview feature	Removed

变更项	v6	v7
模块格式	CommonJS	仅支持 ESM
生成器提供商	`prisma-client-js`	`prisma-client`
输出路径	自动（node_modules）	需显式指定
驱动适配器	可选	强制要求
配置文件	`.env` + schema	`prisma.config.ts`
环境变量加载	自动	手动（通过 dotenv）
中间件	`$use()`	客户端扩展（Client Extensions）
指标功能	预览特性	已移除

Rule Files

规则文件

Detailed migration guides for each breaking change:

rules/esm-support.md        - ESM module configuration
rules/schema-changes.md     - Generator and schema updates
rules/driver-adapters.md    - Required driver adapter setup
rules/prisma-config.md      - New configuration file
rules/env-variables.md      - Environment variable loading
rules/client-imports.md     - Updated import paths
rules/removed-features.md   - Middleware, metrics, CLI flags
rules/accelerate-users.md   - Special handling for Accelerate
rules/ssl-certificates.md   - SSL validation changes

针对每项重大变更的详细迁移指南：

rules/esm-support.md        - ESM 模块配置
rules/schema-changes.md     - 生成器与 schema 更新
rules/driver-adapters.md    - 驱动适配器强制配置
rules/prisma-config.md      - 全新配置文件
rules/env-variables.md      - 环境变量加载
rules/client-imports.md     - 导入路径更新
rules/removed-features.md   - 已移除特性（中间件、指标、CLI 标志）
rules/accelerate-users.md   - Accelerate 用户特殊处理
rules/ssl-certificates.md   - SSL 验证变更

Step-by-Step Migration

分步迁移指南

1. Update package.json for ESM

1. 在 package.json 中配置 ESM

json

{
  "type": "module"
}

json

{
  "type": "module"
}

2. Update tsconfig.json

2. 更新 tsconfig.json

json

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

json

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

3. Update schema.prisma

3. 更新 schema.prisma

prisma

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

// After (v7)
generator client {
  provider = "prisma-client"
  output   = "../generated"
}

prisma

// 之前（v6）
generator client {
  provider = "prisma-client-js"
}

// 之后（v7）
generator client {
  provider = "prisma-client"
  output   = "../generated"
}

4. Create prisma.config.ts

4. 创建 prisma.config.ts

typescript

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'),
  },
})

typescript

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 driver adapter

5. 安装驱动适配器

bash

undefined

bash

undefined

PostgreSQL

npm install @prisma/adapter-pg

MySQL

npm install @prisma/adapter-mariadb mariadb

SQLite

npm install @prisma/adapter-better-sqlite3

Prisma Postgres

npm install @prisma/adapter-ppg @prisma/ppg

Neon

npm install @prisma/adapter-neon

undefined

npm install @prisma/adapter-neon

undefined

6. Update client instantiation

6. 更新客户端实例化代码

typescript

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

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

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

typescript

// 之前（v6）
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()

// 之后（v7）
import { PrismaClient } from '../generated/client'
import { PrismaPg } from '@prisma/adapter-pg'

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

7. Run migrations and generate

7. 运行迁移与生成命令

bash

npx prisma generate
npx prisma migrate dev  # if needed

bash

npx prisma generate
npx prisma migrate dev  # 如有需要

prisma-upgrade-v7

Original

Translation

Upgrade to Prisma ORM 7

升级至 Prisma ORM 7

When to Apply

适用场景

Important Notes

重要说明

Upgrade Steps Overview

升级步骤概览

Quick Upgrade Commands

快速升级命令

Update packages

更新包

Install driver adapter (PostgreSQL example)

安装驱动适配器（PostgreSQL 示例）

Install dotenv for env loading

安装 dotenv 用于加载环境变量

Regenerate client

重新生成客户端

Breaking Changes Summary

重大变更汇总

Rule Files

规则文件

Step-by-Step Migration

分步迁移指南

1. Update package.json for ESM

1. 在 package.json 中配置 ESM

2. Update tsconfig.json

2. 更新 tsconfig.json

3. Update schema.prisma

3. 更新 schema.prisma

4. Create prisma.config.ts

4. 创建 prisma.config.ts

5. Install driver adapter

5. 安装驱动适配器

PostgreSQL

PostgreSQL

MySQL

MySQL

SQLite

SQLite

Prisma Postgres

Prisma Postgres

Neon

Neon

6. Update client instantiation

6. 更新客户端实例化代码

7. Run migrations and generate

7. 运行迁移与生成命令

Troubleshooting

故障排除

"Cannot find module" errors

"无法找到模块" 错误

SSL certificate errors

SSL 证书错误

Connection timeout issues

连接超时问题

Resources

参考资源