Migrations
Migrations are Django's way of turning changes to your models into changes to your database. They are small Python files that record each step, like "create the Event table" or "add a capacity column", so every copy of your project's database can be brought up to date safely.
The two commands
| Command | What it does |
|---|---|
python manage.py makemigrations | Compares your models with the existing migration files and writes a new migration describing the differences. It does not touch the database. |
python manage.py migrate | Applies any migrations that haven't been run yet to the database. |
A helpful way to remember: makemigrations writes the plan; migrate carries it out.
Creating the first migration
With the Event model from the Models page saved and events listed in INSTALLED_APPS, run:
python manage.py makemigrations
On Windows the path is shown with backslashes. Now apply it:
python manage.py migrate
If you haven't run migrate before, you'll also see about eighteen lines like Applying auth.0001_initial... OK for Django's own apps. Django records every applied migration in a special table called django_migrations, so it never applies the same one twice.
Changing a model
Organisers want to limit how many students can attend. Add a capacity field:
events/models.py
class Event(models.Model):
title = models.CharField(max_length=200)
description = models.TextField(blank=True)
venue = models.CharField(max_length=100)
starts_at = models.DateTimeField()
capacity = models.PositiveIntegerField(default=50)
is_free = models.BooleanField(default=True)
created_at = models.DateTimeField(auto_now_add=True)
# Meta, __str__ and methods unchanged
python manage.py makemigrations
python manage.py migrate
The default=50 matters: existing events need some value in the new column. If you add a required field without a default, makemigrations stops and asks you either to type a one-off default for existing rows or to quit and add a default in models.py.
Inside a migration file
Migration files are ordinary Python. You rarely edit them, but it helps to recognise their shape:
events/migrations/0002_event_capacity.py
# Generated by Django 5.2.8 on 2026-11-15 10:45
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
("events", "0001_initial"),
]
operations = [
migrations.AddField(
model_name="event",
name="capacity",
field=models.PositiveIntegerField(default=50),
),
]
dependencies says this migration must run after 0001_initial; operations lists what to do. Because migrations form a chain, Django can always work out the right order.
Inspecting and undoing migrations
See which migrations exist and which are applied ([X]):
python manage.py showmigrations events
See the SQL a migration will run:
python manage.py sqlmigrate events 0001
To undo a migration, migrate back to the one before it. This removes the capacity column (and any data in it):
python manage.py migrate events 0001
Run python manage.py migrate again to re-apply it. The rest of this series assumes capacity is present.
Good habits
- Run
makemigrationsandmigrateevery time you change a model's fields orMetaoptions. - Commit migration files to Git. They are part of your code: teammates and your production server need them.
- Give important migrations a clear name:
python manage.py makemigrations events --name add_event_capacity. - Back up your production database before running migrations on it.
Changing a model and forgetting to migrate. You'll see errors like OperationalError: no such column: events_event.capacity or no such table: events_event. The fix is almost always makemigrations followed by migrate.
Editing or deleting migrations that have already been applied, especially ones teammates or your server have run. Their databases then disagree with the files and you get hard-to-fix errors. If you made a mistake, write a new migration that corrects it.
Key points
makemigrationswrites migration files;migrateapplies them to the database.- Migrations form an ordered chain recorded in the
django_migrationstable. - New required fields need a default so existing rows can be filled.
- Use
showmigrationsandsqlmigrateto inspect, andmigrate app numberto roll back. - Commit migration files, and never edit ones that have already been applied elsewhere.
Tip: use the ← and → keys to move between pages.
