python manage.py migrate qui tourne sans erreur en local ne garantit rien sur ce qui se passe en production. Une migration qui ajoute une colonne NOT NULL sans valeur par défaut, qui renomme un champ, ou qui crée un index sur une table de plusieurs millions de lignes peut verrouiller la table pendant de longues secondes, voire minutes, et bloquer toutes les requêtes concurrentes. Sur une application qui tourne en continu avec plusieurs instances déployées en rolling update, ce verrou se traduit directement par des requêtes HTTP qui timeout.
Pourquoi une migration bloque la production
Le mécanisme sous-jacent est au niveau du moteur de base de données, pas de Django. Sur PostgreSQL, ALTER TABLE pour ajouter une contrainte, changer un type de colonne, ou ajouter un index classique (CREATE INDEX sans CONCURRENTLY) prend un verrou ACCESS EXCLUSIVE sur la table pendant la durée de l'opération. Pendant ce verrou, aucune lecture ni écriture concurrente ne passe.
Il y a une nuance importante selon la version de PostgreSQL : depuis PostgreSQL 11, ajouter une colonne avec une valeur par défaut constante (ALTER TABLE x ADD COLUMN y integer DEFAULT 0) est une opération quasi instantanée au niveau métadonnées, sans réécriture de table. Avant la 11, ou avec une valeur par défaut non constante (comme uuid_generate_v4()), PostgreSQL doit réécrire physiquement toutes les lignes, ce qui verrouille la table pour la durée de la réécriture.
Le second problème, spécifique au déploiement progressif, est l'incompatibilité temporaire entre ancien code et nouveau schéma. Si une migration renomme une colonne, les instances pas encore redéployées exécutent toujours des requêtes avec l'ancien nom de colonne : elles cassent dès que la migration de schéma s'applique, avant même que le nouveau code ne soit déployé partout.
Diagnostiquer avant d'écrire le correctif
Avant de changer quoi que ce soit, il faut mesurer ce que la migration va réellement faire sur la base de production, pas sur une base de dev vide. Deux leviers concrets :
-- Estimer le verrou réel sur une table de taille comparable à la prod
EXPLAIN (ANALYZE, BUFFERS) ALTER TABLE orders ADD COLUMN priority smallint DEFAULT 0;
-- Vérifier les verrous actifs pendant qu'une migration tourne
SELECT pid, relation::regclass, mode, granted
FROM pg_locks
WHERE relation = 'orders'::regclass;
Pour une migration Django spécifiquement, python manage.py sqlmigrate <app> <numero> affiche le SQL généré sans l'exécuter, ce qui permet de repérer à l'avance un CREATE INDEX non concurrent ou un ALTER TABLE suspect avant de le lancer sur une base avec du trafic réel.
La stratégie expand/contract
Le principe général, indépendant de Django, consiste à ne jamais faire une migration qui casse la compatibilité entre l'ancien et le nouveau code en une seule étape. On "étend" le schéma de façon additive et rétrocompatible, on fait cohabiter ancien et nouveau code le temps du déploiement, puis on "contracte" en retirant ce qui n'est plus utilisé, dans un déploiement séparé.
Renommer une colonne sans interruption
Renommer directement avec RenameField casse tout code qui tourne encore sur l'ancien nom pendant le rolling update. La séquence correcte :
- Ajouter la nouvelle colonne en gardant l'ancienne (migration de schéma uniquement, aucune perte de compatibilité).
- Déployer du code qui écrit dans les deux colonnes et lit depuis la nouvelle avec repli sur l'ancienne.
- Lancer une migration de données pour backfiller les lignes existantes.
- Déployer du code qui n'utilise plus que la nouvelle colonne.
- Dans un déploiement ultérieur, supprimer l'ancienne colonne.
# Étape 1 : migration de schéma additive uniquement
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),
),
]
# Étape 3 : migration de données, backfill par lots pour ne pas verrouler
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),
]
Le backfill par lots avec update() ciblé sur le PK évite de verrouiller la table entière en une seule transaction longue, et permet de reprendre le travail s'il est interrompu.
Ajouter un index sans bloquer les écritures
Un CREATE INDEX classique bloque les écritures sur la table pendant toute sa construction. Django expose AddIndexConcurrently depuis la version 3.0, via django.contrib.postgres.operations, qui génère un CREATE INDEX CONCURRENTLY. Cette opération nécessite que la migration soit non atomique.
from django.contrib.postgres.operations import AddIndexConcurrently
class Migration(migrations.Migration):
atomic = False # obligatoire : CREATE INDEX CONCURRENTLY ne peut pas tourner dans une transaction
dependencies = [('orders', '0013_add_reference_code')]
operations = [
AddIndexConcurrently(
model_name='order',
index=models.Index(fields=['reference_code'], name='order_refcode_idx'),
),
]
CONCURRENTLY prend plus de temps et peut échouer en laissant un index invalide (INVALID dans pg_index) s'il est interrompu, il faut alors le supprimer et relancer, mais en échange il ne bloque jamais les écritures concurrentes.
Ajouter une contrainte NOT NULL en deux temps
Ajouter directement une colonne NOT NULL sans défaut échoue si la table contient déjà des lignes, et ajouter une contrainte NOT NULL après coup sur une grande table verrouille la table pendant la validation complète des lignes existantes sur les versions anciennes de PostgreSQL. La séquence sûre : ajouter la colonne nullable, backfiller, puis ajouter une contrainte CHECK avec NOT VALID suivie d'une validation séparée qui ne prend qu'un verrou léger.
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,
),
]
Changer le type d'une colonne, et supprimer une colonne sans risque
Deux autres opérations méritent la même vigilance qu'un renommage. Changer le type d'une colonne avec ALTER COLUMN TYPE, même un changement qui semble anodin comme passer un CharField(max_length=32) à max_length=64, est une opération sans réécriture sur PostgreSQL quand le nouveau type est compatible binairement (élargir la longueur d'un varchar ne nécessite aucune réécriture). Mais convertir entre deux types réellement différents, comme un IntegerField vers un BigIntegerField, ou une colonne texte vers un UUIDField, force PostgreSQL à réécrire chaque ligne et prend le même verrou ACCESS EXCLUSIVE que n'importe quel ALTER TABLE lourd. La réponse expand/contract est identique à celle d'un renommage : ajouter la nouvelle colonne typée, écrire dans les deux, backfiller, basculer, puis supprimer l'ancienne.
Supprimer une colonne paraît anodin puisque RemoveField est rapide sur PostgreSQL. Le danger n'est pas le DDL lui-même, c'est le séquencement avec le déploiement progressif : si la migration tourne avant que toutes les instances aient cessé de lire ou d'écrire cette colonne, toute instance encore sur l'ancien code plante à la prochaine requête qui y fait référence. L'ordre sûr est : déployer du code qui ne référence plus du tout la colonne, confirmer que le déploiement est terminé sur toutes les instances, et seulement ensuite lancer la migration qui la supprime. Exécuter les migrations automatiquement dans la même étape de déploiement que le changement de code supprime cette marge de sécurité, ce qui justifie souvent de découpler l'exécution des migrations dans une étape de pipeline distincte, conditionnée à la fin du déploiement.
# À lancer seulement après confirmation qu'aucune instance ne requête encore 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',
),
]
Renommer un champ sans toucher à la colonne en base
Tous les "renommages" n'exigent pas un changement au niveau base de données. Si l'objectif est uniquement d'améliorer le nom côté Python d'un champ de modèle sans renommer la colonne sous-jacente, l'option db_column de Django combinée à SeparateDatabaseAndState évite complètement une migration de schéma : l'état change pour l'ORM de Django, la base reste intacte.
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=[], # aucun SQL : la colonne garde son vrai nom
),
]
Cela évite toute la chorégraphie expand/contract pour un renommage purement cosmétique, puisqu'il n'y a aucun changement de schéma susceptible d'entrer en conflit avec le déploiement progressif.
Répéter la migration avant qu'elle ne touche la production
Aucune des techniques précédentes ne dispense de vérifier le comportement réel sur un jeu de données représentatif avant de lancer quoi que ce soit en production. Une migration qui paraît sûre sur le papier, un AddIndexConcurrently par exemple, peut encore échouer en cours de route sur une base de staging restaurée depuis un snapshot de production, révélant des problèmes comme une saturation d'espace disque pendant la construction de l'index ou une transaction longue qui détient un verrou conflictuel. Répéter la migration sur un réplica de staging avec des volumes représentatifs de la production, en la laissant tourner jusqu'au bout tout en surveillant pg_stat_progress_create_index pendant son exécution, permet de détecter ces modes d'échec avant qu'ils ne deviennent un incident plutôt qu'après.
Les compromis réels
Cette approche coûte en complexité opérationnelle : chaque changement de schéma qui semblait tenir en une migration se transforme en trois ou quatre déploiements séquentiels, avec du code transitoire (écriture double, lecture avec repli) qui doit être retiré explicitement ensuite. Sur une petite application avec une fenêtre de maintenance acceptable, appliquer une migration bloquante directement, hors heures de trafic, reste souvent plus simple et parfaitement raisonnable. La stratégie expand/contract se justifie quand il n'existe pas de fenêtre de maintenance acceptable, ou que la table concernée est trop grosse pour qu'un verrou bref reste indolore.
Quand ça ne suffit pas
Le découpage en étapes ne protège pas contre les migrations de données elles-mêmes lourdes : backfiller des dizaines de millions de lignes prend du temps même par lots, et peut saturer les connexions à la base ou le réplica utilisé pour les lectures si le rythme des lots n'est pas maîtrisé avec des pauses entre batches. Il faut aussi vérifier que l'outil de déploiement n'exécute pas les migrations Django automatiquement avant que tous les pods aient basculé sur l'ancien code compatible, ce qui demande souvent de découpler l'exécution des migrations du déploiement applicatif plutôt que de les lancer dans le même pipeline CI/CD sans contrôle de séquencement.
À retenir
Le downtime vient presque toujours du verrou pris par le moteur de base de données pendant l'opération DDL, pas de Django en tant que tel : sqlmigrate permet de l'anticiper avant de lancer quoi que ce soit en production. Le pattern expand/contract (ajouter, faire cohabiter, backfiller, basculer, nettoyer) élimine la coupure au prix d'un découpage en plusieurs déploiements, et ne se justifie que quand la fenêtre de maintenance n'est vraiment pas une option.
