articles/2025/safe-django-db-migrations/

[giscus[bot]]

articles/2025/safe-django-db-migrations/

How to run schema-changing Django migrations safely, avoiding schema/code mismatches and server errors during rolling deploys.

https://www.loopwerk.io/articles/2025/safe-django-db-migrations/?utm_campaign=Django%2BNewsletter&utm_medium=email&utm_source=Django_Newsletter_314

[David-Wobrock]

Hello,
Nice article! Thanks for taking the time to write it :)

Indeed, doing safe migrations in Django often relies on avoiding backward incompatible migrations, or doing them in a controlled multi-step manner.

To automate detection of potential problematic migrations, I've created https://github.com/3YOURMIND/django-migration-linter/ a few years ago (shameless plug hehe), as the problem to consistently reflect on migrations becomes harder as a company grows and more developers work on the codebase. The idea is to have an automated safeguard to warn one about backward incompatible migrations :)

[kevinrenskers]

Thanks! Interesting project, in combination with django-deprecate-fields. I was also made aware of https://github.com/charettes/django-syzygy, which is more up my alley I think, but good that there are options!

[Irostovsky]

Hello.
Thanks for the article.
But it seems it is not enough to make the field nullable. When Django model is united - it tries to get all fields described in model and in case there is no field in DB - it crashes.
To fix this we separate DB and state during migrations.
As you wrote, first step is to remove all usage of the field, make it nullable too.
Then remove from model, but in migration do this only on python level.
When migration is executed during deploy - old instances still use this column.
And then remove the column from DB by another migration. And another deploy.

[kevinrenskers]

Thanks for the comment!

What you’re describing is a valid pattern, but it’s solving a slightly different problem than the one this article focuses on.

Django only crashes when the model references a column that does not exist, or when the database requires a value for a non-nullable column. In the flow described in the article, the field is kept in the model until the same deploy that removes the column, so that mismatch never occurs.

Using SeparateDatabaseAndState becomes necessary if you want to remove the field from the model while keeping the column around temporarily (for example to reduce the number of deploys or support very long-running old instances). That’s a perfectly valid advanced technique, but not strictly required for safe zero-downtime migrations if you coordinate model and schema changes together.