Migrations

Handles the full lifecycle of moving a Butterbase app between regions: kicking off a migration, polling its 11-step progress (dump, restore, blob copy, traffic flip), and dealing with things when they go sideways. The orchestration retains your source replica so you can reverse-roll after cutover if the new region misbehaves, but only until you explicitly tear it down. The skill wraps five tools that let you abort before cutover, reverse after cutover, check what's still retained, and clean up once you're confident. Useful because the state machine has real consequences: abort works early, reverse works late, and teardown is permanent.

GitHub stars: 532
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add butterbase-ai/butterbase-skills --skill migrations --agent claude-code

Installs into .claude/skills of the current project.

Files

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.

SKILL.md on GitHub