Atlas 怎么只生成 schema diff SQL 而不直接修改数据库

如果你只想知道“当前数据库”和“目标 schema”之间需要执行哪些 SQL，Atlas 应该使用 atlas schema diff，而不是 atlas schema apply。前者读取两个 schema 状态并打印迁移计划，后者才会把计划应用到目标数据库。

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

这篇用一个可审阅的迁移场景说明完整做法：准备 --from、--to 和 --dev-url，生成 SQL，保存到 diff.sql，再根据输出判断是否存在 ALTER、CREATE 或 DROP。命令只负责计算和展示，不直接修改目标数据库。

先分清三个输入来源

atlas schema diff 的核心是比较两个状态：

• --from：当前状态，可以是数据库 URL、HCL/SQL schema 或迁移目录。
• --to：期望状态，同样可以来自数据库、文件或迁移目录，并且可以重复传入。
• --dev-url：Atlas 用来解析和规划差异的开发数据库。它不是要被修改的生产库。

例如，当前状态来自本地 MySQL，目标状态来自 schema.hcl：

# 只声明差异来源和目标状态，不执行任何 ALTER 或 CREATE
atlas schema diff \
  --from "mysql://user:pass@localhost:3306/app" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/dev"

界面说明图里最重要的是三个输入框的职责：from 描述“现在是什么”，to 描述“希望变成什么”，dev-url 提供规划所需的数据库类型和能力。不要把生产连接串当作开发数据库地址，也不要把 --from 与 --to 反过来。

用 schema diff 只生成 SQL 计划

最小命令已经会把差异计划打印到标准输出。Atlas 官方对该命令的定位是：读取两个 schema 定义，计算差异，并打印把 from 迁移到 to 所需的 SQL 语句。

如果只想查看结果，可以直接运行：

# 预览当前状态到目标状态的迁移 SQL；不会替目标数据库执行
atlas schema diff \
  --from "file://schema-current.sql" \
  --to "file://schema-next.sql" \
  --dev-url "docker://mysql/8/test"

# 需要机器可读或统一缩进时，用模板控制输出格式
atlas schema diff \
  --from "file://schema-current.sql" \
  --to "file://schema-next.sql" \
  --dev-url "docker://mysql/8/test" \
  --format '{{ sql . "  " }}'

输出中的 ALTER 通常表示已有对象定义发生变化，CREATE 表示目标状态新增对象，DROP 表示当前状态存在而目标状态没有的对象。它们是计划文本，不等于已经在数据库里执行成功。

把预览结果保存成 diff.sql

把输出落盘后，评审人可以在合并请求中直接查看 SQL。下面的重定向只保存命令输出，仍然没有执行数据库变更：

# 将 SQL 计划保存为评审文件，便于提交到代码仓库
atlas schema diff \
  --from "mysql://user:pass@localhost:3306/app" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/dev" \
  --format '{{ sql . "  " }}' > diff.sql

# 只读查看文件内容，确认计划中有哪些 DDL
sed -n '1,220p' diff.sql

如果两个状态相同，Atlas 会提示没有需要变更的内容；这时不要为了“得到一条 SQL”而强行修改 schema。空 diff 本身就是一个有用的结果，说明当前状态已经与目标状态同步。

只看部分对象时使用 include 和 exclude

大型 schema 不适合一次把所有对象混在一起评审，可以用过滤条件缩小范围：

# 只保留 users 相关对象，先聚焦一组表的差异
atlas schema diff \
  --from "file://schema-current.sql" \
  --to "file://schema-next.sql" \
  --dev-url "docker://mysql/8/test" \
  --include "users*"

# 排除备份表，避免无关对象干扰本次审阅
atlas schema diff \
  --from "file://schema-current.sql" \
  --to "file://schema-next.sql" \
  --dev-url "docker://mysql/8/test" \
  --exclude "*_backup"

过滤后要记住：结果只代表当前筛选范围。被 exclude 排除的表不会出现在这份 SQL 中，不代表它们没有差异。

不要把四个命令混为一谈

因此，标题中的“只生成 SQL”对应的是 schema diff。如果你的团队需要把 SQL 作为带时间戳的版本文件管理，才考虑 migrate diff；如果目的是把期望 schema 落到数据库，才进入 schema apply，并在共享环境中保留人工审批。

最后按四项确认结果

1. 确认 --from 是当前状态，--to 是目标状态，方向没有颠倒。
2. 确认 --dev-url 只用于解析和规划，命令中没有误放生产写入地址。
3. 打开 diff.sql，逐条检查 ALTER、CREATE、DROP 以及是否误包含被排除对象。
4. 确认本次只运行了 schema diff，没有在后续脚本中自动调用 schema apply。

当你需要的是“先看 SQL，再走评审和发布”，这套流程的关键就是把计算、审阅和执行拆开。Atlas 负责从两个状态生成计划，真正的数据库修改留给明确的 schema apply 或经过批准的迁移流程。

相关问题

schema diff 会自动执行 ALTER TABLE 吗？

不会。它输出的是从 from 到 to 的差异计划；需要实际应用时，应显式使用对应的 apply 或迁移执行流程。

为什么要提供 dev-url？

Atlas 需要开发数据库来解析目标 schema、确定数据库方言并计算迁移计划。它不等于要被变更的生产目标。

如何保存成迁移文件？

如果只是评审 SQL，可以用 shell 重定向保存 diff.sql；如果需要纳入 Atlas 版本化迁移目录，应研究 atlas migrate diff 的工作流，而不是把普通输出文件直接当作完整迁移目录。