ecto-migration

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/ecto-essentials/`	Migrations/schemas
`apply-ecto-conventions`	`skills/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.

Production authorization: prepare and test the migration and rollback locally within the authorized task. Before executing production-impacting locks or a production expand-contract rollout, confirm authorization for that concrete operation; preserve authorization already given.

HARD GATE — Plan and rollback documented:

Lock risk and index concurrency are assessed.
Rollback strategy is documented.
For production-impacting locks, HITL approval is obtained.

If gate fails: Resolve the plan or rollback defect locally; block production execution until the operation is authorized.

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:

The migration changes schema or performs a data backfill, not both.
Indexes are added on foreign keys.
change/0 is reversible or separate up/down functions are provided.

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:

mix ecto.migrate → mix ecto.rollback → mix ecto.migrate succeeds.

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:

A test that depends on the new schema/constraint failed before the migration and passes after.
mix test, mix format --check-formatted, and mix credo --strict pass.
Schemas and typespecs are updated if columns changed.

If gate fails: Update schemas/typespecs, fix formatting, Credo, or test failures.

Verification checklist

Plan + rollback noted
No combined schema+backfill
migrate/rollback/migrate OK
Tests green
HITL for high-risk prod steps

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