新数据模型语法：更多模式控制和更简化的迁移

⚠️ 本文已过时，因为它与现已弃用的 Prisma 1 相关。要了解有关最新版本 Prisma 的更多信息，请阅读文档。 ⚠️

在过去的几个月中，我们与社区合作，为 Prisma 定义了改进的数据模型规范。这个新版本称为 datamodel v1.1，已在今天的稳定版本中提供。查看此处的文档。

截至今天，Prisma 的公共演示服务器将使用新的数据模型语法。查看文档或此教程视频，了解如何升级现有项目。

---

一种更灵活的数据建模方法

数据模型是每个 Prisma 项目的基础。它是底层数据库模式的基础。

当前的数据模型对数据库布局有武断的看法，例如，对于关系、表/列的命名或系统字段。新的数据模型语法取消了许多限制，以便开发人员可以更好地控制他们的模式。

更好地控制您的数据库布局

以下是新的数据模型语法启用的一些功能

• 指定关系应使用关系表还是外键
• 模型/字段名称可以与底层表/列的名称不同
• 使用任何字段作为 id 字段并“自带 ID”
• 使用任何字段作为 createdAt 或 updatedAt 字段

更简单的迁移和改进的自省

在以前的 Prisma 版本中，开发人员必须决定 Prisma 是否应为他们执行数据库迁移，方法是在 PRISMA_CONFIG 中设置 migrations 标志。

最新的 Prisma 版本中已删除 migrations 标志，这意味着开发人员现在始终可以手动迁移数据库或使用 Prisma 进行迁移。

我们还在现有数据库的自省方面投入了大量资金，为使用 Prisma 和旧数据库或需要在某些时候执行手动迁移的开发人员实现了流畅的工作流程。

---

改进的数据模型语法中的新功能是什么？

将模型和字段名称映射到底层表和列

使用旧的数据模型语法，表和列始终完全按照数据模型中的模型和字段命名。使用新的 @db 指令，您可以控制底层数据库中应调用的表和列

在这种情况下，底层表将称为 user，列将称为 full_name。

决定关系如何在数据库模式中表示

旧的数据模型对数据库模式中的关系有武断的看法：它们始终表示为关系表。

一方面，这使得可以轻松地将任何现有关系迁移到多对多关系，而无需额外的工作。但是，这种灵活性可能会带来性能损失，因为关系表的查询通常更昂贵。

虽然 1:1 和 1:n 关系现在可以通过外键表示，但 m:n 关系将继续表示为关系表。

使用新的数据模型，开发人员可以完全控制在底层数据库中表达关系。有两种选择

• 通过内联引用（即外键）表示关系
• 通过关系表表示关系

这是一个包含两个关系的示例（一个是内联，另一个使用关系表）

对于内联关系，@relation(link: INLINE) 指令的位置决定了外键存储在关系的哪一端，在本例中，它存储在 User 表中。

使用任何字段作为 id、createdAt 或 updatedAt

使用旧的数据模型，如果开发人员想要自动生成唯一 ID 或跟踪记录的创建/上次更新时间，则需要使用保留字段。

使用新的 @id、@createdAt 和 @updatedAt 指令，现在可以将此功能添加到模型的任何字段

更灵活的 ID

当前的数据模型始终使用 CUID 来生成和存储数据库记录的全局唯一 ID。datamodel v1.1 现在可以维护自定义 ID 以及使用其他 ID 类型（例如，整数、序列或 UUID）。

---

开始使用新的数据模型语法

我们为您准备了两个简短的教程，以探索新的数据模型

• 选项 A：将旧的 Prisma 项目升级到新的数据模型语法
• 选项 B：从头开始使用新的数据模型语法

有关更广泛的教程和有关开始使用现有数据库的说明，请访问文档。

先决条件：安装最新的 Prisma CLI

要安装最新版本的 Prisma CLI，请运行

在 Docker 中运行 Prisma 时，您需要将其 Docker 镜像升级到 1.31。

选项 A：从旧的 Prisma 版本升级

升级现有 Prisma 项目时，您可以简单地运行 prisma introspect 以使用新语法生成数据模型。以下部分和此视频通过示例描述了确切的过程

1. 旧数据模型设置

假设您已经有一个正在运行的 Prisma 项目，该项目使用（旧）数据模型。

2. 升级您的 Prisma 服务器

在用于部署 Prisma 服务器的 Docker Compose 文件中，确保为 prismagraphql/prisma 镜像使用最新的 1.31 Prisma 版本。例如

现在升级正在运行的 Prisma 服务器

3. 通过自省生成新的数据模型

如果您现在运行 prisma deploy，您的 Prisma CLI 将抛出错误，因为您尝试将旧语法的数据模型部署到更新的 Prisma 服务器。

修复这些错误的最简单方法是通过自省生成以新语法编写的数据模型。在 prisma.yml 所在的目录中运行以下命令

这将自省您的数据库并生成另一个使用新语法的数据模型，称为 datamodel-TIMESTAMP.prisma（例如，datamodel-1554394432089.prisma）。对于上面的示例，将生成以下数据模型

4. 部署新的数据模型

最后一步是删除旧的 datamodel.prisma 文件，并将生成的数据模型重命名为 datamodel.prisma（以便 prisma.yml 中的 datamodel 属性指向使用新语法的生成文件）。

完成后，您可以运行

5. 优化您的数据库模式

由于自省没有更改数据库布局的任何内容，因此所有关系仍然表示为关系表。如果您想了解如何迁移旧的 1:1 和 1:n 关系以使用外键，请查看此处的文档。

选项 B：从头开始

在了解了如何升级现有 Prisma 项目之后，我们现在将引导您完成一个简单的设置，在该设置中，我们将从头开始。

1. 创建一个新的 Prisma 项目

让我们首先设置一个新的 Prisma 项目

在交互式向导中，选择以下内容

1. 选择创建新数据库
2. 选择PostgreSQL（如果您喜欢，也可以选择 MySQL）
3. 选择您首选语言的客户端（可选，因为我们不会使用客户端）

在通过 Docker 启动 Prisma 服务器和数据库之前，请为您的数据库启用端口映射。这将稍后允许您使用本地 DB 客户端（例如 Postico 或 TablePlus）连接到数据库。

在生成的 docker-compose.yml 中，取消注释数据库的 Docker 镜像配置中的以下行

2. 定义数据模型

让我们定义一个利用新的 Prisma 功能的数据模型。打开 datamodel.prisma 并将内容替换为以下内容

以下是有关此数据模型定义的一些重要信息

• 每个模型都映射到一个表，该表的名称与模型相同，但使用 @db 指令小写。
• 存在以下关系
  • 1:1 User 和 Profile 之间
  • 1:n User 和 Post 之间
  • n:m Post 和 Category 之间
• User 和 Profile 之间的 1:1 关系在 User 模型上使用 @relation(link: INLINE) 注释。这意味着如果关系存在，数据库中的 user 记录会引用 profile 记录（因为 profile 字段不是必需的，关系可能只是 NULL）。INLINE 的替代方法是 TABLE，在这种情况下，Prisma 将通过专用关系表跟踪关系。
• User 和 Post 之间的 1:n 关系通过 post 表的 author 列内联跟踪关系，即 @relation(link: INLINE) 指令在 Post 模型的 author 字段上推断。
• Post 和 Category 之间的 n:m 关系通过名为 PostToCategory 的专用关系表进行跟踪。此关系表是数据模型的一部分，并使用 @relationTable 指令进行注释。
• 每个模型都有一个使用 @id 指令注释的 id 字段。
• 对于 User 模型，数据库通过使用 @createdAt 指令注释的字段自动跟踪何时创建记录。
• 对于 Post 模型，数据库通过使用 @createdAt 和 @updatedAt 指令注释的字段自动跟踪何时创建和更新记录。

3. 部署数据模型

在下一步中，Prisma 会将此数据模型映射到底层数据库

4. 在 Prisma Admin 中查看和编辑数据

从这里开始，如果您想以编程方式访问数据库中的数据，可以使用Prisma 客户端。在下面，我们将重点介绍如何使用 Prisma Admin 与数据交互。

访问文档，了解如何使用 TablePlus 连接到数据库并探索底层数据库模式。

要在 Prisma Admin 中访问您的数据，您需要导航到 Prisma 项目的 Admin 端点：https://127.0.0.1:4466/_admin

---

分享您的反馈和想法

虽然新的数据模型语法已经包含了我们社区要求的许多功能，但我们仍然看到进一步改进它的机会。例如，数据模型尚未提供多列索引和多态关系。

我们目前正在开发一种新的数据建模语言，它将是当前使用的SDL 的变体。

我们很想听听您对新数据模型的看法。请通过在反馈仓库中打开一个 issue 或加入Spectrum上的对话来分享您的反馈。