Prisma Migrate 入门

本页解释了如何在开发环境中使用 Prisma Migrate 开始迁移您的 schema。

从零开始使用 Prisma Migrate

要在开发环境中开始使用 Prisma Migrate

创建 Prisma schema

Prisma 7

Prisma 6

schema.prisma

datasource db {
  provider = "postgresql"
}

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

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  published Boolean @default(true)
  authorId  Int
  author    User    @relation(fields: [authorId], references: [id])
}

schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

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

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  published Boolean @default(true)
  authorId  Int
  author    User    @relation(fields: [authorId], references: [id])
}

提示

您可以使用 schema 中的原生类型映射属性来决定创建哪种确切的数据库类型（例如，String 可以映射到 varchar(100) 或 text）。

对于 Prisma 7，请确保在项目根目录中有一个 prisma.config.ts

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";
export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

创建第一次迁移
prisma migrate dev --name init
显示CLI结果
您的 Prisma schema 现在与数据库 schema 同步，并且您已经初始化了迁移历史记录
```
migrations/
  └─ 20210313140442_init/
    └─ migration.sql
```
注意：您的文件夹名称将不同。文件夹命名格式为 YYYYMMDDHHMMSS_your_text_from_name_flag。

向您的 schema 添加其他字段

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

创建第二次迁移

prisma migrate dev --name added_job_title

显示CLI结果

您的 Prisma schema 再次与数据库 schema 同步，并且您的迁移历史记录包含两次迁移

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

您现在有一个可以版本控制并用于将更改部署到测试环境和生产环境的迁移历史记录。

将 Prisma Migrate 添加到现有项目

将 Prisma Migrate 添加到现有项目的步骤是：

内省您的数据库以更新 Prisma schema
创建基线迁移
更新您的 schema 或迁移以解决 Prisma Schema Language 不支持的功能
应用基线迁移
提交迁移历史记录和 Prisma schema

内省以创建或更新您的 Prisma schema

确保您的 Prisma schema 与您的数据库 schema 同步。如果您正在使用 Prisma Migrate 的先前版本，这应该已经实现了。

内省数据库以确保您的 Prisma schema 是最新的
```
prisma db pull
```

创建基线迁移

基线化是为以下数据库初始化迁移历史记录的过程：

在您开始使用 Prisma Migrate 之前已经存在
包含必须维护的数据（例如生产环境），这意味着数据库不能被重置

基线化告诉 Prisma Migrate 假设一个或多个迁移已经已应用。这可以防止生成的迁移在尝试创建已存在的表和字段时失败。

要创建基线迁移

如果您有 prisma/migrations 文件夹，请删除、移动、重命名或存档此文件夹。
运行以下命令以创建一个带有您偏好名称的 migrations 目录。此示例将使用 0_init 作为迁移名称
```
mkdir -p prisma/migrations/0_init
```
注意
0_ 很重要，因为 Prisma Migrate 以字典顺序应用迁移。您可以使用不同的值，例如当前时间戳。

使用 prisma migrate diff 生成迁移并将其保存到文件中

npx prisma migrate diff \
--from-empty \
--to-schema-datamodel prisma/schema.prisma \
--script > prisma/migrations/0_init/migration.sql

审查生成的迁移。

解决 Prisma Schema Language 不支持的功能

要包含数据库中已存在的不支持的数据库功能，您必须替换或修改初始迁移 SQL

打开在创建基线迁移部分生成的 migration.sql 文件。
修改生成的 SQL。例如

如果更改很小，您可以将额外的自定义 SQL 附加到生成的迁移中。以下示例创建了一个部分索引

/* Generated migration SQL */

CREATE UNIQUE INDEX tests_success_constraint ON posts (subject, target)
  WHERE success;

如果更改很大，用数据库转储的结果（mysqldump, pg_dump）替换整个迁移文件会更容易。使用 pg_dump 时，您需要使用以下命令更新 search_path：SELECT pg_catalog.set_config('search_path', '', false);；否则您将遇到以下错误：The underlying table for model '_prisma_migrations' does not exist. `
信息
请注意，一次创建所有表时表的顺序很重要，因为外键是在同一步骤创建的。因此，要么重新排序它们，要么将约束创建移动到所有表创建之后的最后一步，这样您就不会遇到 can't create constraint 错误

应用初始迁移

要应用您的初始迁移

针对您的数据库运行以下命令

npx prisma migrate resolve --applied 0_init

审查数据库 schema，以确保迁移达到所需的最终状态（例如，通过将 schema 与生产数据库进行比较）。

新的迁移历史记录和数据库 schema 现在应该与您的 Prisma schema 同步。

提交迁移历史记录和 Prisma schema

将以下内容提交到版本控制

整个迁移历史记录文件夹
schema.prisma 文件

进一步了解

有关将迁移部署到生产环境的更多信息，请参阅使用 Prisma Migrate 部署数据库更改指南。
请参阅生产环境故障排除指南，了解如何使用 prisma migrate diff、prisma db execute 和/或 prisma migrate resolve 调试和解决生产环境中失败的迁移。

从零开始使用 Prisma Migrate​

将 Prisma Migrate 添加到现有项目​

内省以创建或更新您的 Prisma schema​

创建基线迁移​

解决 Prisma Schema Language 不支持的功能​

应用初始迁移​

提交迁移历史记录和 Prisma schema​

进一步了解​