React / 系统课时

Schema 与数据库迁移

Schema 与数据库迁移

本课用一个博客数据模型完成从 Prisma Schema 到 PostgreSQL 表结构的同步。你将定义模型、枚举、索引和一对多关联,生成可追踪的迁移文件,并掌握修改结构时的安全检查顺序。

学习目标

  • 能用 Prisma Schema 描述字段、约束、枚举、索引和关联
  • 能创建、检查并应用开发环境迁移
  • 能区分开发迁移与生产部署的职责边界

建模前先确定数据库事实

本课使用 PostgreSQL,并假设项目已经执行过 Prisma 初始化。连接地址放在项目根目录的 .env 中,Schema 只描述数据库类型和业务模型,CLI 的连接配置放在 prisma.config.ts。

ts
// prisma.config.ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: {
    url: env("DATABASE_URL"),
  },
});

配置生效后,Prisma CLI 会从 .env 读取 DATABASE_URL。不要把真实账号、密码和公网地址写进 Schema 或提交到版本库;验证时只需确认环境变量存在且数据库可连接。

编写模型、枚举、索引和关联

下面的 Schema 建立 User 与 Post 的一对多关系。authorId 是数据库中的外键字段,author 与 posts 是 Prisma 层的关联字段;复合索引服务于“按状态筛选并按创建时间排序”的常见查询。

prisma
// prisma/schema.prisma
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int        @id @default(autoincrement())
  title     String     @db.VarChar(200)
  content   String?    @db.Text
  status    PostStatus @default(DRAFT)
  authorId  Int
  author    User       @relation(fields: [authorId], references: [id], onDelete: Cascade)
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt

  @@index([authorId])
  @@index([status, createdAt])
}

@id、@unique 和 @default 分别声明主键、唯一约束和默认值;@@index 创建模型级索引。删除用户时,onDelete: Cascade 会连带删除其文章,使用前必须确认这符合业务的数据保留规则。

Prisma Schema 到数据库迁移流程

创建并验证迁移

先校验语法,再创建迁移。校验可以提前发现字段类型、关联和配置错误,避免在执行 SQL 时才失败。

bash
npx prisma validate

预期输出:

text
Prisma schema loaded from prisma/schema.prisma
The schema at prisma/schema.prisma is valid.

随后在开发数据库执行首次迁移:

bash
npx prisma migrate dev --name init-blog

预期结果:

text
Datasource "db": PostgreSQL database "<DATABASE>" at "<HOST>:<PORT>"
Applying migration `<TIME>_init_blog`
Your database is now in sync with your schema.

<DATABASE>、<HOST>、<PORT> 和 <TIME> 会随环境变化。命令成功后,应出现 prisma/migrations/<TIME>_init_blog/migration.sql,数据库中也会生成对应表、外键和索引。

修改结构时的安全顺序

后续新增字段或索引时,先修改 Schema,再使用有业务含义的迁移名执行开发迁移,最后检查生成的 SQL。删除字段、收紧非空约束或修改枚举值可能导致数据丢失,不能只看命令是否成功。

开发环境使用 migrate dev 生成和试跑迁移;生产环境应提交已审查的迁移目录,并通过 migrate deploy 只应用待执行文件。不要在生产库使用重置命令,也不要手工修改已经在其他环境执行过的历史迁移。

如果迁移提示需要重置数据库,先停止操作并检查当前库是否包含重要数据。重置适合可丢弃的本地开发库,不是修复生产迁移冲突的通用方案。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Schema 与数据库迁移

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通