Environment Diff

Environment Diff機能を使用すると、2つの環境のデータベーススキーマを並べて比較できます。ブランチを親にマージする前にどのスキーマ変更が行われたかを理解したり、任意の2つの環境間の構造的差異を監査したりするのに便利です。

環境スキーマdiff比較

Diffの仕組み

比較エンジンは、3つの段階で環境間の構造的差異を特定します：

スキーマ分析: システムはソースとターゲットの両方の環境をイントロスペクトし、テーブル、列、インデックス、制約、リレーションを含む完全な構造を理解します。
比較: 2つの構造は以下で説明する前方のみセマンティクスに従って比較されます。エンジンは、ソース環境からの変更のうちターゲットに欠けているものを正確に特定します。
マイグレーション生成: 検出された各変更について、システムはその変更をターゲット環境に安全に適用するために必要な対応する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文。