升级到 Prisma ORM 7

从早期 Prisma ORM 版本升级时，Prisma ORM v7 引入了重大变更。本指南解释了此次升级可能如何影响您的应用程序，并提供了如何处理任何变更的说明。

本页面回答的问题

• Prisma 7 有哪些变化？
• 如何安全升级？
• 哪些重大变更会影响我的应用程序？

对于使用 AI 代理的开发者，我们提供了一个迁移提示，您可以将其添加到项目中以进行自动迁移。

信息

如果您正在使用 MongoDB，请注意 Prisma ORM v7 尚不支持 MongoDB。您目前应继续使用 Prisma ORM v6。v7 中即将支持 MongoDB。

将 prisma 和 @prisma/client 包升级到 v7

要从早期版本升级到 Prisma ORM v7，您需要更新 prisma 和 @prisma/client 包。

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

yarn up prisma@7 @prisma/client@7

pnpm upgrade prisma@7 @prisma/client@7

bun add @prisma/client@7
bun add prisma@7 --dev

危险

在升级之前，请检查下面的每个重大更改，以了解升级可能如何影响您的应用程序。

重大更改

本节概述了 Prisma ORM v7 中的重大变更。

最低支持的 Node.js 和 TypeScript 版本

	最低版本	推荐
Node	20.19.0	22.x
TypeScript	5.4.0	5.9.x

ESM 支持

Prisma ORM 现在作为 ES 模块发布，这是 Bun、Deno 和 Node 中支持的模块格式。在您的 package.json 中将 type 字段设置为 module。

{
  "type": "module",
  "scripts": {...},
}

如果您正在使用 TypeScript，则需要配置 tsconfig.json 才能使用 ES 模块。

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

Prisma schema 变更

较旧的 prisma-client-js प्रोवाइड者将在未来的 Prisma ORM 版本中移除。升级到新的 prisma-client प्रोवाइड者，它使用新的无 Rust 客户端。这将为您提供更快的查询、更小的捆绑包大小，并在部署到服务器时需要更少的系统资源。

之前

generator client {
  provider = "prisma-client-js"
  engineType = "binary"
}

之后

generator client {
  provider = "prisma-client"
}

此外，datasource 块中的其他字段，如 url、directUrl 和 shadowDatabaseUrl 已弃用。您可以在Prisma 配置中配置它们。

如果您之前使用 directUrl 运行迁移，那么您需要将 directUrl 值传递到 prisma.config.ts 的 url 字段中，因为 url 中定义的连接字符串由 Prisma CLI 用于迁移。

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

export default defineConfig({
  datasource: {
    url: env('DATABASE_URL'),
    shadowDatabaseUrl: env('SHADOW_DATABASE_URL')
  },
})

驱动适配器和客户端实例化

创建新的 Prisma Client 的方式已更改，要求所有数据库都使用驱动适配器。此更改与将主 Prisma Client 尽可能精简和开放的举措保持一致。例如，如果您使用 Prisma Postgres，您现在需要 @prisma/adapter-pg 适配器。这也意味着创建新 Prisma Client 的签名略有更改。

之前

import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient({
  datasources: {
    db: { url: process.env.DATABASE_URL },
  },
  datasourceUrl: process.env.DATABASE_URL,
});

之后

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 });

如果您使用 SQLite，可以使用 @prisma/adapter-better-sqlite3。

import { PrismaClient } from './generated/prisma/client';
import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';

const adapter = new PrismaBetterSqlite3({
  url: process.env.DATABASE_URL || 'file:./dev.db'
})

export const prisma = new PrismaClient({ adapter })

环境变量的显式加载

在 Prisma ORM 7.0.0 中，环境变量默认不加载。相反，开发者需要在调用 prisma CLI 时显式加载变量。可以使用像dotenv这样的库来通过读取适当的 .env 文件管理环境变量的加载。

npm install dotenv

yarn add dotenv

pnpm add dotenv

对于 bun 用户，无需采取任何操作，因为 bun 会自动加载 .env 文件。

Prisma 配置现在用于配置 Prisma CLI

Prisma 配置现在是配置 Prisma CLI 如何与您的数据库交互的默认位置。您现在可以配置您的数据库 URL、schema 位置、迁移输出和自定义种子脚本。

信息

prisma.config.ts 文件应放置在项目的根目录（package.json 所在的目录）中。

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

export default defineConfig({
  // the main entry for your schema
  schema: 'prisma/schema.prisma',
  // where migrations should be generated
  // what script to run for "prisma db seed"
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  // The database URL 
  datasource: {
    // Type Safe env() helper 
    // Does not replace the need for dotenv
    url: env('DATABASE_URL'),
  },
})

Metrics 已从客户端扩展中移除

Metrics 预览功能在Prisma ORM 6.14.0中已弃用，并已从 Prisma ORM 7.0.0 中移除。如果您需要此功能，可以使用您的数据库的底层驱动适配器，或使用客户端扩展使此信息可用。

例如，一个基本的 totalQueries 计数器

const total = 0
const prisma = new PrismaClient().$extends({
  client: {
    $log: (s: string) => console.log(s),
    async $totalQueries() { return total; },
  },
  query: {
      $allModels: {
        async $allOperations({ query, args }) {
          total += 1;
          return query(args);
        },
      },
    },
})

async function main() {
  prisma.$log('Hello world')
  const totalQueries = await prisma.$totalQueries()
  console.log(totalQueries)
}

客户端中间件已移除

客户端中间件 API 已移除。如果可能，请使用客户端扩展。

// ❌ Old (removed)
prisma.$use(async (params, next) => {
  // middleware logic
  return next(params)
})
// ✅ New (use extensions)
const prisma = new PrismaClient().$extends({
  query: {
    user: {
      async findMany({ args, query }) {
        // extension logic
        return query(args)
      }
    }
  }
})

各种环境变量已移除

我们移除了一小部分 Prisma 特定的环境变量。

• PRISMA_CLI_QUERY_ENGINE_TYPE
• PRISMA_CLIENT_ENGINE_TYPE
• PRISMA_QUERY_ENGINE_BINARY
• PRISMA_QUERY_ENGINE_LIBRARY
• PRISMA_GENERATE_SKIP_AUTOINSTALL
• PRISMA_SKIP_POSTINSTALL_GENERATE
• PRISMA_GENERATE_IN_POSTINSTALL
• PRISMA_GENERATE_DATAPROXY
• PRISMA_GENERATE_NO_ENGINE
• PRISMA_CLIENT_NO_RETRY
• PRISMA_MIGRATE_SKIP_GENERATE
• PRISMA_MIGRATE_SKIP_SEED