升级 Prisma ORM 层 (MySQL)

MySQL

概述

本页解释了升级过程的第一步：将你的 Prisma 1 配置升级到 Prisma ORM 2。具体来说，你将学习如何

添加 Prisma ORM 2 CLI 作为开发依赖
创建你的 Prisma ORM 2 schema
确定你的连接 URL 并连接到数据库
内省你的数据库（到目前为止由 Prisma 1 管理）
使用 Prisma 1 升级 CLI 来解决新 Prisma ORM 2 数据模型中的 schema 不兼容性
安装并生成 Prisma Client

完成这些步骤后，你可以继续阅读下一份指南，它解释了如何升级应用程序层以使用 Prisma Client 进行数据库查询。

注意：在升级过程中，获取数据库的图形视图可能会很有帮助。因此，建议使用图形数据库客户端连接到你的数据库，例如 TablePlus 或 Postico。

1. 安装 Prisma ORM 2 CLI

Prisma ORM 2 CLI 可作为 npm 上的 prisma 包提供，并通过 prisma 命令调用。

请注意，Prisma 1 的旧 prisma 命令已重命名为 prisma1。你可以在此处了解更多信息。

你可以在你的 Node.js 项目中按如下方式安装 Prisma ORM 2 CLI（请务必在你 package.json 所在的目录中调用此命令）

npm install prisma --save-dev

注意：对于 Prisma 1，通常建议全局安装 CLI。我们现在建议本地安装 Prisma CLI 以防止版本冲突。

你现在可以通过在 prisma CLI 前加上 npx 来使用其本地安装。

npx prisma

如果你正在一次性升级整个项目，你现在也可以卸载 Prisma 1 CLI（否则请展开下方内容）

# remove global installation
npm uninstall -g prisma1

# remove local installation
npm uninstall prisma1

如果你想同时使用 Prisma 1 CLI，请展开

如果你想继续使用 Prisma 1 CLI，建议删除其全局安装并添加 prisma1 CLI 作为开发依赖

# installs v1.34 of the Prisma 1 CLI
npm uninstall -g prisma
npm install prisma1 --save-dev

你现在可以按如下方式调用它

npx prisma1

请注意，如果你需要小于 1.34 的 CLI 版本（例如 1.30），你可以按如下方式安装它

# installs v1.30 of the Prisma 1 CLI
npm uninstall -g prisma@1.30
npm install prisma@1.30 --save-dev

你现在可以按如下方式调用它

npx prisma

2. 创建你的 Prisma ORM 2 schema

对于本指南，你将首先使用 prisma init 命令创建一个新的 Prisma schema，然后使用内省用数据模型“填充”它。

运行以下命令创建你的 Prisma schema（请注意，如果你已经有一个名为 prisma 的文件夹，这将抛出错误）

npx prisma init

如果你看到以下错误，你需要重命名你当前的 prisma 目录

ERROR  A folder called prisma already exists in your project.
       Please try again in a project that is not yet using Prisma.

你可以将当前 prisma 目录重命名为 prisma1，以明确这包含以前的 Prisma 1 配置

mv prisma prisma1

现在你可以运行 init，它将成功

npx prisma init

它应该打印以下输出

✔ Your Prisma schema was created at prisma/schema.prisma.
  You can now open it in your favorite editor.

Next steps:
1. Set the `DATABASE_URL` in the `.env` file to point to your existing database. If your database has no tables yet, read https://pris.ly/d/getting-started
2. Set the `provider` of your `datasource` block in `schema.prisma` to match your database: `postgresql`, `mysql` or `sqlite`.
3. Run `prisma db pull` to turn your database schema into a Prisma data model.
4. Run `prisma generate` to install Prisma Client. You can then start querying your database.

More information in our documentation:
https://pris.ly/d/getting-started

该命令创建了一个名为 prisma 的新文件夹和两个文件

prisma/schema.prisma：你的 Prisma schema，指定了数据源、生成器和数据模型（请注意，数据模型尚不存在，它将通过内省生成）。
.env：一个 dotenv 文件，用于配置你的数据库连接 URL。

你的初始 Prisma schema 如下所示

schema.prisma

// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

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

在 Prisma 1 中，你需要在 prisma.yml 中指定你想使用的 Prisma Client 语言变体。在 Prisma ORM 2 中，此信息现在通过 generator 块在 Prisma schema 中指定。

注意：与 Prisma 1 不同，Prisma Client 2.0 的 TypeScript 和 JavaScript 变体使用相同的生成器，名为 prisma-client-js。index.d.ts 中生成的类型始终包含在内，即使在纯 JavaScript 项目中也是如此。这使得即使不使用 TypeScript，也能在 VS Code 中实现自动补全等功能。

3. 确定你的连接 URL 并连接到数据库

在 Prisma 1 中，数据库连接是在用于启动 Prisma ORM 服务器的 Docker Compose 文件中配置的。Prisma ORM 服务器随后暴露一个 GraphQL 端点（通过 HTTP），该端点代理来自 Prisma Client 应用程序代码的所有数据库请求。该 HTTP 端点在你的 prisma.yml 中指定。

在 Prisma ORM 2 中，HTTP 层不再暴露，Prisma Client 2.0 配置为“直接”对数据库运行请求（即，请求由 Prisma ORM 的查询引擎代理，但不再有额外的服务器）。

因此，下一步你需要告诉 Prisma ORM 2 你使用哪种数据库（MySQL 或 PostgreSQL）以及它位于何处。

首先，你需要确保 schema.prisma 中 datasource 块上的 provider 字段配置为使用正确的数据库

如果你使用 PostgreSQL，它需要在 provider 字段中定义值 "postgresql"。
如果你使用 MySQL，它需要在 provider 字段中定义值 "mysql"。

在代码块中切换选项卡以查看两者的示例

PostgreSQL
MySQL

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
}

设置 provider 字段后，你可以继续在 .env 文件中配置连接 URL。

假设你用于部署 Prisma ORM 服务器的 Docker Compose 文件中的数据库配置如下所示

docker-compose.yml

PRISMA_CONFIG: |
  port: 4466
  databases:
    default:
      connector: mysql
      host: mysql
      port: 3306
      user: root
      password: randompassword

另外假设你的 prisma.yml 中的 endpoint 配置如下

prisma.yml

endpoint: http://localhost:4466/myproject/dev

根据这些连接详情，你需要在你的 .env 文件中配置 DATABASE_URL 环境变量，如下所示

.env

DATABASE_URL="mysql://root:randompassword@localhost:3306/myproject@dev"

请注意，连接 URL 中的数据库名称通常由你的服务名称和服务阶段（在 prisma.yml 的 endpoint 中）组成，用 @ 字符分隔。

有时 prisma.yml 中未指定服务名称和阶段

prisma.yml

endpoint: http://localhost:4466/

在这种情况下，数据库名称必须按如下方式指定

.env

DATABASE_URL="mysql://root:randompassword@localhost:3306/default@default"

在连接 URL 页面了解更多信息。

4. 内省你的数据库

为本指南目的，我们将使用以下 Prisma 1 数据模型（选择下方的 SQL 选项卡以查看该数据模型在 SQL 中的映射）

Prisma 1 数据模型
SQL

type User {
  id: ID! @id
  email: String @unique
  name: String!
  role: Role! @default(value: CUSTOMER)
  jsonData: Json
  profile: Profile
  posts: [Post!]!
}

type Post {
  id: ID! @id
  createdAt: DateTime! @createdAt
  updatedAt: DateTime! @updatedAt
  title: String!
  content: String
  published: Boolean! @default(value: false)
  author: User @relation(link: TABLE)
  categories: [Category!]!
}

type Profile {
  id: ID! @id
  bio: String
  user: User! @relation(link: INLINE)
}

type Category {
  id: ID! @id
  name: String!
  posts: [Post!]!
}

enum Role {
  ADMIN
  CUSTOMER
}

CREATE TABLE"User" (
    id character varying(25) PRIMARY KEY,
    email text,
    name text NOT NULL,
    role text NOT NULL,
    "jsonData" text
);
CREATE UNIQUE INDEX "User_pkey" ON"User"(id text_ops);
CREATE UNIQUE INDEX "default$default.User.email._UNIQUE" ON"User"(email text_ops);

CREATE TABLE"Post" (
    id character varying(25) PRIMARY KEY,
    title text NOT NULL,
    published boolean NOT NULL,
    "createdAt" timestamp(3) without time zone NOT NULL,
    "updatedAt" timestamp(3) without time zone NOT NULL,
    content text
);
CREATE UNIQUE INDEX "Post_pkey" ON"Post"(id text_ops);

CREATE TABLE"Profile" (
    id character varying(25) PRIMARY KEY,
    bio text,
    user character varying(25) REFERENCES"User"(id) ON DELETE SET NULL
);
CREATE UNIQUE INDEX "Profile_pkey" ON"Profile"(id text_ops);

CREATE TABLE"Category" (
    id character varying(25) PRIMARY KEY,
    name text NOT NULL
);
CREATE UNIQUE INDEX "Category_pkey" ON"Category"(id text_ops);

CREATE TABLE"_PostToUser" (
    "A" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE,
    "B" character varying(25) NOT NULL REFERENCES"User"(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON"_PostToUser"("A" text_ops,"B" text_ops);
CREATE INDEX "_PostToUser_B" ON"_PostToUser"("B" text_ops);

CREATE TABLE"_CategoryToPost" (
    "A" character varying(25) NOT NULL REFERENCES"Category"(id) ON DELETE CASCADE,
    "B" character varying(25) NOT NULL REFERENCES"Post"(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX "_CategoryToPost_AB_unique" ON"_CategoryToPost"("A" text_ops,"B" text_ops);
CREATE INDEX "_CategoryToPost_B" ON"_CategoryToPost"("B" text_ops);

请注意，此数据模型有三个关系

1-1：User ↔ Profile
1-n：User ↔ Post（通过 _PostToUser 关系表维护）
m-n：Post ↔ Category（通过 _CategoryToPost 关系表维护）

现在你可以使用以下命令对你的数据库运行 Prisma ORM 的内省

npx prisma db pull

这是调用 db pull 时发生情况的图形化说明

Introspect your database

对于上述 Prisma 1 数据模型，这将生成以下 Prisma ORM 2 schema（请注意，模型已重新排序以匹配 Prisma 1 数据模型的初始顺序）

schema.prisma

model User {
  id       String    @id @default(cuid())
  email    String?   @unique
  name     String
  role     String
  jsonData String?
  Profile  Profile[]
  Post     Post[]
}

model Post {
  id        String     @id @default(cuid())
  createdAt DateTime
  updatedAt DateTime
  title     String
  content   String?
  published Boolean
  Category  Category[]
  User      User[]
}

model Profile {
  id   String  @id @default(cuid())
  bio  String?
  user String? @unique
  User User?   @relation(fields: [user], references: [id])
}

model Category {
  id   String @id @default(cuid())
  name String
  Post Post[]
}

尽管这已经是一个有效的 Prisma ORM 2 schema，但它缺少其 Prisma 1 对应版本中的一些功能

Post 上的 createdAt 和 updatedAt 字段没有自动生成的日期值
User 上的 role 字段没有默认值
Post 上的 published 字段没有默认值

此外还存在一些不一致之处，导致 Prisma Client API 不那么符合惯用/人体工程学

User ↔ Profile 是 1-n 关系而不是 1-1 关系
User ↔ Post 是 m-n 关系而不是 1-n 关系
关系字段采用大写（例如 User 上的 Profile 和 Post）
User 上的 jsonData 字段是 String 类型而不是 Json 类型
User 上的 role 字段是 String 类型而不是 Role，role 的 enum 定义完全缺失

尽管这些不一致实际上不会影响你在 Prisma Client API 中可用的“功能集”，但它们会让你失去之前存在的某些约束/保证。

例如，Prisma ORM 现在无法保证一个 User 最多连接到一个 Profile，因为表之间的关系在内省期间被识别为 1-n，所以一个 User 记录现在可能连接到多个 Profile 记录。

另一个问题是，你可以在 jsonData 和 role 字段中存储任何文本，无论它是否为有效的 JSON 或代表 Role 枚举的值。

要了解有关这些不一致的更多信息，请查阅 Schema 不兼容性页面。

接下来，我们将使用 Prisma schema 升级 CLI 逐一解决这些不兼容性。

5. 使用 Prisma schema 升级 CLI 解决 schema 不兼容性

Prisma 1 升级 CLI 是一个交互式工具，可帮助你升级 Prisma schema 并解决上述大部分不一致之处。

Prisma 1 升级 CLI 分两个主要阶段工作

通过纯 SQL 修复数据库 schema
向 Prisma ORM 2 schema 添加缺失属性以及其他 schema 修复

在第一阶段，它将生成并打印一些 SQL 语句，你应该针对你的数据库运行这些语句以调整数据库 schema。你可以运行所有语句，或者在继续第二阶段之前运行其中一部分。

在第二阶段，你无需手动执行任何操作。升级 CLI 将通过添加某些 Prisma ORM 级别属性（例如 @default(cuid)) 或 @updatedAt）、调整关系字段名称以匹配你的 Prisma 1 数据模型中的名称，并确保在你的 Prisma 1 数据模型中两侧都必需的 1-1 关系在 Prisma ORM 2 schema 中也必需，从而更改你的 Prisma schema。

请注意，你可以在过程中的任何时候重新开始，并从第二阶段回到第一阶段。

在此图中，绿色区域显示第一阶段，蓝色区域显示第二阶段。请注意，你可以在阶段之间选择性地运行 prisma db pull 来更新你的 Prisma ORM 数据模型

Fixing the schema incompatibilities

要使用升级 CLI，你可以在项目中本地安装它，或者像这里一样使用 npx 一次性调用而无需安装

npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma

CLI 将向你显示以下消息

◮ Welcome to the interactive Prisma Upgrade CLI that helps with the
upgrade process from Prisma 1 to Prisma ORM 2.

Please read the docs to learn more about the upgrade process:
https://pris.ly/d/how-to-upgrade

➤ Goal
The Upgrade CLI helps you resolve the schema incompatibilities
between Prisma 1 and Prisma ORM 2. Learn more in the docs:
https://pris.ly/d/schema-incompatibilities

➤ How it works
Throughout the process, you'll need to adjust your database schema by sending
SQL statements to it. The SQL statements are provided by the Upgrade CLI.

Note that the Upgrade CLI never makes changes to your database,
you are in full control over any operations that are executed against it.

You can stop and re-run the Upgrade CLI at any time.

These are the different steps of the upgrade process:

  1. The Upgrade CLI generates SQL commands for you to run on your database.
  2. You run the SQL commands against your database.
  3. You run the `npx prisma db pull` command again.
  4. You run the `npx prisma-upgrade` command again.
  5. The Upgrade CLI adjusts the Prisma ORM 2 schema by adding missing attributes.

➤ Note
It is recommended that you make a full backup of your existing data before starting
the upgrade process. If possible, the migration should be performed in a staging
environment before executed against a production environment.

➤ Help
If you have any questions or run into any problems along the way,
please create an issue at:
https://github.com/prisma/prisma1-upgrade/issues/new

Are you ready? [Y/n]

按下 Y 按钮，然后按键盘上的 RETURN 确认以继续。

确认后，CLI 将输出你应该对数据库运行的 SQL 语句

➤ Adjust your database schema
Run the following SQL statements against your database:

  Fix columns with ENUM data types
  https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database

    ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL;


  Add missing `DEFAULT` constraints to the database
  https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database

    ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL DEFAULT 'CUSTOMER';
    ALTER TABLE `Post` CHANGE `published` `published` TINYINT(1) NOT NULL DEFAULT 0;


  Fix columns with JSON data types
  https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database

    ALTER TABLE `User` CHANGE `jsonData` `jsonData` JSON ;


  Replicate `@createdAt` behavior in Prisma ORM 2.0
  https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database

    ALTER TABLE `Post` CHANGE `createdAt` `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP;


  Fix 1-1 relations by adding `UNIQUE` constraints
  https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint

    ALTER TABLE `Profile` ADD UNIQUE (`user`);


  Migrate IDs from varchar(25) to varchar(30)
  https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length

    SET FOREIGN_KEY_CHECKS=0;
    ALTER TABLE `Category` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
    ALTER TABLE `Post` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
    ALTER TABLE `Profile` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
    ALTER TABLE `Profile` CHANGE `user` `user` char(30) CHARACTER SET utf8 ;
    ALTER TABLE `User` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
    SET FOREIGN_KEY_CHECKS=1;

➤ Breaking changes detected

In order to fully optimize your database schema, you'll need to run a few SQL
statements that can break your Prisma 1 setup. Note that these changes are optional
and if you are upgrading gradually and running Prisma 1 and Prisma ORM 2 side-by-side,
you should not perform these changes yet. Instead, you can perform them whenever
you are ready to completely remove Prisma 1 from your project.
If you are upgrading all at once, you can safely perform these changes now.

Learn more in the docs:
https://pris.ly/d/how-to-upgrade'

注意：如果你看到关于破坏性更改的提示，现在可以忽略它。我们稍后会讨论。

显示的 SQL 语句被归类为多个“类别”，所有这些都旨在解决某个 schema 不兼容性

修复 ENUM 数据类型的列
向数据库添加缺失的 DEFAULT 约束
修复 JSON 数据类型的列
在 Prisma 2 中复制 @createdAt 行为
通过添加 UNIQUE 约束修复 1-1 关系

作为下一步，你可以开始将 SQL 语句发送到你的数据库。请注意，所有这些更改都是非破坏性的，你将能够继续与 Prisma ORM 2 同时使用 Prisma 1。

接下来的章节将分别介绍要发送到数据库的不同类型的 SQL 语句。

5.1. 通过纯 SQL 修复数据库 schema（非破坏性）

在本节中，我们将逐一检查打印出的 SQL 语句并针对数据库运行它们。

5.1.1. 修复 ENUM 数据类型的列

该工具所做的第一件事是帮助你确保 Prisma 1 数据模型中的 enum 定义在底层数据库中表示为实际的 ENUM 类型，目前它们被表示为纯字符串（例如 MySQL 中的 MEDIUMTEXT）。

CLI 当前显示以下输出

Fix columns with ENUM data types
https://pris.ly/d/schema-incompatibilities#enums-are-represented-as-text-in-database

  ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL;

现在，继续针对你的数据库运行这些语句。

Altering columns to use ENUM with SQL

5.1.2. 向数据库添加缺失的 `DEFAULT` 约束

接下来，升级 CLI 通过生成 SQL 语句，将相应的 DEFAULT 约束直接添加到数据库中，从而帮助你解决数据库中未表示默认值的问题。

在这种情况下，缺少两个 DEFAULT 约束，这是该工具建议的

Add missing `DEFAULT` constraints to the database
https://pris.ly/d/schema-incompatibilities#default-values-arent-represented-in-database

  ALTER TABLE `User` CHANGE `role` `role` ENUM('ADMIN', 'CUSTOMER') NOT NULL DEFAULT 'CUSTOMER';
  ALTER TABLE `Post` CHANGE `published` `published` TINYINT(1) NOT NULL DEFAULT 0;

你现在可以使用命令行客户端或像 TablePlus 这样的 GUI 对你的数据库运行这些 SQL 语句

TablePlus GUI

5.1.3. 修复 JSON 数据类型的列

接下来，该工具帮助你确保 Prisma 1 数据模型中的 Json 字段在底层数据库中表示为 JSON 列，目前它们被表示为纯字符串（例如 MySQL 中的 MEDIUMTEXT）。

将列类型更改为 JSON 将确保该字段在 Prisma ORM 2 内省期间被正确识别为 Json。

CLI 当前显示以下输出

Fix columns with JSON data types
https://pris.ly/d/schema-incompatibilities#json-type-is-represented-as-text-in-database

  ALTER TABLE `User` CHANGE `jsonData` `jsonData` JSON ;

你现在可以使用命令行客户端或像 TablePlus 这样的 GUI 对你的数据库运行这些 SQL 语句

TablePlus GUI

5.1.4. 在 Prisma ORM 2 中复制 `@createdAt` 行为

该工具接下来所做的是帮助你解决 @createdAt 行为未在数据库中表示的问题

CLI 当前显示以下输出

Replicate `@createdAt` behavior in Prisma ORM 2.0
https://pris.ly/d/schema-incompatibilities#createdat-isnt-represented-in-database

  ALTER TABLE `Post` CHANGE `createdAt` `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP;

你现在可以使用命令行客户端或像 TablePlus 这样的 GUI 对你的数据库运行这些 SQL 语句。

5.1.5. 通过添加 `UNIQUE` 约束修复 1-1 关系

现在，该工具将通过在数据库中为名为 user 的外键列（以 Prisma 1 数据模型中的关系字段命名）添加 UNIQUE 约束，帮助你将 User ↔ Profile 之间的当前 1-n 关系转回 1-1 关系。

CLI 当前显示以下输出

Fix 1-1 relations by adding `UNIQUE` constraints
https://pris.ly/d/schema-incompatibilities#inline-1-1-relations-are-recognized-as-1-n-missing-unique-constraint

  ALTER TABLE `Profile` ADD UNIQUE (`user`);

你现在可以使用命令行客户端或像 TablePlus 这样的 GUI 对你的数据库运行这些 SQL 语句。

5.1.6. 修复 CUID 长度不匹配问题

注意：这些 SQL 语句即使在你更改了底层数据库中的列类型后，仍会继续出现在升级 CLI 中。这是升级 CLI 当前的一个限制。

最后，该工具将通过在数据库中为名为 user 的外键列（以 Prisma 1 数据模型中的关系字段命名）添加 UNIQUE 约束，帮助你将当前类型为 VARCHAR(25) 的 ID 列转换为 VARCHAR(30)。

CLI 当前显示以下输出

Migrate IDs from varchar(25) to varchar(30)
https://pris.ly/d/schema-incompatibilities#mismatching-cuid-length

SET FOREIGN_KEY_CHECKS=0;
ALTER TABLE `Category` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
ALTER TABLE `Post` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
ALTER TABLE `Profile` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
ALTER TABLE `Profile` CHANGE `user` `user` char(30) CHARACTER SET utf8 ;
ALTER TABLE `User` CHANGE `id` `id` char(30) CHARACTER SET utf8 NOT NULL;
SET FOREIGN_KEY_CHECKS=1;

你现在可以使用命令行客户端或像 TablePlus 这样的 GUI 对你的数据库运行这些 SQL 语句。

5.1.7. 检测到破坏性更改

如果升级 CLI 打印了关于破坏性更改的提示，你的数据库 schema 需要进行一些调整，这将破坏 Prisma 1 的兼容性，以便充分优化。

如果没有检测到破坏性更改，你可以跳到第 5.2 节

根据你的升级策略，你可以现在执行这些更改，或者跳到升级 CLI 的下一阶段

如果你遵循逐步并行升级策略，请暂时不要执行这些更改，因为它们会破坏你的 Prisma 1 设置。在这种情况下，你可以通过键入 n 并按下 RETURN 继续到升级 CLI 的下一阶段。
如果你遵循一次性升级策略，你可以现在执行这些更改。在这种情况下，请键入 Y 并按下 RETURN 继续。

5.2. 通过纯 SQL 修复数据库 schema（破坏性）

在本节中，你将解决导致你的 Prisma 1 设置中断的 schema 不兼容性。如果你的项目中仍在运行 Prisma 1，请勿执行这些更改！

5.2.1. 修复不正确的 m-n 关系

现在，升级 CLI 帮助你修复 Prisma 1 使用关系表表示的所有 1-1 和 1-n 关系，这些关系在你的新 Prisma ORM 2 schema 中当前仅作为 m-n 关系存在。具体来说，User ↔ Post 关系就是这种情况，它目前被定义为 m-n 关系，但实际上应该是一个 1-n 关系。

要解决此问题，你需要执行以下迁移

在 Post 上创建一个新的外键列，直接链接到 User 表。
将关系表中的外键值迁移到 Post 上的新外键列中。
删除关系表。

CLI 现在打印出这些说明

➤ Adjust your database schema
Run the following SQL statements against your database:

  Fix one-to-many table relations
  https://pris.ly/d/schema-incompatibilities#all-non-inline-relations-are-recognized-as-m-n

    ALTER TABLE `Post` ADD COLUMN `authorId` char(25) CHARACTER SET utf8 ;
    ALTER TABLE `Post` ADD CONSTRAINT author FOREIGN KEY (`authorId`) REFERENCES `User`(`id`);
    UPDATE `Post`, `_PostToUser` SET `Post`.`authorId` = `_PostToUser`.B where `_PostToUser`.A = `Post`.`id`;
    DROP TABLE `_PostToUser`;


➤ Next Steps

After you executed one or more of the above SQL statements against your database,
please run the following two commands to refresh your Prisma ORM 2 Schema and check
the changes.

  1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema.
  2. Run `npx prisma-upgrade` again.

If you can't or don't want to execute the remaining SQL statements right now, you can
skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2
schema that are not picked up by introspection.

Skip to the last step? [Y/n]?

对于此修复，你需要运行三条 SQL 语句

在 Post 表上创建新列 authorId。此列应该是引用 User 表 id 字段的外键

ALTER TABLE `Post` ADD COLUMN `authorId` char(25) CHARACTER SET utf8 ;
ALTER TABLE `Post` ADD CONSTRAINT author FOREIGN KEY (`authorId`) REFERENCES `User`(`id`);

编写一个 SQL 查询，读取 _PostToUser 关系表中的所有行，并针对每一行
1. 通过查找列 A 中的值找到相应的 Post 记录
2. 将列 B 中的值作为 authorId 的值插入到该 Post 记录中
```
UPDATE `Post`, `_PostToUser` SET `Post`.`authorId` = `_PostToUser`.B where `_PostToUser`.A = `Post`.`id`;
```
删除 _PostToUser 关系表
```
DROP TABLE `_PostToUser`;
```

Fixing incorrect m-n relations with SQL

执行这些命令后，关系表中列 B 的记录的用户 ID 值将迁移到新的 authorId 列。

5.2. 重新内省你的数据库以更新你的 Prisma schema

至此，你已使用升级 CLI 解决了 schema 不兼容性。现在，你可以通过键入 n 并按下 RETURN 来暂时退出升级 CLI。

在本节中，你将通过另一次内省来更新你的 Prisma schema。这一次，Prisma schema 之前的缺陷将得到解决，因为数据库 schema 已经调整

npx prisma db pull

这次，生成的 Prisma schema 如下所示

schema.prisma

model User {
  id       String   @id
  name     String
  email    String?  @unique
  jsonData Json?
  role     Role     @default(CUSTOMER)
  Post     Post[]
  Profile  Profile?
}

model Post {
  id        String     @id
  createdAt DateTime   @default(now())
  updatedAt DateTime
  title     String
  content   String?
  published Boolean    @default(false)
  authorId  String?
  User      User?      @relation(fields: [authorId], references: [id])
  Category  Category[] @relation(references: [id])
}

model Category {
  id   String @id
  name String
  Post Post[] @relation(references: [id])
}

model Profile {
  bio  String?
  id   String  @id
  user String? @unique
  User User?   @relation(fields: [user], references: [id])
}

enum Role {
  ADMIN
  CUSTOMER
}

此 schema 大部分问题已解决，但仍缺少以下内容

5.2. 向 Prisma 2 schema 添加缺失属性以及其他 schema 修复

CLI 现在打印以下内容

➤ What happens next
As a last step, some final adjustments will be made to your Prisma ORM 2 schema
to carry over some Prisma ORM-level attributes that aren't picked up by introspection.

As a last step, some final adjustments will be made to your Prisma ORM 2.0
schema to carry over some Prisma ORM-level attributes that aren't picked
up by introspection.

Warning
Your current Prisma ORM 2.0 schema will be overwritten, so please
make sure you have a backup!

Are you ready? [Y/n]

此时，你可能已经运行了 CLI 打印的所有 SQL 语句，或者跳过了一些。无论哪种情况，你现在都可以进行最后一步，让升级 CLI 添加缺失的 Prisma ORM 2 属性。通常这些属性是以下内容

你的 @id 字段的 @default(cuid())
Prisma 1 中使用此属性的任何字段的 @updatedAt
@map 和 @@map 作为 Prisma 1 中 @db 和 @@db 的替代

在那一步中，升级 CLI 还修复了过渡到 Prisma ORM 2 过程中发生的其他问题

它确保 Prisma 1 中两侧都必需的 1-1 关系在你的 Prisma ORM 2 schema 中也必需
它将关系字段重命名为与你的 Prisma 1 数据模型中相同的名称（即将推出）

要应用这些更改，你可以重新运行升级 CLI

npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma

如果你没有解决所有 schema 不兼容性，升级 CLI 现在会打印剩余的 SQL 语句（以及用于迁移 ID 的语句）。你此时可以忽略它们，并在提示时持续键入 Y 并按下 RETURN 以继续到最后一步。

如果你确实解决了所有 schema 不兼容性，则不会打印 SQL 语句，并且升级 CLI 只输出以下内容

$ npx prisma-upgrade prisma1/prisma.yml prisma/schema.prisma

➤ Next Steps

After you executed one or more of the previous SQL statements against your database,
please run the following two commands to refresh your Prisma ORM 2 schema and check
the changes.

  1. Run `npx prisma db pull` again to refresh your Prisma ORM 2 schema.
  2. Run `npx prisma-upgrade` again.

If you can't or don't want to execute the remaining SQL statements right now, you can
skip to the last step where the Upgrade CLI adds missing attributes to your Prisma ORM 2
schema that are not picked up by introspection.

Skip to the last step? [Y/n]?

再一次，键入 Y 并按下 RETURN 进行确认。

升级 CLI 的最终提示现在要求你确认它将对你的 Prisma schema 进行的上述更改

➤ What happens next
As a last step, some final adjustments will be made to your Prisma ORM 2 schema
to carry over some Prisma ORM-level attributes that aren't picked up by introspection.

As a last step, some final adjustments will be made to your Prisma ORM 2.0
schema to carry over some Prisma ORM-level attributes that aren't picked
up by introspection.

Warning
Your current Prisma ORM 2.0 schema will be overwritten, so please
make sure you have a backup!

Are you ready? [Y/n]

最后一次，键入 Y 并按下 RETURN 进行确认。

这是升级 CLI 的最终输出

Updating prisma/schema.prisma...
Done updating prisma/schema.prisma!

✔ Congratulations, you're all set!

➤ Note
If you didn't execute all generated SQL commands against your database,
you can re-run the Upgrade CLI at any time.

Note that the Upgrade CLI doesn't resolve all of the schema incompatibilities
between Prisma 1 and Prisma ORM 2. If you want to resolve the remaining ones,
you can do so manually by following this guide:
https://pris.ly/d/upgrading-the-prisma-layer

➤ Next steps
Otherwise you can continue your upgrade process by installing Prisma Client 2:
npm install @prisma/client

You can find guides for different upgrade scenarios in the docs:
https://pris.ly/d/upgrade-from-prisma-1

5.3. 最终结果

Prisma schema 的最终版本应如下所示

schema.prisma

model User {
  id       String   @id @default(cuid())
  name     String
  email    String?  @unique
  jsonData Json?
  role     Role     @default(CUSTOMER)
  Post     Post[]
  Profile  Profile?
}

model Post {
  id        String     @id @default(cuid())
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt
  title     String
  content   String?
  published Boolean    @default(false)
  authorId  String?
  User      User?      @relation(fields: [authorId], references: [id])
  Category  Category[] @relation(references: [id])
}

model Profile {
  id   String  @id @default(cuid())
  bio  String?
  user String? @unique
  User User?   @relation(fields: [user], references: [id])
}

model Category {
  id   String @id @default(cuid())
  name String
  Post Post[] @relation(references: [id])
}

enum Role {
  ADMIN
  CUSTOMER
}

5.4. 重命名关系字段

你会注意到此版本的 Prisma ORM 2 schema 的一件事是所有关系字段都以其各自的模型命名，例如

schema.prisma

model User {
  Post    Post[]
  Profile Profile?
}

model Post {
  User     User?      @relation(fields: [authorId], references: [id])
  Category Category[] @relation(references: [id])
}

model Profile {
  User User? @relation(fields: [user], references: [id])
}

model Category {
  Post Post[] @relation(references: [id])
}

这并不理想，你实际上可以手动将它们全部重命名为以前的版本！

因为所有关系字段都是虚拟的，这意味着它们不会在数据库中显现，所以你可以随意命名它们。在这种情况下，所有关系字段都小写，有时是复数形式。

重命名后它们是这样的

schema.prisma

model User {
  posts   Post[]
  profile Profile?
}

model Post {
  author     User?      @relation(fields: [authorId], references: [id])
  categories Category[] @relation(references: [id])
}

model Profile {
  user  String? @unique
  owner User?   @relation(fields: [user], references: [id])
}

model Category {
  posts Post[] @relation(references: [id])
}

注意：对于 User 和 Profile 之间的 1-1 关系，无法将旧名称 user 设置为关系字段。这是因为会与已存在的持有外键的关系标量字段发生命名冲突。在这种情况下，你可以选择一个不同的名称，或者通过 SQL 直接在数据库中重命名外键列。

5.5. 解决剩余的 schema 不兼容性

还有一些 schema 不兼容性尚未由升级 CLI 解决。此时，你仍未修复标量列表。你可以在 Schema 不兼容性页面上找到针对此问题及其他问题的推荐解决方案。

6. 安装并生成 Prisma Client

现在你的 Prisma ORM 2 schema 已准备就绪，你可以使用以下命令安装 Prisma Client

npm install @prisma/client

7. 下一步

恭喜你，你已成功将 Prisma ORM 层升级到 Prisma ORM 2！接下来，你可以使用以下指南之一更新你的应用程序代码

从旧版到新版 Nexus：如果你当前正在使用 GraphQL Nexus 运行 Prisma 1，请选择本指南。
从 prisma-binding 到 Nexus：如果你当前正在使用 prisma-binding 运行 Prisma 1 并希望升级到 Nexus（和 TypeScript），请选择本指南。
从 prisma-binding 到 SDL-first：如果你当前正在使用 prisma-binding 运行 Prisma 1 并希望升级到 SDL-first GraphQL 服务器，请选择本指南。
REST API：如果你当前正在使用 Prisma Client 1 运行 Prisma 1 并正在构建 REST API，请选择本指南。

附赠：Prisma Client API 比较

本节包含 Prisma 1 和 Prisma ORM 2 的 Prisma Client API 的高级别并排比较。有关新的 Prisma Client API 的更多详细信息，你可以查阅 Prisma Client 文档。

读取单个记录

Prisma Client (v1)

const user = await prisma.user({ id: 1 })

Prisma Client (v2)

await prisma.user.findUnique({
  where: { id: 1 },
})

读取记录列表

Prisma Client (v1)

const user = await prisma.users()

Prisma Client (v2)

await prisma.user.findMany()

过滤列表

Prisma Client (v1)

const users = await prisma.users({
  where: {
    name: 'Alice',
  },
})

Prisma Client (v2)

await prisma.user.findMany({
  where: {
    name: 'Alice',
  },
})

分页列表

Prisma Client (v1)

const posts = await prisma.posts({
  skip: 5,
  first: 10,
})

Prisma Client (v2)

await prisma.user.findMany({
  skip: 5,
  take: 10,
})

注意：你可以在相应的发行说明或文档中的分页页面中了解有关新分页 API 的更多信息。

排序列表

Prisma Client (v1)

await prisma.posts({
  orderBy: 'title_ASC',
})

Prisma Client (v2)

await prisma.posts({
  orderBy: {
    title: 'asc',
  },
})

创建记录

Prisma Client (v1)

await prisma.createUser({
  name: 'Alice',
})

Prisma Client (v2)

await prisma.user.create({
  data: {
    name: 'Alice',
  },
})

更新记录

Prisma Client (v1)

await prisma.updateUser({
  where: { id: 1 },
  data: {
    name: 'James',
    email: 'james@prisma.io',
  },
})

Prisma Client (v2)

await prisma.user.update({
  where: { id: 1 },
  data: {
    name: 'James',
    email: 'james@prisma.io',
  },
})

删除记录

Prisma Client (v1)

await prisma.deleteUser({ id: 1 })

Prisma Client (v2)

await prisma.user.delete({
  where: { id: 1 },
})

选择字段与加载关系

在 Prisma 1 中，选择特定字段和/或加载对象关系的唯一方法是使用基于字符串的 $fragment 和 $graphql 函数。在 Prisma ORM 2 中，现在可以使用 select 和 include 以简洁且类型安全的方式完成此操作。

这种方法的另一个好处是，你可以在任何 Prisma Client 查询中使用 select 和 include，例如 findUnique、findMany、create、update、delete 等。

Prisma Client (v1)

await prisma.user({ id: 1 }).$fragment(`
  fragment NameAndEmail on User { id email }`
`)

Prisma Client (v2)

await prisma.user.findUnique({
  where: { id: 1 },
  select: {
    id: true,
    email: true,
  },
})

例如，在 Prisma 1 中，创建新记录并仅在返回对象中检索 id 是不可能的。使用 Prisma ORM 2，你可以按如下方式实现

await prisma.user.create({
  data: {
    name: 'Alice',
  },
  select: {
    id: true,
  },
})

概述​

1. 安装 Prisma ORM 2 CLI​

2. 创建你的 Prisma ORM 2 schema​

3. 确定你的连接 URL 并连接到数据库​

4. 内省你的数据库​

5. 使用 Prisma schema 升级 CLI 解决 schema 不兼容性​

5.1. 通过纯 SQL 修复数据库 schema（非破坏性）​

5.1.1. 修复 ENUM 数据类型的列​

5.1.2. 向数据库添加缺失的 DEFAULT 约束​

5.1.3. 修复 JSON 数据类型的列​

5.1.4. 在 Prisma ORM 2 中复制 @createdAt 行为​

5.1.5. 通过添加 UNIQUE 约束修复 1-1 关系​

5.1.6. 修复 CUID 长度不匹配问题​

5.1.7. 检测到破坏性更改​

5.2. 通过纯 SQL 修复数据库 schema（破坏性）​

5.2.1. 修复不正确的 m-n 关系​

5.2. 重新内省你的数据库以更新你的 Prisma schema​

5.2. 向 Prisma 2 schema 添加缺失属性以及其他 schema 修复​

5.3. 最终结果​

5.4. 重命名关系字段​

5.5. 解决剩余的 schema 不兼容性​

6. 安装并生成 Prisma Client​

7. 下一步​

附赠：Prisma Client API 比较​

读取单个记录​

读取记录列表​

过滤列表​

分页列表​

排序列表​

创建记录​

更新记录​

删除记录​

选择字段与加载关系​

概述

1. 安装 Prisma ORM 2 CLI

2. 创建你的 Prisma ORM 2 schema

3. 确定你的连接 URL 并连接到数据库

4. 内省你的数据库

5. 使用 Prisma schema 升级 CLI 解决 schema 不兼容性

5.1. 通过纯 SQL 修复数据库 schema（非破坏性）

5.1.1. 修复 ENUM 数据类型的列

5.1.2. 向数据库添加缺失的 `DEFAULT` 约束

5.1.3. 修复 JSON 数据类型的列

5.1.4. 在 Prisma ORM 2 中复制 `@createdAt` 行为

5.1.5. 通过添加 `UNIQUE` 约束修复 1-1 关系

5.1.6. 修复 CUID 长度不匹配问题

5.1.7. 检测到破坏性更改

5.2. 通过纯 SQL 修复数据库 schema（破坏性）

5.2.1. 修复不正确的 m-n 关系

5.2. 重新内省你的数据库以更新你的 Prisma schema

5.2. 向 Prisma 2 schema 添加缺失属性以及其他 schema 修复

5.3. 最终结果

5.4. 重命名关系字段

5.5. 解决剩余的 schema 不兼容性

6. 安装并生成 Prisma Client

7. 下一步

附赠：Prisma Client API 比较

读取单个记录

读取记录列表

过滤列表

分页列表

排序列表

创建记录

更新记录

删除记录

选择字段与加载关系