# Migrations

> 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

- **Type:** Skill
- **Install:** `agentstack add skill-butterbase-ai-butterbase-skills-migrations`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [butterbase-ai](https://agentstack.voostack.com/s/butterbase-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [butterbase-ai](https://github.com/butterbase-ai)
- **Source:** https://github.com/butterbase-ai/butterbase-skills/tree/main/skills/migrations

## Install

```sh
agentstack add skill-butterbase-ai-butterbase-skills-migrations
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [butterbase-ai](https://github.com/butterbase-ai)
- **Source:** [butterbase-ai/butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-butterbase-ai-butterbase-skills-migrations
- Seller: https://agentstack.voostack.com/s/butterbase-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.