QSL

blog

0%

prisma

Posted on Disqus:

Prisma 命令行

Prisma CLI 提供了一套完整的命令来支持数据库的开发、迁移和维护工作。下面我将主要命令按照开发流程和环境进行分类说明，并特别注明在 PostgreSQL 数据库下的注意事项。

核心命令速览

下表汇总了Prisma的核心CLI命令及其主要用途，你可以对其有个快速的整体印象。

命令 主要用途 典型使用场景
prisma init 初始化一个新的Prisma项目结构。 新项目搭建，创建schema.prisma和.env文件模板。
prisma generate 根据数据模型生成Prisma Client（类型安全的查询客户端）。 每次修改schema.prisma文件后都必须运行，以使更改生效于代码。
prisma db pull 从现有数据库提取结构，生成Prisma数据模型（反向工程）。 接管一个已有的数据库项目。
prisma db push 将Prisma数据模型中的更改直接同步到数据库，不生成迁移文件。 仅用于开发环境的快速原型设计，切勿在生产环境使用。
prisma migrate dev 在开发环境中，创建并应用数据库迁移文件，同时生成Client。 开发阶段管理所有数据库结构变更的主要命令。
prisma migrate deploy 将已生成的迁移文件应用到生产环境数据库。 在生产服务器上部署最新的数据库结构变更。
prisma migrate resolve 手动解决迁移冲突，标记某个迁移为已应用或已回滚。 当migrate deploy失败，数据库状态与迁移历史不一致时。
prisma migrate reset 重置整个数据库，清空所有数据并重新应用所有迁移。 开发或测试环境中，需要回归到初始干净状态时。
prisma studio 启动一个Web界面，用于直观地查看和编辑数据库中的数据。 开发调试时快速查看、修改数据。
prisma db seed 运行种子脚本，为数据库填充初始数据。 在migrate reset后或首次初始化数据库后自动填充基础数据。

执行prisma migrate系列命令，会产生数据记录表_prisma_migrations，记录每次迁移的详细信息，包括名称、开始时间、结束时间、状态等。Prisma在数据库中的id是迁移文件的MD5哈希值，所以迁移结束后手动修改迁移文件也会报不一致的错误。

开发环境工作流

在开发过程中，你会频繁使用以下命令来迭代你的数据模型。

  1. 定义与同步模型
    修改 prisma/schema.prisma 文件，定义你的数据模型（Models）。

  2. 创建与应用迁移
    当你对数据模型感到满意时，运行以下命令来创建一次正式的迁移记录：

     
    1
    npx prisma migrate dev --name your_migration_name
    
 这个命令会：
 - 在 `/prisma/migrations` 目录下生成一个包含SQL语句（如`CREATE TABLE`, `ALTER TABLE`）的迁移文件。
 - 立即将这份迁移文件应用到你的开发数据库。
 - 自动运行 `prisma generate`，确保Prisma Client是最新的。

  3. 重置与填充数据
    如果开发数据库陷入混乱，可以使用 prisma migrate reset 来彻底重置它。这个命令会清空数据库并重新从头应用所有迁移。你可以在 package.json 的 prisma 段配置 seed 命令，这样在 reset 后会自动运行，为数据库填充初始测试数据。

生产环境部署流程

生产环境的操作需要更加谨慎，核心原则是：只应用已经生成并经过测试的迁移文件，绝不直接修改数据库结构。

  1. 准备迁移文件：在开发环境中，通过 prisma migrate dev 创建的所有迁移文件（位于 /prisma/migrations 目录）都需要纳入版本控制系统。
  2. 部署应用：将你的应用代码（包括Prisma Client和迁移文件目录）部署到生产服务器。
  3. 应用迁移：在生产服务器上，运行以下命令来更新数据库结构： 
    1
    npx prisma migrate deploy
    这个命令会检查数据库中的 _prisma_migrations 表，找出所有尚未应用的迁移文件，然后按创建顺序依次执行。它不会使用本地的 schema.prisma 文件来修改数据库。
  4. 生成客户端：在部署脚本中，确保在应用迁移后运行 prisma generate，以确保生产服务器上的Prisma Client与数据库结构匹配。

关键注意事项与技巧

  • db push 与 migrate dev 的区别：这是最重要的概念。db push 是一个直接同步工具，方便快速迭代，但无版本迁移记录。migrate dev 是正式的、可版本化的数据库变更管理方式。生产环境必须使用迁移工作流。
  • 安全处理字段重命名：默认情况下，在Prisma模型中重命名字段会生成 DROP COLUMN 和 ADD COLUMN 的SQL，导致原有数据丢失。为了安全地重命名，可以使用 --create-only 参数先创建迁移文件，然后手动修改生成的SQL文件，将 DROP 和 ADD 改为 RENAME COLUMN，再应用迁移。
  • 解决迁移冲突：如果生产环境数据库的状态与迁移历史记录不一致，migrate deploy 会失败。此时可以使用 prisma migrate resolve 命令手动将某个迁移标记为已应用或已回滚，来解决冲突。
  • 回滚迁移：如果在开发过程中发现某个迁移有误，可以使用 prisma migrate resolve --rolled-back "your_migration_name" 将其标记为已回滚，然后重新创建正确的迁移。

禁止

  • **不要在生产环境使用 db push**：它会直接修改数据库结构，且无法追踪变更历史。
  • 不要在生产环境使用 migrate reset: 它会清空所有数据并重置数据库，仅用于开发环境。

Q&A

1. 如果在开发环境prisma migrate reset，接着又进行了了数据库schema的修改去修改Table定义，此时使用prisma migrate dev –name your_migration_name产生的迁移文件只是对应这次schema的修改吗？

是的。在你描述的场景下，使用 prisma migrate dev --name your_migration_name 产生的迁移文件通常只会包含你最近这次对Schema的修改。

下面这个表格清晰地对比了prisma migrate reset之后两种不同的工作流程，帮助你理解其中的区别。

操作步骤 数据库状态 迁移历史状态 migrate dev 行为
1. prisma migrate reset 被重置，数据清空，但会重新完整地应用所有已存在的迁移文件，使其结构与当前schema.prisma文件定义一致。 迁移记录表（_prisma_migrations）会被重置并重新填充，记录显示所有迁移都已被应用。 准备就绪，等待新的变更。
2. 修改schema.prisma 保持不变，与最新的schema.prisma定义出现差异。 保持不变，仍然记录所有旧迁移已应用。 检测到数据库当前结构与你修改后的新schema.prisma定义之间存在差异。
3. prisma migrate dev --name ... 根据新生成的迁移文件更新结构，使其与新的schema.prisma定义同步。 将新生成的迁移记录添加到历史中。 生成一个全新的迁移文件，其内容仅包含使数据库从“重置后状态”变为“修改后schema状态”所需的SQL指令。

prisma migrate dev 命令非常智能，它会执行以下操作：

  1. 对比差异：首先，它会将你当前的Prisma数据模型（schema.prisma文件）与数据库的当前结构进行比较。
  2. 检查历史：同时，它会查看数据库中的迁移历史记录表（_prisma_migrations），了解哪些迁移已经被应用。
  3. 生成迁移：当它发现数据库的结构与你的Prisma数据模型不一致，但这种不一致并非由于有未应用的迁移文件造成时（正如你在执行reset后，数据库已处于最新状态），它会认为这是一次新的、基于最新模型的变更。因此，它会为你最近的这次schema修改生成一个新的迁移文件。

    所以prisma并不是依赖迁移记录，当它发现数据库和Prisma数据模型已经一致了，那么迁移记录如果未应用，也是可行的，具体下面有提及。

有一种情况需要留意：如果在执行 prisma migrate reset 之后、运行 prisma migrate dev 之前，你手动修改了数据库结构（例如，直接用SQL语句添加了一个字段），或者使用了 prisma db push 命令，这会使数据库进入一个Prisma迁移系统无法预期的状态。

此时再运行 prisma migrate dev，Prisma可能会检测到无法协调的差异。它通常会提供解决方案，最常见的是提示你是否要重置数据库（这将再次清空数据）并基于当前的schema.prisma文件重新创建所有的迁移历史。因此，在开发过程中，保持使用迁移工作流而非混合使用db push或手动修改，是更稳妥的做法。

2. 我要修改schema，正确的操作流程是什么？

  1. 修改schema.prisma文件
  2. 创建并应用迁移：在终端运行npx prisma migrate dev --name your_migration_name，为本次变更创建一个迁移文件。此命令会：
    a. 生成迁移文件：在 prisma/migrations目录下创建一个新的文件夹（以时间戳和你的命名开头），其中包含 migration.sql文件，文件里是具体的 SQL 变更语句（如 ALTER TABLE…）。
    b. 将迁移应用到开发数据库：自动执行该 SQL 文件，修改你的开发数据库结构。
    c. 重新生成 Prisma Client：确保你的客户端代码与最新的 Schema 定义保持同步

3. 如果我很频繁的修改schema，那么怎么管理迁移文件

频繁修改Schema时，管理迁移文件的核心在于保持迁移历史的清晰、可读和可回溯。
| 目标 | 核心实践 | 具体操作与命令 |
| :— | :— | :— |
| 保持提交历史清晰 | 功能对应原则：每个完整的功能或用户故事对应一个迁移文件。 | 在功能分支上开发，所有相关的Schema修改都通过 prisma migrate dev 进行。功能完成合并前，使用 --create-only 生成一个最终的、描述性的迁移文件 。 |
| 合并微小变更 | 手动合并迁移：将开发周期内的多个零散变更合并成一个有意义的迁移。 | 使用 prisma migrate dev --create-only --name descriptive_name 生成迁移文件但不应用，手动编辑或合并SQL语句，然后使用 prisma migrate deploy 应用 。 |
| 规范团队协作 | 代码审查与命名规范：将迁移文件视为重要代码，进行审查并采用一致的命名规则。 | 迁移文件命名格式如 add_user_table、add_email_to_user。在PR中审查迁移文件的SQL内容 。 |
| 准备生产部署 | 严格分离环境与备份：绝不在生产环境使用 migrate dev，且每次部署前备份。 | 生产环境始终使用 prisma migrate deploy 。执行生产迁移前，使用 pg_dump (PostgreSQL) 等工具备份数据库 。 |

开发阶段的最佳实践

  1. 为功能而非动图创建迁移：在开发一个新功能时，你可能会对schema.prisma文件进行多次修改。理想的工作流是，在一个功能分支上完成所有必要的Schema调整，然后在这些变更合并到主分支之前，生成一个单一的、描述清晰的迁移文件。这确保了版本历史中每个迁移都对应一个完整的业务功能，而非零碎的开发步骤 。
  2. 使用 --create-only 标志进行精细控制：当需要精确控制生成的SQL，或者计划将多个小变更合并时，可以使用 prisma migrate dev --create-only --name your_migration_name 命令。这个命令会生成迁移SQL文件，但不会立即应用到数据库，给你机会去审查和编辑SQL内容，确认无误后再通过 prisma migrate deploy 应用它 。
  3. 利用重置功能进行大胆探索：在开发环境，可以放心使用 prisma migrate reset 命令。它会清空数据库并从头重新应用所有迁移，非常适合在频繁修改Schema的早期阶段用来快速得到一个干净的状态 。

4. 我手动修改了schema，然后运行了npx prisma migrate deploy，此时数据库已经反应了我的修改。我再次修改schema，再次运行npx prisma migrate deploy，数据库又进行了修改。此时数据库中应该有2条migration记录，是不是？

您对流程的理解有一个非常关键的误解。简单来说，您描述的操作（修改schema后直接运行 prisma migrate deploy）不会在数据库中产生两条迁移记录，实际上，它很可能根本不会成功，并会报错。

下面这个表格清晰地对比了这两个核心命令的区别，这正是理解整个流程的关键。

命令 核心功能 是否创建迁移文件 使用环境 比喻
prisma migrate dev 创建迁移文件，并立即将其应用到数据库。 ✅ 是 仅限开发环境 “修路队”：负责设计和铺设新的道路（迁移文件）。
prisma migrate deploy 应用现有（已生成）的迁移文件到数据库。 ❌ 否 生产环境/测试环境 “高铁司机”：只负责在已铺好的轨道（迁移文件）上行驶，不修新路。

您设想的问题是直接运行 prisma migrate deploy 来应对新的schema修改。这之所以行不通，是因为：

  • migrate deploy 找不到新迁移文件：migrate deploy 命令的唯一职责是查找 prisma/migrations/ 文件夹中那些已经生成但尚未应用的迁移文件。如果您只是修改了 schema.prisma 而没有先用 migrate dev 生成对应的迁移文件，那么 migrate deploy 就无文件可应用。
  • 环境隔离：prisma migrate dev 是一个强大的命令，它可能会重置数据库，因此绝对不能在生产环境使用。生产环境应该是一个稳定、只读的环境，只能被动地应用经过测试的、已成文的迁移脚本（即通过 migrate deploy），而不能在现场创建新的迁移。

5. prisma migrate dev 可以只生成迁移文件，不执行迁移文件吗？

关于 prisma migrate dev 命令，一个常见的误解是它“只”生成迁移文件。恰恰相反，它的核心设计是一个一体化的命令，通常会连续完成“生成迁移文件”和“在开发数据库上应用该迁移”这两个动作。

特性 / 场景 描述
默认行为 生成迁移文件 并立即 应用到开发数据库。
--create-only 参数 使用此参数时，只生成迁移文件，不执行应用。允许您检查或手动修改生成的SQL。
典型工作流步骤 1. 对比Schema与数据库 -> 2. 生成迁移文件 -> 3. 应用迁移 -> 4. 生成Prisma Client。
主要使用场景 开发环境中的标准数据库变更流程。
与 migrate deploy 的区别 migrate deploy 专门用于在生产环境中应用已存在的迁移文件，而不会生成新文件。

如何实现“只生成不执行”？

1
npx prisma migrate dev --name your_migration_name --create-only

这个命令会生成迁移文件，但会暂停在应用阶段，让你有机会审查甚至编辑生成的SQL。当你确认迁移文件无误后，需要再次运行 npx prisma migrate dev（不加 --create-only）来继续完成迁移的应用。这在处理像安全地重命名字段这类需要自定义SQL的场景中特别有用。

环境区分与注意事项

请务必记住，**prisma migrate dev 只能在开发环境使用**。对于生产环境，应使用 prisma migrate deploy 命令。migrate deploy 命令不会生成新的迁移文件，它的职责是检查 prisma/migrations 目录，并将所有尚未应用到生产数据库的迁移文件按顺序执行。
简而言之，prisma migrate dev 默认是“生成并执行”迁移文件。只有在附加 --create-only 参数时，才会实现“只生成不执行”的效果。

6. prisma reset会清空迁移文件记录吗？

关于 prisma migrate reset 命令，其核心行为可以总结为：它会清空数据库中的数据以及数据库中的迁移历史记录，但不会删除你项目文件系统里的迁移文件。

受影响对象 prisma migrate reset 的影响 说明
数据库中的数据 会被清空 所有表中的数据都将被删除。
数据库中的迁移历史记录 (_prisma_migrations 表) 会被重置 该表本身会被删除并重新创建，从而清空所有迁移记录。
项目中的迁移文件 (prisma/migrations/ 目录) 不会被删除 本地硬盘上所有以时间戳命名的迁移文件夹和其中的 .sql 文件都会完好无损地保留。

命令的工作流程与用途

理解了这个核心区别后，我们来看看这个命令具体做了什么，以及它通常用在什么场景。

  1. 工作流程：当你执行 npx prisma migrate reset 后，它会：

    • 丢弃数据库中所有由 Prisma Migrate 创建的表及其数据。
    • 清除用于记录迁移历史的 _prisma_migrations 表。
    • 然后，它会重新创建 _prisma_migrations 表，并依据你项目 prisma/migrations/ 目录下现有的所有迁移文件，从头开始按顺序将它们全部应用到数据库，使数据库结构恢复到与当前数据模型一致的最新状态。

  2. 主要用途：这个命令是一个强大的开发工具。当你的开发数据库因为频繁的修改而处于一个混乱或不一致的状态时，它提供了一种“一键重置”的方法，让你能从一个干净的状态重新开始。绝对不要在生产环境中使用此命令，因为它会导致数据全部丢失。

7. prisma migrate reset, 为什么还需要应用migrate文件，它不是已经清理了表，当创建表的时候不是已经安装最新的schema生成表了吗？

简单来说，prisma migrate reset 在清理数据库后，并不是直接按照您当前最新的 schema.prisma 文件来创建表，而是通过重新按顺序执行所有迁移文件来重建数据库结构。
下面这个表格清晰地对比了相关概念，帮助您理解其中的核心差异。
| 概念 | 角色与职责 | 与 migrate reset 的关系 |
| :— | :— | :— |
| schema.prisma 文件 | 声明式模型：定义数据库结构应该是什么样子（目标状态）。 | 是生成迁移文件的蓝图，但 migrate reset 不直接使用它来创建数据库。 |
| 迁移文件 (migrations/ 目录) | 版本化记录：包含一系列SQL脚本，记录了如何从零一步步构建到当前结构的所有变更（过程历史）。 | migrate reset 重建数据库的唯一依据。它严格按顺序重新应用所有迁移文件。 |
| _prisma_migrations 表 | 迁移历史账本：数据库中的一个特殊表，记录了哪些迁移已经被应用。 | 在重置过程中会被清除，然后在应用迁移文件时重新创建并填充。 |

prisma migrate reset 命令的执行流程是这样的：

  1. 删除现有结构：首先，命令会丢弃您的开发数据库中所有由 Prisma Migrate 创建的表。
  2. 清除历史记录：同时，用于记录迁移历史的 _prisma_migrations 表也被清除。
  3. 重新应用所有迁移：接着，命令会查看 prisma/migrations 文件夹，按照迁移文件的时间戳顺序，从头开始依次执行每一个迁移文件中的SQL命令。这就像是在一个全新的空数据库上，严格按照项目的历史变更记录，一步一步地重新构建起最新的数据库结构。
  4. 重建历史记录：在此过程中，_prisma_migrations 表也会被重新创建，并且所有迁移记录都会被标记为已应用。

为什么采用这种设计？

您可能会问，为什么不直接根据最新的 schema.prisma 生成表呢？这种设计有几个重要原因：

  • 保证迁移历史的连续性：这是最主要的原因。Prisma Migrate 的核心是版本控制。通过强制重放所有迁移，它能确保您的迁移历史是一条从零到当前状态的、完整且连续的链条。这对于团队协作、CI/CD流程以及排查问题至关重要。
  • 验证迁移文件的正确性：这个过程也是一个验证步骤。如果某个迁移文件存在错误（例如，SQL语法错误或逻辑错误），在重置时就会暴露出来，让您在开发阶段就能发现并修复，避免将问题带到生产环境。
  • 为生产环境部署做准备：生产环境的数据不能被随意重置。因此，生产环境使用 prisma migrate deploy 命令，它的工作方式正是“应用尚未运行的迁移文件”，而不是直接读取 schema.prisma。开发环境的 reset 模拟了这种“应用迁移”的行为，确保开发与生产行为一致。

快速同步的替代方案

如果您在非常早期的原型阶段，需要快速迭代且不关心迁移历史，Prisma 确实提供了一个直接同步的工具：prisma db push。这个命令会直接将您 schema.prisma 的当前状态与数据库同步，不会创建迁移文件。但请注意，**db push 仅用于开发**，绝不能用于生产环境，因为它会导致数据库的变更无法通过迁移历史进行追踪和管理。

8. 我已经使用了prisma db push命令，怎么生成这次的迁移文件

使用 prisma db push 后想要为这次变更生成迁移文件。直接为已经执行的 db push 操作生成迁移文件是不可能的，因为这两种命令的工作流程不同，但您可以通过设置“基线”来补救，以便后续使用规范的迁移流程。

设置基线迁移

由于 db push 不会在 _prisma_migrations 表中留下记录，Prisma Migrate 会认为数据库当前的状态是“空白”的。为了弥补这一点，我们需要手动创建一个“基线迁移”，告诉Prisma：“数据库的当前状态就是这个样子，所有在此之前的变化都已就位”。之后的新变更就可以通过 migrate dev 来管理了。
操作步骤如下：

  1. 确保状态一致：首先，确认您的数据库结构已经和当前的 prisma/schema.prisma 文件定义完全一致。可以再运行一次 npx prisma db push 进行确认。
  2. 创建基线迁移目录：在 prisma/migrations 目录下，创建一个新的迁移文件夹。为了强调这是一个基础的初始状态，可以命名为 0_init 或 baseline。 
    1
    mkdir -p prisma/migrations/0_init
  3. 生成基线SQL文件：使用 prisma migrate diff 命令来生成一个SQL文件, migrate diff这个是关键命令，这个文件的内容应该是从空数据库状态到当前Schema状态所需的所有操作。 
    1
    npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql
    关键检查：生成后，请务必打开 prisma/migrations/0_init/migration.sql 文件检查一下，确保其中的SQL语句（如建表等）符合您的预期。
  4. 标记基线迁移为已应用：使用 prisma migrate resolve 命令，将这个我们手动创建的基线迁移标记为“已应用”。这样，Prisma就会认为这个迁移所代表的数据库状态已经完成，后续的迁移将基于此状态进行，接着可以按正常的流程进行修改chema. 
    1
    npx prisma migrate resolve --applied 0_init

9. _prisma_migrations 表中的applied_steps_count如果是0或者1代表什么意思？

_prisma_migrations 表中的 applied_steps_count 字段记录了某个迁移文件在执行过程中实际成功应用的SQL语句数量。

下面这个表格清晰地展示了不同取值的含义：
| 取值 | 通常含义 | 状态说明 |
| :— | :— | :— |
| 0 | 迁移已被记录，但包含的SQL语句未执行或执行失败。 | 异常或进行中状态 |
| 1 | 迁移包含的所有SQL变更已成功应用。 | 正常完成状态 |

详细解释与场景分析

_prisma_migrations 表是Prisma Migrate用来追踪数据库迁移历史的内部表。每当使用 prisma migrate dev 或 prisma migrate deploy 应用一个迁移时，都会在此表中创建一条记录。每个迁移文件（migration.sql）可以包含一条或多条SQL语句（例如，创建表、添加字段、创建索引等）。applied_steps_count 字段的值就指示了这个迁移文件中的SQL语句有多少被成功执行。

  • 取值为 0 的情况：这通常表示一个未成功完成的迁移状态。可能的原因包括：
    • 迁移执行失败：在应用迁移的过程中，某条SQL语句执行出错（例如，语法错误、外键冲突、权限不足等），导致整个迁移任务被标记为失败。此时，迁移虽在历史记录中，但其 applied_steps_count 为 0。
    • 使用 --create-only 参数：如果你在创建迁移时使用了 prisma migrate dev --create-only 命令，Prisma 只会生成迁移文件，而不会立即执行它。这种情况下，该迁移记录在 _prisma_migrations 表中的 applied_steps_count 也会是 0，直到你后续通过 prisma migrate dev（不带 --create-only）或 prisma migrate deploy 成功应用它。
  • 取值为 1 (或更多) 的情况：这是最常见且健康的状态。它表示该迁移文件中的所有SQL操作都已成功应用到数据库。即便你的 migration.sql 文件里只有一条SQL语句（大多数情况如此），计数就是 1。如果文件中有多条语句，并且都成功执行了，计数就会是相应的语句数量。

如果在生产环境或重要开发环境中发现 applied_steps_count 为 0 的迁移记录，这通常意味着存在需要解决的迁移问题。Prisma 提供 prisma migrate resolve 命令来手动干预迁移状态。具体操作取决于你的意图：

  • 如果确认迁移中的SQL确实未执行，且现在需要执行，你应该解决导致失败的根本原因，然后使用 prisma migrate deploy 重新尝试应用迁移。
  • 如果确认该迁移所定义的变更已经通过其他方式（例如手动执行SQL）在数据库中存在，你可以使用 prisma migrate resolve --applied <migration_name> 命令将该迁移标记为已应用，这会将 applied_steps_count 设置为一个正值（通常是1）。

10. prisma migrate resolve –rolled-back “your_migration_name” 这个命令的作用

prisma migrate resolve --rolled-back "your_migration_name" 这个命令的核心作用是手动告知Prisma迁移系统，某个指定的迁移已被回滚（撤销）。它主要用来处理迁移过程中出现的异常状态，使迁移历史记录与实际数据库状态重新保持一致。
| 特性 | 说明 |
| :— | :— |
| 主要功能 | 将名为 your_migration_name 的迁移记录标记为“已回滚”(ROLLED BACK)。 |
| 操作对象 | 数据库中的 _prisma_migrations 表（迁移历史记录表）。 |
| 是否执行SQL | 否。此命令本身不执行任何实际的数据库回滚操作。 |
| 典型使用场景 | 解决迁移失败后的状态锁定；手动回滚后同步迁移历史。 |

命令工作原理与典型场景

理解这个命令的关键在于明确：它只更新Prisma内部的迁移历史记录，而不会直接操作数据库表结构。
Prisma通过一个名为 _prisma_migrations 的特殊表来跟踪所有迁移文件的应用状态。当一次迁移尝试失败后，它会在此表中留下一条状态为“失败”的记录。Prisma的防护机制会阻止新的迁移应用，直到这个失败状态被解决。
prisma migrate resolve --rolled-back 命令的作用就是手动将这条失败迁移记录的状态更改为“已回滚”。这相当于告诉Prisma：“这个迁移带来的变更已经被撤销，你可以继续处理后续的迁移了。”
此命令通常在以下两种场景下使用：

  1. 迁移执行失败后进行清理：当 prisma migrate dev 或 prisma migrate deploy 命令执行某个迁移文件中的SQL语句失败后（例如，因语法错误或数据冲突），该迁移会被标记为失败并阻塞后续所有迁移。在修复了导致失败的问题后，你可以使用此命令将失败的迁移标记为已回滚，从而解除阻塞状态。
  2. 手动执行回滚后同步状态：如果你通过其他方式（如手动执行SQL或使用数据库管理工具）撤销了某个迁移的变更，你需要使用此命令在Prisma的迁移历史中标记该迁移已回滚，以使Prisma的元数据与数据库实际状态同步。

重要注意事项

  • 此命令不执行数据库操作：再次强调，它仅修改迁移历史记录。实际的回滚操作（如执行 DROP COLUMN, DROP TABLE 等）需要你通过其他方式完成。
  • 谨慎使用：错误地使用此命令可能导致迁移历史记录与数据库的实际结构不一致，从而引发更复杂的问题。请确保在完全理解当前状况后再使用。
  • 与 prisma migrate reset 的区别：prisma migrate reset 是一个破坏性命令，它会清空数据库并重新应用所有迁移，通常仅在开发环境使用。而 prisma migrate resolve --rolled-back 则是一个调整元数据的修复命令，可在生产环境谨慎使用。

11. 如果applied_steps_count为0的迁移记录长期存在，会对后续的数据库迁移操作产生什么具体影响？

在 Prisma 的 _prisma_migrations 表中，如果一条迁移记录的 applied_steps_count 为 0，意味着这个迁移文件虽然存在于你的迁移历史文件夹中，但其包含的 SQL 语句并未成功应用到数据库。让这种状态的迁移记录长期存在，确实会对后续的数据库操作产生一系列具体影响。
| 影响领域 | 具体表现 |
| :— | :— |
| 迁移流程阻塞 | 执行 prisma migrate dev 或 prisma migrate deploy 时，Prisma 会检测到存在未应用的迁移，导致操作失败或中断。 |
| 数据模型不一致 | 数据库的实际结构（Schema）与 Prisma 数据模型（schema.prisma）所定义的结构不一致，可能引发应用查询错误。 |
| 团队协作混乱 | 不同开发人员或环境间的数据库状态不一致，导致协作困难，可能出现在A机器上正常但在B机器上报错的情况。 |
| 架构漂移警告 | 使用 prisma migrate dev 时，Prisma 会利用影子数据库对比检测到的架构差异与未应用的迁移，可能产生令人困惑的警告。 |

理解核心原因与解决方案

出现 applied_steps_count 为 0 的记录，通常源于以下情况：

  • 迁移执行失败：在应用迁移的过程中，某条SQL语句因错误（如语法错误、约束冲突等）而执行失败。
  • 使用 --create-only 参数：仅生成了迁移文件，但尚未执行。

解决步骤

解决此问题的核心思路是让迁移记录的状态与实际数据库状态重新达成一致。你可以使用 Prisma 提供的 prisma migrate resolve 命令来手动干预。
具体操作取决于你的意图：

  1. 如果确认迁移需要应用，但之前失败了：

    • 首先，检查并解决导致迁移失败的根本原因（例如，修复SQL脚本）。
    • 然后，使用 prisma migrate deploy 命令重新尝试应用该迁移。成功后，其 applied_steps_count 会更新为正数。

  2. 如果确认该迁移的变更已通过其他方式完成（例如手动执行了SQL），或此迁移已不再需要：

    • 你可以使用以下命令，将该迁移标记为“已应用”状态。这会将 applied_steps_count 设置为一个正值（通常是1），但不会实际执行迁移文件中的SQL语句。这是一种状态修复操作。
      1
      npx prisma migrate resolve --applied "你的迁移名称"
    • 请注意：此操作前提是你百分之百确定数据库的当前结构已经包含了该迁移所定义的所有变更。如果判断失误，会导致数据模型与数据库结构永久不一致。

12. prisma resolve和 prisma resolve –rolled-back是什么区别？

prisma migrate resolve 命令用于手动修正 Prisma 迁移系统中的状态记录。简单来说，prisma migrate resolve 用于将迁移标记为 “已成功应用”，而 prisma migrate resolve --rolled-back 用于将迁移标记为 “已回滚”。它们都只修改迁移历史记录，而不会实际执行或回滚数据库中的 SQL 操作。

下面这个表格清晰地展示了两者的核心区别。

特性 prisma migrate resolve --applied prisma migrate resolve --rolled-back
核心作用 将指定迁移标记为已应用。 将指定迁移标记为已回滚。
修改的数据库状态 更新 _prisma_migrations 表中该条记录的状态。 更新 _prisma_migrations 表中该条记录的状态。
是否执行迁移文件中的SQL 否 否
典型应用场景 迁移已由其他方式（如手动）成功应用到数据库，但迁移历史中无记录。 1. 一个迁移应用失败，需要解除阻塞状态。
2. 迁移的变更已被手动撤销，需要同步迁移历史。

💡 工作原理与使用场景

理解这两个命令的关键在于明确：它们只操作Prisma内部的迁移历史记录（即 _prisma_migrations 表），而不会直接执行或回滚任何数据库结构变更。你可以把它们看作是迁移历史的“管理员”，负责修正账本，而不是直接去修改仓库里的实物。

使用 prisma migrate resolve --applied 的场景

假设你的数据库里已经存在某张表（比如通过 prisma db push 或手动执行SQL语句创建的），但Prisma的迁移历史中并没有相应的记录。这时，如果你运行 prisma migrate dev 或 prisma migrate deploy，Prisma会尝试去创建这张已存在的表，从而导致冲突。

解决方法是：你可以先创建一个对应的迁移文件（或使用已存在的），然后使用 --applied 参数告诉Prisma：“这个迁移所代表的变更已经在数据库里了，请直接将其标记为已完成。” 这样，Prisma就会跳过该迁移，继续处理后续的迁移。

1
2
# 示例：将名为 "2023100100000_init" 的迁移标记为已应用
npx prisma migrate resolve --applied 2023100100000_init

使用 prisma migrate resolve --rolled-back 的场景

这个命令通常用于处理迁移过程中的异常状态。主要场景有两个：

  1. 迁移应用失败后清理：当一个迁移（例如名为 add_email_table）在执行过程中失败后，它会在迁移历史中留下一个“失败”的记录。这个失败记录会阻塞所有后续的迁移。此时，你可以使用 --rolled-back 参数将这个失败的迁移标记为“已回滚”，从而解除阻塞，以便你修复问题后重新尝试。

    1
    2
    # 示例：将失败的迁移 "add_email_table" 标记为已回滚
    npx prisma migrate resolve --rolled-back add_email_table

  2. 手动回滚后同步状态：如果你通过数据库管理工具手动执行了SQL，撤销了某个迁移的变更，你需要让Prisma的迁移历史与数据库的实际状态同步。这时，就需要使用 --rolled-back 将该迁移标记为已回滚。

实践案例：处理一个失败的迁移

假设你在团队协作中遇到以下情况：

  1. 同事小张创建并成功应用了迁移 2023111100000_add_profile。
  2. 你在不知情的情况下，在本地也创建了一个同名的迁移（但内容不同）。
  3. 当你尝试运行 prisma migrate deploy 时，由于表已存在，迁移失败。
  4. 此时迁移被阻塞，无法继续。

修复流程如下：

  1. 标记失败迁移为已回滚：首先，清除失败的迁移记录。 
    1
    npx prisma migrate resolve --rolled-back 2023111100000_add_profile
  2. 解决冲突：删除或重命名你本地产生的重复迁移文件，确保你的迁移历史与团队一致。
  3. 继续正常部署：现在可以正常应用新的迁移了。 
    1
    npx prisma migrate deploy

总结

简单来说，这两个命令是 Prisma 迁移系统的“状态修复工具”。--applied 用于补录“成功”记录，而 --rolled-back 用于处理“失败”或记录“撤销”操作。正确使用它们可以解决因迁移状态不同步导致的各类问题，但在操作前务必确保数据库的实际结构与你将要标记的状态完全吻合，否则会导致更严重的不一致。