---
title: "Migrations · Agent Wranglers"
url: https://agentwranglers.se/playbook/data/migrations
updated: 2026-10-20
licence: "All rights reserved"
---

# Migrations

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> Change the schema only through numbered migrations in version control. Run them in the deploy, test them on a copy, and keep old and new code working.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers data playbook: https://agentwranglers.se/playbook/data/migrations`.

## Required

- [Change the schema only with migrations](https://agentwranglers.se/playbook/data/migrations/versioned-migrations): Every schema change is a numbered migration file in version control. Nobody changes a shared database by hand.
- [Never edit an applied migration](https://agentwranglers.se/playbook/data/migrations/immutable-migrations): Once a migration has run anywhere outside your own machine, never change it. Fix mistakes with a new migration.
- [Expand first and contract later](https://agentwranglers.se/playbook/data/migrations/expand-and-contract): Make every schema change work with both the old and the new code, so deploys and rollbacks never break.
- [Test migrations on a copy of production data](https://agentwranglers.se/playbook/data/migrations/test-migrations): Run each migration on a recent copy of production data before it reaches production, and time it.
- [Fix production data with reviewed scripts](https://agentwranglers.se/playbook/data/migrations/data-fixes): Change or delete production data only with a reviewed script in version control. The script checks how many rows it touched before it commits.

## Recommended

- [Keep migrations from locking tables](https://agentwranglers.se/playbook/data/migrations/lock-safe-migrations): Write migrations that never block a busy table for long. A long lock stops every request that touches it.

- Previous: [Transactions and concurrency](https://agentwranglers.se/playbook/data/transactions-and-concurrency)
- Next: [Backups and recovery](https://agentwranglers.se/playbook/data/backups-and-recovery)
- [All chapters](https://agentwranglers.se/playbook/data)