Why must Django data migrations use historical models?

Explains migration state, historical model lookup, replay safety, and the limits of migration-time models.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

Django stores model state in migration files so it can reconstruct the schema at each migration step. Code in RunPython should obtain models through the migration app registry, usually with apps.get_model(), rather than importing the current model class. A direct import may work today but fail when a fresh database replays the migration after the model has changed.

Full answer below

Practice focus

Whether schema history is treated as executable release code rather than a one-time local script.

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Overview
A migration must work with the model shape at that point in history, not whatever the application model becomes later.
Django stores model state in migration files so it can reconstruct the schema at each migration step. Code in RunPython should obtain models through the migration app registry, usually with apps.get_model(), rather than importing the current model class. A direct import may work today but fail when a fresh database replays the migration after the model has changed.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
Historical models include fields, relationships, selected managers, and versioned metadata, but they do not include ordinary custom instance methods or a current custom implementation. Migration code must therefore use the historical fields directly and keep any required helper logic stable. I make data migrations bounded, deterministic, and reversible where practical, and I test a clean migration replay rather than only upgrading one existing database.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Importing the current model into RunPython.
Calling a custom model method that historical models do not contain.
Combining a large blocking backfill with a risky schema change.

Why must Django data migrations use historical models?

Practice focus

Answer path

Overview

Review signals

Follow-up prompts

Continue the section

Tech stacks

Skill areas

Suggest an improvement

Found this answer useful?