migrations

# 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:

- **Before `flipping_routing`** (still in dump / restore / copy phases): use `manage_migrations` `action: "abort"`. Cancels cleanly; no data flipped.
- **After `flipping_routing`** (already cut over): abort is locked. Use `manage_migrations` `action: "reverse"`. This rolls back to source — works only while the source replica is still retained (i.e. you haven't called `teardown_source_replica` yet).
- **Move is done and stable** (the new region is serving traffic without issues for a while): use `teardown_source_replica({ migration_id })`. Stops paying for source-region storage. After this, `reverse` is no longer available.

---

## 4. Inspecting in-flight + retained state

- `manage_migrations({ action: "get_active", app_id })` → `{ migration: AppMigration | null }`. Tells you if a move is in progress right now.
- `manage_migrations({ action: "list_source_replicas" })` → all retained replicas the caller owns. Call this before any teardown so you know what you'd lose.

---

## 5. Common pitfalls

- **Calling `move_app` again while one is active** — backend returns 409 `ineligible`. Resolve by waiting for the active migration to terminate, or aborting it first.
- **Trying to abort after cutover** — returns 409. The path forward is `reverse`, not abort.
- **Tearing down a replica too early** — once it's gone, reverse-move is no longer possible. Verify the destination region has been serving traffic cleanly before teardown.
- **Forgetting `dest_region` is validated** — invalid slugs return 400. Always `list_regions` first if you're not sure.

---

## 6. What this skill does NOT cover

- Schema migrations (table/column changes) — use `butterbase-skills:schema-design`.
- Region selection at app *creation* time — use `init_app` directly with the `region` parameter.
- Cross-region replica reads (none — Butterbase is single-region-active per app).