使用 Atlas 和 Prisma ORM 进行高级数据库模式管理

简介

Atlas 是一个强大的数据建模和迁移工具，支持高级数据库模式管理工作流，例如 CI/CD 集成、模式监控、版本控制等。

在本指南中，您将学习如何通过在现有 Prisma ORM 项目中替换 Prisma Migrate 来利用 Atlas 的高级模式管理和迁移工作流。

这样，您仍然可以使用 Prisma ORM 直观的数据模型和类型安全的查询功能，同时利用 Atlas 提供的增强迁移功能。

您可以在 GitHub 上找到本教程的示例仓库。该仓库有与本指南的每个步骤对应的分支。

为什么使用 Atlas 而不是 Prisma Migrate？

Prisma Migrate 是一个强大的迁移工具，涵盖了应用程序开发人员在管理数据库模式时的大多数用例。它提供了专门为将您从开发到生产而设计的工作流，并考虑了团队协作。

然而，为了获得更多功能，您可以在以下场景中使用 Atlas 等专用工具来增强您的迁移工作流：

• 持续集成 (CI)：通过 Atlas，您可以在问题进入生产环境之前通过强大的GitHub Actions、GitLab 和CircleCI Orbs 集成来发现问题。您还可以检测有风险的迁移、测试数据迁移、数据库函数等。
• 持续交付 (CD)：Atlas 可以集成到您的管道中，提供与您的部署机制（例如Kubernetes Operator、Terraform 等）的原生集成。
• 模式监控：Atlas 可以监控您的数据库模式并在其偏离预期状态时向您发出警报。
• 支持底层数据库功能：对高级数据库对象（如视图、存储过程、触发器、行级安全性等）进行自动迁移规划。

先决条件

要成功完成本指南，您需要：

• 一个现有的 Prisma ORM 项目（已安装 prisma 和 @prisma/client 包）
• 一个 PostgreSQL 数据库及其连接字符串
• 您的机器上已安装 Docker（用于管理 Atlas 的临时开发数据库）

出于本指南的目的，我们假设您的 Prisma 模式包含我们作为主要示例在整个文档中使用的标准 User 和 Post 模型。如果您没有 Prisma ORM 项目，可以使用 orm/script 示例来遵循本指南。

此步骤的起点是示例仓库中的 start 分支。

步骤 1：将 Atlas 添加到现有 Prisma ORM 项目

要开始本教程，首先安装 Atlas CLI：

如果您喜欢不同的安装方法（如 Docker 或 Homebrew），您可以在此处找到。

接下来，导航到使用 Prisma ORM 的项目根目录并创建主 Atlas 模式文件，名为 atlas.hcl：

现在，向其中添加以下代码：

要获取 Atlas 模式文件的语法高亮和其他便捷功能，请安装 Atlas VS Code 扩展。

在上面的代码片段中，您正在做两件事：

• 通过 data 块定义一个名为 prisma 的 external_schema：Atlas 能够集成来自各种来源的数据库模式定义。在这种情况下，来源 是由 prisma migrate diff 命令生成的 SQL，该命令通过 program 字段指定。
• 使用 env 块指定有关您的环境（称为 local）的详细信息：
  • dev：指向一个影子数据库（在 Atlas 中称为 dev 数据库）。与 Prisma Migrate 类似，Atlas 也使用影子数据库来“试运行”迁移。您在此处提供的连接类似于 Prisma 模式中的 shadowDatabaseUrl。然而，为了方便起见，我们在此案例中使用 Docker 来管理这些临时数据库实例。
  • schema：指向 Prisma ORM 目标数据库的数据库连接 URL（在大多数情况下，这将与 DATABASE_URL 环境变量相同）。
  • migration：指向您希望存储 Atlas 迁移文件的文件系统目录（类似于 prisma/migrations 文件夹）。请注意，您也排除了 _prisma_migrations 不被 Atlas 的迁移历史记录跟踪。

除了影子数据库，Atlas 的迁移系统和 Prisma Migrate 还有另一个共同点：它们都使用数据库中的专用表来跟踪已应用的迁移历史。在 Prisma Migrate 中，此表名为 _prisma_migrations。在 Atlas 中，它名为 atlas_schema_revisions。

为了告诉 Atlas 您的数据库的当前状态（及其所有现有表和其他数据库对象）应该成为跟踪项目中迁移的起点，您需要进行初始基线迁移。

为此，首先运行以下命令来创建 Atlas 的迁移目录：

此命令

1. 查看您 local 环境的当前状态，并根据 Atlas 模式中定义的 external_schema 生成 SQL 迁移文件。
2. 创建 atlas/migrations 文件夹并将 SQL 迁移文件放入其中。

运行后，您的文件夹结构应类似于此：

此时，Atlas 尚未对您的数据库执行任何操作——它只在您的本地机器上创建了文件。

现在，您需要应用生成的迁移，以告诉 Atlas 这应该是其迁移历史的开始。为此，运行 atlas migrate apply 命令，但这次提供 --baseline __TIMESTAMP__ 选项。

从 Atlas 在 atlas/migrations 中创建的文件名中复制时间戳，并用它替换下一个代码片段中的 __TIMESTAMP__ 占位符值。同样，将 __DATABASE_URL__ 占位符替换为您的数据库连接字符串：

假设生成的迁移文件名为 20241210094213.sql，并且您的数据库正在 postgresql://johndoe:mypassword42@localhost:5432/example-db?search_path=public&sslmode=disable 运行，则该命令应如下所示：

命令输出将显示以下内容：

如果您现在检查您的数据库，您会发现 atlas_schema_revisions 表已创建，并包含两个条目，指定了 Atlas 迁移历史的开始。

您的项目现在应该处于类似于示例仓库的 step-1 分支的状态。

步骤 2：使用 Atlas 运行迁移

接下来，您将学习如何编辑 Prisma 模式并使用 Atlas 迁移在数据库中反映更改。从高层次来看，该过程将如下所示：

1. 更改 Prisma 模式
2. 运行 atlas migrate diff 创建迁移文件
3. 运行 atlas migrate apply 对数据库执行迁移文件
4. 运行 prisma generate 更新您的 Prisma Client
5. 通过 Prisma Client 在您的应用程序代码中访问修改后的模式

出于本教程的目的，我们将使用一个 Tag 模型扩展 Prisma 模式，该模型与 Post 模型具有多对多关系：

完成更改后，现在运行命令以在您的机器上创建迁移文件：

像以前一样，这会在 atlas/migrations 文件夹中创建一个新文件，例如 20241210132739.sql，其中包含反映数据模型更改的 SQL 代码。在上面我们的更改中，它将如下所示：

接下来，您可以使用与之前相同的 atlas migrate apply 命令应用迁移，这次不带 --baseline 选项（请记住替换 __DATABASE_URL__ 占位符）：

您的数据库模式现在已更新，但 node_modules/@prisma/client 中的生成的 Prisma Client 尚不知道模式更改。这就是为什么您需要使用 Prisma CLI 重新生成它：

现在，您可以进入您的应用程序代码并对更新的模式运行查询。在我们的示例中，这将是一个涉及新 Tag 模型的查询，例如：

您的项目现在应该处于类似于示例仓库的 step-2 分支的状态。

步骤 3：向数据库模式添加部分索引

在本节中，您将学习如何使用 Prisma 模式不支持的功能扩展数据库模式。例如，我们将使用一个部分索引。

实现此工作流如下：

1. 在 atlas 目录中创建一个反映所需更改的 SQL 文件
2. 更新 atlas.hcl 以包含该 SQL 文件，以便 Atlas 知道它
3. 运行 atlas migrate diff 创建迁移文件
4. 运行 atlas migrate apply 对数据库执行迁移文件

这次，您无需重新生成 Prisma Client，因为您没有手动编辑 Prisma 模式文件。

让我们添加一个部分索引！

首先，在 atlas 目录中创建一个名为 published_posts_index.sql 的文件：

然后，向其中添加以下代码：

这会为 published 字段设置为 true 的 Post 记录创建一个索引。当您查询这些已发布的帖子时，此查询很有用，例如：

您现在需要调整 atlas.hcl 文件，以确保它知道模式的新 SQL 片段。您可以通过使用 composite_schema 方法来实现。按如下方式调整您的 atlas.hcl 文件：

请注意，composite_schema 仅通过 Atlas Pro 计划可用，并且需要您通过 atlas login 进行身份验证。

Atlas 现在知道模式更改，因此您可以像以前一样继续生成迁移文件：

您会再次在 atlas/migrations 目录中看到一个新文件。继续使用与之前相同的命令执行迁移（将 __DATABASE_URL__ 替换为您自己的连接字符串）：

恭喜！您的数据库现在已更新，包含一个部分索引，这将使您对已发布帖子的查询更快。

您的项目现在应该处于类似于示例仓库的 step-3 分支的状态。

结论

在本教程中，您学习了如何将 Atlas 集成到现有 Prisma ORM 项目中。使用 Prisma ORM 时，Atlas 可用于增强您的模式管理和迁移工作流。

如果您想快速查看本教程的最终结果，请查看示例仓库。