React / 系统课时
Schema 与数据库迁移
Schema 与数据库迁移
本课用一个博客数据模型完成从 Prisma Schema 到 PostgreSQL 表结构的同步。你将定义模型、枚举、索引和一对多关联,生成可追踪的迁移文件,并掌握修改结构时的安全检查顺序。
学习目标
- 能用 Prisma Schema 描述字段、约束、枚举、索引和关联
- 能创建、检查并应用开发环境迁移
- 能区分开发迁移与生产部署的职责边界
建模前先确定数据库事实
本课使用 PostgreSQL,并假设项目已经执行过 Prisma 初始化。连接地址放在项目根目录的 .env 中,Schema 只描述数据库类型和业务模型,CLI 的连接配置放在 prisma.config.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/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 会连带删除其文章,使用前必须确认这符合业务的数据保留规则。

创建并验证迁移
先校验语法,再创建迁移。校验可以提前发现字段类型、关联和配置错误,避免在执行 SQL 时才失败。
npx prisma validate预期输出:
Prisma schema loaded from prisma/schema.prisma
The schema at prisma/schema.prisma is valid.随后在开发数据库执行首次迁移:
npx prisma migrate dev --name init-blog预期结果:
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 只应用待执行文件。不要在生产库使用重置命令,也不要手工修改已经在其他环境执行过的历史迁移。
如果迁移提示需要重置数据库,先停止操作并检查当前库是否包含重要数据。重置适合可丢弃的本地开发库,不是修复生产迁移冲突的通用方案。