Butterbase App Migrations (Multi-Region)

Moving an app between regions is an orchestrated migration: data dumped from source, restored in dest, blobs copied, runtime brought up, then traffic flipped. Source replica is retained for safe rollback until you tear it down.

Four small tools wrap the orchestration:

Tool	Purpose
list_regions	Discover what regions exist before suggesting one.
move_app	Start a migration. Returns a migration_id.
move_app_status	Read the current step + replica state of a specific migration.
manage_migrations	Operational ops: get_active, abort, reverse, list_source_replicas.
teardown_source_replica	Decommission the retained source replica once you're confident.

---

1. The step sequence

A successful move walks through 11 steps in order:

requested → reserving_dest → blocking_writes → dumping_data →
restoring_data → copying_blobs → copying_runtime → flipping_routing →
setting_up_reverse_replication → unblocking_writes → completed

The cutover happens at flipping_routing. Before that, the app is still served from the source. After that, traffic is on the destination.

Terminal states: completed, aborted, failed.

---

2. Start a move

list_regions              → confirm dest region is supported
move_app(app_id, dest_region) → { migration_id, status: "queued" }

Then poll with move_app_status({ app_id, migration_id }) every few seconds (or call manage_migrations({ action: "get_active", app_id }) if you've forgotten the id).

---

3. Recovery: pick the right escape hatch

Stuck or wrong choice? Different state, different tool: