跳到主内容

关于迁移历史

本页介绍 Prisma ORM 如何使用迁移历史来跟踪您的数据模型变更。

迁移历史​

您的迁移历史是数据模型变更的记录，它通过以下方式表示：

  • 一个 prisma/migrations 文件夹，其中包含每个迁移的子文件夹和 migration.sql 文件

    migrations/
      └─ 20210313140442_init/
        └─ migration.sql
      └─ 20210313140442_added_job_title/
        └─ migration.sql

    migrations 文件夹是您的数据模型历史的唯一真实来源。

  • 数据库中的 _prisma_migrations 表，用于检查

    • 迁移是否已在数据库上运行
    • 已应用的迁移是否被删除
    • 已应用的迁移是否被更改

    如果您更改或删除迁移（不推荐），接下来的步骤取决于您是在开发环境（因此使用 migrate dev）还是在生产/测试环境（因此使用 migrate deploy）。

不要编辑或删除已应用的迁移​

通常，您不应编辑或删除已应用的迁移。这样做可能导致开发环境和生产环境的迁移历史之间出现不一致，从而产生不可预见的后果——即使更改最初看起来没有破坏任何东西。

以下场景模拟了导致看似无害不一致的更改：

  1. 通过将 VARCHAR(550) 的值更改为 VARCHAR(560)，修改已在开发环境中应用的现有迁移
    ./prisma/migrations/20210310143435_default_value/migrations.sql
      -- AlterTable
     ALTER TABLE "Post" ALTER COLUMN "content" SET DATA TYPE VARCHAR(560);
    进行此更改后，迁移历史的最终状态不再与 Prisma Schema 匹配，Prisma Schema 仍为 @db.VarChar(550)。
  2. 运行 prisma migrate dev 会导致错误，因为迁移已被更改，并建议重置数据库。
  3. 运行 prisma migrate reset - Prisma Migrate 会重置数据库并重新运行所有迁移，包括您编辑的迁移。
  4. 应用所有现有迁移后，Prisma Migrate 将迁移历史的最终状态与 Prisma Schema 进行比较并检测到差异：
    • Prisma Schema 为 @db.VarChar(550)
    • 数据库 Schema 为 VARCHAR(560)
  5. Prisma Migrate 会生成一个新的迁移，将值改回 550，因为迁移历史的最终状态应与 Prisma Schema 匹配。
  6. 从现在起，当您使用 prisma migrate deploy 将迁移部署到生产和测试环境时，Prisma Migrate 将始终警告您迁移历史不匹配（并且每次运行命令时都会继续警告您）——即使 Schema 的最终状态匹配。 
    6 migrations found in prisma/migrations
    WARNING The following migrations have been modified since they were applied:
    20210310143435_change_type

在 migrate reset 后看似没有破坏任何东西的更改可能会隐藏问题——您最终可能会在生产环境中遇到在开发环境中无法复现的错误，反之亦然——特别是如果更改涉及高度定制的迁移。

如果 Prisma Migrate 报告已应用的迁移缺失或被编辑，我们建议修复根本原因（恢复文件或撤销更改），而不是重置。

将迁移历史提交到源代码管理​

您必须将整个 prisma/migrations 文件夹提交到源代码管理。这包括 prisma/migrations/migration_lock.toml 文件，该文件用于检测您是否尝试更改提供程序。

仅对 schema.prisma 文件进行源代码管理是不够的——您必须包含迁移历史。这是因为：

  • 当您开始自定义迁移时，您的迁移历史包含无法在 Prisma Schema 中表示的信息。例如，您可以自定义迁移以减轻由破坏性更改引起的数据丢失。
  • 用于将更改部署到预生产、测试和生产环境的 prisma migrate deploy 命令仅运行迁移文件。它不使用 Prisma Schema 来获取模型。
© . All rights reserved.