| name | ecto-migration |
| type | playbook |
| tags | ["playbooks"] |
| license | MIT |
| description | Safe migration playbook with hard gates and HITL for production risk: plan locks/rollback → implement schema-only migration → migrate/rollback/re-migrate → never mix backfill → expand-contract for NOT NULL → suite green. Trigger: migration, ecto.migrate, add column, index concurrently, expand-contract.
|
| metadata | {"version":"1.0.0","user-invocable":"true","entry_point":true,"phases":"Phase 1: Plan, Phase 2: Implement, Phase 3: Migrate cycle, Phase 4: Verify","hard_gates":"Plan and rollback documented, No combined schema and data migrations, Migrate-rollback-migrate cycle green, Format Credo and full suite green","dependencies":{"source":"self","skills":["ecto-essentials","apply-ecto-conventions"]}} |
Ecto Migration Playbook
HARD-GATE
- A migration plan and rollback story are documented before any migration is written.
- Schema changes and data backfill are never combined in the same migration.
- A test that depends on the new schema/constraint fails before the migration is applied and passes after.
- The
mix ecto.migrate → mix ecto.rollback → mix ecto.migrate cycle must succeed.
mix format --check-formatted, mix credo --strict, and the full mix test suite are green.- HITL approval is obtained for production-impacting locks.
When to use
Any schema change: tables, columns, indexes, constraints.
Atomic skills this playbook loads
| Skill | Path | Role |
|---|
ecto-essentials | skills/database/ecto-essentials/ | Migrations/schemas |
apply-ecto-conventions | skills/database/apply-ecto-conventions/ | Repo/query conventions |
Flow
flowchart TD
A[Plan locks rollback impact] --> B[HITL if prod risk]
B --> C[Write schema migration]
C --> D[migrate rollback migrate]
D --> E[Suite green]
E --> F[Separate backfill migration if needed]
Agent Phases
Phase 1 — Plan
Assess: lock risk, expand-contract need, rollback strategy, index concurrency.
HUMAN-IN-THE-LOOP: for production-impacting locks or multi-step expand-contract, present plan and wait for approval.
HARD GATE — Plan and rollback documented:
If gate fails: Re-document the plan and rollback; do not write the migration until the plan is approved.
Phase 2 — Implement
- Schema change or data backfill — never both in one migration
- Indexes on FKs; reversible
change/0 when possible
HARD GATE — No combined schema and data migrations:
If gate fails: Split the migration into a schema migration and a separate backfill migration.
Phase 3 — Migrate cycle
mix ecto.migrate
mix ecto.rollback
mix ecto.migrate
HARD GATE — Migrate-rollback-migrate cycle green:
If gate fails: Fix the migration reversibility before proceeding.
Phase 4 — Verify
mix test
Update schemas/typespecs if columns changed.
HARD GATE — Format Credo and full suite green:
If gate fails: Update schemas/typespecs, fix formatting, Credo, or test failures.
Verification checklist
Error Recovery
Irreversible migration → stop; write compensating migration; do not force production.
Output Style
## Ecto Migration Report
**Plan:** <lock risk, rollback strategy, HITL status>
**Migration:** `<migration filename>`
**HARD-GATE results:**
- Plan and rollback documented: PASS / FAIL
- No combined schema and data migrations: PASS / FAIL
- Migrate-rollback-migrate cycle green: PASS / FAIL
- Format Credo and full suite green: PASS / FAIL
**Command results:**
- `mix ecto.migrate`: exit 0 / non-zero
- `mix ecto.rollback`: exit 0 / non-zero
- `mix test`: exit 0 / non-zero
**Verdict:** APPROVE / REQUEST_CHANGES
