01
the lock queue is what takes you down
The usual story about a migration causing an outage goes like this: someone adds a column with a default to a huge table, Postgres rewrites every row, and the site hangs. That was true before Postgres 11. Since 11, adding a column with a non-volatile default is a catalog change that finishes instantly no matter how big the table is, and the default is stored once rather than written into every row. A constant or a stable function such as now() qualifies. A volatile default like gen_random_uuid() or clock_timestamp() still rewrites the table, which you can confirm by comparing pg_relation_filenode() before and after.
What still takes sites down is the lock queue. Most ALTER TABLE forms, including the cheap ADD COLUMN, need an ACCESS EXCLUSIVE lock for a moment, and that lock conflicts with everything, even a plain SELECT. If any transaction is holding even a read lock on the table, say a report that started a minute ago or a connection sitting idle in transaction, the ALTER has to wait. Every query that arrives after it then queues behind the waiting ALTER, because Postgres won't let them jump ahead of a pending exclusive lock. A migration that would take a millisecond turns into a table nobody can read until the old transaction finishes. You can watch this happen with three psql sessions: one opens a transaction and selects from the table, the second runs alter table ... add column, and a simple select ... where id = 1 in the third hangs until the first commits.
The defence is a short lock_timeout, so the migration gives up quickly instead of freezing traffic, plus a retry. You don't need to touch the migrations to set it: libpq reads PGOPTIONS from the environment, and psycopg passes it through, so the deploy step can look like this:
When the lock isn't available within three seconds, the statement fails with canceling statement due to lock timeout. Django runs each migration in its own transaction on Postgres, so the failed one rolls back cleanly and the next attempt starts it again. The exception is a migration with atomic = False, which is covered below.
When a migration does hang, find out who is in the way before killing anything:
The rest of this post is the release sequence that keeps every step short: expand, backfill, switch, contract. The running example replaces customer.email with a normalized, unique, non-null primary_email, and all of the code was run against Postgres 18 with Django 6.1.
02
expand with columns old code can live with
During a deploy, old and new versions of the app run side by side, so every schema change has to work with both. The first release only adds things. A new nullable column is the simplest case. A new non-null column needs a default that lives in the database, and this is where Django's db_default (added in Django 5.0) beats default:
sqlmigrate shows the difference. With db_default=Now() Django emits ADD COLUMN "created_at" timestamp with time zone DEFAULT (STATEMENT_TIMESTAMP()) NOT NULL and leaves the default in place, which is metadata-only on Postgres 11 and later because statement_timestamp() is stable. With a Python-side default=timezone.now, Django adds the column with a literal timestamp as the default and then immediately runs ALTER COLUMN ... DROP DEFAULT. That's also cheap, but it leaves the column non-null with no default, so any pod still running the old code fails on insert with a not-null violation until the rollout finishes. The database default keeps old inserts working.
03
indexes without blocking writes
A plain CREATE INDEX blocks writes for the whole build. CREATE INDEX CONCURRENTLY only takes a SHARE UPDATE EXCLUSIVE lock, but Postgres refuses to run it inside a transaction block, so the migration must set atomic = False. Django ships an operation for the common case, AddIndexConcurrently in django.contrib.postgres.operations, which keeps the model state in sync without hand-written SQL.
A unique index on an expression is where it gets awkward. models.UniqueConstraint(Lower("primary_email"), ...) is the right model declaration, and on Postgres Django implements it as a unique index, but the generated migration builds it without CONCURRENTLY. SeparateDatabaseAndState fixes that: run your own SQL against the database and tell Django's migration state that the constraint now exists.
The model's Meta declares the same index and constraint, and makemigrations --check reports no changes afterwards, which is how you know the state and the database agree. Because the index name matches what Django would have generated, later migrations that alter or drop the constraint work normally.
Non-atomic migrations need more care when they fail. If a concurrent build is cancelled, by lock_timeout or a duplicate value, Postgres leaves an INVALID index behind, and Django doesn't record the migration as applied. A retry then fails with "already exists". Drop the invalid index and run it again. Avoid IF NOT EXISTS on these statements: it turns the retry into a silent success while the invalid index enforces nothing.
04
backfill outside the migration, with a trigger for writes in flight
Before backfilling, make sure rows written during and after the backfill come out right, otherwise the backfill chases a moving target. While old code still writes only email, a temporary trigger keeps primary_email in step. It has to handle updates as well as inserts, because old code that changes an email after the backfill would otherwise leave primary_email stale:
Ship it in a migration via RunSQL, with a reverse that drops the trigger and the function. The backfill itself doesn't belong in a migration: a RunPython that walks millions of rows runs inside one transaction, holds its locks to the end and can't be resumed. A management command that commits small batches is easier on the database and safe to restart:
The cursor advances with max(id) from the batch. Taking the last row of UPDATE ... RETURNING instead is a common bug, because Postgres doesn't promise that RETURNING follows the ORDER BY of the CTE that fed it. The data-modifying CTE runs even though the final select doesn't reference it, since Postgres always executes those exactly once. Each loop iteration commits on its own under Django's autocommit, so stopping the command loses at most one batch, and a restart just walks the ids again and skips rows that are already filled. Watch replication lag while it runs and raise PAUSE if replicas fall behind.
05
switch, then enforce not null without a long lock
Once the backfill is done, the next release reads primary_email and writes both columns, and only after it's fully rolled out do you enforce the constraint. ALTER COLUMN ... SET NOT NULL on its own scans the whole table while holding ACCESS EXCLUSIVE, which on a big table is exactly the lock-queue outage from the start of this post. Since Postgres 12 it skips that scan if existing constraints already prove the column has no nulls, and a validated CHECK (primary_email IS NOT NULL) does. Validation takes only SHARE UPDATE EXCLUSIVE, so reads and writes continue during the scan:
atomic = False is deliberate. In one transaction, the brief ACCESS EXCLUSIVE lock from adding the constraint would be held through the validation scan, which defeats the point. Run non-atomically, each statement commits on its own. With client_min_messages = debug1 Postgres even tells you it skipped the scan: "existing constraints on column ... are sufficient to prove that it does not contain nulls". The CHECK is redundant afterwards, so the last step drops it.
Postgres 18 shortens this. It stores NOT NULL as a real constraint in pg_constraint and lets you add it as NOT VALID, so alter table customers_customer add constraint customer_primary_email_not_null not null primary_email not valid enforces the rule for new rows immediately, and a later validate constraint checks existing rows under SHARE UPDATE EXCLUSIVE and leaves the column properly NOT NULL, with no CHECK to clean up. Foreign keys follow the same pattern on any supported version: add them NOT VALID, then VALIDATE CONSTRAINT in a separate step.
06
contract much later
Removing the old column is the last step, and it should wait a full release or two after the switch, until nothing reads email anymore: not the app, not a forgotten cron job, not an analytics export. Do it in two stages. First tell Django the field is gone while the column stays, so the ORM stops selecting and inserting it:
The trigger SQL lives in a plain module next to the app, because Django refuses to load a non-migration file from the migrations package. The drop not null is the part people forget. Once the model no longer knows about email, new inserts leave it out, and a NOT NULL column without a default rejects every one of them. A release later, when the column is truly unused, a plain RemoveField or RunSQL drops it, and that takes the same short ACCESS EXCLUSIVE lock as any other ALTER, so the lock_timeout retry still applies.
That leaves you with five or six small migrations for one conceptual change, and that's fine. Squashing them later shortens test setup on fresh databases, but it does nothing for production safety, so do it only after every environment has applied the originals.
