心智模型

本指南提供了在使用关系数据库时使用 Prisma Migrate 进行数据库迁移的概念性概述。它涵盖：什么是数据库迁移、它们的价值、什么是 Prisma Migrate 以及如何在不同环境中使用 Prisma Migrate 改进数据库架构。

¥This guide provides a conceptual overview of database migrations using Prisma Migrate when working with relational databases. It covers: what database migrations are, their value, and what Prisma Migrate is and how you can evolve your database schema with Prisma Migrate in different environments.

如果你正在使用 MongoDB，请使用 prisma db push 来改进你的架构。

¥If you are working with MongoDB, use prisma db push to evolve your schema.

什么是数据库迁移？

¥What are database migrations?

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

¥Database migrations are a controlled set of changes that modify and evolve the structure of your database schema. Migrations help you transition your database schema from one state to another. For example, within a migration you can create or remove tables and columns, split fields in a table, or add types and constraints to your database.

演化数据库模式的模式

¥Patterns for evolving database schemas

本节描述不断发展的数据库模式的一般模式迁移模式。

¥This section describes general schema migration patterns for evolving database schemas.

两种主要的架构迁移模式是：

¥The two main schema migration patterns are:

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

  ¥Model/Entity-first migration: with this pattern, you define the structure of the database schema with code and then use a migration tool to generate the SQL, for example, for syncing your application and database schema.

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

  ¥Database-first migration: with this pattern, you define the structure of your database and apply it to your database using SQL. You then introspect the database to generate the code that describes the structure of your database to sync your application and database schema.

信息

注意

¥Note

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

¥For simplicity, we chose the terminology above to describe the different patterns for evolving database schemas. Other tools and libraries may use different terminology to describe the different patterns.

理想情况下，迁移文件 (SQL) 应与应用代码存储在一起。它们还应该在版本控制中进行跟踪，并与处理应用的团队的其他成员共享。

¥The migration files (SQL) should ideally be stored together with your application code. They should also be tracked in version control and shared with the rest of the team working on the application.

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

¥Migrations provide state management which helps you to track the state of the database.

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

¥Migrations also allow you to replicate the state of a database at a specific point in time which is useful when collaborating with other members of the team, e.g. switching between different branches.

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

¥For further information on database migrations, see the Prisma Data Guide.

什么是 Prisma 迁移？

¥What is Prisma Migrate?

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

¥Prisma Migrate is a database migration tool that supports the model/ entity-first migration pattern to manage database schemas in your local environment and in production.

在项目中使用 Prisma Migrate 时的工作流程将是迭代的，如下所示：

¥The workflow when using Prisma Migrate in your project would be iterative and look like this:

本地开发环境（Feature 分支）

¥Local development environment (Feature branch)

1. 发展你的 Prisma 架构

   ¥Evolve your Prisma schema

2. 使用 prisma migrate dev 或 prisma db push 将 Prisma 架构与本地开发数据库的数据库架构同步

   ¥Use either prisma migrate dev or prisma db push to sync your Prisma schema with the database schema of your local development database

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

¥Preview/ staging environment(Feature pull request)

1. 将你的更改推送到功能拉取请求

   ¥Push your changes to the feature pull request

2. 使用 CI 系统（例如 GitHub Actions）将你的 Prisma 架构和迁移历史记录与使用 prisma migrate deploy 的预览数据库同步

   ¥Use a CI system (e.g. GitHub Actions) to sync your Prisma schema and migration history with your preview database using prisma migrate deploy

生产（主干）

¥Production (main branch)

1. 将应用代码从功能分支合并到主分支

   ¥Merge your application code from the feature branch to your main branch

2. 使用 CI 系统（例如 GitHub Actions）使用 prisma migrate deploy 将 Prisma 架构和迁移历史记录与生产数据库同步

   ¥Use a CI system (e.g. GitHub Actions) to sync your Prisma schema and migration history with your production database using prisma migrate deploy

Prisma Migrate 如何跟踪迁移状态

¥How Prisma Migrate tracks the migration state

Prisma Migrate 使用以下状态来跟踪数据库架构的状态：

¥Prisma Migrate uses the following pieces of state to track the state of your database schema:

• Prisma 架构：定义数据库模式结构的事实来源。

  ¥Prisma schema: your source of truth that defines the structure of the database schema.

• 迁徙历史：prisma/migrations 文件夹中的 SQL 文件代表对数据库架构所做的更改历史记录。

  ¥Migrations history: SQL files in your prisma/migrations folder representing the history of changes made to your database schema.

• 迁移表：数据库中的 prisma_migrations 表，用于存储已应用于数据库的迁移的元数据。

  ¥Migrations table: prisma_migrations table in the database that stores metadata for migrations that have been applied to the database.

• 数据库架构：数据库的状态。

  ¥Database schema: the state of the database.

使用 Prisma Migrate 时的要求

¥Requirements when working with Prisma Migrate

• 理想情况下，你应该为每个环境使用一个数据库。例如，你可能有一个单独的数据库用于开发、预览和生产环境。

  ¥Ideally, you should use one database per environment. For example, you might have a separate database for development, preview, and production environments.

• 你在开发环境中使用的数据库是一次性的 - 你可以根据需要轻松创建、使用和删除数据库。

  ¥The databases you use in development environments are disposable — you can easily create, use, and delete databases on demand.

• 各个环境使用的数据库配置应该一致。这对于确保跨工作流移动的特定迁移对数据库产生相同的更改非常重要。

  ¥The database configuration used in each environments should be consistent. This is important to ensure a certain migration that moves across the workflow yields the same changes to the database.

• Prisma 架构作为事实来源 — 描述 数据库模式 的形状。

  ¥The Prisma schema serves as the source of truth — describing the shape of your database schema.

使用 Prisma Migrate 改进你的数据库架构

¥Evolve your database schema with Prisma Migrate

本节介绍如何在不同环境中发展数据库架构：使用 Prisma Migrate 进行开发、暂存和生产。

¥This section describes how you can evolve your database schema in different environments: development, staging, and production, using Prisma Migrate.

Prisma 在开发环境中迁移（本地）

¥Prisma Migrate in a development environment (local)

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

¥Track your migration history with prisma migrate dev

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

¥The prisma migrate dev command allows you to track the changes you make to your database. The prisma migrate dev command automatically generates SQL migration files (saved in /prisma/migrations) and applies them to the database. When a migration is applied to the database, the migrations table (_prisma_migrations) in your database is also updated.

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

¥The prisma migrate dev command tracks the state of the database using the following pieces of state:

• Prisma 模式

  ¥the Prisma schema

• 迁徙历史

  ¥the migrations history

• 迁移表

  ¥the migrations table

• 数据库模式

  ¥the database schema

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

¥Note: The pieces of state used to track the state of a migration are the same as the ones described in how Prisma Migrate tracks the migration state section.

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

¥You can customize migrations before you apply them to the database using the --create-only flag. For example, you might want to edit a migration if you want to rename columns without incurring any data loss or load database extensions (in PostgreSQL) and database views (currently not supported).

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

¥Under the hood, Prisma Migrate uses a shadow database to detect a schema drift and generate new migrations.

注意：prisma migrate dev 仅用于一次性数据库的开发。

¥Note: prisma migrate dev is intended to be used only in development with a disposable database.

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

¥If prisma migrate dev detects a schema drift or a migration history conflict, you will be prompted to reset (drop and recreate your database) your database to sync the migration history and the database schema.

Expand to see the shadow database explained using a cartoon

解决架构漂移

¥Resolve schema drifts

当预期的数据库架构与迁移历史记录中的架构不同时，就会发生架构漂移。例如，当你手动更新数据库架构而不同时更新 Prisma 架构和 prisma/migrations 时，可能会发生这种情况。

¥A schema drift occurs when the expected database schema is different from what is in the migration history. For example, this can occur when you manually update the database schema without also updating the Prisma schema and prisma/migrations accordingly.

对于此类实例，你可以使用 prisma migrate diff 命令来比较迁移历史记录并恢复对数据库架构所做的更改。

¥For such instances, you can use the prisma migrate diff command to compare your migration history and revert changes made to your database schema.

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

¥You can use migrate diff to generate the SQL that either:

• 恢复数据库模式中所做的更改以将其与当前 Prisma 模式同步

  ¥Reverts the changes made in the database schema to synchronize it with the current Prisma schema

• 向前移动数据库架构以应用 Prisma 架构和 /migrations 中缺失的更改

  ¥Moves your database schema forward to apply missing changes from the Prisma schema and /migrations

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

¥You can then apply the changes to your database using prisma db execute command.

构建你的架构原型

¥Prototype your schema

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

¥The prisma db push command allows you to sync your Prisma schema and database schema without persisting a migration (/prisma/migrations). The prisma db push command tracks the state of the database using the following pieces of state:

• Prisma 模式

  ¥the Prisma schema

• 数据库模式

  ¥the database schema

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

¥The prisma db push command is useful when:

• 你希望在本地快速构建原型并迭代架构设计，而不需要将这些更改部署到其他环境（例如其他开发者或登台和生产环境）。

  ¥You want to quickly prototype and iterate on schema design locally without the need to deploy these changes to other environments such as other developers, or staging and production environments.

• 你优先考虑达到所需的最终状态，而不是为达到该最终状态而执行的更改或步骤（无法预览 prisma db push 所做的更改）

  ¥You are prioritizing reaching a desired end-state and not the changes or steps executed to reach that end-state (there is no way to preview changes made by prisma db push)

• 你不需要控制架构更改如何影响数据。无法协调架构和数据迁移 - 如果 prisma db push 预计更改将导致数据丢失，你可以使用 --accept-data-loss 选项接受数据丢失或停止该过程 - 无法自定义更改。

  ¥You do not need to control how schema changes impact data. There is no way to orchestrate schema and data migrations - if prisma db push anticipates that changes will result in data loss, you can either accept data loss with the --accept-data-loss option or stop the process - there is no way to customize the changes.

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

¥If the prisma db push command detects destructive change to your database schema, it will prompt you to reset your database. For example, this will happen when you add a required field to a table with existing content without providing a default value.

当你的数据库架构与迁移历史记录和迁移表不同步时，就会出现 图式漂移。

¥A schema drift occurs when your database schema is out of sync with your migrations history and migrations table.

Prisma 在临时和生产环境中迁移

¥Prisma Migrate in a staging and production environment

同步你的迁移历史记录

¥Sync your migration histories

prisma migrate deploy 命令允许你将开发环境中的迁移历史记录与暂存或生产环境中的数据库同步。

¥The prisma migrate deploy command allows you to sync your migration history from your development environment with your database in your staging or production environment.

在幕后，migrate deploy 命令：

¥Under the hood, the migrate deploy command:

1. 比较已应用的迁移（捕获的 _prisma_migrations）和迁移历史记录（/prisma/migrations）

   ¥Compares already applied migrations (captured _prisma_migrations) and the migration history (/prisma/migrations)

2. 应用待处理的迁移

   ¥Applies pending migrations

3. 使用新迁移更新 _prisma_migrations 表

   ¥Updates _prisma_migrations table with the new migrations

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

¥The command should be run in an automated CI/ CD environment, for example GitHub Actions.

如果你没有迁移历史记录 (/migrations)，即使用 prisma db push，则必须在临时和生产环境中继续使用 prisma db push。请注意应用于数据库模式的更改，因为其中一些更改可能具有破坏性。例如，prisma db push 无法判断你何时执行列重命名。它将提示数据库重置（删除并重新创建）。

¥If you don't have a migration history (/migrations), i.e using prisma db push, you will have to continue using prisma db push in your staging and production environments. Beware of the changes being applied to the database schema as some of them might be destructive. For example, prisma db push can't tell when you're performing a column rename. It will prompt a database reset (drop and re-creation).