跳至主要内容

Prisma Migrate 入门

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

从零开始使用 Prisma Migrate​

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

  1. 创建一个 Prisma schema

    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）。

    1. 创建第一次迁移
    prisma migrate dev --name init
    显示CLI结果

    你的 Prisma schema 现在与数据库 schema 同步，并且你已初始化了迁移历史记录

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

  2. 向你的 schema 添加额外字段

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

  3. 创建第二次迁移

    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 添加到现有项目所涉及的步骤是：

  1. 内省数据库以更新你的 Prisma schema
  2. 创建基线迁移
  3. 更新你的 schema 或迁移以解决 Prisma Schema Language 不支持的特性
  4. 应用基线迁移
  5. 提交迁移历史记录和 Prisma schema

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

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

  1. 内省数据库以确保你的 Prisma schema 是最新的 
    prisma db pull

创建基线迁移​

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

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

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

要创建基线迁移

  1. 如果你有一个 prisma/migrations 文件夹，请删除、移动、重命名或归档此文件夹。
  2. 运行以下命令以在你偏好的名称下创建 migrations 目录。本例将使用 0_init 作为迁移名称 
    mkdir -p prisma/migrations/0_init
    注意

    0_很重要，因为 Prisma Migrate 以字典序应用迁移。你可以使用不同的值，例如当前时间戳。

  3. 使用 prisma migrate diff 生成迁移并保存到文件 
    npx prisma migrate diff \
    --from-empty \
    --to-schema-datamodel prisma/schema.prisma \
    --script > prisma/migrations/0_init/migration.sql
  4. 审查生成的迁移。

解决 Prisma Schema Language 不支持的特性​

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

  1. 打开在创建基线迁移部分生成的 migration.sql 文件。
  2. 修改生成的 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 错误

应用初始迁移​

要应用你的初始迁移

  1. 在你的数据库上运行以下命令

    npx prisma migrate resolve --applied 0_init

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

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

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

将以下内容提交到源代码管理：

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

进一步了解​

© . All rights reserved.