Migration Files Explained
Anatomy of a Migration File
Every migration file defines a Migration class with two important attributes: dependencies, listing migrations that must run before it, and operations, the actual list of changes to apply.
Example: Anatomy of a Migration File
This migration depends on 0001_initial having already run, then adds a new published field to the existing Article table.
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [('blog', '0001_initial')]
operations = [
migrations.AddField(
model_name='article',
name='published',
field=models.BooleanField(default=False),
),
]Common Operation Types
Django generates different operation classes depending on the kind of model change: CreateModel for a brand-new model, AddField or RemoveField for a single field, and AlterField for changing a field's options.
Example: Common Operation Types
This operation changes the Article model's title field to allow up to 300 characters instead of its previous length.
migrations.AlterField(
model_name='article',
name='title',
field=models.CharField(max_length=300),
)Why Order Matters
Migrations run in dependency order, not filename order alone — each file's dependencies list tells Django exactly which migrations must be applied first, even across different apps.
Note: You can inspect an app's migration graph with the showmigrations command.
Example: Why Order Matters
This lists every migration in the blog app with an [X] next to ones already applied, showing the real applied order.
python manage.py showmigrations blog⚠️ Run this command in your terminal.
- Manually renumbering or renaming migration files, which breaks Django's dependency tracking between them.
- Assuming a migration file's operations list matches the current model exactly, when several migrations can each make small incremental changes.
- Deleting a migration that a later migration depends on, which makes migrate fail with a missing-dependency error.
- Each migration file has a numbered name and lives inside its app's migrations/ folder.
- A Migration class lists dependencies (which migrations must run first) and operations (what actually changes).
- Operations map to Python classes like CreateModel, AddField, and AlterField.
- Reading a migration file tells you exactly what SQL-equivalent change it will make.
Chapter Quiz — Complete all 8 topics to unlock
0/8 topics done
Complete these topics first: