使用 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」。