内省：接入现有数据库

前面的章节都是「先写 Schema，再生成数据库」。内省（Introspection）正好反过来：读取现有数据库的结构，自动生成数据模型。老项目接入 Prisma，靠的就是它。

db pull：数据库到 Schema 的逆向

先配置好连接。v7 里连接地址放在 prisma.config.ts，schema 的 datasource 块只留 provider：

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

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

然后一条命令：

npx prisma db pull

Prisma 会连接数据库，读取表、列、索引、约束，翻译成数据模型写进 schema.prisma。之后执行 prisma generate，就能用 Prisma Client 查询了。

常用旗标：

• --force：忽略现有 schema 的改动，全量覆盖
• --print：只把结果打印到终端，不写文件
• --schemas：只内省指定的数据库 schema

命名映射规则

内省不是照抄名字，而是按约定转换：

• 表名 comments → 模型 Comment，自动加 @@map("comments")
• 列名 comment_text → 字段 commentText，自动加 @map("comment_text")
• 非法字符会被清洗：表名 42User 清洗成 User 并保留 @@map("42User")；列名 two$two 变成 two_two 并加 @map

清洗后可能撞名，比如 42User 和 24User 都会变成 User。生成客户端时会报「模型重名」，需要手动改其中一个。

关系靠外键识别：

• 外键列带 UNIQUE 约束 → 一对一
• 普通外键 → 一对多
• 符合命名约定的中间表 → 隐式多对多
• 同一对表有多个外键 → 自动加关系名消歧

反复内省与保留改动

不用 Prisma Migrate、而是用 SQL 管理库结构的项目，会反复执行 db pull。关系型数据库的内省会合并手工改动，以下内容会被保留：

• @map / @@map、自定义关系名
• 注释、@updatedAt、cuid() / uuid() 默认值

字段顺序和枚举顺序由数据库决定。想丢弃所有手工修改，用 --force。

Unsupported 类型与视图

数据库有些特性 PSL 表达不了，比如 PostgreSQL 的 polygon。内省会把它标记为：

model Location {
  id   Int                        @id @default(autoincrement())
  area Unsupported("polygon")?
}

这类字段不会出现在 Prisma Client 里。需要读写时，只能用 $queryRaw 走原始 SQL。

数据库视图（view）是预览功能，要在生成器里开启：

generator client {
  provider        = "prisma-client"
  output          = "./generated"
  previewFeatures = ["views"]
}

开启后，db pull 会把视图内省为 view 块，SQL 定义存放在 prisma/views/ 目录。视图只能查询，不能增删改。目前 PostgreSQL、MySQL、SQL Server、CockroachDB 支持内省视图。

只内省部分表

子集内省没有官方开关，两个相关做法：

1. 建一个只有部分表权限的数据库用户，用它的身份执行 db pull
2. @@ignore 只影响 Prisma Client 生成，不会缩小 db pull 的内省范围；若只是不想让某些模型进客户端可加 @@ignore，真正缩小内省范围只能用受限权限账号（方案 1）。

接入现有库的完整流程

1. 安装依赖：npm install prisma --save-dev，再装 @prisma/client、数据库驱动与适配器
2. npx prisma init --datasource-provider postgresql --output ../generated/prisma
3. 在 .env 填好 DATABASE_URL
4. npx prisma db pull 生成数据模型
5. 建立基线：完整基线化流程见第 32 章
6. npx prisma generate 生成客户端
7. 实例化 PrismaClient（传入适配器），开始查询

import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! });
const prisma = new PrismaClient({ adapter });

参考来源

• Prisma 官方文档：What is introspection?
• Prisma 官方文档：prisma db pull
• Prisma 官方文档：Add Prisma ORM to an existing project（PostgreSQL）
• Mapagam：Managing Schema Introspection