Engineering Advanced MigrationPlanningRollback

Migration Architect

Migration planning, compatibility checking, and rollback generation.

$skillfish add ~skills/migration-architect

Real Examples Get Started Models & Context

Real Conversations

See how the Migration Architect skill responds to actual requests. These are representative examples of what your AI agent will produce.

You

We need to add a NOT NULL column tenant_id UUID to our orders table which has 8.2 million rows. We're on PostgreSQL 14 on RDS. We can't have more than 30 seconds of downtime. What's the migration strategy?

Agent

Adding a NOT NULL column directly to a large table will lock it for the full backfill — at 8.2M rows that's likely 10–20 minutes on RDS. You need a three-phase expand-contract migration.

Phase 1 — Expand (deploy now, no downtime):

-- Add column as nullable first — instant, no lock
ALTER TABLE orders ADD COLUMN tenant_id UUID;
-- Add index concurrently (no table lock)
CREATE INDEX CONCURRENTLY idx_orders_tenant_id ON orders(tenant_id);

Deploy app code that writes tenant_id on all new orders.

Phase 2 — Backfill (run during off-hours):

-- Batch update to avoid long transactions
DO $$ 
DECLARE batch_size INT := 10000;
BEGIN
  LOOP
    UPDATE orders SET tenant_id = resolve_tenant(account_id)
    WHERE tenant_id IS NULL
    LIMIT batch_size;
    EXIT WHEN NOT FOUND;
    PERFORM pg_sleep(0.1); -- brief pause between batches
  END LOOP;
END $$;

Monitor with: SELECT count(*) FROM orders WHERE tenant_id IS NULL;

Phase 3 — Contract (after backfill complete):

-- Add NOT NULL constraint — fast if no NULLs remain
ALTER TABLE orders ALTER COLUMN tenant_id SET NOT NULL;

Rollback plan: If Phase 3 fails, the column stays nullable — no data loss, app code continues writing it. Rollback Phase 1 only if Phase 2 is still pending.

Risk assessment: MEDIUM. Main risk is backfill taking longer than expected if resolve_tenant() is slow. Run on a staging copy of prod data first to time it.

You

Our Rails monolith handles user auth, billing, and inventory — all in one app. We want to extract billing first because it's the most independent. The billing code is about 8,000 lines. How do we do this without a big-bang rewrite?

Agent

The Strangler Fig pattern is the right call. Here's the phase plan for billing extraction:

Phase 1 — Add API gateway proxy (Week 1-2)

Deploy nginx or a thin Rails engine that intercepts billing requests:

Client → Rails Monolith → /api/billing/* → API Gateway
                                              ↓ (phase 1: proxy back)
                                          Monolith billing controller

No behavior change yet — just add the routing layer. Validate with smoke tests.

Phase 2 — Build billing service in parallel (Weeks 3-8)

New service (Node/Python/Go — your choice) with its own database
Dual-write: monolith writes to both its DB and billing service via events
Billing service reads are feature-flagged to 1% of traffic initially

Phase 3 — Traffic migration (Weeks 9-12)

# Feature flag controls read traffic
if feature_flag('billing_service_reads', user_id):
    return billing_service.get_invoices(account_id)
else:
    return monolith_billing.get_invoices(account_id)

Ramp: 1% → 10% → 50% → 100% over 3 weeks. Compare outputs with shadow testing.

Phase 4 — Cut over writes, retire monolith billing (Weeks 13-14)

Switch writes to billing service primary, monolith as secondary. After 72h stable → remove monolith billing code.

Compatibility checker will flag these breaking points to resolve before Phase 3:

3 shared ActiveRecord models that cross billing/inventory boundaries
2 Sidekiq jobs that mix billing and inventory logic
1 GraphQL type that merges order + invoice fields

You

We're migrating from Heroku to AWS ECS Fargate next month. Our app is a Django/Postgres stack, about 40k monthly active users. I need a rollback plan in case something goes wrong 2 hours after cutover.

Agent

Here's a tested rollback plan for the Heroku → ECS Fargate migration:

Pre-migration requirements (must be in place before cutover):

Heroku app kept live but scaled to minimum (not terminated) during 72h window
DNS TTL reduced to 60s at T-24h
RDS PostgreSQL populated from Heroku's Postgres via pg_dump + pg_restore
CDC (logical replication) streaming Heroku Postgres → RDS during migration window

Cutover decision gate at T+2h:

Metric	Rollback Trigger
P95 response time	>2x Heroku baseline (>800ms)
5xx error rate	>0.5% sustained for 5 min
Failed health checks	>3 consecutive on any task
DB connection errors	Any in application logs

Rollback execution (<5 minutes):

# Step 1 — Point DNS back to Heroku (60s to propagate)
aws route53 change-resource-record-sets \
  --hosted-zone-id $ZONE_ID \
  --change-batch file://rollback-dns.json

# Step 2 — Scale up Heroku dynos
heroku ps:scale web=4 worker=2 --app myapp-prod

# Step 3 — Verify Heroku is receiving traffic
curl -sf https://myapp.com/health | jq .database

Data reconciliation after rollback:

Stop CDC replication
Any writes that hit ECS between cutover and rollback are in RDS
Run reconciliation script to replay missing writes to Heroku Postgres
Max data gap: seconds (CDC lag) — not hours

Keep Heroku app alive for 72h post-cutover regardless of success. Terminating it early eliminates your rollback option.

Get Started

How to install and use this skill in your preferred environment.

Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase. Web-based AI can use the knowledge and frameworks, but won't have tool access.

Models & Context

Which AI models and context windows work best with this skill.

Recommended Models

Best

Claude Opus 4 Claude Sonnet 4 GPT-4.1 Gemini 2.5 Pro Grok 3 Kimi K2

Good

Claude Haiku 4.5 GPT-4.1 mini Gemini 2.5 Flash Grok 3 mini

Larger models produce more detailed, production-ready outputs.

Context Window

This skill's SKILL.md is typically 3–10 KB — fits in any modern context window.

8K Skill only

32K+ Skill + conversation

100K+ Skill + references + codebase

All current frontier models (Claude, GPT, Gemini) support 100K+ context. Use the full window for complex multi-service work.

Pro tips for best results

1

Be specific

Include numbers — users, budget, RPS — so the skill can size the architecture.

2

Share constraints

Compliance needs, team size, and existing stack all improve the output.

3

Iterate

Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.

4

Combine skills

Pair with companion skills below for end-to-end coverage.

Ready to try Migration Architect?

Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.

$skillfish add ~skills/migration-architect

← Browse all 169 skills

Migration Architect

Real Conversations

Get Started

Claude Code, OpenCode, or any CLI agent

Cursor, Windsurf, or IDE-based agents

Claude.ai, ChatGPT, Gemini, or any web AI

Models & Context

Recommended Models

Context Window

Pro tips for best results

Ready to try Migration Architect?