Prisma 7 完整详细介绍#

1
项目根目录/
2
├── prisma/
3
│   └── schema.prisma        ← 数据模型定义（核心文件）
4
├── prisma.config.ts         ← Prisma 7 新增：配置数据库连接 URL
5
└── .env                     ← 环境变量（存数据库密码等）

1
model Product {
2
  id          Int      @id @default(autoincrement())
3

4
  // 普通文本，PostgreSQL 存为 TEXT
5
  name        String
6

7
  // 限制最大长度为 100 个字符
8
  sku         String   @db.VarChar(100)
9

10
  // 长文本，适合存商品详情
11
  description String   @db.Text
12

13
  // 精确小数，@db.Decimal(10, 2) 表示最多 10 位，小数点后 2 位
14
  // 价格存 Decimal 不会有浮点精度问题（Float 会有）
15
  price       Decimal  @db.Decimal(10, 2)
16

17
  // 库存数量，整数
18
  stock       Int      @default(0)
19

20
  // 评分，浮点数
21
  rating      Float    @default(0.0)
22

23
  // 是否上架
24
  isActive    Boolean  @default(true)
25

26
  // 商品创建时间
27
  createdAt   DateTime @default(now())
28

29
  // 商品图片列表，用 JSON 存储图片 URL 数组
30
  images      Json     @default("[]")
31
}

1
model User {
2
  // @id 标记为主键
3
  // 一张表只能有一个 @id 字段
4
  id  Int  @id
5

6
  // @id 通常配合 @default 使用
7
  // autoincrement() = 自增整数（1, 2, 3, 4...）
8
  id  Int  @id @default(autoincrement())
9

10
  // uuid() = 随机生成 UUID 字符串
11
  // 例如：'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
12
  // 适合分布式系统，不会因为 ID 连续而暴露数据量
13
  id  String  @id @default(uuid())
14

15
  // cuid() = 生成唯一的短字符串
16
  // 例如：'clh123abc456def'
17
  id  String  @id @default(cuid())
18
}

1
model User {
2
  id    Int    @id @default(autoincrement())
3

4
  // @unique 该字段值全表唯一，不能重复
5
  // 插入重复值时 Prisma 会抛出 P2002 错误
6
  email String @unique
7

8
  // @@unique 多字段组合唯一（放在模型底部）
9
  // 含义：firstName + lastName 的组合不能重复
10
  // 但单独 firstName 或 lastName 可以重复
11
  firstName String
12
  lastName  String
13

14
  @@unique([firstName, lastName])
15
}

1
model Post {
2
  id Int @id @default(autoincrement())
3

4
  // 字符串默认值
5
  status    String   @default("draft")
6

7
  // 数字默认值
8
  viewCount Int      @default(0)
9

10
  // 布尔默认值
11
  published Boolean  @default(false)
12

13
  // 时间默认值：now() 表示插入时取当前时间
14
  createdAt DateTime @default(now())
15

16
  // @updatedAt：每次 update 操作时自动更新为当前时间
17
  // 不需要在代码里手动传这个字段
18
  updatedAt DateTime @updatedAt
19
}

1
model Article {
2
  id        Int    @id @default(autoincrement())
3
  title     String
4
  status    String
5
  authorId  Int
6
  createdAt DateTime @default(now())
7

8
  // @@index 给字段加索引，提升查询性能
9
  // 适合经常作为 where 条件的字段
10
  @@index([authorId])
11

12
  // 多字段组合索引
13
  @@index([status, createdAt])
14
}

1
model User {
2
  id      Int     @id @default(autoincrement())
3
  name    String          // 必填，不能为 null
4
  avatar  String?         // ? 表示可选，可以为 null
5
  phone   String?         // 插入时不传这个字段也不报错
6
  bio     String?  @db.Text  // 可选 + 指定数据库类型
7
}

1
model User {
2
  id        Int    @id @default(autoincrement())
3
  firstName String
4
  lastName  String
5
  email     String
6

7
  // @@map 指定数据库表名
8
  // 如果不写，默认表名就是模型名（User），区分大小写
9
  // 写了 @@map("users")，数据库里的表名就是 users（小写）
10
  @@map("users")
11

12
  // @@unique 多字段组合唯一约束
13
  @@unique([firstName, lastName])
14

15
  // @@index 多字段索引
16
  @@index([email])
17
}

1
// 一对多：User（一）→ Post（多）
2

3
model User {
4
  id    Int    @id @default(autoincrement())
5
  name  String
6
  email String @unique
7

8
  // posts 字段：声明这个用户可以关联多篇文章
9
  // Post[] 表示数组，这不是真实的数据库列
10
  // 只是 Prisma 用来做关联查询的声明
11
  // 数据库里 users 表不会有 posts 这一列
12
  posts Post[]
13
}
14

15
model Post {
16
  id       Int    @id @default(autoincrement())
17
  title    String
18
  content  String @db.Text
19

20
  // authorId 是真实存在于数据库的外键列
21
  // 存储关联用户的 id 值
22
  authorId Int
23

24
  // author 字段：声明关联关系
25
  //   fields: [authorId]       本表（posts）用哪个字段做外键
26
  //   references: [id]         关联到 User 表的哪个字段
27
  //   onDelete: Cascade        删除用户时，该用户的文章也自动删除
28
  //   onDelete: Restrict       如果用户有文章，拒绝删除用户（默认）
29
  //   onDelete: SetNull        删除用户时，文章的 authorId 设为 null
30
  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)
31

32
  @@map("posts")
33
}

1
-- users 表（无 posts 列）
2
CREATE TABLE "users" (
3
  "id"    SERIAL PRIMARY KEY,
4
  "name"  TEXT NOT NULL,
5
  "email" TEXT NOT NULL UNIQUE
6
);
7

8
-- posts 表（有 author_id 外键列）
9
CREATE TABLE "posts" (
10
  "id"       SERIAL PRIMARY KEY,
11
  "title"    TEXT NOT NULL,
12
  "content"  TEXT NOT NULL,
13
  "authorId" INTEGER NOT NULL,
14
  FOREIGN KEY ("authorId") REFERENCES "users"("id") ON DELETE CASCADE
15
);

1
// 查询用户时，同时获取其所有文章（联表查询）
2
const user = await prisma.user.findUnique({
3
  where: { id: 1 },
4
  include: { posts: true }, // 联表获取文章列表
5
});
6
// user.posts → Post 数组
7

8
// 查询文章时，同时获取作者信息
9
const post = await prisma.post.findUnique({
10
  where: { id: 1 },
11
  include: { author: true }, // 联表获取作者信息
12
});
13
// post.author → User 对象
14

15
// 创建文章时，关联到已有用户
16
const post = await prisma.post.create({
17
  data: {
18
    title: "文章标题",
19
    content: "内容",
20
    author: { connect: { id: 1 } }, // 关联 id=1 的用户
21
  },
22
});

1
model User {
2
  id      Int      @id @default(autoincrement())
3
  email   String   @unique
4
  name    String
5

6
  // profile 字段：声明一对一关联
7
  // UserProfile? 末尾的 ? 表示详情可选（用户可以没有详情）
8
  profile UserProfile?
9
}
10

11
model UserProfile {
12
  id     Int    @id @default(autoincrement())
13
  bio    String? @db.Text    // 个人简介（可选）
14
  avatar String?             // 头像 URL（可选）
15
  phone  String?             // 手机号（可选）
16

17
  // 外键字段：关联 User 的 id
18
  userId Int   @unique       // @unique 保证一对一（每个 userId 只能出现一次）
19

20
  // 关联声明
21
  user   User  @relation(fields: [userId], references: [id], onDelete: Cascade)
22

23
  @@map("user_profiles")
24
}

1
// 查询用户时，同时获取详情
2
const user = await prisma.user.findUnique({
3
  where: { id: 1 },
4
  include: { profile: true },
5
});
6
// user.profile → UserProfile 对象 或 null
7

8
// 创建用户详情，关联到用户
9
const profile = await prisma.userProfile.create({
10
  data: {
11
    bio: "前端开发者",
12
    avatar: "https://example.com/avatar.jpg",
13
    user: { connect: { id: 1 } },
14
  },
15
});

1
model Comment {
2
  id        Int       @id @default(autoincrement())
3
  content   String
4
  createdAt DateTime  @default(now())
5

6
  // 外键：父评论的 id（顶级评论该字段为 null）
7
  // Int? 末尾 ? 表示可选，顶级评论没有父评论
8
  parentId  Int?
9

10
  // 关联到同一张表的父评论
11
  parent    Comment?  @relation("CommentReplies", fields: [parentId], references: [id])
12

13
  // 反向关联：该评论下的所有子评论（回复）
14
  // 注意：双方都要有相同的关系名 "CommentReplies"
15
  replies   Comment[] @relation("CommentReplies")
16

17
  @@map("comments")
18
}

1
// 查询顶级评论（parentId 为 null 的）以及其所有回复
2
const comments = await prisma.comment.findMany({
3
  where: { parentId: null },
4
  include: {
5
    replies: {
6
      include: { replies: true }, // 最多嵌套两层
7
    },
8
  },
9
});

1
model User {
2
  // 方式一：整数自增主键（最常见）
3
  // autoincrement() 从 1 开始，每次插入自动 +1
4
  id Int @id @default(autoincrement())
5

6
  // 方式二：UUID 字符串主键
7
  // 优点：不暴露数据量，适合分布式系统
8
  // 缺点：索引性能稍差，存储空间稍大
9
  id String @id @default(uuid())
10

11
  // 方式三：cuid 字符串主键
12
  // 比 UUID 短，包含时间戳，有一定排序性
13
  id String @id @default(cuid())
14
}
15

16
// 复合主键（多个字段联合作为主键）
17
// 适合中间表
18
model PostTag {
19
  postId Int
20
  tagId  Int
21

22
  // @@id 声明复合主键：postId + tagId 的组合唯一
23
  @@id([postId, tagId])
24
}

1
model Post {
2
  id       Int  @id @default(autoincrement())
3
  title    String
4

5
  // authorId 就是外键字段
6
  // 这个字段的值必须在 User 表的 id 字段里存在
7
  // 如果插入一个不存在的 authorId，数据库会报外键约束错误
8
  authorId Int
9

10
  // @relation 声明外键约束
11
  author   User @relation(fields: [authorId], references: [id])
12
}

1
model Post {
2
  author User @relation(
3
    fields: [authorId],
4
    references: [id],
5

6
    // onDelete 控制当关联的父记录被删除时，子记录怎么处理
7
    // 有四个选项：
8

9
    // Cascade  → 级联删除，删除用户时同时删除其所有文章（最常用）
10
    // Restrict → 限制删除，如果用户有文章则不允许删除用户（默认值）
11
    // SetNull  → 置空，删除用户时把文章的 authorId 设为 null（需要字段是可选的）
12
    // NoAction → 不做任何操作（依赖数据库的默认行为）
13
    onDelete: Cascade
14
  )
15
}

1
1. 读取 prisma/schema.prisma 里的模型定义
2
   ↓
3
2. 和数据库当前结构对比，计算出"差异"
4
   ↓
5
3. 自动生成 SQL 语句（建表、加字段、加索引等）
6
   ↓
7
4. 在数据库里执行这些 SQL
8
   ↓
9
5. 把生成的 SQL 保存到 prisma/migrations/ 目录（作为历史记录）
10
   ↓
11
6. 重新执行 prisma generate，更新 Prisma Client 的类型

1
-- Prisma 自动生成，不要手动修改
2

3
CREATE TABLE "users" (
4
    "id"        SERIAL PRIMARY KEY,
5
    "email"     TEXT NOT NULL,
6
    "name"      TEXT NOT NULL,
7
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
8
    "updatedAt" TIMESTAMP(3) NOT NULL
9
);
10

11
CREATE UNIQUE INDEX "users_email_key" ON "users"("email");
12

13
CREATE TABLE "posts" (
14
    "id"        SERIAL PRIMARY KEY,
15
    "title"     TEXT NOT NULL,
16
    "content"   TEXT NOT NULL,
17
    "published" BOOLEAN NOT NULL DEFAULT false,
18
    "authorId"  INTEGER NOT NULL,
19
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
20
    "updatedAt" TIMESTAMP(3) NOT NULL
21
);
22

23
ALTER TABLE "posts"
24
    ADD CONSTRAINT "posts_authorId_fkey"
25
    FOREIGN KEY ("authorId") REFERENCES "users"("id")
26
    ON DELETE CASCADE ON UPDATE CASCADE;

1
// 创建
2
const user = await prisma.user.create({
3
  data: { name: "大伟", email: "dawei@example.com", password: "123456" },
4
});
5

6
// 查询所有
7
const users = await prisma.user.findMany();
8

9
// 按主键查单条
10
const user = await prisma.user.findUnique({ where: { id: 1 } });
11

12
// 按条件查第一条
13
const user = await prisma.user.findFirst({ where: { role: "admin" } });
14

15
// 更新
16
const updated = await prisma.user.update({
17
  where: { id: 1 },
18
  data: { name: "新名字" },
19
});
20

21
// 删除
22
await prisma.user.delete({ where: { id: 1 } });

1
// 等于
2
prisma.post.findMany({ where: { published: true } });
3

4
// 包含（模糊匹配，类似 SQL LIKE '%xxx%'）
5
prisma.post.findMany({ where: { title: { contains: "Vue3" } } });
6

7
// 开头匹配
8
prisma.post.findMany({ where: { title: { startsWith: "NestJS" } } });
9

10
// 大于 / 小于
11
prisma.post.findMany({ where: { viewCount: { gt: 100 } } });
12
// gt > | gte >= | lt < | lte <=
13

14
// 多条件 AND（默认就是 AND）
15
prisma.post.findMany({
16
  where: {
17
    published: true,
18
    authorId: 1,
19
  },
20
});
21

22
// 多条件 OR
23
prisma.post.findMany({
24
  where: {
25
    OR: [{ title: { contains: "Vue" } }, { title: { contains: "React" } }],
26
  },
27
});
28

29
// NOT
30
prisma.post.findMany({
31
  where: { NOT: { published: true } },
32
});

1
// include：获取关联数据（类似 SQL JOIN）
2
const user = await prisma.user.findUnique({
3
  where: { id: 1 },
4
  include: {
5
    profile: true, // 包含用户详情
6
    posts: true, // 包含所有文章
7
  },
8
});
9

10
// include 嵌套（文章里还要获取评论）
11
const user = await prisma.user.findUnique({
12
  where: { id: 1 },
13
  include: {
14
    posts: {
15
      include: { comments: true }, // 文章里的评论
16
      where: { published: true }, // 只要已发布的文章
17
      orderBy: { createdAt: "desc" }, // 按时间排序
18
    },
19
  },
20
});
21

22
// select：只返回指定字段（比 include 更精确）
23
const user = await prisma.user.findUnique({
24
  where: { id: 1 },
25
  select: {
26
    id: true,
27
    name: true,
28
    email: true,
29
    // password 不返回（安全）
30
    posts: {
31
      select: { id: true, title: true },
32
    },
33
  },
34
});

1
// 排序
2
prisma.post.findMany({
3
  orderBy: { createdAt: "desc" }, // desc 降序 | asc 升序
4
});
5

6
// 多字段排序
7
prisma.post.findMany({
8
  orderBy: [{ published: "desc" }, { createdAt: "desc" }],
9
});
10

11
// 分页（skip + take）
12
// 第 2 页，每页 10 条
13
const page = 2;
14
const pageSize = 10;
15
prisma.post.findMany({
16
  skip: (page - 1) * pageSize, // 跳过前 10 条
17
  take: pageSize, // 取 10 条
18
  orderBy: { createdAt: "desc" },
19
});
20

21
// 统计总数（用于前端显示总页数）
22
const total = await prisma.post.count({ where: { published: true } });

1
// 给文章添加标签
2
await prisma.post.update({
3
  where: { id: 1 },
4
  data: {
5
    tags: {
6
      connect: [{ id: 1 }, { id: 2 }], // 添加标签
7
      disconnect: [{ id: 3 }], // 移除标签
8
      set: [{ id: 1 }, { id: 4 }], // 替换为新标签（先清空再添加）
9
    },
10
  },
11
});