# Migration Strategist

> Manages major schema changes with zero-downtime using the expand-contract pattern, rather than writing unstable from-scratch migrations.

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

## Install

```sh
agentstack add skill-fatih-developer-fth-skills-migration-strategist
```

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

## About

# Migration Strategist Protocol

This skill focuses on taking a database from State A to State B without causing downtime, locks, or data loss in production. Direct `ALTER TABLE` operations on large tables are dangerous and often require a multi-step rollout.

**Core assumption:** You cannot lock the table. You cannot break the old version of the application while the new version is deploying.

---

## 1. The Zero-Downtime Pipeline
When asked "How do I rename this column?" or "How do I split this table?", standard `ALTER TABLE RENAME` breaks the app. 
Always enforce a backward-compatible migration strategy:

### The Expand & Contract Pattern (4 Steps)
For breaking changes (e.g., renaming a column `name` to `full_name`):

1. **Add (Expand):** Add the new column `full_name` (nullable initially).
2. **Dual Write:** Deploy application code that writes to BOTH `name` and `full_name`, but reads from `name`.
3. **Backfill:** Write a script or background job to populate `full_name` using `name` for old rows.
4. **Switch & Drop (Contract):** Change the app to read/write ONLY `full_name`. After successful deployment, run a final migration to drop `name`.

## 2. Output Format (The Plan)

Provide a numbered timeline mapping Application Code states vs Database changes.

**Required Outputs (Must write BOTH to `docs/database-report/`):**

1. **Human-Readable Markdown (`docs/database-report/migration-strategist-report.md`)**
```markdown
### 🕰️ Step 1: Database Expand (Migration 1)
- Add `full_name` column.
- SQL: `ALTER TABLE users ADD COLUMN full_name VARCHAR(255);`

### 💻 Step 2: Application Release (v1.1)
- Code updates to write to BOTH `name` and `full_name`.
- Read from `name`.

### 🔄 Step 3: Data Backfill Script
- SQL: `UPDATE users SET full_name = name WHERE full_name IS NULL;`
- Action: Run this out-of-band in batches of 10,000 to avoid long locks.

### 💻 Step 4: Application Release (v1.2)
- Code updates to read/write ONLY to `full_name`.

### ✂️ Step 5: Database Contract (Migration 2)
- SQL: `ALTER TABLE users DROP COLUMN name;`
- Action: Execute only when v1.1 is fully retired from traffic.
```

2. **Machine-Readable JSON (`docs/database-report/migration-strategist-output.json`)**
```json
{
  "skill": "migration-strategist",
  "steps": [
    {"phase": "expand", "target_table": "users", "action": "add_column", "details": "full_name"},
    {"phase": "app_release_1", "action": "dual_write"},
    {"phase": "backfill", "query": "UPDATE users SET full_name = name"},
    {"phase": "app_release_2", "action": "read_write_new_only"},
    {"phase": "contract", "target_table": "users", "action": "drop_column", "details": "name"}
  ]
}
```

## 3. Rollback Strategy
Every Migration plan must include a clear rollback path if Step 2 or Step 4 fails. How do we reverse it?
- "If v1.2 fails, rollback to v1.1. Data is still dual-written to `name`, so reverting the code is safe."

---

## Guardrails
- **No `DEFAULT` on new columns for large tables:** In some older SQL versions, adding a column with a default value locks and rewrites the entire table. Use nullable + background backfill.
- **Data Type Casting:** Be explicitly careful about data truncation passing from State A to State B.
- **Constraints Last:** Add `NOT NULL`, `UNIQUE`, or Foreign Keys only at the very end of the backfill process.

## Source & license

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

- **Author:** [fatih-developer](https://github.com/fatih-developer)
- **Source:** [fatih-developer/fth-skills](https://github.com/fatih-developer/fth-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-fatih-developer-fth-skills-migration-strategist
- Seller: https://agentstack.voostack.com/s/fatih-developer
- 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%.