Prisma Migrate 如何使用？

在开发项目时，数据库的管理和变更操作常常让人头疼不已。今天要给大家分享的Prisma Migrate，就能很好地解决这些问题。这篇文章将详细介绍Prisma Migrate的使用方法，包括它在项目初始化、数据库修改、环境部署以及现有项目接入等方面的具体操作，还会结合实际场景推荐一种高效的工作流。

一、理解基础概念：ORM与Prisma Migrate

（一）什么是ORM？

在深入了解Prisma Migrate之前，先得搞清楚ORM这个概念。ORM的全称是Object-relational mapping，中文叫对象关系映射。简单来说，它就是用来解决面向对象编程和关系数据库之间“沟通障碍”的一种技术。打个比方，面向对象编程就像是我们日常生活中的语言，而关系数据库则像是一种特殊的外语，ORM就相当于一个翻译官，通过描述对象和数据库之间映射的元数据，把程序里的对象自动保存到关系数据库中，让两者能够顺畅“交流” 。

（二）Prisma Migrate的作用

Prisma是一款常用的JS/TS ORM框架，它为开发者提供了一种方便的方式，让我们在JavaScript或TypeScript语言环境中操作数据库。在Prisma里，定义数据库结构靠的是schema.prisma文件，这个文件就像是数据库结构在JavaScript世界里的“代言人”，我们操作这些对象，实际上就是在操作数据库。

想象一下，我们的项目和数据库里有个User结构。比如下面这个schema.prisma文件里定义的：

/// schema.prisma model user { id Int @id @default(autoincrement()) name String? password String? @db.VarChar(64) }

要是想给这个User结构添加一个“用户创建时间”的字段，按照理想情况，只操作schema.prisma文件就能完成对数据库的变更。而Prisma Migrate就是实现这一操作的得力助手，它不仅能帮我们完成数据库变更，还能把每次变更都管理得井井有条，记录下来，方便后续查看和追溯。

二、项目开发中的Prisma Migrate操作

（一）初始化项目

在一个全新的Prisma项目中，Prisma Migrate从项目初始化阶段就开始发挥作用。在命令行中输入下面这条命令：

prisma migrate dev --name init

这条命令执行后，Prisma会把定义在schema.prisma里的结构同步到数据库中，同时还会创建一个migrations记录。这个记录就像是一个“变更日记”，把数据库的每一次重要变动都记下来。生成的migrations记录文件夹通常以时间开头，再加上下划线和我们指定的名称，像这样：

migrations/ └─ 20241122022542_init/ └─ migration.sql

migration.sql文件里的内容就是用来修改数据库的SQL语句。以上面的User结构为例，生成的SQL语句可能是这样：

-- CreateTable CREATE TABLE user ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255), password VARCHAR(64) );

（二）继续修改数据库

假设我们要给之前的User结构加上“用户创建时间”字段，那就需要修改schema.prisma文件，修改后的内容如下：

/// schema.prisma model user { id Int @id @default(autoincrement()) name String? password String? @db.VarChar(64) + createdAt DateTime @default(now()) @map("created_at") }

修改完schema.prisma文件后，继续使用prisma migrate dev命令来同步变更：

prisma migrate dev --name added_user_createat

执行这条命令后，会生成第二个迁移记录，数据库结构也会和schema.prisma里定义的保持一致。这时候migrations文件夹里就多了一个记录这次变更的文件夹：

migrations/ └─ 20241122024309_added_user_createat/ └─ migration.sql └─ 20241122022542_init/ └─ migration.sql

migration.sql里的SQL语句会根据变更内容进行调整，这次添加字段的SQL语句类似这样：

-- AlterTable ALTER TABLE user ADD COLUMN created_at DATETIME DEFAULT CURRENT_TIMESTAMP;

经过这些操作，项目的迁移记录就完整了。我们可以把这些记录文件添加到Git进行保存，方便后续管理和部署到不同环境。

三、部署到不同环境：测试与生产环境的操作

（一）直接同步

在将Prisma结构和数据库结构同步时，有两种比较简单的方法，分别是prisma db push和prisma db pull。

prisma db push：使用这个命令可以快速把Prisma结构同步到数据库中。不过要注意，它可能会重置数据库，所以使用的时候一定要小心。操作步骤就是先更新schema.prisma文件，然后执行prisma db push，最后数据库的结构就会根据schema.prisma的内容进行更新。
prisma db pull：这个命令的作用和prisma db push相反，是把数据库结构同步到Prisma结构中。如果需要强行覆盖本地Prisma结构，可以使用prisma db pull --force。执行完prisma db pull后，还需要运行prisma generate来更新Prisma Client。

但这两个命令都有个缺点，就是没办法管理迁移历史，只是单纯地把两边的结构进行同步。所以它们更适合在项目刚开始创建，或者需要覆盖现有结构的时候使用。

（二）带有迁移记录的同步

如果想要在同步结构的同时管理迁移记录，那就需要用到prisma migrate dev和prisma migrate deploy这两个命令。

prisma migrate dev：这个命令会记录迁移记录并且更新数据库结构。在执行的时候，它会先对比更新后的schema.prisma结构和数据库现有的结构，找出差异部分，然后生成对应的SQL语句，保存在migrations文件夹下。同时，它还会在数据库表中插入一条迁移记录，最后完成数据库结构的更新。比如，我们给User结构添加“用户创建时间”字段时执行的就是这个命令。另外，要是加上--create-only参数，像这样prisma migrate dev --create-only，就可以只生成SQL迁移文件，方便我们自定义编辑这次迁移，比如重命名列或者加载数据库扩展等操作。不过要注意，prisma migrate dev可能会覆盖数据库，所以千万别在生产环境中使用。
prisma migrate deploy：这个命令通常用于生产环境的部署。它会去比较数据库表中的迁移记录，找到那些还没有应用到数据库的迁移记录，然后执行对应的迁移SQL，最后更新迁移数据表。如果我们之前自定义编辑过迁移的SQL文件，就可以用prisma migrate deploy把这些变更应用到数据库中。当然，也可以手动执行SQL文件，但这样数据库里的migrations迁移记录就没办法自动记录了。在一些特殊情况下，如果Prisma Client无法连接到生产环境数据库，也可以手动完成这个部署步骤。

四、现有项目接入Prisma Migrate

由于prisma migrate dev和prisma migrate deploy都需要对比之前的迁移记录，所以不能直接在已有项目中接入Prisma Migrate。不过，我们可以通过补充之前的数据库迁移记录来实现接入。具体步骤如下：

生成第一次迁移记录：在命令行中输入这条命令：

prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script > migration.sql

这条命令会根据当前的schema.prisma文件生成一个迁移SQL文件。
2. 整理迁移记录：把生成的/migration.sql文件复制到/migrations/20241113065155_init目录下（这里的init名字可以自己取，但前面的时间一定要比之后的日期早，因为Prisma Migrate有时候会根据文件夹名称来排序并执行SQL）。
3. 标记迁移记录已应用：使用下面这条命令标记这条记录已经应用过了：

prisma migrate resolve --applied "20241113065155_init"

完成这些步骤后，数据库里就有了初始化记录，之后就可以按照Prisma Migrate的正常流程进行项目开发了。

五、推荐工作流：结合CI系统高效开发

为了更高效地使用Prisma Migrate，推荐结合代码仓库分支合并和CI系统（比如GitHub Actions）来进行开发。具体的工作流程是这样的：

在开发新功能时，基于主分支创建一个新的功能分支，比如git checkout -b ft/comments。
在功能分支上进行开发，使用prisma migrate dev命令管理数据库变更。开发完成后，将代码推送到远程仓库，并创建Pull Request。
在Pull Request的预览环境中，可以检查数据库变更是否符合预期。确认无误后，将功能分支合并到主分支。
最后，在主分支上使用prisma migrate deploy命令，把Prisma架构和迁移历史记录同步到生产数据库中。

通过这样的工作流，可以更好地管理数据库变更，确保开发、测试和生产环境中的数据库结构一致，提高项目开发的效率和稳定性。

六、总结回顾

我因为工作需要学习Prisma Migrate的使用方法，过程中发现相关通俗易懂的文档比较少，好在最后在他人的帮助下，总算是把Prisma Migrate的使用摸透了。