Skip to content
Kuza Ndoto Academy

Migrations

IntermediateChapter 4 · Page 13 of 234 min readUpdated 15 Nov 2026

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

CommandWhat it does
python manage.py makemigrationsCompares your models with the existing migration files and writes a new migration describing the differences. It does not touch the database.
python manage.py migrateApplies any migrations that haven't been run yet to the database.

A helpful way to remember: makemigrations writes the plan; migrate carries it out.

models.py makemigrations 0002_event_capacity.py migrate Database you edit commit to Git table updated
Figure 1. The migration file sits between your code and the database, so every copy of the project can apply the same changes in the same order.

Creating the first migration

With the Event model from the Models page saved and events listed in INSTALLED_APPS, run:

python manage.py makemigrations
Migrations for 'events': events/migrations/0001_initial.py + Create model Event

On Windows the path is shown with backslashes. Now apply it:

python manage.py migrate
Operations to perform: Apply all migrations: admin, auth, contenttypes, events, sessions Running migrations: Applying events.0001_initial... OK

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
Migrations for 'events': events/migrations/0002_event_capacity.py + Add field capacity to event
python manage.py migrate
Operations to perform: Apply all migrations: admin, auth, contenttypes, events, sessions Running migrations: Applying events.0002_event_capacity... OK

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
events [X] 0001_initial [X] 0002_event_capacity

See the SQL a migration will run:

python manage.py sqlmigrate events 0001
BEGIN; -- -- Create model Event -- CREATE TABLE "events_event" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "title" varchar(200) NOT NULL, "description" text NOT NULL, "venue" varchar(100) NOT NULL, "starts_at" datetime NOT NULL, "is_free" bool NOT NULL, "created_at" datetime NOT NULL); COMMIT;

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
Operations to perform: Target specific migration: 0001_initial, from events Running migrations: Rendering model states... DONE Unapplying events.0002_event_capacity... OK

Run python manage.py migrate again to re-apply it. The rest of this series assumes capacity is present.

Good habits

  • Run makemigrations and migrate every time you change a model's fields or Meta options.
  • 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.
Common mistake

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.

Common mistake

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

  • makemigrations writes migration files; migrate applies them to the database.
  • Migrations form an ordered chain recorded in the django_migrations table.
  • New required fields need a default so existing rows can be filled.
  • Use showmigrations and sqlmigrate to inspect, and migrate app number to roll back.
  • Commit migration files, and never edit ones that have already been applied elsewhere.
Up next · Models & DatabasesORM QueriesCreate, read, update and delete records.
→

Tip: use the ← and → keys to move between pages.