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	열의 nullable 제약 조건이 전환됨	경우에 따라
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 문.