# Migrations

Use when moving a Butterbase app between regions, checking migration progress, aborting...

- Repository: https://github.com/butterbase-ai/butterbase-skills (535 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add butterbase-ai/butterbase-skills --skill migrations -g -a claude-code -y`
Codex: `npx skills add butterbase-ai/butterbase-skills --skill migrations -g -a codex -y`
Cursor: `npx skills add butterbase-ai/butterbase-skills --skill migrations -g -a cursor -y`
Gemini CLI: `npx skills add butterbase-ai/butterbase-skills --skill migrations -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add butterbase-ai/butterbase-skills`

## Description

Use when moving a Butterbase app between regions, checking migration progress, aborting a stuck move, reverse-rolling a completed move, or tearing down retained source replicas after a move is stable

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/butterbase-ai/butterbase-skills/blob/HEAD/skills/migrations/SKILL.md