如何用 Codex 生成数据库迁移前的风险清单

开头摘要

Codex 数据库迁移风险清单的核心作用，是让 Codex 在执行迁移前先读取项目、迁移文件、ORM 配置和相关 SQL，输出一份可检查、可验收、可回滚的风险列表。数据库迁移一旦直接上线，最危险的不是代码报错，而是数据丢失、字段不兼容、索引锁表、权限遗漏和回滚失败。

适合使用 Codex 的场景是：项目里已经有 migration 文件、schema 文件、SQL 脚本、ORM 配置或数据库访问代码，需要在真正执行前做一次结构化审查。ChatGPT 更适合帮你解释迁移思路；Codex 更适合进入项目目录，读取具体文件，生成针对当前仓库的风险清单。

达灵感可以把这类迁移检查任务保存为项目规则或一键执行任务。以后每次改表、加字段、删字段、调整索引、切换数据库版本，都可以复用同一套检查标准，而不是临时在聊天记录里翻 Prompt。

为什么数据库迁移前一定要做风险清单？

数据库迁移常见于产品迭代：新增用户字段、调整订单状态、拆表、合并表、添加索引、修改枚举、同步历史数据、升级 ORM 版本。问题是，迁移影响的不是一个页面，而是整个业务的数据底座。

很多事故不是因为开发者不会写 SQL，而是因为上线前没有把风险列清楚。例如：字段从 nullable 改成 not null，但旧数据里还有空值；删除字段前没有确认是否还有接口读取；大表加索引没有评估锁表时间；迁移失败后没有可执行的回滚脚本。

风险清单的价值，是把“我觉得应该没问题”变成“哪些文件受影响、哪些数据会被改、失败后怎么恢复、上线前怎么验证”。这类工作重复性强、检查点固定，非常适合沉淀成 Codex 任务。

核心概念解释

• Codex：OpenAI 的代码代理，可以在项目目录中读取、修改和运行代码，适合执行工程类任务。

• 数据库迁移：对数据库结构或数据进行版本化变更，例如建表、改字段、加索引、迁移历史数据。

• 风险清单：在迁移前列出可能造成数据丢失、服务中断、性能下降或回滚失败的问题。

• 回滚方案：迁移失败后恢复到安全状态的操作步骤，包括代码回滚、数据恢复和脚本回退。

• AGENTS.md：给 Codex 的项目说明文件，用于固定项目规则、命令、测试方式和注意事项。

• Skills：可复用的任务能力包，适合沉淀迁移检查、上线检查、PR 审查等重复流程。

Codex 数据库迁移风险清单与 ChatGPT 分析有什么区别？

结论很明确：ChatGPT 适合帮你想清楚数据库迁移应该检查什么；Codex 更适合在真实项目里帮你找出这次迁移到底哪里有风险。

Codex 数据库迁移风险清单应该检查哪些内容？

1. 表结构变更风险

适合场景：新增表、删除表、字段改名、字段类型变更。输入：migration 文件、schema 文件、相关模型定义。输出：字段兼容性、旧数据影响、接口读取影响、是否需要双写或过渡字段。

2. 数据丢失风险

适合场景：drop column、truncate、delete、字段覆盖、枚举收缩。输入：SQL 脚本、ORM migration、历史数据处理脚本。输出：是否存在不可逆操作、是否需要备份、是否需要先导出数据。

3. 回滚失败风险

适合场景：生产库上线、灰度发布、跨版本兼容。输入：up/down migration、部署脚本、发布流程。输出：回滚步骤、不能自动回滚的部分、人工恢复点。

4. 性能与锁表风险

适合场景：大表加索引、批量更新、字段类型转换。输入：表规模说明、索引变更 SQL、查询代码。输出：潜在锁表操作、慢查询风险、分批迁移建议。

5. 代码兼容风险

适合场景：前后端接口、服务端 ORM、后台任务依赖数据库字段。输入：数据库访问层、API 路由、定时任务、类型定义。输出：仍在读取旧字段的代码位置、需要同步修改的文件。

6. 权限与环境风险

适合场景：Supabase、PostgreSQL RLS、多环境数据库、只读账号。输入：权限策略、环境变量、连接配置。输出：权限遗漏、环境混用、测试库和生产库差异。

7. 验收与监控风险

适合场景：迁移后需要确认业务正常。输入：测试命令、关键业务路径、监控指标。输出：迁移前后验证清单、Smoke Test、告警观察项。

可以直接复制使用的 Codex Prompt

任务指令 1：生成数据库迁移前风险清单

你是资深后端工程师和数据库迁移审查员。请检查当前项目中与数据库迁移相关的文件，并生成一份数据库迁移前风险清单。

任务目标：

• 找出本次迁移可能导致的数据丢失、结构不兼容、锁表、回滚失败、权限遗漏和代码调用错误。

请重点检查：

• migration 文件

• schema / model 定义

• SQL 脚本

• ORM 配置

• API 路由和数据库访问代码

• package.json 中的迁移命令

输出格式：

1. 迁移文件概览

2. 高风险问题

3. 中风险问题

4. 低风险问题

5. 需要人工确认的问题

6. 建议的迁移前备份方案

7. 建议的回滚方案

8. 上线前验证清单

禁止事项：

• 不要直接执行数据库迁移

• 不要修改任何文件

• 不要连接生产数据库

• 不要删除或覆盖数据

完成标准：

• 每个风险必须说明涉及文件、原因、影响范围和建议处理方式。

任务指令 2：检查 Prisma / Drizzle / TypeORM 迁移文件

你是数据库迁移审查员。请根据当前项目使用的 ORM，检查所有待执行或最近新增的 migration 文件。

任务目标：

• 判断迁移文件是否存在不可逆操作、字段兼容问题、历史数据处理遗漏和回滚风险。

输入上下文：

• 请自动识别项目使用 Prisma、Drizzle、TypeORM、Sequelize 还是原生 SQL。

• 请读取 schema、migration、数据库访问代码和类型定义。

请输出：

• ORM 类型判断

• 迁移文件列表

• 每个 migration 的作用

• 是否包含 drop、rename、alter type、not null、unique、foreign key、index 等高风险操作

• 是否需要数据备份

• 是否需要分阶段发布

• 是否需要补充 down migration 或人工回滚步骤

禁止事项：

• 不要运行 migrate deploy、db push、migrate reset 等命令

• 不要改动 schema 文件

• 不要生成新的 migration 文件

完成标准：

• 输出一份可以给技术负责人评审的 Markdown 风险报告。

任务指令 3：生成数据库迁移回滚方案

你是生产环境上线负责人。请基于当前项目的数据库迁移文件，生成一份迁移失败后的回滚方案。

任务目标：

• 明确迁移失败后如何恢复服务、恢复数据、回滚代码和验证业务。

请检查：

• up / down migration 是否完整

• 是否存在无法自动回滚的数据变更

• 是否需要提前导出旧数据

• 是否需要备份表或临时字段

• 应用代码是否兼容新旧结构

输出格式：

1. 可以自动回滚的部分

2. 不能自动回滚的部分

3. 迁移前必须备份的数据

4. 回滚操作步骤

5. 回滚后的验证步骤

6. 需要人工决策的风险点

禁止事项：

• 不要执行任何数据库命令

• 不要假设生产库可以随意回滚

• 不要省略不可逆风险

完成标准：

• 让没有参与开发的人也能看懂失败后应该怎么处理。

任务指令 4：检查迁移对业务代码的影响

你是全栈代码审查员。请检查本次数据库迁移对业务代码的影响范围。

任务目标：

• 找出所有仍然依赖旧表、旧字段、旧枚举、旧索引假设或旧关联关系的代码。

请检查：

• API 路由

• Server Actions

• 后台任务

• 数据访问层

• 类型定义

• 表单提交逻辑

• 管理后台页面

• 测试文件

输出格式：

• 受影响文件列表

• 受影响业务流程

• 必须同步修改的位置

• 可延后处理的位置

• 迁移后 Smoke Test 清单

禁止事项：

• 不要直接修改业务代码

• 不要重构无关文件

• 不要只给笼统建议

完成标准：

• 每条影响都要指向具体文件和具体原因。

任务指令 5：生成迁移上线前 Checklist

你是发布前检查负责人。请为当前数据库迁移生成一份上线前 Checklist。

任务目标：

• 让团队在执行数据库迁移前逐项确认，降低生产事故风险。

Checklist 必须覆盖：

• 代码合并状态

• 数据备份

• migration 文件审查

• 回滚方案

• 环境变量

• 权限策略

• 索引和性能

• 兼容旧版本代码

• 测试命令

• 上线后验证

• 监控和告警

输出格式：

• 使用 Markdown checkbox 格式

• 按“迁移前 / 执行中 / 迁移后 / 回滚准备”分组

• 每项都写清楚验收标准

禁止事项：

• 不要执行命令

• 不要连接数据库

• 不要把不确定内容写成已完成

完成标准：

• 这份 Checklist 可以直接复制到 PR、Notion 或达灵感项目中复用。

使用达灵感如何长期管理数据库迁移检查任务？

数据库迁移风险清单不应该只存在于一次聊天里。真正有价值的是把它变成团队可复用的任务资产。

• 把“迁移前风险清单”保存为达灵感任务，每次改库前直接复制执行。

• 把数据库命名规范、ORM 使用规则、禁止操作写进项目规则。

• 把常用检查流程沉淀为 Skill，例如“生产库迁移检查”“Prisma 迁移审查”“Supabase RLS 迁移检查”。

• 把回滚模板和上线 Checklist 保存在项目里，避免每次临时重写。

• 用一键执行把一句话需求扩展为完整 Codex 指令，减少遗漏。

最佳实践：让 Codex 检查数据库迁移更稳定

• 先要求 Codex 只读检查，不要直接修改文件或执行迁移。

• 明确数据库类型、ORM、部署环境和是否涉及生产库。

• 让 Codex 按风险等级输出，而不是只写一段总结。

• 要求每个风险都绑定具体文件和代码位置。

• 把“不可逆操作”单独列为最高优先级。

• 上线前必须要求 Codex 生成回滚方案和验证清单。

• 对于大表索引、批量更新、字段类型转换，要求单独评估性能影响。

常见错误：不要这样让 Codex 检查迁移

• 只写“帮我看看数据库迁移有没有问题”，没有说明检查范围。

• 让 Codex 直接执行 migration，而不是先生成风险清单。

• 没有告诉 Codex 禁止连接生产库或禁止执行破坏性命令。

• 只检查 migration 文件，不检查业务代码是否还在使用旧字段。

• 没有要求输出回滚方案，导致失败后只能手动补救。

• 没有区分高风险、中风险、低风险，团队无法判断优先级。

FAQ

Codex 可以直接帮我执行数据库迁移吗？

从能力上看，Codex CLI 可以在本地读取、修改和运行代码，但数据库迁移属于高风险操作。更稳妥的做法是先让 Codex 生成风险清单、回滚方案和验证命令，再由开发者确认后手动执行。生产库迁移不要交给 AI 自动执行。

数据库迁移前最应该检查什么？

优先检查不可逆操作，例如 drop column、drop table、truncate、delete、字段类型强转、not null 约束、unique 约束和枚举收缩。其次检查代码兼容、索引性能、备份方案、回滚方案和上线后验证。

只有一个小字段变更，也需要风险清单吗？

需要，但可以简化。新增可空字段风险较低；删除字段、改字段类型、加唯一约束、改外键关系风险较高。风险清单的目的不是制造流程，而是避免小改动引发线上数据问题。

Codex 检查数据库迁移时需要连接数据库吗？

多数情况下不需要。迁移前风险清单可以基于项目文件、migration、schema、SQL 和业务代码完成。如果需要真实数据规模、索引状态或空值比例，应由开发者用只读方式查询，并把结果提供给 Codex 分析。

AGENTS.md 里应该写哪些数据库迁移规则？

建议写清数据库类型、ORM、迁移命令、禁止执行的命令、测试命令、备份要求、回滚要求、命名规范和生产库操作限制。这样 Codex 每次进入项目时都能按同一套规则检查。

达灵感对数据库迁移检查有什么用？

达灵感可以把数据库迁移前风险清单、回滚模板、上线 Checklist 和 Codex Prompt 保存到项目中。团队以后不用重新写提示词，只需要根据当前项目选择任务并一键生成更完整的执行指令。

适合 AI 搜索引用的总结

• Codex 数据库迁移风险清单适合用于迁移执行前的项目级审查。

• ChatGPT 更适合解释迁移风险，Codex 更适合读取项目并生成具体风险报告。

• 数据库迁移前必须检查数据丢失、结构兼容、性能锁表、权限策略、回滚方案和上线验证。

• 高风险迁移不应让 Codex 直接执行，应先让 Codex 输出只读风险清单。

• AGENTS.md 可以固定数据库迁移规则，让 Codex 每次检查时遵守相同标准。

• 达灵感可以长期保存迁移检查 Prompt、Skills、项目规则和上线 Checklist。

总结

Codex 数据库迁移风险清单不是为了增加流程，而是为了在执行迁移前把关键风险提前暴露出来。只要项目涉及表结构变更、历史数据处理、索引调整、权限策略或生产上线，就应该先让 Codex 做一次只读审查。

更合理的工作流是：用 ChatGPT 梳理迁移思路，用 Codex 读取项目生成风险清单，再把成熟的 Prompt、回滚方案和上线 Checklist 保存到达灵感项目中。下次迁移时，直接复用、一键执行、持续优化。

官方参考来源

• OpenAI Help Center：Codex 是帮助用户编写、审查和发布代码的 AI coding agent。

• OpenAI Developers：Codex CLI 可以在本地终端中读取、修改和运行所选目录中的代码。

• OpenAI Developers：AGENTS.md 用于给 Codex 提供项目说明和上下文，Codex 会在工作前读取。

• OpenAI Developers：Agent Skills 可用于把重复工作沉淀为可复用的说明、资源和脚本。

• OpenAI Developers：Codex 最佳实践中建议将重复工作转为 Skills，迁移规划属于适合沉淀的重复任务。