CommunityRédaction et éditiongithub.com

windchillscalanthes-ship-it/safe-migrations

Détectez la migration de base de données qui verrouille votre table avant qu'elle ne soit déployée. Une compétence d'agent Claude qui examine les migrations pour détecter les risques de temps d'arrêt et les réécrit en étapes sécurisées sans interruption. PostgreSQL et MySQL, pour tout framework.

Qu'est-ce que safe-migrations ?

Safe Migrations est une compétence d'agent IA (comme Claude Code, Cursor ou Codex) qui aide les développeurs à prévenir les pannes causées par des migrations de base de données risquées. Elle analyse les fichiers de migration SQL pour identifier les opérations dangereuses telles que l'ajout d'une colonne avec une valeur par défaut, la création d'un index non concurrent, ou l'ajout d'une contrainte NOT NULL, qui peuvent verrouiller des tables sous un accès exclusif (ACCESS EXCLUSIVE) et bloquer tout le trafic. Pour chaque risque identifié, la compétence fournit une réécriture concrète et exécutable en étapes sans verrou, en utilisant des techniques comme les index concurrents, les contraintes NOT VALID, et le motif Expand/Contract. Elle prend en charge PostgreSQL et MySQL/MariaDB, avec des références détaillées par moteur, framework (Rails, Django, etc.), et motifs génériques. L'agent utilise un catalogue de risques classé par gravité (🔴 Non sûr, 🟡 Attention, 🟢 Sûr) et produit un rapport structuré avec des étapes de réécriture prêtes à copier-coller. Cela permet d'intégrer la révision des migrations dans le flux de développement, avant le commit ou lors de la revue de PR.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add windchillscalanthes-ship-it/safe-migrations

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. É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.

  2. 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.

  3. 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.
  4. 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).
  5. 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érationPourquoi c'est dangereuxApproche sécurisée
1Ajouter une colonne avec un DEFAULTUne 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).
2SET NOT NULL sur une colonne existanteAnalyse 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.
3CREATE 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).
4DROP INDEXACCESS EXCLUSIVE sur la table.DROP INDEX CONCURRENTLY (Postgres 9.2+).
5Ajouter FOREIGN KEYVerrouille 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).
6Ajouter une contrainte UNIQUEConstruit un index unique sous un verrou bloquant.CREATE UNIQUE INDEX CONCURRENTLY → ALTER TABLE … ADD CONSTRAINT … UNIQUE USING INDEX <nom> (attache l'index existant, rapide).
7Ajouter une contrainte CHECKAnalyse la table sous ACCESS EXCLUSIVE.ADD CONSTRAINT … CHECK (…) NOT VALID → VALIDATE CONSTRAINT.
8ALTER COLUMN … TYPERéé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.
9RENAME colonne/tableLe 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.
10DROP COLUMNLe 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.
11Remplir en une seule grosse UPDATETransaction 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.
12Pas de lock_timeout / statement_timeoutMê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.

Skills associés