Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 77 ยท Models and the ORM

Migrations

Learn Django migrations: makemigrations and migrate, migration files, operations, dependencies, sqlmigrate, data migrations and squashing.

Your models describe what the database should look like, but the database itself does not read Python. Migrations are the bridge. A migration is a small Python file that records one step in the history of your schema: "create the Book table", "add an ISBN column", "fill the new column with data". Django applies those steps in order and remembers which ones it has already run, so every developer, test database and production server ends up with the same structure.

Think of migrations as version control for your database schema. You change your models, ask Django to write the step, review it like any other code, commit it, and apply it everywhere. Understanding this loop will save you from the two classic problems: a database that does not match the code, and teammates whose migrations collide. This lesson follows Models and Fields and prepares you for QuerySets.

The migration workflow

flowchart LR
    M["Edit models.py"] --> MM["makemigrations"]
    MM --> F["0002_xxx.py<br/>(commit it)"]
    F --> MG["migrate"]
    MG --> DB[("Database")]
    MG --> LOG["django_migrations table<br/>records applied names"]

makemigrations writes the file; migrate runs it and records the name so it is never run twice.

There are two commands, and they do very different things:

  • python manage.py makemigrations compares your current models with the state described by the existing migration files and writes a new migration file for the difference. It never touches the database.
  • python manage.py migrate looks at the django_migrations table, finds migration files that are not recorded there, and runs them. This is the command that changes the database.

Two read-only helpers complete the toolbox: showmigrations lists every migration and whether it is applied, and sqlmigrate app 0001 prints the SQL a migration would run without running it.

Running the loop yourself

A real project has migration files in yourapp/migrations/. The example below builds a tiny app called shopapp in a scratch folder (the in-browser Python has a temporary file system), then drives the very same commands with call_command(). The messages that real Django prints are shown as they are. To keep the output the same on every machine, the example filters out the lines that contain file paths.

Python makemigrations, sqlmigrate and migrate

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Walk through what you just saw:

  1. makemigrations reported + Create model Book and wrote 0001_initial.py. The file is plain Python: a Migration class with dependencies and a list of operations.
  2. showmigrations first shows [ ], an unapplied migration. After migrate, it shows [X].
  3. sqlmigrate revealed the SQL, wrapped in a transaction. Django added the id primary key for you because the model did not declare one.
  4. The database now holds shopapp_book and the bookkeeping table django_migrations.

Migrations only exist for apps that are in INSTALLED_APPS and have a migrations package with an __init__.py file. If makemigrations says "No changes detected" for a brand-new app, pass the app label explicitly: makemigrations shopapp.

Anatomy of a migration file

Look at the printed 0001_initial.py. Three parts matter:

  • initial = True marks the first migration of an app.
  • dependencies lists the migrations that must run first, as (app_label, migration_name) pairs. This is how Django builds a graph of the whole project: migrations of different apps can depend on each other (for example, an app with a foreign key to auth.User depends on an auth migration).
  • operations is the ordered list of changes. Each item is an object that knows how to apply itself and, for most of them, how to reverse itself.

The operations you meet most often:

Operation What it does
CreateModel, DeleteModel Creates or drops a table
AddField, RemoveField, AlterField, RenameField Changes a column
RenameModel Renames a table and updates references
AddIndex, AddConstraint Creates indexes and check or unique constraints
RunPython(forwards, backwards) Runs Python code, usually to move data
RunSQL(sql, reverse_sql) Runs raw SQL

Django writes migrations for most model changes automatically. Two situations need your attention: adding a non-nullable field to a table that already has rows (Django will ask for a default, or you supply one on the field), and renaming a field (Django may see it as "remove one column and add another", which would lose data; it asks whether you renamed it, so answer carefully).

Evolving a schema and moving data

Now the realistic part: the model changes after the first migration was applied. The example below adds an isbn field to the model, lets makemigrations detect it (first with --dry-run, which only reports), applies it, and then adds a hand-written data migration that tidies the titles of the rows that already exist. Finally it migrates backwards to 0001, which removes the column again.

Python A schema change, a data migration and a rollback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The important points:

  • With --dry-run, Django printed + Add field isbn to book but wrote no file; the second call wrote 0002_book_isbn.py. Its single AddField operation has default='', and its dependency on 0001_initial is what keeps the order correct.
  • The data migration is a normal file with RunPython. Inside the function, get models with apps.get_model("shopapp", "Book") rather than importing them. The apps argument holds the historical models, as they looked at that point in the migration history. Importing the current model class would break the day the model changes again.
  • RunPython.noop as the second argument makes the step reversible without doing anything on the way back. Without a reverse function, migrate refuses to go backwards past that migration.
  • migrate shopapp 0001 unapplied 0003 and 0002 in reverse order and dropped the column, and showmigrations shows the files are still there but unapplied. The data in the table survives, apart from the dropped column.

Working with migrations in a team

Some habits keep migrations painless:

  • Commit migration files. They are part of your source code. Never add them to .gitignore.
  • Never edit a migration that others may have applied. Make a new migration instead. Editing history makes databases diverge silently.
  • Review the generated file before committing, and run sqlmigrate for anything risky, such as dropping or altering large tables.
  • Separate schema from data. Put RunPython steps in their own migration, so a failure is easy to understand.
  • Resolve conflicts. If two branches each create 0005_..., Django finds two "leaf" nodes and migrate complains about conflicting migrations. Run makemigrations --merge to create a merge migration that depends on both.
  • Do not hand-delete rows in django_migrations. If you must tell Django that a migration was already applied, use migrate --fake, and only when you are sure the schema really matches.

Squashing

Long-lived projects collect hundreds of migrations, and each new test database has to run them all. The command python manage.py squashmigrations shopapp 0001 0003 combines a range into a single 0001_squashed_0003_... migration that lists the old ones in its replaces attribute. Databases that already applied the old migrations keep working, and fresh databases take the shortcut. After every environment has moved past the squashed range, you can delete the old files and remove the replaces line. Squashing is a maintenance chore you do now and then, not a daily tool, and it cannot always optimize RunPython steps, so check the result.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command changes the database schema?

    migrate runs unapplied migrations against the database. makemigrations only writes files; showmigrations and sqlmigrate only report.
  2. 2. Why should a data migration use apps.get_model() instead of importing the model class?

    The apps registry passed to RunPython holds historical models. The current class may have fields that did not exist yet when the migration ran.
  3. 3. You already applied 0004 on a shared database and notice a mistake in it. What should you do?

    Applied migrations are history. Editing them makes databases diverge, so you add a new migration that corrects the schema.
  4. 4. What does the dependencies list in a migration express?

    dependencies are (app_label, migration_name) pairs. Django builds a graph from them to decide the order in which migrations run.

Summary

  • Migrations are versioned Python files that describe schema changes. makemigrations writes them, migrate applies them and records each one in the django_migrations table.
  • Use showmigrations to see the status and sqlmigrate to see the SQL before running it.
  • A migration has dependencies and a list of operations such as CreateModel, AddField and RunPython.
  • Data migrations use RunPython with historical models from apps.get_model() and should provide a reverse function.
  • Commit migrations, never edit applied ones, resolve conflicts with makemigrations --merge, and squash old history occasionally.

With the table in place, it is time to put data into it and read it back: QuerySets: Create, Read, Update, Delete.