A migration file is a generated Python program that records a change needed to keep Django models and database tables in sync. Changing a model class changes only Python code; the database does not update by magic. Run makemigrations to create the file, then run migrate to apply its declared database operations. section 4.12 section 10.6
Migration files live in an app’s migrations directory. A first migration commonly has a name such as 0001_initial.py; later names include a sequence number and a clue about the model or field changed. The filename helps developers, while Django uses declared dependencies—not the number alone—to determine execution order. section 10.1 section 10.6
Listing 10.3 The initial migration script for the Promoters app
# RiffMates/promoters/migrations/0001_initial.py
from django.db import migrations, models
class Migration(migrations.Migration): #1
initial = True #2
dependencies = [] #3
operations = [ #4
migrations.CreateModel( #5
name="Promoter",
fields=[ #6
(
"id", #7
models.BigAutoField(
auto_created=True,
primary_key=True,
serialize=False,
verbose_name="ID",
),
),
(
"first_name", #8
models.CharField(max_length=25)
),
("last_name", models.CharField(max_length=25)),
],
),
]
An initial migration is mostly a description for Django rather than hand-written database code. Its Migration class marks the initial state, lists prerequisite migrations, and supplies operations. Here, CreateModel describes creating the Promoter table and its automatically generated ID, first_name, and last_name fields. section 10.1.1
The Migration class organizes a database change with three main parts:
- initial — a Boolean that is true for an app’s first migration. section 10.1.1
- dependencies — migrations that must run before this one. section 10.1.1
- operations — objects describing changes, such as CreateModel or AddField. section 10.1.1 section 10.1.2
Adding models for venues and rooms
After adding Venue and Room models, run python manage.py makemigrations bands. Django generates 0002_venue_room.py with operations to create both models. Running python manage.py migrate then applies bands.0002_venue_room, preparing the database before Venue and Room objects are created in the shell. section 4.7.1
Changing an existing table needs extra care because rows may already exist. Adding a required famous_for field left no acceptable NULL value for existing Promoter rows, so makemigrations requested either a one-off default or a model-level default. The resulting migration depends on 0001_initial and uses AddField with the chosen value. section 10.1.2
Migration files can also express data work, not only schema changes. RunPython can call one function while migrating forward and another while migrating backward. An empty migration made with makemigrations --empty can provide a starting point for custom operations. section 10.6
A practical change sequence
Add a street-address field, generate and apply a migration, then add location fields in another migration. To consolidate data into a multiline address field, create migrations that add the new field, convert existing data, and finally remove the old fields. Migrations can later be squashed together. section 10.5
