使用 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 中称为开发数据库）。与 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 客户端
5. 通过 Prisma 客户端在您的应用程序代码中访问修改后的模式

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

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

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

接下来，您可以使用与之前相同的 atlas migrate apply 命令应用迁移，这次减去 --baseline 选项（请记住将 __DATABASE_URL__ 占位符替换为您自己的数据库连接字符串）。

您的数据库模式现在已更新，但您的 node_modules/@prisma/client 内生成的 Prisma 客户端尚未意识到模式的更改。这就是为什么您需要使用 Prisma CLI 重新生成它的原因。

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

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

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

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

实现此目的的工作流程如下所示：

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

这次，您无需重新生成 Prisma 客户端，因为您没有对 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 可用于增强您的模式管理和迁移工作流程。

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