跳到主要内容

心理模型

本指南提供了一个使用 Prisma Migrate 在处理关系型数据库时进行数据库迁移的概念概述。它涵盖了：数据库迁移是什么、它们的价值、以及 Prisma Migrate 是什么，以及如何在不同的环境中使用 Prisma Migrate 演进数据库模式。

如果你正在使用 MongoDB，请使用 prisma db push 来演进你的模式。

什么是数据库迁移？​

数据库迁移是一组受控的更改，用于修改和演进数据库模式的结构。迁移帮助你将数据库模式从一种状态过渡到另一种状态。例如，在迁移中，你可以创建或删除表和列、拆分表中的字段，或向数据库添加类型和约束。

演进数据库模式的模式​

本节描述了用于演进数据库模式的一般模式迁移模式。

两种主要的模式迁移模式是

  • **模型/实体优先迁移：**使用此模式，你可以使用代码定义数据库模式的结构，然后使用迁移工具生成 SQL，例如，用于同步你的应用程序和数据库模式。

Model-first migration flow

  • **数据库优先迁移：**使用此模式，你可以定义数据库的结构，并使用 SQL 将其应用于数据库。然后，你**内省**数据库以生成描述数据库结构的代码，以同步你的应用程序和数据库模式。

Database-first migration flow

info

注意

为简单起见，我们选择了上面的术语来描述演进数据库模式的不同模式。其他工具和库可能使用不同的术语来描述不同的模式。

迁移文件 (SQL) 应该与你的应用程序代码一起存储。它们也应该在版本控制中跟踪，并与团队中其他成员共享。

迁移提供**状态管理**，这将帮助你跟踪数据库的状态。

迁移还允许你在特定时间点复制数据库的状态，这在与团队的其他成员合作时很有用，例如，在不同分支之间切换。

有关数据库迁移的更多信息，请参阅Prisma 数据指南。

什么是 Prisma Migrate？​

Prisma Migrate 是一种数据库迁移工具，支持**模型/实体优先**迁移模式，用于管理本地环境和生产环境中的数据库模式。

在你的项目中使用 Prisma Migrate 时，工作流程应该是迭代的，看起来像这样

本地开发环境（功能分支）

  1. 演进你的 Prisma 模式
  2. 使用prisma migrate dev 或prisma db push 将你的 Prisma 模式与本地开发数据库的数据库模式同步

预览/暂存环境（功能拉取请求）

  1. 将你的更改推送到功能拉取请求
  2. 使用 CI 系统（例如 GitHub Actions）将你的 Prisma 模式和迁移历史记录与你的预览数据库同步，使用 prisma migrate deploy

生产（主分支）

  1. 将你的应用程序代码从功能分支合并到你的主分支
  2. 使用 CI 系统（例如 GitHub Actions）将你的 Prisma 模式和迁移历史记录与你的生产数据库同步，使用 prisma migrate deploy

Prisma Migrate workflow

Prisma Migrate 如何跟踪迁移状态​

Prisma Migrate 使用以下状态来跟踪数据库模式的状态

  • **Prisma 模式：**你定义数据库模式结构的真实来源。
  • **迁移历史记录：**prisma/migrations 文件夹中的 SQL 文件，代表对数据库模式所做的更改的历史记录。
  • **迁移表：**数据库中的 prisma_migrations 表，存储已应用于数据库的迁移的元数据。
  • **数据库模式：**数据库的状态。

Prisma Migrate "state management"

使用 Prisma Migrate 时的要求​

  • 理想情况下，你应该为每个环境使用一个数据库。例如，你可能为开发、预览和生产环境拥有一个单独的数据库。
  • 你在开发环境中使用的数据库是可丢弃的 - 你可以轻松地按需创建、使用和删除数据库。
  • 每个环境中使用的数据库配置应该保持一致。这对于确保在整个工作流程中移动的特定迁移对数据库产生相同的更改至关重要。
  • Prisma 模式作为真实来源 - 描述了你的数据库模式的形状。

使用 Prisma Migrate 演进数据库模式​

本节描述了如何使用 Prisma Migrate 在不同的环境中演进数据库模式：开发、暂存和生产。

开发环境（本地）中的 Prisma Migrate​

使用 prisma migrate dev 跟踪你的迁移历史记录​

prisma migrate dev 命令允许你跟踪对数据库所做的更改。prisma migrate dev 命令会自动生成 SQL 迁移文件（保存在 /prisma/migrations 中），并将它们应用于数据库。当迁移应用于数据库时，数据库中的迁移表 (_prisma_migrations) 也会更新。

Prisma Migrate dev flow

prisma migrate dev 命令使用以下状态跟踪数据库的状态

  • Prisma 模式
  • 迁移历史记录
  • 迁移表
  • 数据库模式

**注意：**用于跟踪迁移状态的状态与Prisma Migrate 如何跟踪迁移状态部分中描述的状态相同。

你可以在将迁移应用于数据库之前使用 --create-only 标志自定义迁移。例如，你可能想要编辑迁移，如果你想要重命名列而不会造成任何数据丢失或加载数据库扩展（在 PostgreSQL 中）和数据库视图（目前不支持）。

在幕后，Prisma Migrate 使用影子数据库 来检测模式漂移 并生成新的迁移。

**注意：**prisma migrate dev 仅用于开发，并且使用可丢弃的数据库。

如果 prisma migrate dev 检测到模式漂移或迁移历史记录冲突，你将被提示重置（删除并重新创建你的数据库）你的数据库，以同步迁移历史记录和数据库模式。

展开以查看使用卡通解释的影子数据库

A cartoon that shows how the shadow database works.

解决模式漂移​

模式漂移发生在预期数据库模式与迁移历史记录中的模式不同时。例如，当你手动更新数据库模式但没有相应地更新 Prisma 模式和 prisma/migrations 时，就会发生这种情况。

对于此类情况，你可以使用 prisma migrate diff 命令来比较你的迁移历史记录并还原对数据库模式所做的更改。

Revert database schema with migrate diff

你可以使用 migrate diff 生成以下任一 SQL：

  • 还原对数据库模式所做的更改，使其与当前 Prisma 模式同步
  • 将数据库模式向前移动，以应用来自 Prisma 模式和 /migrations 的缺失更改

然后，你可以使用 prisma db execute 命令将更改应用于你的数据库。

原型你的模式​

prisma db push 命令允许你同步 Prisma 模式和数据库模式，而无需持久化迁移 (/prisma/migrations)。prisma db push 命令使用以下状态跟踪数据库的状态

  • Prisma 模式
  • 数据库模式

prisma db push development flow

prisma db push 命令在以下情况下很有用：

  • 你想要**快速原型和迭代**本地模式设计，而无需将这些更改部署到其他环境，例如其他开发人员或暂存和生产环境。
  • 您优先考虑达到**预期最终状态**，而不是执行的更改或步骤以达到该状态（无法预览prisma db push所做的更改）。
  • 您无需控制架构更改如何影响数据。无法编排架构和数据迁移 - 如果prisma db push预期更改会导致数据丢失，您可以选择使用--accept-data-loss选项接受数据丢失，或停止该过程 - 无法自定义更改。

如果prisma db push命令检测到对数据库架构的破坏性更改，它将提示您重置数据库。例如，当您向包含现有内容的表添加必填字段但未提供默认值时，就会发生这种情况。

当您的数据库架构与迁移历史记录和迁移表不同步时，就会发生架构漂移。

在暂存和生产环境中使用 Prisma Migrate​

同步您的迁移历史记录​

使用prisma migrate deploy命令，您可以将开发环境中的迁移历史记录与暂存或生产环境中的数据库同步。

在幕后，migrate deploy命令会

  1. 比较已应用的迁移（捕获的_prisma_migrations）和迁移历史记录（/prisma/migrations）
  2. 应用待处理的迁移
  3. 使用新的迁移更新_prisma_migrations表

Workflow of Prisma Migrate

应在自动化的 CI/ CD 环境中运行该命令，例如 GitHub Actions。

如果您没有迁移历史记录（/migrations），例如使用prisma db push，则必须在暂存和生产环境中继续使用prisma db push。请注意对数据库架构应用的更改，因为其中一些更改可能是破坏性的。例如，prisma db push无法识别何时执行列重命名。它将提示您重置数据库（删除和重新创建）。