Environment Diff 功能允许您并排比较两个环境的数据库架构。这对于在将分支合并回其父环境之前了解分支中进行了哪些架构更改，或审计任意两个环境之间的结构差异非常有用。

---

Diff 如何工作

比较引擎在三个阶段识别环境之间的结构差异：

1. 架构分析： 系统内省源环境和目标环境，以了解其完整结构（包括表、列、索引、约束和关系）。
2. 比较： 两个结构按照仅向前语义（如下所述）进行比较。引擎准确识别源环境中目标环境缺少的更改。
3. 迁移生成： 对于每个检测到的更改，系统自动生成将更改安全应用到目标环境所需的相应 SQL 命令。

---

仅向前 Diff 语义

Diff 引擎使用仅向前语义。这意味着：

• 在源中存在但不在目标中的对象 → 显示为 CREATED（需要在目标中创建）
• 在两个环境中都存在的对象 → 逐字段比较，差异显示为修改
• 仅在目标中存在的对象 → 不显示为 DROPPED

这是一个重要的设计决策。如果表仅在目标环境中存在，则它从未在源中存在。将其显示为 TABLE_DROPPED 会令人误解，因为源中从未执行过删除操作。Diff 专门专注于源自源并需要传播到目标的更改。

例外： 对于在两个环境中都存在的表内的列级更改，会检测到 COLUMN_DROPPED，因为它表示在源中执行的实际列删除操作。

---

更改类型

Diff 引擎检测以下架构更改类别：

更改类型	描述	Breaking
TABLE_CREATED	表在源中存在但不在目标中	否
COLUMN_ADDED	在源中的表添加了新列	否
COLUMN_DROPPED	列在目标中存在但在源中被删除	是
COLUMN_TYPE_CHANGED	列的数据类型被修改	视情况*
COLUMN_NULLABLE_CHANGED	列的可空约束被切换	视情况
COLUMN_DEFAULT_CHANGED	列的默认值被修改	否
INDEX_CREATED	添加了新索引	否
INDEX_DROPPED	删除了索引	否
ENUM_CREATED	新的枚举类型在源中存在但不在目标中	否
ENUM_VALUE_ADDED	向枚举添加了新值	否
ENUM_VALUE_REMOVED	从枚举中删除了值	是
VIEW_CREATED	视图在源中存在但不在目标中	否
VIEW_MODIFIED	视图的 SQL 定义被更改	否
RELATIONSHIP_ADDED	添加了新的外键关系	否
RELATIONSHIP_DROPPED	删除了外键关系	是

* 类型收窄（例如 text → varchar(50) 或 int8 → int4）被归类为 breaking，因为可能导致数据丢失。类型扩展（例如 varchar → text）被归类为安全。

注意： 顶级 TABLE_DROPPED、ENUM_DROPPED 和 VIEW_DROPPED 不由仅向前 diff 生成。仅在目标中存在的对象从源的角度不被视为“已删除”。

---

Cherry-Pick 选择

Diff 视图支持选择性更改应用。用户可以：

• 使用复选框选择或取消选择单个更改
• 使用组复选框选择或取消选择组内的所有更改（例如，特定表的所有更改）
• Breaking（破坏性）更改默认不预选 — 用户必须显式选择加入

只有选中的更改在应用合并时才会被包含。

---

GraphQL API

Query: environmentDiff

query EnvironmentDiff($input: EnvironmentDiffInput!) {
  environmentDiff(input: $input) {
    success
    message
    changes {
      changeType
      objectType
      objectName
      fieldName
      oldValue
      newValue
      isBreaking
      sql
    }
    summary {
      totalChanges
      breakingChanges
      addedTables
      droppedTables
      modifiedTables
    }
  }
}

Variables:

{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "sourceEnvironment": "master",
    "targetEnvironment": "staging"
  }
}

---

理解 Diff 输出

changes 数组中的每个条目代表具有以下字段的单个架构更改：

• changeType：上述更改类型标识符之一。
• objectType：受影响的数据库对象类型（table、column、index、enum、view、relationship）。
• objectName：受影响对象的名称（例如表名）。
• fieldName：对于列级更改，特定列的名称。
• oldValue / newValue：修改的前后值（例如 "varchar(255)" → "text"）。
• isBreaking：指示此更改是否可能导致数据丢失或 API 中断的布尔值。
• sql：为应用此更改而生成的 DDL 语句。