数据库迁移动手前，先确认正在处理哪个 Supabase 项目、哪个 Git 分支和哪个数据库环境。项目引用、组织、区域与远端链接都要核对。命令能执行不代表目标选对了。
先查版本和当前状态
Supabase 产品与 CLI 持续更新。让 Codex 先读官方 changelog，再运行本机 CLI 的 --version 和相关命令的 --help。随后用 supabase migration list 比较本地文件与远端历史，检查工作树里有没有未提交迁移。
新迁移通过 supabase migration new <name> 创建，再把 SQL 写进生成的时间戳文件。团队开始使用迁移以后，远端表编辑器和 SQL 编辑器不应继续承担随手改结构的工作，否则 Git 文件与 supabase_migrations.schema_migrations 会失去同步。
在本地重放完整链条
先审 SQL 的锁表时间、默认值、非空约束、索引、回填和删除操作。大量数据回填要与结构变更分开评估。使用本地 Supabase 环境运行 supabase db reset，它会重建本地数据库，按顺序应用所有迁移，再执行种子数据。这个结果能证明迁移链可以从空库重放。
public 等暴露 schema 中的表要启用 RLS，并写出符合真实访问模型的策略。只给 authenticated 角色权限还没有限制具体行。新增表是否自动出现在 Data API 也受项目设置和平台变更影响，迁移后要检查暴露设置、角色授权与 API 访问结果。
数据库类型会跟着 schema 变化。使用生成类型的项目应重新执行 supabase gen types，再跑应用测试、类型检查和涉及读写权限的集成测试。
预览远端动作再部署
远端部署前运行 supabase db push --dry-run，阅读待应用迁移。确认链接仍指向预期环境，生产数据已有符合团队制度的备份与恢复安排，再由约定的发布者执行 supabase db push。多人同时推送会增加迁移历史冲突，官方团队流程建议一次只由一人部署。
不要在生产运行 supabase db reset --linked。这个命令会删除已链接远端数据库的 schema，并从本地迁移重建，只适合明确可丢弃的开发或测试环境。migration repair 只修改迁移历史记录，不会替你执行或回滚 SQL，使用前必须先确认真实 schema 状态。
大改动按兼容阶段发布
给线上表增加必填字段时，可以先添加允许空值的新列，让旧应用仍能读写。随后发布兼容新旧字段的应用，分批回填历史数据，并用查询核对空值数量。确认所有写入都带新字段以后，再增加非空约束。删除旧列留到后续迁移，等旧版本不再运行。
重命名、类型转换和大表索引也要先评估锁与执行时间。先在接近生产规模的测试环境查看执行计划与耗时，记录回滚办法和观察指标。迁移已经写入数据时，简单执行反向 SQL 可能造成丢失，回退计划要说明应用版本、schema 与数据怎样一起恢复。
部署后用普通用户和管理员路径分别查询，检查 RLS、触发器、函数与应用类型。Dashboard 里看见新列，只证明结构出现了，还没有证明客户端权限和业务读写正确。
交付时分别写明本地重放、预览环境验证、生产部署和线上查询验证。只完成迁移文件与本地测试，就标记为本地完成。