skip to content

Zero-Downtime Changes

2 roadmaps5 questions

Expand/contract migrations let old and new code share one schema: db_default for NOT NULL columns, AddIndexConcurrently, SeparateDatabaseAndState. Interviewers ask how to rename a column live.

part ofDjangooverview, primer and where to startread it →
on this pageshow

explore

questions

5

In Django, how do you rename a model field live when the previous release keeps querying the old column during the deploy?

level: seniorimportance: must knowfreq 45%

answer

  1. what RenameField does to the column
  2. old code names every column
  3. rename the attribute, not the column
  4. db_column and a later drop

basics

~20 s

Avoid RenameField's RENAME COLUMN while old code runs. Either rename only the Python attribute and keep db_column pointing at the old column, or change the column across releases: add, write both, backfill, switch reads, then drop.

solid answer

~40 s

`RenameField` becomes `ALTER TABLE ... RENAME COLUMN`, and the release still serving traffic names the old column explicitly in every SELECT and INSERT, so it fails from the moment `migrate` runs. The cheapest fix is often not to rename the column at all: rename the attribute and set `db_column="data"`; `makemigrations` asks whether the field was renamed and writes an `AlterField` plus `RenameField` that change no column, which `sqlmigrate` confirms. If the column itself must change, spread it over releases: add the new field nullable or with `db_default`, write both fields, backfill, switch reads, then make the old field nullable, remove it from the model with a state-only `SeparateDatabaseAndState`, and drop the column in a later release.

code

python · 6 lines
python
from django.db import models


class Event(models.Model):
    # renamed from `data`; the column keeps its old name
    payload = models.JSONField(db_column="data")

go deeper

for a junior

Know that RenameField renames the database column and that db_column lets the attribute and the column have different names.

for a middle

Explain why explicit column lists make a column rename break the running release, and what makemigrations writes for an attribute-only rename.

for a senior

Lay out the multi-release column change: dual writes, backfill, read switch, nullable old field, state-only removal, and the later RunSQL drop.

for a principal

Decide when a naming change justifies several deploys and when db_column is the pragmatic answer, and set that expectation for the team.

## Why RenameField breaks a rolling deploy Django's ORM never uses `SELECT *`: every query lists the model's columns by name, and every `INSERT` lists the fields it writes. The previous release was built against the old model, so its SQL references `analytics_event.data`. `RenameField` on PostgreSQL runs `ALTER TABLE "analytics_event" RENAME COLUMN "data" TO "payload"`. The statement itself is quick, but from that moment every query from old processes fails with an unknown column until the last old process is gone. Deploying code first does not help either: the new code would query `payload` before it exists. ## Option 1: rename the attribute, keep the column Most renames are about readable Python, not the column name. Django separates the two with `db_column`: 1. Rename `data` to `payload` in the model and add `db_column="data"`. 2. Run `makemigrations`. It asks `Was event.data renamed to event.payload (a JSONField)? [y/N]`; answer yes. 3. The autodetector writes an `AlterField` that sets `db_column` to the existing column name and a `RenameField`. Because the column name is unchanged, neither emits a rename; `sqlmigrate` shows no `RENAME COLUMN`. 4. Deploy. Old and new releases both use the column `data`. The cost is a permanent mismatch between the attribute and the column name, which only matters to people writing raw SQL. ## Option 2: change the column over several releases When the column really must change (a new type, a new meaning, or a naming standard), treat it as adding a new field and retiring the old one. | Release | Model and migrations | Old column | New column | |---|---|---|---| | 1 | add `payload` with `null=True` or `db_default`; code writes both fields | read and written | written | | 2 | backfill `payload` in a data migration; code reads `payload` | written | read and written | | 3 | make `data` nullable; stop writing it; remove `data` from the model with a state-only `SeparateDatabaseAndState` | still in the table, unused | read and written | | 4 | drop the `data` column with `RunSQL` | gone | only column | ## Retiring the old field safely - **Make it nullable first.** Once `data` is gone from the model, new inserts omit it; a `NOT NULL` column without a database default would reject them. - **Remove it from state, not from the table.** `SeparateDatabaseAndState(state_operations=[RemoveField(...)], database_operations=[])` updates Django's model state so the autodetector is satisfied, while the column stays for the previous release that still selects it. - **Drop the column one release later**, when no running code references it, with `RunSQL` (a `RemoveField` there would fail, because the field is no longer in migration state). ## Choosing between them - Pure naming change: option 1, one deploy, no data movement. - Type or meaning change, or a mandated column name: option 2, accepting several deploys. - A maintenance window where no old code runs: a plain `RenameField` is fine. The interviewer wants to hear that Django's explicit column lists are why a rename is not zero-downtime, and that `db_column` plus state-only operations are the Django tools that make it so.

  • Why not deploy the new code first and run RenameField afterwards?
    The new code queries the new column name, which does not exist until the migration runs, so the same failure happens in the other direction. Any order that has one release referencing a column the other lacks breaks requests; only a period where both names exist, or no rename, avoids it.
  • Why must the old field be nullable before it is removed from the model?
    After removal, Django's INSERTs omit that column. If it is still `NOT NULL` with no database default, every new row is rejected. Making it nullable, or giving it `db_default`, one release earlier keeps inserts valid until the column is dropped.

saying these in an interview costs you the question

  • RenameField is safe because renaming a column is instant
  • Django selects with SELECT star, so renamed columns are picked up
  • db_column on a renamed attribute forces a column rename
  • Removing a field from the model and dropping its column in one release is safe
  • A NOT NULL column can stay NOT NULL after its field is removed
open as a page

In Django, how would you add a NOT NULL column to a 50-million-row events table without downtime, and why does db_default matter?

level: seniorimportance: must knowfreq 48%

basics

~20 s

Declare the field with db_default so AddField leaves a DEFAULT on the column. With only a Python default, Django drops the column default after filling existing rows, and the old release's INSERTs, which omit the column, then fail.

open as a page

What does Django's SeparateDatabaseAndState migration operation do, and when would you reach for it?

level: middleimportance: should knowfreq 30%

basics

~20 s

SeparateDatabaseAndState takes two lists: state_operations change Django's model state, database_operations change the real schema. It lets you change one without the other, such as removing a field from the models a release before dropping its column.

open as a page

In Django on PostgreSQL, how do you add an index to a 50-million-row events table without blocking writes?

level: seniorimportance: should knowfreq 36%

basics

~10 s

Replace the generated AddIndex with AddIndexConcurrently from django.contrib.postgres.operations and set atomic = False on the migration, because CREATE INDEX CONCURRENTLY cannot run in a transaction. RemoveIndexConcurrently does the same for dropping.

open as a page

What migration policy would you set for a Django team deploying continuously, so every migration stays safe while the previous release still serves traffic?

level: principalimportance: should knowfreq 25%

basics

~20 s

Require every migration to work with both the new and the previous release: additive changes ship with the code, destructive steps a release later, indexes built concurrently, backfills in separate data migrations, and each migration's SQL reviewed with sqlmigrate.

open as a page