Migrations de base et changements de schéma

Une pull request contient au plus une migration de schéma, et le chemin de retour arrière est livré dans la même PR. Des migrations regroupées ne peuvent pas être annulées indépendamment — et on découvre qu'il fallait le rollback à 2 h du matin, pas au moment de la revue, où l'écrire prend quatre minutes.

Bloque : sans rollback dans le diff, le plan de réponse à incident se résume à improviser.

Une migration qui modifie une table existante fixe un `lock_timeout` court (et un `statement_timeout`) en tête de fichier, pour qu'un DDL incapable d'obtenir son verrou échoue vite au lieu d'attendre. Un `ALTER` en attente se place derrière la transaction qu'il attend, et toute requête ultérieure sur cette table se place derrière l'`ALTER` — un verrou que la migration n'obtient jamais met donc la table à l'arrêt aussi longtemps qu'elle persiste.

Bloque : sans cela, une seule instruction bloquée fige toutes les lectures et écritures sur la table — une panne, et non un déploiement raté.

Supprimer ou renommer une colonne ou une table se fait dans une PR distincte et postérieure au changement de code qui a cessé de s'en servir — expand, migrate, contract. Pendant un rolling update, anciens et nouveaux process tournent en même temps : une colonne supprimée dans la même release casse toutes les requêtes encore servies par l'ancienne version.

Bloque : c'est de loin la première cause de 500 au moment du déploiement sur une codebase saine.

Ajouter une colonne `NOT NULL` sans valeur par défaut à une table remplie est refusé. Ajoutez-la nullable (ou avec un défaut), remplissez-la par lots, puis resserrez la contrainte dans une migration ultérieure. La version en une seule instruction réécrit la table, ou la verrouille en exclusif, pendant toute la durée de la réécriture.

Bloque : cela prend un verrou d'écriture sur une table en production — une panne que rien n'annonce dans le diff.

`CREATE INDEX` et `DROP INDEX` sur une table au volume de production utilisent `CONCURRENTLY`, et la migration est marquée comme non transactionnelle. Un `CREATE INDEX` ordinaire tient un verrou qui bloque toutes les écritures sur la table jusqu'à la fin — soit, sur une grosse table, des minutes et non des secondes.

Bloque : même raisonnement — un verrou sur une table en production, invisible pour qui ne sait pas où regarder.

Les colonnes monétaires ou de quantité précise utilisent `numeric`/`decimal`, ou une colonne entière en unité mineure. `float`, `real` et `double precision` sont refusés pour ces usages. Le flottant ne représente pas exactement les fractions décimales : les sommes cessent de se réconcilier, et l'écart grandit avec le volume.

Bloque : changer le type d'une colonne plus tard impose une réécriture complète de la table et un audit des données.

Une migration qui touche des lignes existantes les traite par lots, avec une borne explicite et une clé de reprise, ou bien tourne comme un job séparé plutôt qu'à l'intérieur de la migration. Un unique `UPDATE` sur toute la table tient une longue transaction, bloque l'autovacuum et génère du WAL plus vite que les réplicas ne peuvent le consommer.

Avertit : sur une petite table, c'est sans danger — c'est au reviewer de trancher au vu du nombre réel de lignes.

Chaque colonne de clé étrangère porte un index, créé dans la même migration. Sans lui, une suppression ou une mise à jour sur la ligne parente déclenche un parcours séquentiel de la table enfant pour chaque ligne concernée — rapide en développement avec cent lignes, incident à dix millions.

Avertit : c'est un décrochage de performance, et l'index s'ajoute facilement après coup.

Les colonnes de temps utilisent `timestamptz` (ou l'équivalent) et prennent par défaut le `now()` UTC de la base. `timestamp without time zone` est refusé. Un horodatage naïf signifie en silence « le fuseau qu'avait le process qui a écrit », ce qui change dès qu'un serveur change de région ou qu'un worker s'exécute ailleurs.

Avertit : le dommage est une ambiguïté progressive des données, pas une casse immédiate.

Les seeds, les corrections et les reprises de données ponctuelles vivent dans leur propre migration ou dans un script, jamais mêlés au DDL du même fichier. DDL et DML n'ont ni le même profil de verrouillage ni la même histoire de rollback — les mélanger, c'est ne plus pouvoir annuler la moitié sûre sans la moitié risquée.

Indicatif : une règle d'hygiène qui ne paie que le jour où quelque chose tourne mal.

Les tables sont en snake_case et au pluriel, les clés étrangères s'appellent `<singulier>_id`, les booléens se lisent comme des prédicats (`is_active`, `has_access`), et les mots réservés sont évités. C'est cette cohérence qui permet à n'importe qui — humain ou agent — de deviner correctement un nom de colonne au lieu d'aller lire le schéma.

Indicatif : c'est du goût, mais c'est un goût constant qui rend un schéma navigable.