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

引言

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

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

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

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

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

Prisma Migrate 是一个强大的迁移工具，涵盖了应用程序开发者管理数据库 schema 的大多数用例。它提供了专为带您从开发到生产以及考虑团队协作而设计的工作流程。

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

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

先决条件

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

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

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

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

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

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

如果您喜欢其他安装方法（例如 Docker 或 Homebrew），可以在此处找到。

接下来，进入使用 Prisma ORM 的项目根目录，创建主Atlas schema 文件，名为 atlas.hcl

现在，将以下代码添加到其中

要获得 Atlas schema 文件的语法高亮显示和其他便利功能，请安装Atlas VS Code 扩展。

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

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

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

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

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

此命令

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

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

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

现在，您需要 apply（应用）生成的迁移，告诉 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 schema 并使用 Atlas 迁移在数据库中反映更改。概括来说，流程如下

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

为了本教程的目的，我们将扩展 Prisma schema，添加一个 Tag 模型，该模型与 Post 模型具有多对多关系

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

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

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

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

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

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

步骤 3：向数据库 schema 添加局部索引

在本节中，您将学习如何使用 Prisma schema 中不支持的功能扩展您的数据库 schema。例如，我们将使用 partial index（局部索引）。

实现此目标的流程如下

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

这次，您无需重新生成 Prisma Client，因为您没有对 Prisma schema 文件进行任何手动编辑。

现在，让我们去添加一个局部索引！

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

然后，将以下代码添加到其中

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

您现在需要调整 atlas.hcl 文件，确保它知道 schema 的新 SQL 代码片段。您可以通过使用 composite_schema 方法来做到这一点。按如下方式调整您的 atlas.hcl 文件

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

Atlas 现在已知道 schema 的更改，因此您可以继续像之前一样生成迁移文件

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

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

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

结论

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

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