Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Environment Diff compares the database schemas of two environments side by side. Use it before a merge to see exactly what would flow from source to target, or to audit drift between any two environments. The diff engine introspects both environments’ schemas, runs a forward-only comparison, and generates the SQL needed to bring the target up to date. Environment schema diff comparison

​
How the diff works

Three stages, all server-side:
StageWhat happens
1. Schema analysisThe platform introspects both environments — tables, columns, indexes, constraints, relationships, enums, views.
2. ComparisonThe two structures are compared with forward-only semantics (see below).
3. Migration generationFor every detected change, the platform produces the DDL needed to apply it to the target.

​
Forward-only semantics

The engine compares source against target asymmetrically. Specifically:
  • Objects in source but not target → shown as CREATED. They need to be created in the target.
  • Objects in both → compared field by field. Differences are flagged as modifications.
  • Objects only in target → not shown as DROPPED.
The third rule is the key design decision. If a table exists only in the target, it was never present in the source — labeling it TABLE_DROPPED would suggest an intentional drop happened in the source. The diff focuses on changes that originated in the source and need to flow to the target. Exception — for column-level changes within a table that exists in both environments, COLUMN_DROPPED is detected, because that’s an actual column-removal operation performed on the source.

​
Change types

Change typeDescriptionBreaking
TABLE_CREATEDTable in source but not target.No
COLUMN_ADDEDNew column added to a source table.No
COLUMN_DROPPEDColumn removed from a source table that still exists in target.Yes
COLUMN_TYPE_CHANGEDColumn data type modified.Depends*
COLUMN_NULLABLE_CHANGEDColumn’s nullable constraint toggled.Depends
COLUMN_DEFAULT_CHANGEDColumn default value modified.No
INDEX_CREATEDNew index added.No
INDEX_DROPPEDIndex removed.No
ENUM_CREATEDNew enum type in source.No
ENUM_VALUE_ADDEDNew value on an enum.No
ENUM_VALUE_REMOVEDValue removed from an enum.Yes
VIEW_CREATEDView in source but not target.No
VIEW_MODIFIEDView SQL definition changed.No
RELATIONSHIP_ADDEDNew foreign key relationship.No
RELATIONSHIP_DROPPEDForeign key relationship removed.Yes
*Type narrowing (text → varchar(50), int8 → int4) is breaking — it can lose data. Type widening (varchar → text) is safe. TABLE_DROPPED, ENUM_DROPPED, and VIEW_DROPPED aren’t generated at the top level — see forward-only semantics above.

​
Cherry-pick selection

The diff view supports selecting individual changes for a subsequent merge:
  • Tick or untick each change individually.
  • Use the group checkbox on a table to select or deselect all changes for that table at once.
  • Breaking changes are not pre-selected by default. You have to explicitly opt in to drops, type narrowing, and enum-value removals — protection against accidental data loss.
The selection set is what flows into the merge. Anything you leave unticked stays in the source.

​
Reading the diff output

Each entry in the diff has these fields:
FieldWhat it tells you
changeTypeOne of the change-type identifiers above.
objectTypetable, column, index, enum, view, or relationship.
objectNameThe name of the affected object (e.g., the table name).
fieldNameFor column-level changes, the column name.
oldValue / newValueBefore/after values for modifications (e.g., varchar(255) → text).
isBreakingBoolean — true if the change can cause data loss or API breakage.
sqlThe DDL statement that would apply this change.

​
Use cases

GoalHow to use the diff
Pre-merge reviewDiff source → target before clicking Merge to see exactly what will flow.
Audit drift between environmentsDiff staging against master to surface ad-hoc changes that snuck into one but not the other.
Generate migration SQLRead the sql field on each change to feed into another tool.
Verify a merge succeededDiff source → target after a merge — should return zero differences if the merge was clean.

​
Running the diff via GraphQL

query EnvironmentDiff($input: EnvironmentDiffInput!) {
  environmentDiff(input: $input) {
    success
    message
    changes {
      changeType
      objectType
      objectName
      fieldName
      oldValue
      newValue
      isBreaking
      sql
    }
    summary {
      totalChanges
      breakingChanges
      addedTables
      droppedTables
      modifiedTables
    }
  }
}

{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "sourceEnvironment": "master",
    "targetEnvironment": "staging"
  }
}
The summary block is a quick at-a-glance view; changes carries the detail.

​
FAQ

Forward-only semantics. A table that exists only in the target was never in the source, so describing it as “dropped” would be misleading. Drops are surfaced at the column level only, where they reflect an actual removal that happened in the source.
A change that may cause data loss or break consumers of the API. Drops, narrowing type changes, removing enum values, and removing relationships are flagged as breaking. They’re never pre-selected for merge — you have to opt in.
The diff is pairwise. To compare three environments, run two diffs and reconcile. Most workflows compare a feature branch against staging and staging against master independently.
Schema only — tables, columns, indexes, enums, views, relationships. Data differences aren’t surfaced; the diff is about structural drift, not row counts.
Both environments must be in active status. Diffs against environments in branching, merging, or error state are rejected — the schemas may not be in a consistent state to compare.