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.

Merge applies schema changes from one environment (the source) to another (the target). It’s the operation that propagates structural changes — new tables, new columns, new indexes — across your development lifecycle. The flow is deliberately conservative: every merge is preceded by an automatic backup, runs as a single transaction, and rolls back automatically if anything fails. You pick exactly which changes to apply via the cherry-pick UI; you never commit to “merge everything” without seeing the list first.

​
How merge works

StepWhat happens
1. SelectionPick a source and a target environment.
2. AnalysisThe platform runs a diff and surfaces the changes missing in the target.
3. Review and cherry-pickTick the changes you want to apply. Breaking changes are never pre-selected — you have to opt in.
4. Automatic backupA pre-merge backup of the target is created automatically.
5. Atomic applicationSelected changes are applied as a single transaction. All-or-nothing.
6. Status updateOn success, the target is in its new state and a history entry is recorded. On failure, the target rolls back to its pre-merge state.

​
Transactional DDL

Every merge runs inside a single database transaction:
  • All-or-nothing — every selected change applies, or none does. There’s no partial state.
  • No partial migrations — if the third of ten changes fails, the first two are rolled back along with the rest.
  • Rollback is automatic — you don’t run a recovery step. The transaction aborts and the target’s schema is exactly what it was before you clicked Merge.
This applies even when the failing change is the very last one in the batch.

​
Environment locking

While a merge is in progress, the target environment is locked:
  • Other merges into the same target are rejected.
  • Branching from the target is rejected.
  • Schema edits on the target via the Data Model UI are rejected.
The lock is automatically released on success, on rollback, or when the merge enters the error state. Reads against the target continue to work — only mutating schema operations are blocked.

​
Cherry-pick selection

The merge UI is a checkbox tree built on top of the diff:
  • Per-change selection — tick individual changes (a single column added, a single index created).
  • Group selection — tick the parent checkbox on a table to select all changes for that table at once.
  • Breaking-change protection — drops, type narrowing, and enum-value removals are unticked by default. You explicitly opt in.
Anything you leave unticked stays in the source. The same change can be merged in a later operation by re-running the merge.

​
Pre-merge backup

Before any DDL runs, the platform takes a full backup of the target environment — schema and data. The backup is keyed to the merge so it shows up in the Backups view as Pre-merge alongside the migration record in History. If the merge succeeds but you discover a regression hours or days later, restore from that pre-merge backup to revert the target to its exact pre-merge state. See Backups → Restoring.

​
On failure

If any DDL in the batch fails:
  1. The transaction aborts. The target’s schema goes back to its pre-merge state.
  2. The merge record is marked failed in History with the failure reason and the index of the offending change.
  3. The target environment’s lock is released.
  4. The pre-merge backup is preserved (it’s a normal backup like any other).
A failed merge doesn’t leave a half-migrated database. Fix the failing change in the source — usually a constraint conflict, a NOT-NULL backfill issue, or a circular dependency — and re-run.

​
Rollback

Rolling back a successful merge means restoring the pre-merge backup:
  1. Open Backups.
  2. Find the Pre-merge entry from the merge you want to undo.
  3. Restore it to the same target environment.
A restore reverts the entire database (schema + data) to the snapshot point. It’s not a per-change undo — the whole environment goes back to the moment before the merge ran. Verify changes in staging before merging into production to keep this option as a last resort.

​
Common patterns

PatternHow to do it
Promote a feature branch to stagingMerge feature-x → staging. Cherry-pick only the changes that are ready.
Promote staging to productionMerge staging → master. Run the diff first to confirm everything’s expected.
Sync dev with master after a hotfixMerge master → dev. Useful when a hotfix in production needs to flow back.
Test a destructive changeMerge with the breaking change ticked into a qa-* environment, verify, then merge into staging.

​
Running merge via GraphQL

mutation MergeEnvironments($input: MergeEnvironmentInput!) {
  mergeEnvironments(input: $input) {
    success
    message
    migrationId
    changesApplied
    backupId
  }
}
The migrationId is the entry in History; the backupId is the pre-merge backup’s ID, also visible in Backups.

​
FAQ

Cherry-pick what you want now. Re-run the merge later — the diff regenerates against the current target state, so the unmerged changes will show up again ready to apply.
Yes. Adding a NOT-NULL column without a default fails if the target has rows that can’t satisfy it. Type-narrowing a column fails if existing values don’t fit. The transaction aborts, the rollback runs, the merge is marked failed.
Merge moves schema, not data. To copy data between environments, branch a new environment in Full mode (or restore a backup of the source into the target). See Creating environments.
A failed merge rolls back automatically inside the transaction — the target never changes. Restoring after a successful merge means using the pre-merge backup to undo a merge that completed but turned out to be a mistake.
No. The target has to be active. If a previous merge is still running, wait for it to finish or for it to fail and clear. The status indicator on the environment switcher shows the current state.