Atlas migrate lint 怎么在部署前检查迁移是否可重放

Atlas 的迁移检查不是把 SQL 再读一遍，而是用开发数据库模拟迁移目录中的变更，再把破坏性操作、锁表风险、数据依赖和策略问题报告出来。部署前最稳妥的做法是：先固定迁移目录和范围，再用与目标数据库类型一致的 --dev-url 执行 atlas migrate lint，确认没有阻断性诊断后，才把结果交给后续发布流程。

官方地址：https://www.atlasgo.io/

先把迁移目录和检查范围选对

进入项目工作区后，先确认迁移文件和 atlas.sum 属于同一份版本化历史。Atlas CLI 默认使用 file://migrations，如果项目目录不同，就显式写出 --dir，这样 CI 和本地不会因为当前工作目录不同而分析错文件。

图1是原创操作示意图：左侧选中 Migrations → Lint，配置区同时出现迁移目录、开发数据库和待检查范围。它不是 Atlas 官网截图，也不是实际运行证据。

用 --latest 或 --git-base 选择本次变更

只准备检查最后一个迁移时，可以使用 --latest 1。如果一个分支上有多份连续迁移，按实际发布窗口调整 N。需要检查当前分支相对 main 的所有迁移时，则使用 --git-base main，并确保命令在正确的仓库目录执行。

# 只检查最近一份迁移，避免把整段历史重复纳入本次门禁
atlas migrate lint \
  --dir "file://migrations" \
  --dev-url "docker://mysql/8/dev" \
  --latest 1

# 检查当前分支相对 main 的迁移变化；--git-dir 指向仓库工作目录
atlas migrate lint \
  --dir "file://migrations" \
  --dev-url "docker://mysql/8/dev" \
  --git-base main \
  --git-dir "."

这里的 docker://mysql/8/dev 是开发数据库示例，实际项目要替换成与迁移方言一致的临时实例。不要为了“让检查通过”把 MySQL 迁移换到 SQLite；不同数据库的锁、类型和约束行为可能完全不同。

从报告判断迁移能否继续

运行后重点看三件事：分析到哪些版本、是否出现 diagnostics、最后的版本和 schema change 摘要。看到 no diagnostics found 与 version ok，表示本次选定范围没有被 lint 规则阻断；如果出现 destructive、data-dependent、锁或兼容性提示，就先回到未应用的迁移文件修正，再重跑同一范围。

图2把成功摘要和需要回修的状态放在同一张原创结果说明图中，帮助你核对“没有诊断”和“没有执行生产库”不是一回事。

把一次 lint 变成可复查的部署前清单

1. 迁移目录是当前分支的目录，atlas.sum 没有被忽略或误改。
2. --dev-url 的数据库类型与目标库一致，且不含生产密码。
3. 本次范围使用了正确的 --latest 或 --git-base，输出中的版本与发布内容相符。
4. 诊断已逐条处理；没有把 warning 机械地改成忽略规则。
5. 记录命令、范围、结果和修复提交，供代码评审或 CI 复查。

如果需要浏览器报告，可在已登录 Atlas 的环境中追加 --web；它只是打开报告视图，不会替你执行生产迁移。权限或发行版能力变化时，以当前官方文档和团队账号配置为准。

常见问题

lint 通过后可以直接执行 apply 吗？

不能直接等同。lint 是迁移分析和模拟检查，apply 才是面向目标数据库的执行动作；两者应由独立的发布门禁控制。

为什么要使用与目标库一致的 dev database？

SQL 方言、类型、锁和约束语义都可能不同。用错数据库类型，得到的“通过”不能代表目标库也能安全重放。

--latest 1 和 --git-base main 怎么选？

只验收最近一份文件用 --latest 1；要覆盖当前分支相对基线的变更，用 --git-base main，并检查仓库目录是否正确。