Prisma 7.2.0 + MySQL 数据库配置完整指南
一、项目背景
本项目使用 Prisma 7.2.0 连接现有 MySQL 数据库(spacehelper),需要在不破坏现有数据的前提下,将数据库表结构同步到 Prisma schema,并添加新的业务表(如 agent_sessions)。
二、核心配置变更(Prisma 7.2.0 重大更新)
1. Schema 配置简化
Prisma 7.2.0 不再支持在 schema.prisma 中配置 url:
// ❌ 错误写法(Prisma 6.x)
datasource db {
provider = "mysql"
url = env("DATABASE_URL")
}
// ✅ 正确写法(Prisma 7.2.0)
datasource db {
provider = "mysql"
// 不再需要 url 配置
}
2. PrismaClient 必须提供 Adapter
src/lib/db.ts 配置:
import { PrismaClient } from '@prisma/client';
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import mariadb from 'mariadb';
// 解析 DATABASE_URL 并创建连接池
const url = new URL(process.env.DATABASE_URL || 'mysql://localhost:3306/test');
const pool = mariadb.createPool({
host: url.hostname,
port: parseInt(url.port) || 3306,
user: url.username,
password: url.password,
database: url.pathname.slice(1),
connectionLimit: 5,
});
// 全局单例 Prisma 客户端
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma || new PrismaClient({
adapter: new PrismaMariaDb(pool as any), // 必须提供 adapter
log: process.env.NODE_ENV === "development" ? ["query"] : [],
});
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
export default prisma;
3. 必需的依赖包
{
"dependencies": {
"@prisma/client": "7.2.0",
"@prisma/adapter-mariadb": "^7.2.0",
"mariadb": "^3.4.5",
"prisma": "7.2.0"
}
}
三、数据库同步完整流程
流程 A:从现有数据库拉取表结构(推荐)
适用场景:已有数据库,需要生成 Prisma schema
# 1. 拉取现有数据库所有表结构
npx prisma db pull --url="mysql://user:password@host:port/database"
# 2. 生成 Prisma Client
npx prisma generate
# 3. 检查生成的 schema.prisma
# Prisma 会自动生成所有表的模型定义
注意事项:
- 会覆盖 schema.prisma 中的模型定义
- 保留
@@map映射到数据库表名 - 自动推断字段类型和关系
流程 B:推送 Schema 到数据库
适用场景:在 schema.prisma 中新增了表或字段,需要同步到数据库
# 推送 schema 到数据库(开发环境)
npx prisma db push --url="mysql://user:password@host:port/database"
# 如果有数据丢失警告,确认后使用
npx prisma db push --url="mysql://user:password@host:port/database" --accept-data-loss
警告处理:
⚠️ There might be data loss when applying the changes:
• You are about to drop the `xxx` table, which is not empty
原因:schema 中缺少数据库已有的表定义,Prisma 认为需要删除这些表。
解决方案:
- 先执行
db pull获取完整表结构 - 在完整 schema 基础上添加新表
- 再执行
db push
流程 C:混合场景(推荐生产流程)
# 1. 拉取现有数据库结构
npx prisma db pull --url="mysql://..."
# 2. 手动编辑 schema.prisma
# - 添加新表(如 AgentSession)
# - 调整字段类型
# - 添加索引和关系
# 3. 推送到数据库
npx prisma db push --url="mysql://..."
# 4. 生成 Prisma Client
npx prisma generate
四、Schema 编写最佳实践
1. 映射现有数据库表
model User {
id Int @id @default(autoincrement()) @map("id")
uuid String @unique @db.VarChar(36)
name String @db.VarChar(100)
email String? @unique @db.VarChar(100)
// ... 其他字段
// 关系定义
agentSessions AgentSession[]
@@map("users") // 映射到数据库的 users 表
@@index([status])
@@index([email])
}
2. 字段类型对应关系
| MySQL 类型 | Prisma 类型 | 示例 |
|---|---|---|
| INT AUTO_INCREMENT | Int @id @default(autoincrement()) | 主键 |
| VARCHAR(n) | String @db.VarChar(n) | 字符串 |
| TEXT | String @db.Text | 长文本 |
| TIMESTAMP | DateTime @db.Timestamp(0) | 时间戳 |
| BIGINT | BigInt | 大整数 |
| JSON | Json | JSON 数据 |
| TINYINT(1) | Boolean | 布尔值 |
| ENUM(...) | Enum 类型 | 枚举 |
3. 移除不支持的属性
Prisma 7.2.0 移除的语法:
// ❌ 不再支持
status UserStatus @db.Enum("active", "banned", "deleted")
// ✅ 正确写法
status UserStatus @default(active)
// 枚举定义
enum UserStatus {
active
banned
deleted
}
4. 新增表示例
model AgentSession {
id String @id @default(uuid()) @db.VarChar(36)
userId Int? @map("user_id") // 可空,支持游客
sessionKey String @unique @map("session_key") @db.VarChar(50)
context String @db.Text
workspace String @db.VarChar(500)
status String @db.VarChar(50)
totalSteps Int @default(0) @map("total_steps")
fileList Json? @map("file_list") // JSON 存储数组
createdAt DateTime @default(now()) @map("created_at") @db.Timestamp(0)
updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamp(0)
// 关系
user User? @relation(fields: [userId], references: [id], onDelete: SetNull)
// 索引
@@index([userId])
@@index([sessionKey])
@@index([status])
@@map("agent_sessions")
}
五、常见问题与解决方案
问题 1:Error P1012 - datasource.url 不支持
错误信息:
Error: Prisma schema validation - (get-config wasm)
Error code: P1012
error: The datasource property `url` is no longer supported in schema files.
解决方案:
- 从 schema.prisma 中移除
url = env("DATABASE_URL") - 在 PrismaClient 构造函数中提供
adapter - CLI 命令使用
--url参数
问题 2:Using engine type "client" requires adapter
错误信息:
Error: Using engine type "client" requires either "adapter" or "accelerateUrl"
解决方案:
// src/lib/db.ts
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import mariadb from 'mariadb';
const pool = mariadb.createPool({
host: 'xxx',
port: 3306,
user: 'xxx',
password: 'xxx',
database: 'xxx',
});
export const prisma = new PrismaClient({
adapter: new PrismaMariaDb(pool as any), // 添加 adapter
});
问题 3:字段类型不匹配
场景:代码中 userId 是字符串,但数据库是 Int
解决方案:
// API 路由中转换类型
const userId = session?.user.id ? Number(session.user.id) : null;
// 创建记录
await prisma.agentSession.create({
data: { userId, /* ... */ }
});
问题 4:NextAuth 类型扩展
场景:session.user 默认没有 id 字段
解决方案:
// src/types/next-auth.d.ts
import 'next-auth';
declare module 'next-auth' {
interface Session {
user: {
id: string;
name?: string | null;
email?: string | null;
image?: string | null;
}
}
}
问题 5:构建时 prisma.config.ts 报错
错误信息:
Cannot find module '@prisma/client/generator-config'
解决方案:
- 移除 schema.prisma 中的
config = "./prisma.config.ts" - 重命名或删除 prisma.config.ts(仅用于 CLI)
- Adapter 配置直接在 db.ts 中完成
问题 6:数据丢失警告
场景:db push 提示会删除现有表
解决方案:
# 1. 先拉取完整 schema
npx prisma db pull --url="..."
# 2. 在完整 schema 基础上修改
# 3. 再推送(此时不会有警告)
npx prisma db push --url="..."
六、环境变量配置
.env 文件示例
# 数据库连接
DATABASE_URL="mysql://app_user:password@49.235.182.130:3306/spacehelper"
# AI 模型配置
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini
# NextAuth
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://localhost:3000
# GitHub OAuth(可选)
GITHUB_ID=
GITHUB_SECRET=
七、完整工作流程总结
初始化项目(已有数据库)
# 1. 安装依赖
pnpm install
# 2. 从数据库拉取 schema
npx prisma db pull --url="mysql://user:pass@host:port/db"
# 3. 生成 Prisma Client
npx prisma generate
# 4. 测试数据库连接
npm run dev
添加新表
# 1. 编辑 prisma/schema.prisma,添加新模型
# 2. 推送到数据库
npx prisma db push --url="mysql://..."
# 3. 重新生成 Client
npx prisma generate
# 4. 重启开发服务器
npm run dev
生产部署
# 1. 构建项目
npm run build
# 2. 生成 Prisma Client(如未生成)
npx prisma generate
# 3. 运行迁移(生产环境)
npx prisma migrate deploy
# 4. 启动服务
npm start
八、调试技巧
1. 查看生成的 SQL
// 开发环境启用查询日志
export const prisma = new PrismaClient({
log: ["query", "info", "warn", "error"],
});
2. 检查 Prisma 版本
npx prisma --version
# 输出示例
# prisma : 7.2.0
# @prisma/client : 7.2.0
3. 验证 Schema
npx prisma validate
4. 格式化 Schema
npx prisma format
九、注意事项
- 备份数据:任何数据库操作前先备份
- 环境隔离:开发/测试/生产使用不同数据库
- 版本一致:
prisma和@prisma/client版本必须一致 - 类型转换:注意 NextAuth 返回的 user.id 是字符串
- 关系外键:定义 relation 时注意 onDelete 策略
- 索引优化:根据查询频率添加 @@index
- JSON 字段:MySQL 5.7+ 才支持 JSON 类型
- 连接池:生产环境合理配置 connectionLimit