Safe Migrations (Migrations Sécurisées)
Détectez les modifications de schéma qui verrouillent silencieusement une table ou la réécrivent sur le disque — et transformez-les en migrations sécurisées sans interruption avant qu'elles n'atteignent la production.
Une seule ligne anodine (SET NOT NULL, CREATE INDEX, ADD FOREIGN KEY, une colonne avec un DEFAULT) peut prendre un verrou ACCESS EXCLUSIVE ou forcer une réécriture complète de la table. Sur une table volumineuse et très sollicitée, cela signifie que chaque lecture et écriture s'accumule derrière la migration — une panne. Cette compétence examine une migration, explique exactement ce qui serait verrouillé et pourquoi, et produit une réécriture sécurisée.
Quand l'utiliser
- Vous êtes en train d'écrire une nouvelle migration et vous voulez la vérifier avant le commit.
- Vous êtes en train de réviser une migration dans une PR/diff.
- Vous êtes sur le point d'exécuter une migration sur une table qui contient déjà des lignes.
- Quelqu'un demande « cette migration est-elle sûre ? », « est-ce que cela va verrouiller la table ? » ou « comment faire cela sans temps d'arrêt ? ».
Si la table cible est vide ou minuscule (une table fraîchement créée dans la même migration, une table de configuration avec une poignée de lignes), la plupart de ces risques ne s'appliquent pas — dites-le et ne sur-ingeniériez pas.
Flux de travail
-
Établir le contexte. Identifiez le moteur (PostgreSQL vs MySQL/MariaDB et, si possible, la version majeure) et le framework. La version compte : plusieurs opérations sont sûres sur Postgres 11/12+ mais pas avant. Si la version est inconnue, signalez les opérations dont la sécurité dépend de la version.
-
Localiser les opérations. Lisez chaque fichier de migration et listez chaque opération de schéma ou de données qu'il effectue. Une migration en regroupe souvent plusieurs.
-
Classer chaque opération selon le catalogue de risques ci-dessous. Attribuez une sévérité :
- 🔴 Non sûr — prendra un verrou bloquant, réécrira la table, ou cassera une version d'application en cours d'exécution. Doit être réécrit.
- 🟡 Attention — sûr seulement sous conditions (petite table, version spécifique du moteur, faible trafic, paramètres corrects). Mentionnez la condition.
- 🟢 Sûr — métadonnées uniquement ou autrement non bloquant. Aucun changement nécessaire.
-
Réécrire les opérations non sûres. Pour chaque 🔴/🟡, donnez :
- le risque concret (quel verrou, ce qu'il bloque, impact approximatif),
- une réécriture sécurisée sous forme d'étapes exécutables (SQL et, lorsqu'un framework est utilisé, le code idiomatique du framework), et
- la séquence de déploiement lorsque le code de l'application doit changer en synchronisation (voir Expand / Contract ci-dessous).
-
Rapporter en utilisant le modèle de sortie à la fin. Commencez par les éléments non sûrs.
Pour des détails spécifiques au moteur et au framework, chargez les fichiers de référence à la demande :
reference/postgres.md— Verrous PostgreSQL, versions et réécritures sécurisées (le plus détaillé).reference/mysql.md— DDL en ligne MySQL/MariaDB,ALGORITHM/LOCK, gh-ost.reference/patterns.md— Modèles indépendants du moteur : expand/contract, remplissages par lots,lock_timeout, compatibilité N-1.reference/frameworks.md— Comment exprimer les index concurrents, désactiver la transaction DDL, et séparer l'état vs le schéma dans chaque framework.
Lisez le fichier de référence pertinent pour la migration que vous avez sous les yeux plutôt que de deviner le comportement spécifique à une version.
Catalogue des risques (les contrevenants fréquents)
Centré sur Postgres ; les différences MySQL sont dans reference/mysql.md. « Réécriture » = toute la table est copiée sur le disque ; « analyse » = lecture complète de la table ; les deux sont maintenues sous un verrou qui bloque le trafic concurrent.
| # | Opération | Pourquoi c'est dangereux | Approche sécurisée |
|---|---|---|---|
| 1 | Ajouter une colonne avec un DEFAULT | Une valeur par défaut volatile (ex. gen_random_uuid(), random()) réécrit la table sous ACCESS EXCLUSIVE. Toute valeur par défaut réécrit sur Postgres < 11. | Ajoutez la colonne nullable sans valeur par défaut → ALTER … SET DEFAULT (nouvelles lignes seulement) → remplissez les lignes existantes par lots → ajoutez NOT NULL (ligne 2). |
| 2 | SET NOT NULL sur une colonne existante | Analyse complète de la table sous ACCESS EXCLUSIVE pour vérifier l'absence de null — bloque les lectures et les écritures. | Ajoutez CHECK (col IS NOT NULL) NOT VALID → VALIDATE CONSTRAINT (non bloquant) → SET NOT NULL (Postgres 12+ réutilise la vérification validée et ignore l'analyse) → supprimez éventuellement la contrainte CHECK. |
| 3 | CREATE INDEX (non concurrent) | Prend un verrou SHARE qui bloque les écritures pendant toute la construction. | CREATE INDEX CONCURRENTLY — doit s'exécuter en dehors d'une transaction ; peut laisser un index INVALID en cas d'échec (supprimez et réessayez). |
| 4 | DROP INDEX | ACCESS EXCLUSIVE sur la table. | DROP INDEX CONCURRENTLY (Postgres 9.2+). |
| 5 | Ajouter FOREIGN KEY | Verrouille les deux tables et analyse la table enfant pour valider les lignes existantes. | Ajoutez la contrainte NOT VALID (rapide, pas d'analyse) → VALIDATE CONSTRAINT dans une étape séparée (prend seulement SHARE UPDATE EXCLUSIVE). |
| 6 | Ajouter une contrainte UNIQUE | Construit un index unique sous un verrou bloquant. | CREATE UNIQUE INDEX CONCURRENTLY → ALTER TABLE … ADD CONSTRAINT … UNIQUE USING INDEX <nom> (attache l'index existant, rapide). |
| 7 | Ajouter une contrainte CHECK | Analyse la table sous ACCESS EXCLUSIVE. | ADD CONSTRAINT … CHECK (…) NOT VALID → VALIDATE CONSTRAINT. |
| 8 | ALTER COLUMN … TYPE | Réécrit généralement la table et ses index sous ACCESS EXCLUSIVE. (Exceptions : élargir/supprimer une limite de longueur varchar est seulement une modification de métadonnées.) | Expand/contract : ajoutez une nouvelle colonne, double-écriture + remplissage, basculez les lectures, supprimez l'ancienne colonne. |
| 9 | RENAME colonne/table | Le DDL est instantané, mais il casse la version de l'application en cours d'exécution dès qu'il est validé. | Ne renommez jamais sur place sur une application en production. Expand/contract : ajoutez le nouveau nom, double-écriture, remplissage, basculez les lectures, supprimez l'ancien — sur deux déploiements. |
| 10 | DROP COLUMN | Le code de l'application qui y fait encore référence (y compris SELECT *) casse ; les données sont perdues (difficile à annuler). | Phase de contraction uniquement : déployez d'abord le code de l'application qui cesse d'utiliser la colonne, puis supprimez-la dans une migration ultérieure. |
| 11 | Remplir en une seule grosse UPDATE | Transaction longue → contention de verrou, gonflement de la table, retard de réplication. | Traitez par lots selon les plages de clés primaires avec un commit entre chaque lot ; gardez chaque lot court. Faites-le en dehors de la migration de schéma. |
| 12 | Pas de lock_timeout / statement_timeout | Même un DDL instantané a besoin d'un bref verrou ACCESS EXCLUSIVE. S'il fait la queue derrière une longue requête, il bloque toutes les requêtes qui arrivent après lui — un blocage en cascade. | Définissez un lock_timeout (et statement_timeout) bas avant le DDL pour que la migration échoue rapidement au lieu de faire tomber le site. |
Principes directeurs
- Expand / contract (changement parallèle). Tout changement qui n'est pas rétro-compatible doit être divisé afin que la base de données soit simultanément compatible avec les versions ancienne et nouvelle de l'application pendant un déploiement. Expand (ajouter, rétro-compatible) → migrer les données / double-écriture → contract (supprimer) — généralement sur deux déploiements ou plus. C'est l'épine dorsale des renommages, changements de type, divisions et fusions.
- Un changement logique par migration. Plus facile à réviser, à raisonner et à annuler. Ne mélangez jamais un changement de schéma avec un remplissage de données volumineux dans la même transaction.
- Compatibilité N-1. Pendant un déploiement, les deux versions de l'application s'exécutent en même temps. Le schéma doit servir les deux.
- Séparez le schéma des données. Le DDL structurel et les remplissages de lignes appartiennent à des étapes différentes (et souvent à des déploiements différents).
- Adaptez la profondeur du conseil. Les tables vides/petites/nouvelles n'ont besoin de rien de tout cela. Ne transformez pas une modification de deux lignes en une danse en cinq étapes lorsque la table a 12 lignes.
Modèle de sortie
## Révision de sécurité des migrations
**Moteur :** <ex. PostgreSQL 14> · **Framework :** <ex. Rails> · **Fichiers révisés :** <n>
### 🔴 <fichier> — NON SÛR
**Opération :** <ce qu'elle fait>
**Risque :** <quel verrou / réécriture, ce qu'il bloque>
**Impact probable :** <ex. "verrou global sur `users` pendant la durée d'une analyse complète ; sur une table de 40M de lignes, secondes à minutes de trafic bloqué">
**Réécriture sécurisée :**
<étapes exécutables — SQL et/ou code du framework>
**Séquence de déploiement :** <uniquement si le code de l'application doit changer en synchronisation>
### 🟡 <fichier> — ATTENTION
**Opération / Risque / Condition / Recommandation**
### 🟢 <fichier> — SÛR
<une ligne : pourquoi c'est sûr, aucune action nécessaire>
---
**Résumé :** <n non sûrs, n attention, n sûrs.> <une ligne de conclusion.>
Montrez toujours la réécriture sécurisée comme quelque chose que l'utilisateur peut copier et exécuter — pas seulement une description de ce qu'il faut faire.