La función Environment Diff te permite comparar los esquemas de base de datos de dos entornos lado a lado. Es útil para entender qué cambios de esquema se han realizado en una rama antes de fusionarla con su padre, o para auditar diferencias estructurales entre dos entornos cualesquiera.

---

Cómo funciona el Diff

El motor de comparación identifica diferencias estructurales entre entornos en tres etapas:

1. Análisis de esquema: El sistema introspecciona ambos entornos fuente y destino para entender su estructura completa — incluyendo tablas, columnas, índices, restricciones y relaciones.
2. Comparación: Las dos estructuras se comparan siguiendo semántica solo hacia adelante (explicada abajo). El motor identifica exactamente qué cambios del entorno fuente faltan en el destino.
3. Generación de migración: Para cada cambio detectado, el sistema genera automáticamente los comandos SQL correspondientes para aplicar ese cambio al entorno destino de forma segura.

---

Semántica de Diff solo hacia adelante

El motor de diff usa semántica solo hacia adelante. Esto significa:

• Objetos que existen en fuente pero NO en destino → se muestran como CREATED (necesitan crearse en destino)
• Objetos que existen en AMBOS → se comparan campo por campo, las diferencias se muestran como modificaciones
• Objetos que existen SOLO en destino → NO se muestran como DROPPED

Esta es una decisión de diseño importante. Si una tabla existe solo en el entorno destino, nunca estuvo presente en la fuente. Mostrarla como TABLE_DROPPED sería engañoso porque nunca se realizó una operación de eliminación en la fuente. El diff se enfoca exclusivamente en cambios que se originaron en la fuente y deben propagarse al destino.

Excepción: Para cambios a nivel de columna dentro de tablas que existen en ambos entornos, COLUMN_DROPPED SÍ se detecta porque representa una operación real de eliminación de columna realizada en la fuente.

---

Tipos de cambio

El motor de diff detecta las siguientes categorías de cambios de esquema:

Tipo de cambio	Descripción	Rompiente
TABLE_CREATED	Una tabla existe en fuente pero no en destino	No
COLUMN_ADDED	Se añadió una nueva columna a una tabla en fuente	No
COLUMN_DROPPED	Una columna existe en destino pero fue eliminada en fuente	Sí
COLUMN_TYPE_CHANGED	Se modificó el tipo de datos de una columna	Depende*
COLUMN_NULLABLE_CHANGED	Se cambió la restricción nullable de una columna	Depende
COLUMN_DEFAULT_CHANGED	Se modificó el valor por defecto de una columna	No
INDEX_CREATED	Se añadió un nuevo índice	No
INDEX_DROPPED	Se eliminó un índice	No
ENUM_CREATED	Un nuevo tipo enum existe en fuente pero no en destino	No
ENUM_VALUE_ADDED	Se añadió un nuevo valor a un enum	No
ENUM_VALUE_REMOVED	Se eliminó un valor de un enum	Sí
VIEW_CREATED	Una vista existe en fuente pero no en destino	No
VIEW_MODIFIED	Se cambió la definición SQL de una vista	No
RELATIONSHIP_ADDED	Se añadió una nueva relación de clave foránea	No
RELATIONSHIP_DROPPED	Se eliminó una relación de clave foránea	Sí

* El estrechamiento de tipo (ej: text → varchar(50) o int8 → int4) se clasifica como rompiente porque puede causar pérdida de datos. El ensanchamiento de tipo (ej: varchar → text) se clasifica como seguro.

Nota: Los TABLE_DROPPED, ENUM_DROPPED y VIEW_DROPPED de nivel superior no se generan por el diff solo hacia adelante. Los objetos que existen solo en destino no se consideran “eliminados” desde la perspectiva de la fuente.

---

Selección Cherry-Pick

La vista de diff soporta aplicación selectiva de cambios. Los usuarios pueden:

• Seleccionar o deseleccionar cambios individuales usando casillas
• Seleccionar o deseleccionar todos los cambios dentro de un grupo (ej: todos los cambios de una tabla específica) usando la casilla del grupo
• Los cambios rompientes (destructivos) no están preseleccionados por defecto — el usuario debe optar explícitamente

Solo los cambios seleccionados se incluirán al aplicar el 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"
  }
}

---

Entendiendo la salida del Diff

Cada entrada en el array changes representa un único cambio de esquema con los siguientes campos:

• changeType: Uno de los identificadores de tipo de cambio listados arriba.
• objectType: El tipo de objeto de base de datos afectado (table, column, index, enum, view, relationship).
• objectName: El nombre del objeto afectado (ej: el nombre de la tabla).
• fieldName: Para cambios a nivel de columna, el nombre de la columna específica.
• oldValue / newValue: Los valores antes y después para modificaciones (ej: "varchar(255)" → "text").
• isBreaking: Un booleano que indica si este cambio podría causar pérdida de datos o ruptura de API.
• sql: La declaración DDL generada para aplicar este cambio.