Environment Diff

Funkcja Environment Diff umożliwia porównanie schematów bazy danych dwóch środowisk obok siebie. Przydatna do zrozumienia zmian schematu w gałęzi przed merge do rodzica lub audytu różnic strukturalnych między dowolnymi dwoma środowiskami.

Porównanie diff schematu środowisk

Jak działa Diff

Silnik porównawczy identyfikuje różnice strukturalne między środowiskami w trzech etapach:

Analiza schematu: System introspekcjonuje oba środowiska źródłowe i docelowe, aby zrozumieć pełną strukturę — w tym tabele, kolumny, indeksy, ograniczenia i relacje.
Porównanie: Dwie struktury są porównywane według semantyki tylko do przodu (wyjaśnione poniżej). Silnik identyfikuje dokładnie, które zmiany ze środowiska źródłowego brakują w docelowym.
Generowanie migracji: Dla każdej wykrytej zmiany system automatycznie generuje odpowiadające polecenia SQL do bezpiecznego zastosowania tej zmiany w środowisku docelowym.

Semantyka Diff tylko do przodu

Silnik diff używa semantyki tylko do przodu. Oznacza to:

Obiekty istniejące w źródle, ale NIE w celu → wyświetlane jako CREATED (trzeba je utworzyć w celu)
Obiekty istniejące w OBIE → porównywane pole po polu, różnice jako modyfikacje
Obiekty istniejące TYLKO w celu → NIE wyświetlane jako DROPPED

To ważna decyzja projektowa. Jeśli tabela istnieje tylko w środowisku docelowym, nigdy nie była w źródle. Pokazanie jej jako TABLE_DROPPED byłoby mylące, bo w źródle nie wykonano operacji usunięcia. Diff skupia się wyłącznie na zmianach pochodzących ze źródła i wymagających propagacji do celu.

Wyjątek: Dla zmian na poziomie kolumn w tabelach istniejących w obu środowiskach COLUMN_DROPPED JEST wykrywane, bo reprezentuje faktyczną operację usunięcia kolumny wykonaną w źródle.

Typy zmian

Silnik diff wykrywa następujące kategorie zmian schematu:

Typ zmiany	Opis	Breaking
`TABLE_CREATED`	Tabela istnieje w źródle, ale nie w celu	Nie
`COLUMN_ADDED`	Dodano nową kolumnę do tabeli w źródle	Nie
`COLUMN_DROPPED`	Kolumna istnieje w celu, ale została usunięta w źródle	Tak
`COLUMN_TYPE_CHANGED`	Zmieniono typ danych kolumny	Zależy*
`COLUMN_NULLABLE_CHANGED`	Zmieniono ograniczenie nullable kolumny	Zależy
`COLUMN_DEFAULT_CHANGED`	Zmieniono wartość domyślną kolumny	Nie
`INDEX_CREATED`	Dodano nowy indeks	Nie
`INDEX_DROPPED`	Usunięto indeks	Nie
`ENUM_CREATED`	Nowy typ enum istnieje w źródle, ale nie w celu	Nie
`ENUM_VALUE_ADDED`	Dodano nową wartość do enum	Nie
`ENUM_VALUE_REMOVED`	Usunięto wartość z enum	Tak
`VIEW_CREATED`	Widok istnieje w źródle, ale nie w celu	Nie
`VIEW_MODIFIED`	Zmieniono definicję SQL widoku	Nie
`RELATIONSHIP_ADDED`	Dodano nową relację klucza obcego	Nie
`RELATIONSHIP_DROPPED`	Usunięto relację klucza obcego	Tak

* Zawężenie typu (np. text → varchar(50) lub int8 → int4) jest klasyfikowane jako breaking, bo może powodować utratę danych. Poszerzenie typu (np. varchar → text) jest klasyfikowane jako bezpieczne.

Uwaga: Top-level TABLE_DROPPED, ENUM_DROPPED i VIEW_DROPPED nie są generowane przez diff tylko do przodu. Obiekty istniejące tylko w celu nie są traktowane jako “usunięte” z perspektywy źródła.

Selekcja Cherry-Pick

Widok diff obsługuje selektywne stosowanie zmian. Użytkownicy mogą:

Zaznaczać lub odznaczać poszczególne zmiany za pomocą checkboxów
Zaznaczać lub odznaczać wszystkie zmiany w grupie (np. dla konkretnej tabeli) za pomocą checkboxa grupy
Zmiany breaking (destrukcyjne) nie są domyślnie zaznaczone — użytkownik musi wyraźnie się na nie zgodzić

Tylko zaznaczone zmiany będą uwzględnione przy stosowaniu 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"
  }
}

Zrozumienie wyjścia Diff

Każdy wpis w tablicy changes reprezentuje pojedynczą zmianę schematu z polami:

changeType: Jeden z identyfikatorów typów zmian wymienionych powyżej.
objectType: Rodzaj dotkniętego obiektu bazy danych (table, column, index, enum, view, relationship).
objectName: Nazwa dotkniętego obiektu (np. nazwa tabeli).
fieldName: Dla zmian na poziomie kolumny — nazwa konkretnej kolumny.
oldValue / newValue: Wartości przed i po dla modyfikacji (np. "varchar(255)" → "text").
isBreaking: Boolean wskazujący, czy zmiana może powodować utratę danych lub uszkodzenie API.
sql: Wygenerowana instrukcja DDL do zastosowania tej zmiany.