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

简介

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

在本指南中，您将学习如何在现有 Prisma ORM 项目中用 Atlas 替换 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 database_）。与 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 在您的应用程序代码中访问修改后的模式

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

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

和以前一样，这会在 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 的文件

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

这会在 Post 记录上创建一个索引，其 published 字段设置为 true。当您查询这些已发布文章时，此查询非常有用，例如

您现在需要调整 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 可用于增强您的模式管理和迁移工作流。

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