跳到主要内容

生成向下迁移

本指南描述了如何生成一个向下迁移 SQL 文件,该文件可以回滚给定的迁移文件

关于向下迁移

生成迁移 SQL 文件时,您可能希望同时创建一个“向下迁移”SQL 文件,该文件能够回滚对应“向上迁移”文件中的 schema 更改。请注意,“向下迁移”有时也称为“迁移回滚”。

本指南解释了如何使用 Prisma Migrate 的 migrate diff 命令 来创建向下迁移,以及如何在向上迁移失败的情况下使用 db execute 命令将其应用到您的生产数据库。

警告

本指南仅适用于为关系型数据库生成 SQL 向下迁移。不适用于 MongoDB。

信息

migrate diffdb execute 命令在版本 3.9.0 及更高版本中处于预览状态,并在版本 3.13.0 及更高版本中正式可用。

生成向下迁移时的注意事项

生成向下迁移文件时,需要注意一些事项:

  • 可以使用如何将向下迁移应用到失败的迁移中的步骤,在迁移失败后用于回滚数据库 schema。这需要使用 migrate resolve 命令,该命令只能用于失败的迁移。如果您的向上迁移成功了但您想回滚它,则需要将您的 schema.prisma 文件恢复到向上迁移之前的状态,并使用 migrate dev 命令生成新的迁移。
  • 向下迁移将回滚您的数据库 schema,但作为向上迁移一部分执行的数据和应用代码的其他更改将不会被回滚。例如,如果您的脚本在迁移期间更改了数据,当您运行向下迁移时,这些数据不会被改回。
  • 您将无法使用 migrate diff 来回滚迁移文件中手动更改或添加的 SQL。如果您有任何自定义添加项,例如视图或触发器,您将需要:
    • 按照以下说明创建向下迁移
    • 使用migrate dev --create-only创建向上迁移,以便在将其应用到数据库之前进行编辑
    • 手动将您的自定义 SQL 添加到向上迁移中(例如添加视图)
    • 手动将反向的自定义 SQL 添加到向下迁移中(例如删除视图)

如何生成和运行向下迁移

本节描述了如何与对应的向上迁移一起生成向下迁移 SQL 文件,然后在生产环境向上迁移失败后运行它以回滚数据库 schema。

例如,以下 Prisma schema 包含 UserPost 模型作为起点:

schema.prisma
model Post {
id Int @id @default(autoincrement())
title String @db.VarChar(255)
content String?
author User @relation(fields: [authorId], references: [id])
authorId Int
}

model User {
id Int @id @default(autoincrement())
name String?
posts Post[]
}

您需要先创建向下迁移,然后才能创建相应的向上迁移。

生成迁移

  1. 编辑您的 Prisma schema 以进行向上迁移所需的更改。在此示例中,您将添加新的 Profile 模型:

    schema.prisma
    model Post {
    id Int @id @default(autoincrement())
    title String @db.VarChar(255)
    content String?
    author User @relation(fields: [authorId], references: [id])
    authorId Int
    }

    model Profile {
    id Int @id @default(autoincrement())
    bio String?
    user User @relation(fields: [userId], references: [id])
    userId Int @unique
    }

    model User {
    id Int @id @default(autoincrement())
    name String?
    posts Post[]
    profile Profile?
    }
  2. 生成向下迁移的 SQL 文件。为此,您将使用 migrate diff 进行比较:

    • 从新编辑的 schema
    • 到上一次迁移后的 schema 状态

    并将结果输出到 SQL 脚本 down.sql 中。

    有两种可能的选项用于指定“to”状态:

    • 使用 --to-migrations:这将与迁移目录中给定的迁移状态进行比较。这是首选选项,因为它更健壮,但需要一个影子数据库。要使用此选项,运行:

      npx prisma migrate diff \
      --from-schema-datamodel prisma/schema.prisma \
      --to-migrations prisma/migrations \
      --shadow-database-url $SHADOW_DATABASE_URL \
      --script > down.sql
    • 使用 --to-schema-datasource:这将与数据库状态进行比较。这不需要影子数据库,但依赖于数据库具有最新的 schema。要使用此选项,运行:

      npx prisma migrate diff \
      --from-schema-datamodel prisma/schema.prisma \
      --to-schema-datasource prisma/schema.prisma \
      --script > down.sql
  3. 生成并应用向上迁移,名称为 add_profile

    npx prisma migrate dev --name add_profile

    这将在 prisma/migrations 目录中创建一个新的 <timestamp>_add_profile 目录,其中包含您的新的向上迁移文件 migration.sql

  4. 将您的 down.sql 文件复制到新目录中,与向上迁移文件放在一起。

如何将向下迁移应用到失败的迁移

如果之前的向上迁移失败,您可以使用以下步骤在生产数据库上应用向下迁移:

在向上迁移失败后,将向下迁移应用到您的生产数据库:

  1. 使用 db execute 在数据库服务器上运行您的 down.sql 文件

    npx prisma db execute --file ./down.sql --schema prisma/schema.prisma
  2. 使用 migrate resolve 记录您已回滚名为 add_profile 的向上迁移

    npx prisma migrate resolve --rolled-back add_profile