Introduction to Django Migrations
What a Migration Represents
A migration file is a small Python module containing a list of operations (like CreateModel or AddField) that Django translates into SQL for your database. Each app keeps its migrations in an app/migrations/ folder, numbered in the order they should run.
Note: Migrations are just Python code — you can open and read them like any other file.
Example: What a Migration Represents
This migration creates an Article table with an id and a title column — exactly what Django generates the first time you run makemigrations on a new model.
# migrations/0001_initial.py
from django.db import migrations, models
class Migration(migrations.Migration):
initial = True
operations = [
migrations.CreateModel(
name='Article',
fields=[
('id', models.AutoField(primary_key=True)),
('title', models.CharField(max_length=200)),
],
),
]Why Migrations Exist
Without migrations you would have to write raw SQL by hand every time a model changed, and keep every teammate's database in sync manually. Migrations let Django generate that SQL for you and apply it consistently everywhere.
Warning: Never edit a table directly in the database while your models.py says something different — the two will drift apart.
Example: Why Migrations Exist
This Article model is the source of truth; a migration is generated from it, never written from scratch by hand.
# models.py
from django.db import models
class Article(models.Model):
title = models.CharField(max_length=200)
published = models.BooleanField(default=False)
def __str__(self):
return self.titleThe Two-Step Migration Workflow
Django splits migrations into two commands: makemigrations reads your models and writes the migration file, then migrate actually applies it to the database. Both are run from the terminal inside your project.
Note: Run makemigrations after every model change, even a small one like renaming a field.
Example: The Two-Step Migration Workflow
makemigrations creates the migration file describing the change; migrate then executes it against the database.
python manage.py makemigrations
python manage.py migrate⚠️ Run this command in your terminal.
- Editing the database tables by hand instead of changing the model and creating a migration, which leaves Django's migration history out of sync with the real schema.
- Deleting migration files from the migrations/ folder because they 'look messy', which breaks migrate for every other environment that still expects them.
- Assuming a migration runs the moment you save a model change, when it only exists after you actually run makemigrations.
- A migration is a Python file that describes one change to your models, like adding a table or a field.
- Django keeps a full history of migrations so the database can be rebuilt from scratch on any machine.
- Every model change needs a new migration before it takes effect in the database.
- Migrations are the bridge between your Python models and the real SQL tables.
Chapter Quiz — Complete all 8 topics to unlock
0/8 topics done
Complete these topics first: