Функция 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 есть в источнике, но не в цели	Нет
ENUM_VALUE_ADDED	В enum добавлено новое значение	Нет
ENUM_VALUE_REMOVED	Из enum удалено значение	Да
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 (деструктивные) по умолчанию не предвыбраны — пользователь должен явно согласиться

При применении merge будут включены только выбранные изменения.

---

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-оператор для применения этого изменения.