A python manage.py migrate that runs cleanly locally guarantees nothing about what happens in production. A migration that adds a NOT NULL column without a default, renames a field, or builds an index on a table with millions of rows can lock that table for seconds or minutes, blocking every concurrent query. On an application running continuously across several instances during a rolling deploy, that lock shows up directly as timed-out HTTP requests.
Why a migration blocks production
The underlying mechanism lives at the database engine level, not in Django. On PostgreSQL, ALTER TABLE to add a constraint, change a column type, or build a regular index (CREATE INDEX without CONCURRENTLY) takes an ACCESS EXCLUSIVE lock on the table for the duration of the operation. While that lock is held, no concurrent read or write goes through.
There's an important nuance depending on the PostgreSQL version: since PostgreSQL 11, adding a column with a constant default (ALTER TABLE x ADD COLUMN y integer DEFAULT 0) is a near-instant metadata-only operation, with no table rewrite. Before version 11, or with a non-constant default (like uuid_generate_v4()), PostgreSQL has to physically rewrite every row, which locks the table for the entire rewrite.
The second problem, specific to rolling deployments, is the temporary mismatch between old code and the new schema. If a migration renames a column, instances that haven't redeployed yet still run queries against the old column name: they break as soon as the schema migration lands, before the new code has even reached every instance.
Diagnose before writing the fix
Before changing anything, measure what the migration will actually do against a table shaped like production, not an empty dev database. Two concrete tools:
-- Estimate the real lock cost on a table sized like production
EXPLAIN (ANALYZE, BUFFERS) ALTER TABLE orders ADD COLUMN priority smallint DEFAULT 0;
-- Check active locks while a migration is running
SELECT pid, relation::regclass, mode, granted
FROM pg_locks
WHERE relation = 'orders'::regclass;
For a Django migration specifically, python manage.py sqlmigrate <app> <number> prints the generated SQL without running it, which lets you catch a non-concurrent CREATE INDEX or a suspicious ALTER TABLE before firing it against a database under real traffic.
The expand/contract strategy
The general principle, independent of Django, is to never ship a migration that breaks compatibility between old and new code in a single step. You "expand" the schema additively in a backward-compatible way, let old and new code coexist during the rollout, then "contract" by removing what's no longer used in a separate deployment.
Renaming a column without downtime
Renaming directly with RenameField breaks any code still running on the old name mid rolling-update. The safe sequence:
- Add the new column while keeping the old one (schema-only migration, no compatibility loss).
- Deploy code that writes to both columns and reads from the new one with a fallback to the old one.
- Run a data migration to backfill existing rows.
- Deploy code that only uses the new column.
- In a later deployment, drop the old column.
# Step 1: additive schema migration only
class Migration(migrations.Migration):
dependencies = [('orders', '0012_alter_order')]
operations = [
migrations.AddField(
model_name='order',
name='reference_code',
field=models.CharField(max_length=32, null=True),
),
]
# Step 3: data migration, backfilled in batches to avoid a long lock
def backfill_reference_code(apps, schema_editor):
Order = apps.get_model('orders', 'Order')
batch_size = 2000
qs = Order.objects.filter(reference_code__isnull=True).order_by('pk')
while True:
batch = list(qs[:batch_size].values_list('pk', 'legacy_ref'))
if not batch:
break
for pk, legacy_ref in batch:
Order.objects.filter(pk=pk).update(reference_code=legacy_ref)
class Migration(migrations.Migration):
dependencies = [('orders', '0013_add_reference_code')]
operations = [
migrations.RunPython(backfill_reference_code, migrations.RunPython.noop),
]
Batching the backfill with a targeted update() on the primary key avoids locking the whole table in one long transaction, and lets the work resume cleanly if it's interrupted.
Adding an index without blocking writes
A regular CREATE INDEX blocks writes on the table for the entire build. Django has exposed AddIndexConcurrently since version 3.0, via django.contrib.postgres.operations, which generates a CREATE INDEX CONCURRENTLY. This requires the migration to be non-atomic.
from django.contrib.postgres.operations import AddIndexConcurrently
class Migration(migrations.Migration):
atomic = False # required: CREATE INDEX CONCURRENTLY cannot run inside a transaction
dependencies = [('orders', '0013_add_reference_code')]
operations = [
AddIndexConcurrently(
model_name='order',
index=models.Index(fields=['reference_code'], name='order_refcode_idx'),
),
]
CONCURRENTLY takes longer and can leave an invalid index (flagged INVALID in pg_index) if it's interrupted, which then needs to be dropped and retried, but in exchange it never blocks concurrent writes.
Adding a NOT NULL constraint in two steps
Adding a NOT NULL column directly without a default fails outright if the table already has rows, and adding a NOT NULL constraint after the fact on a large table locks it for the full validation of existing rows on older PostgreSQL versions. The safe sequence is to add the column nullable, backfill it, then add a CHECK constraint with NOT VALID followed by a separate validation step that only takes a lightweight lock.
class Migration(migrations.Migration):
atomic = False
dependencies = [('orders', '0014_backfill_reference_code')]
operations = [
migrations.RunSQL(
sql="ALTER TABLE orders ADD CONSTRAINT reference_code_not_null CHECK (reference_code IS NOT NULL) NOT VALID;",
reverse_sql="ALTER TABLE orders DROP CONSTRAINT reference_code_not_null;",
),
migrations.RunSQL(
sql="ALTER TABLE orders VALIDATE CONSTRAINT reference_code_not_null;",
reverse_sql=migrations.RunSQL.noop,
),
]
Changing a column's type, and dropping a column safely
Two other operations deserve the same scrutiny as renames. Changing a column's type with ALTER COLUMN TYPE, even something as apparently harmless as CharField(max_length=32) to max_length=64, is safe and metadata-only on PostgreSQL when the new type is binary-compatible (widening a varchar length doesn't require a rewrite). But converting between genuinely different types, such as an IntegerField to a BigIntegerField, or a text column to a UUIDField, forces PostgreSQL to rewrite every row and takes the same ACCESS EXCLUSIVE lock as any other heavy ALTER TABLE. The expand/contract answer is the same as for a rename: add the new-typed column, dual-write, backfill, switch over, then drop the old one.
Dropping a column looks harmless since RemoveField is a cheap, fast operation on PostgreSQL. The danger isn't the DDL itself, it's sequencing against the rolling deploy: if the migration runs before every instance has stopped reading or writing that column, any instance still running old code crashes on the next query referencing it. The safe order is: deploy code that no longer references the column at all, confirm the rollout is complete across every instance, and only then run the migration that drops it. Running migrations automatically as part of the same deploy step that ships the code change removes that safety margin, which is why migration execution is often worth decoupling into its own pipeline step gated on deployment completion.
# Only run after confirming no running instance still queries old_status_code
class Migration(migrations.Migration):
dependencies = [('orders', '0016_stop_using_old_status_code')]
operations = [
migrations.RemoveField(
model_name='order',
name='old_status_code',
),
]
Renaming a field without touching the database column
Not every "rename" needs a database-level change at all. If the goal is purely to improve the Python-facing name of a model field without renaming the underlying column, Django's db_column option combined with SeparateDatabaseAndState avoids a schema migration entirely: the state changes for Django's ORM, the database stays untouched.
class Order(models.Model):
reference_code = models.CharField(max_length=32, db_column='refcode')
class Migration(migrations.Migration):
dependencies = [('orders', '0017_remove_old_status_code')]
operations = [
migrations.SeparateDatabaseAndState(
state_operations=[
migrations.RenameField(
model_name='order',
old_name='refcode',
new_name='reference_code',
),
],
database_operations=[], # no SQL at all: the column keeps its real name
),
]
This sidesteps the whole expand/contract dance for a purely cosmetic rename, since there's no schema change for the rolling deploy to race against.
Rehearsing the migration before it touches production
None of the techniques above remove the need to actually verify behavior against a realistic dataset before running anything against production. A migration that looks safe on paper, an AddIndexConcurrently for instance, can still fail partway through on a staging database restored from a production snapshot, surfacing problems like disk space exhaustion during index build or a long-running transaction holding a conflicting lock. Rehearsing against a staging replica with production-like row counts and letting the migration run end to end, including a check of pg_stat_progress_create_index while it's in flight, catches these failure modes before they become an incident instead of after.
The real tradeoffs
This approach costs operational complexity: a schema change that used to fit in one migration turns into three or four sequential deployments, with transitional code (dual writes, fallback reads) that has to be explicitly removed afterward. On a small application with an acceptable maintenance window, running a blocking migration directly, outside traffic hours, is often still simpler and perfectly reasonable. The expand/contract strategy earns its cost when no acceptable maintenance window exists, or when the table involved is too large for even a brief lock to go unnoticed.
When it isn't enough
Splitting the change into steps doesn't protect against heavy data migrations themselves: backfilling tens of millions of rows takes time even in batches, and can saturate database connections or the read replica if the batch pace isn't controlled with pauses between runs. It's also worth checking that the deployment pipeline doesn't run Django migrations automatically before every pod has rolled over to compatible code; this often means decoupling migration execution from the application deployment rather than firing both in the same CI/CD pipeline without sequencing control.
Takeaway
Downtime almost always comes from the lock the database engine takes during the DDL operation, not from Django itself; sqlmigrate lets you see that coming before running anything in production. The expand/contract pattern (add, coexist, backfill, switch over, clean up) removes the outage at the cost of splitting the change into several deployments, and is worth that cost only when a maintenance window genuinely isn't an option.
