Prisma 迁移与查询报错排查：从 migrate 到连接池
作者：夸父
逐日 AI 的数据层基于 Prisma（MySQL）。本文排查三类高频问题：migrate 失败、连接池耗尽、以及查询超时——每类给诊断命令与修复动作。
migrate 失败的两类场景
新部署首次 migrate：数据库为空报错多半是连接配置（DATABASE_URL 的用户名/密码/端口/库名）——先 npx prisma db pull 或手动连一次验证连接串。
存量升级 migrate：有数据的库做 schema 变更时失败——典型是加 NOT NULL 字段没默认值、或改字段类型冲突。修复：schema 里补默认值/改成可空再 migrate；涉及数据转换的，手写 SQL 先处理数据再迁移。升级前必有备份（见备份手册），migrate 失败可回滚。
连接池耗尽（P2024）
症状：批量任务高峰时报 "Timed out fetching connection"。原因：Prisma 的连接池默认大小有限，批量生成的高并发查询把池借空。处理：DATABASE_URL 里加连接池参数（?connection_limit=20&pool_timeout=20），并把 worker 的并发数与连接池大小匹配（并发 10 的 worker 至少 10 个连接）。见批量调度的并发设置。
查询超时与慢查询
定位三步：1. 开查询日志（Prisma client 的 log 配置）看慢在哪条 SQL；2. EXPLAIN 这条 SQL——缺索引还是全表扫描；3. 补索引（schema 里 @@index 后重新 migrate）。逐日 AI 的高频查询（项目列表、切片状态）都有默认索引，自定义查询时注意配套索引。
schema 变更的最佳实践
小步迁移（每次一个逻辑变更）、迁移文件不手改（用 prisma migrate dev 生成）、生产环境用 migrate deploy（不用 dev 的 shadow database 流程）。schema 演进的完整纪律见升级指南。
常见问题
migrate 报"P3006 migrate failed"怎么排查？
先看详细报错里的 SQL 语句——迁移失败通常是：库里已有数据与新 schema 冲突（如加非空字段没给默认值）、或历史迁移记录与实际 schema 不一致。处理：改 schema 补默认值重跑，或用 prisma migrate resolve 标记解决。
查询突然变慢是 Prisma 的问题吗？
多数不是。Prisma 的查询延迟异常通常是：N+1 查询（循环里查库）、缺索引的大表查询、连接池耗尽排队。开 Prisma 的查询日志看实际 SQL，确认后到数据库层优化。