# Write Migration

> Write or edit an Alembic migration safely against production data and constraints. Use for migrations, schema constraints, indexes, or column defaults.

- Skill: `learntocloud/write-migration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add learntocloud/write-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/learntocloud/write-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: learntocloud (https://skillmd.com/u/learntocloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/learntocloud/write-migration

---


# Write Migration

Treat any migration merged to a shared branch or applied to an environment as
immutable; correct it with a new migration. An unmerged migration may be
edited when it is known not to have run outside disposable local databases.

Preserve these production-safety rules:

- Drop incompatible check constraints before transforming rows, then recreate
  and validate them.
- Clean or merge existing duplicates before adding uniqueness.
- Set local lock and statement timeouts.
- Build production indexes concurrently inside
  `op.get_context().autocommit_block()`.
- Make upgrades safe for populated databases and write a valid downgrade.
- Keep one Alembic head and follow repository naming/docstring checks.

Inspect adjacent migrations and `api/scripts/lint_migration_sql.py` for current
conventions. Run the migration-specific checks plus `uv run poe check`.