Prisma版本升级指南从4到5

版本升级的核心目的：
│
├── 安全性
│   ├── 修复安全漏洞
│   ├── 更新依赖版本
│   └── 提升系统安全性
│
├── 功能性
│   ├── 获取新特性
│   ├── 性能优化
│   └── 改进开发体验
│
├── 兼容性
│   ├── 支持新的 Node.js 版本
│   ├── 支持新的 TypeScript 版本
│   └── 支持新的数据库版本
│
└── 维护性
    ├── 保持依赖最新
    ├── 避免技术债务
    └── 便于团队协作

版本升级完整流程：
│
├── 第一步：获取更新信息
│   ├── 检查可用更新
│   └── 查看更新内容
│
├── 第二步：查看变更日志
│   ├── 阅读 Change Log
│   ├── 关注 Removal 和 Deprecated
│   └── 了解 Breaking Changes
│
├── 第三步：执行更新
│   ├── 更新依赖包
│   ├── 生成类型文件
│   └── 处理兼容性问题
│
├── 第四步：测试验证
│   ├── 启动项目
│   ├── 构建项目
│   └── 运行测试
│
└── 第五步：处理问题
    ├── 修复错误
    ├── 替换废弃 API
    └── 调整配置

# 检查过时的依赖
npm outdated

# 输出示例
Package         Current  Wanted  Latest  Location
prisma           4.16.0  4.16.0  5.0.0   node_modules/prisma
@prisma/client   4.16.0  4.16.0  5.0.0   node_modules/@prisma/client

# 安装 npm-check-updates
npm install -g npm-check-updates

# 检查更新
ncu

# 输出示例
@prisma/client   4.16.0  →   5.0.0
prisma           4.16.0  →   5.0.0

# 执行更新（修改 package.json）
ncu -u

# 安装更新后的依赖
npm install

GitHub Releases 查看步骤：
│
├── 第一步：访问 GitHub 仓库
│   └── https://github.com/prisma/prisma
│
├── 第二步：点击 Releases 标签
│   └── 查看所有发布的版本
│
├── 第三步：查看版本详情
│   ├── 版本号和发布时间
│   ├── 更新说明（Release Notes）
│   └── Breaking Changes
│
└── 第四步：查看变更日志
    └── 点击 CHANGELOG.md 链接

官方文档查看步骤：
│
├── 第一步：访问 Prisma 官方文档
│   └── https://www.prisma.io/docs
│
├── 第二步：搜索 Change Log
│   └── 在搜索框输入 "change log"
│
├── 第三步：查看版本迁移指南
│   ├── Upgrade to Prisma 5
│   ├── Breaking Changes
│   └── Deprecation Notices
│
└── 第四步：阅读详细说明
    └── https://www.notion.so/prismaio/Prisma-5-is-here-e7cb65fe3b2741e5a2b7f6a3fb32a4b2

Prisma 5 移除的功能：
│
├── 移除的 API
│   ├── 某些旧的方法签名
│   ├── 废弃的配置选项
│   └── 旧的工具函数
│
├── 移除的特性
│   ├── 旧的迁移系统
│   ├── 废弃的生成器选项
│   └── 旧的连接池配置
│
└── 注意事项
    ├── 检查代码中是否使用
    ├── 查找替代方案
    └── 更新代码实现

// Prisma 4：对象形式
const result = await prisma.user.findMany({
  select: {
    id: true,
    name: true,
    email: true,
  },
});

// Prisma 5：支持数组形式
const result = await prisma.user.findMany({
  select: ['id', 'name', 'email'],  // 更简洁
});

// prisma/schema.prisma

model Product {
  id          Int     @id @default(autoincrement())
  price       Int
  salePrice   Int?
  
  // 多列对比索引
  @@index([price, salePrice])
  
  @@map("products")
}

// 查询价格比促销价高的产品
const products = await prisma.product.findMany({
  where: {
    price: {
      gt: prisma.product.fields.salePrice,  // 对比两列
    },
  },
});

// Prisma 5：支持在 findUnique 中使用更多过滤条件
const user = await prisma.user.findUnique({
  where: {
    id: 1,
  },
  // 可以添加额外的过滤条件
  // 确保返回的记录符合特定条件
});

// 结合唯一字段和非唯一字段过滤
const post = await prisma.post.findUnique({
  where: {
    id: 1,
  },
});

Prisma 5 性能改进：
│
├── 查询优化
│   ├── 减少数据库往返次数
│   ├── 优化 JOIN 查询
│   └── 改进批量操作性能
│
├── 连接池优化
│   ├── 更高效的连接管理
│   ├── 减少连接等待时间
│   └── 提升并发性能
│
└── 类型生成优化
    ├── 更快的 prisma generate
    ├── 更小的生成文件
    └── 改进类型推断

# 1. 检查 Node.js 版本
node -v
# 建议使用 Node.js 18.x 或 20.x

# 2. 检查当前 Prisma 版本
npx prisma -v

# 3. 备份项目
git add .
git commit -m "backup: before upgrade to Prisma 5"
git branch backup-prisma-4

# 4. 查看当前依赖
cat package.json | grep prisma

# 更新 Prisma Client
npm install @prisma/client@5

# 更新 Prisma CLI 和核心库（开发依赖）
npm install -D prisma@5

# 或者使用 pnpm
pnpm update @prisma/client@5
pnpm update -D prisma@5

# 使用 npm-check-updates
ncu -u

# 手动选择要更新的包
ncu -i

# 只更新 prisma 相关
ncu -f prisma,@prisma/client -u

# 安装更新后的依赖
pnpm install

# 更新后必须执行
npx prisma generate

# 输出示例
 Generated Prisma Client (5.0.0 | library) to ./node_modules/@prisma/client in 123ms

You can now start using Prisma Client in your code. Reference: https://pris.ly/d/client

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

# 1. 启动开发服务器
pnpm start:dev

# 2. 构建项目
pnpm build

# 3. 运行测试
pnpm test

# 4. 检查 TypeScript 编译
npx tsc --noEmit

# 错误信息
Error: Cannot find module '@prisma/client/index'

# 解决方案
npx prisma generate

# 错误信息
error: The engine "node" is incompatible with this module.

# 解决方案：升级 Node.js
nvm install 18
nvm use 18

# 或使用 Node.js 20
nvm install 20
nvm use 20

# 错误信息
error TS2749: 'PrismaClient' refers to a value, but is being used as a type here.

# 解决方案：升级 TypeScript
npm install -D typescript@5

# 使用 npm-check-updates 查看所有更新
ncu

# 输出示例
@prisma/client        4.16.0  →   5.0.0
prisma                4.16.0  →   5.0.0
typescript            4.9.5   →   5.0.0
eslint                8.40.0  →   9.0.0
@typescript-eslint/*  5.59.0  →   6.0.0

# 执行更新
ncu -u

# 安装依赖
pnpm install

TypeScript 4 → 5 升级注意：
│
├── 新特性
│   ├── const 类型参数
│   ├── extends 支持多个配置文件
│   └── 枚举增强
│
├── Breaking Changes
│   ├── 更严格的类型检查
│   ├── 某些类型推断变化
│   └── 废弃的编译选项
│
└── 建议
    ├── 阅读 TypeScript 5 Release Notes
    ├── 检查 tsconfig.json 配置
    └── 修复类型错误

ESLint 8 → 9 升级注意：
│
├── 新特性
│   ├── 配置文件格式变更（flat config）
│   ├── 性能优化
│   └── 更好的规则提示
│
├── Breaking Changes
│   ├── .eslintrc 格式废弃
│   ├── 某些规则移除
│   └── 插件接口变更
│
└── 建议
    ├── 迁移到 eslint.config.js
    ├── 更新 ESLint 插件
    └── 检查自定义规则

升级前检查清单：
│
├── 1. 环境准备
│   ├── Node.js 版本是否符合要求
│   ├── 包管理器版本是否最新
│   └── 是否有足够的磁盘空间
│
├── 2. 项目备份
│   ├── 提交当前代码到 Git
│   ├── 创建备份分支
│   └── 备份重要配置文件
│
├── 3. 查看更新内容
│   ├── 阅读 Change Log
│   ├── 关注 Breaking Changes
│   └── 记录需要修改的代码
│
├── 4. 制定升级计划
│   ├── 确定升级顺序
│   ├── 准备回滚方案
│   └── 预留足够时间
│
└── 5. 通知团队成员
    ├── 告知升级计划
    ├── 说明可能的影响
    └── 安排测试时间

#!/bin/bash
# Prisma 升级脚本

echo "=== Prisma 4 → 5 升级脚本 ==="

# 1. 备份当前版本
echo "1. 备份当前版本..."
git add .
git commit -m "chore: backup before Prisma 5 upgrade"

# 2. 检查 Node.js 版本
echo "2. 检查 Node.js 版本..."
NODE_VERSION=$(node -v | cut -d 'v' -f 2 | cut -d '.' -f 1)
if [ "$NODE_VERSION" -lt 16 ]; then
    echo "错误：需要 Node.js 16 或更高版本"
    exit 1
fi

# 3. 更新 Prisma
echo "3. 更新 Prisma..."
pnpm update @prisma/client@5
pnpm update -D prisma@5

# 4. 生成类型文件
echo "4. 生成 Prisma Client..."
npx prisma generate

# 5. 测试构建
echo "5. 测试构建..."
pnpm build
if [ $? -ne 0 ]; then
    echo "构建失败，请检查错误"
    exit 1
fi

# 6. 启动项目
echo "6. 启动项目..."
pnpm start:dev &
sleep 5
if [ $? -eq 0 ]; then
    echo " 升级成功！"
else
    echo " 升级失败，请检查错误"
fi

升级后验证清单：
│
├── 1. 编译验证
│   ├── TypeScript 编译是否通过
│   ├── ESLint 检查是否通过
│   └── 项目是否能正常构建
│
├── 2. 运行验证
│   ├── 开发服务器能否启动
│   ├── 数据库连接是否正常
│   └── API 接口是否正常响应
│
├── 3. 功能验证
│   ├── 核心 CRUD 操作是否正常
│   ├── 关系查询是否正常
│   └── 事务处理是否正常
│
├── 4. 性能验证
│   ├── 响应时间是否正常
│   ├── 内存占用是否正常
│   └── 数据库查询性能
│
└── 5. 文档更新
    ├── 更新 README.md
    ├── 更新依赖版本说明
    └── 记录升级过程中的问题

# 如果升级失败，执行回滚

# 1. 恢复 package.json
git checkout package.json pnpm-lock.yaml

# 2. 重新安装依赖
pnpm install

# 3. 重新生成 Prisma Client
npx prisma generate

# 4. 切换到备份分支（如果需要）
git checkout backup-prisma-4

# 清理依赖缓存
rm -rf node_modules
rm pnpm-lock.yaml

# 重新安装依赖
pnpm install

# 如果仍有问题，逐个更新
pnpm update @prisma/client@5
pnpm update -D prisma@5

# 1. 重新生成 Prisma Client
npx prisma generate

# 2. 重启 TypeScript 服务器（VSCode）
# Cmd + Shift + P → TypeScript: Restart TS Server

# 3. 检查 tsconfig.json 配置
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

// 旧语法（可能不再支持）
const users = await prisma.user.findMany({
  where: {
    AND: [
      { name: { contains: 'John' } },
    ],
  },
});

// 新语法
const users = await prisma.user.findMany({
  where: {
    name: { contains: 'John' },
  },
});

# 1. 检查迁移状态
npx prisma migrate status

# 2. 重新生成迁移
npx prisma migrate dev --name init

# 3. 如果需要重置数据库
npx prisma migrate reset

# 一键升级 Prisma
pnpm update @prisma/client@5 && pnpm update -D prisma@5 && npx prisma generate

# 完整升级流程
ncu -u && pnpm install && npx prisma generate && pnpm build

# 测试升级结果
pnpm start:dev && pnpm test

项目基本信息：
│
├── 项目类型：NestJS + Prisma
├── 当前版本
│   ├── Prisma: 4.16.0
│   ├── Node.js: 16.20.0
│   ├── TypeScript: 4.9.5
│   └── ESLint: 8.40.0
│
└── 目标版本
    ├── Prisma: 5.0.0
    ├── Node.js: 18.x 或 20.x
    ├── TypeScript: 5.x
    └── ESLint: 9.x

# 步骤 1：备份当前版本
git add .
git commit -m "chore: backup before Prisma 5 upgrade"
git branch backup-prisma-4

# 步骤 2：检查 Node.js 版本
node -v  # v16.20.0
nvm install 18
nvm use 18
node -v  # v18.19.0

# 步骤 3：查看可用更新
ncu

# 输出：
# @prisma/client  4.16.0  →  5.0.0
# prisma          4.16.0  →  5.0.0
# typescript      4.9.5   →  5.0.0
# eslint          8.40.0  →  9.0.0

# 步骤 4：更新 Prisma
pnpm update @prisma/client@5
pnpm update -D prisma@5

# 步骤 5：生成类型文件
npx prisma generate
#  Generated Prisma Client (5.0.0)

# 步骤 6：测试启动
pnpm start:dev
#  启动成功

# 步骤 7：测试构建
pnpm build
#  构建成功

# 步骤 8：更新其他依赖
ncu -u
pnpm install

# 步骤 9：再次测试
pnpm start:dev
pnpm build

# 步骤 10：提交代码
git add .
git commit -m "chore: upgrade to Prisma 5"

升级过程中遇到的问题：
│
├── 问题一：找不到 Prisma Client 类型文件
│   ├── 错误：Cannot find module '@prisma/client/index'
│   ├── 原因：更新后未生成类型文件
│   └── 解决：npx prisma generate
│
├── 问题二：Node.js 版本不兼容
│   ├── 错误：The engine "node" is incompatible
│   ├── 原因：Node.js 16 不支持
│   └── 解决：升级到 Node.js 18
│
└── 问题三：TypeScript 类型错误
    ├── 错误：类型推断错误
    ├── 原因：TypeScript 版本过旧
    └── 解决：升级 TypeScript 到 5.x

Prisma 版本升级核心要点：
│
├── 获取更新
│   ├── npm outdated / ncu
│   ├── GitHub Releases
│   └── 官方 Change Log
│
├── 查看更新内容
│   ├── 关注 Removals
│   ├── 关注 Breaking Changes
│   └── 了解新特性
│
├── 执行升级
│   ├── 更新 @prisma/client
│   ├── 更新 prisma (devDependencies)
│   └── 执行 prisma generate
│
├── 测试验证
│   ├── 启动项目
│   ├── 构建项目
│   └── 运行测试
│
└── 处理问题
    ├── 升级 Node.js 版本
    ├── 升级 TypeScript 版本
    └── 替换废弃 API

Prisma 5 主要新特性：
│
├── select 支持数组形式
│   └── select: ['id', 'name', 'email']
│
├── 多列对比支持
│   └── where: { price: { gt: prisma.product.fields.salePrice } }
│
├── 性能优化
│   ├── 查询优化
│   ├── 连接池优化
│   └── 类型生成优化
│
└── 依赖更新
    ├── Node.js 16/18/20
    ├── TypeScript 5.x
    └── PostgreSQL 15/16

学习路径规划：
│
├── 第一阶段：理解概念（1 天）
│   ├── 理解版本升级的重要性
│   ├── 掌握获取更新的方式
│   └── 理解 Breaking Changes
│
├── 第二阶段：实践操作（1 天）
│   ├── 执行 Prisma 升级
│   ├── 解决升级过程中的问题
│   └── 测试验证升级结果
│
└── 第三阶段：深入理解（持续）
    ├── 关注版本发布动态
    ├── 学习新特性使用
    └── 优化升级流程