Codex修改数据库后项目启动失败怎么办？Migration、Schema与数据结构排查

使用 Codex 修改真实项目时，经常会遇到一种情况：

代码已经改完了，但项目一启动就报数据库相关错误。

常见表现包括：

新增字段后查询失败；
本地代码已经有新字段，数据库里却没有；
Migration 文件已经生成，但项目还是启动不了；
测试环境正常，开发环境报错；
数据库提示列不存在、表不存在或约束冲突；
Codex继续修改业务代码，却一直解决不了问题。

这种情况很多时候不是业务代码写错。

真正需要检查的是：

代码里的数据结构，和实际数据库里的结构是不是同一个版本。

一、先确认Schema到底改了什么

例如原来的用户表只有：

复制代码

id
name
email

现在新增：

复制代码

avatar

Codex可能已经修改：

ORM Model；
Type定义；
查询代码。

但如果真实数据库仍然只有旧结构，运行时就可能出现：

复制代码

column "avatar" does not exist

所以第一步应该确认：

Schema发生了什么变化。

不要一看到启动失败就继续改Service或Controller。

二、修改Schema不等于数据库已经同步

这是很常见的误区。

例如你修改：

复制代码

schema.prisma

或者ORM里的Model定义。

这只能说明：

代码希望数据库长成什么样。

真实数据库是否发生变化，还取决于：

Migration有没有生成；
Migration有没有执行；
执行的是不是当前数据库。

所以要把：

复制代码

修改Schema

和：

复制代码

修改真实数据库

看成两个步骤。

三、先检查Migration是否真的生成

如果项目使用数据库迁移机制，Schema变化以后通常会有对应Migration。

例如：

复制代码

migrations/
  add_user_avatar/

如果代码已经引用新字段，却根本没有新的Migration，就需要检查：

数据库结构变化是否真正被记录。

可以让 Codex先回答：

本次代码修改是否涉及数据库Schema变化？如果涉及，对应Migration在哪里？

先确认这一点，再决定后续操作。

四、有Migration，也要确认是否真正执行

有时候Migration文件已经存在。

但数据库仍然是旧结构。

这通常说明：

Migration还没有在当前环境执行。

例如：

开发环境已经运行；

测试数据库没有运行。

或者：

本地数据库更新了；

Docker里的数据库还是旧版本。

所以遇到结构错误时，可以确认：

当前连接的是哪个数据库；
已经执行到哪一个Migration；
最新Migration是否成功完成。

不要只看文件存在。

五、代码连接的数据库可能不是你以为的那个

例如电脑里同时有：

复制代码

本地数据库
Docker数据库
测试数据库
开发服务器数据库

你已经在本地数据库执行Migration。

但项目实际通过环境变量连接的是Docker数据库。

结果仍然报：

复制代码

column does not exist

这时候不是Migration失效。

而是：

执行Migration和运行项目使用的不是同一个数据库。

可以重点检查：

复制代码

DATABASE_URL

或者项目实际使用的数据库连接配置。

六、Migration顺序错误也可能导致启动失败

长期项目里可能已经存在很多Migration：

复制代码

001_create_user
002_add_status
003_create_order
004_update_user

新Migration可能依赖前面的结构。

如果某个旧Migration没有执行成功，直接运行后面的Migration，也可能失败。

所以不要只检查：

最新Migration有没有执行？

还应该确认：

整个迁移历史是否连续。

特别是：

新环境；
测试数据库；
刚重新创建的数据库；

更容易出现这个问题。

七、新增非空字段要注意旧数据

例如给已有表新增：

复制代码

status NOT NULL

但数据库中已经存在几万条旧数据。

这些历史记录并没有 status。

这时候Migration可能直接失败。

更稳的方式可能是：

先提供默认值；

或者：

先允许为空；

补齐旧数据；

再增加非空限制。

所以数据库修改不能只考虑：

新数据以后怎么写。

还要考虑：

旧数据现在长什么样。

八、删除或改名字段风险更高

新增字段通常比较直观。

但如果任务是：

复制代码

username → display_name

或者直接删除旧字段，就要更加谨慎。

因为可能还有：

旧查询；
后台任务；
测试；
报表；
其他服务；

继续读取原字段。

所以涉及字段改名时，不建议只修改Schema。

还要检查：

所有调用方是否同步更新。

这和普通代码重命名不同。

数据库字段可能被更多系统长期使用。

九、不要为了启动成功直接重置数据库

开发环境报错以后，一个很容易想到的办法是：

直接删库重建。

对于纯本地临时项目，这有时可行。

但真实项目尤其是包含重要数据时，这种操作风险非常高。

数据库排查应该优先确认：

哪个Migration失败；
为什么失败；
当前Schema差异在哪里。

而不是一遇到问题就清空数据重新开始。

十、可以先比较"代码Schema"和"真实Schema"

如果不知道问题在哪，可以把两边分开确认。

代码认为应该存在什么

例如：

复制代码

users:
id
name
avatar
status

数据库实际有什么

例如：

复制代码

users:
id
name

一对比就能发现：

问题不是业务逻辑。

而是数据库缺少：

复制代码

avatar
status

这种方式比不断修改查询代码更直接。

十一、一个比较稳定的排查顺序

Codex修改数据库后项目启动失败，可以按下面顺序：

第一步：确认Schema变化。

到底新增、删除或修改了什么？

第二步：检查Migration。

有没有对应迁移文件？

第三步：确认Migration是否执行。

不要只看文件存在。

第四步：确认数据库连接。

项目到底连接的是哪一个数据库？

第五步：检查历史数据。

新约束是否和旧数据冲突？

第六步：再检查业务代码。

确认所有调用方都使用新结构。

十二、可以给Codex增加一条数据库修改规则

以后涉及数据库任务，可以提前写：

复制代码

数据库修改要求：

1. 修改Schema前先说明变化；
2. 如果需要Migration，先生成并说明；
3. 不直接删除已有数据；
4. 字段改名要检查所有调用方；
5. 新增非空字段要考虑历史数据；
6. 完成后确认代码Schema与实际数据库结构一致。

这能减少：

代码改完了，数据库却没跟上

这种问题。

最后

Codex修改数据库后项目启动失败，很多时候真正的问题不是：

代码写错了。

而是：

代码Schema和真实数据库Schema已经不一致。

排查时可以重点确认：

Schema改了什么 → Migration有没有生成 → 有没有执行 → 执行的是哪个数据库 → 历史数据能不能兼容。

尤其是长期项目里，数据库结构变化通常比普通代码修改风险更高。

不要只关注：

新代码能不能编译。

还要确认：

真实数据库是否已经完成同样的变化。

把这条链路理清以后，很多"代码明明改完了，项目却启动不了"的数据库问题都会更容易定位。

持续更新 Codex、大模型开发与 AI 编程实战内容，更多技术内容和稳定订阅渠道欢迎搜索关注「仙逆GPT」。