database-migration

Présentation de la skill database-migration

À quoi sert la skill database-migration

La skill database-migration est conçue pour planifier et générer des migrations de schéma et de données dans des workflows ORM et SQL courants, avec une attention particulière portée à la sécurité du rollback et aux déploiements sans interruption. Elle est surtout utile quand vous avez besoin de plus qu’un simple prompt du type « write a migration » : par exemple, lorsqu’un changement touche des données de production actives, impose un déploiement par étapes, ou doit s’intégrer à un framework de migration précis comme Sequelize ou TypeORM.

À qui s’adresse cette skill database-migration

Les profils les plus concernés sont les équipes de Database Engineering, les ingénieurs backend, les ingénieurs plateforme et les développeurs assistés par IA qui ont besoin d’un résultat exploitable en production, pas seulement correct sur le plan syntaxique. Si vous modifiez des tables, faites du backfill de données, renommez des colonnes de manière sûre ou changez de logique ORM, cette skill donne au modèle un cadre de départ bien plus solide qu’un prompt vierge.

Pour quel besoin elle est la plus pertinente

Utilisez la skill database-migration lorsque le vrai sujet est de produire un plan de migration réellement exécutable : fichiers de migration, séquençage du rollout, stratégies de rollback et prise en compte des transformations de données. Sa valeur n’est pas seulement de générer du code. Elle sert surtout à réduire l’incertitude sur l’ordre des opérations, les fenêtres de compatibilité et la reprise après échec.

Ce qui la différencie d’un prompt de code classique

Par rapport à un prompt ordinaire, cette skill database-migration apporte un cadre explicite autour de :

• exemples de migration adaptés aux ORM
• patterns up et down explicites
• logique pensée pour le zero-downtime
• workflows mêlant changement de schéma et changement de données
• procédures de rollback traitées comme une exigence de premier plan

Elle est donc plus adaptée aux changements en production qu’une simple demande de type « generate SQL ».

Ce qui entre dans son périmètre — et ce qui n’y entre pas

Le contenu actuel de la skill est particulièrement solide sur les patterns de migration et les structures d’exemple, surtout pour Sequelize et TypeORM. Elle est en revanche plus légère sur l’automatisation spécifique au dépôt, les scripts de validation et les règles de décision, car le dossier de la skill n’expose que SKILL.md. En pratique, elle guide bien la préparation et la rédaction des migrations, mais vous devez toujours fournir les détails de votre stack, vos contraintes et votre modèle de déploiement pour obtenir un résultat fiable.

Comment utiliser la skill database-migration

Contexte d’installation de la skill database-migration

Si vous utilisez le système Skills de ce dépôt, installez la skill depuis le repo puis invoquez-la dans une session agent qui a déjà accès à votre base de code et au contexte de schéma. Une installation type ressemble à ceci :

npx skills add https://github.com/wshobson/agents --skill database-migration

Comme cette skill est fournie principalement sous la forme d’un unique fichier SKILL.md, sa valeur dépend largement de la manière dont vous formulez votre demande et de la richesse du contexte de schéma que vous lui donnez.

Commencez par lire ce fichier avant de l’utiliser

Commencez par :

• plugins/framework-migration/skills/database-migration/SKILL.md

Comme il n’existe pas de rules/, resources/ ou scripts de support visibles pour cette skill, vous n’avez pas besoin d’une longue phase de lecture du dépôt. Le parcours utile est simple : examinez SKILL.md, puis passez rapidement à vos propres fichiers de schéma, à votre configuration ORM et à votre historique de migrations.

Les informations à fournir pour que la skill fonctionne bien

La skill database-migration est nettement plus performante si vous fournissez :

• l’ORM ou l’outil de migration actuel : Sequelize, TypeORM, Prisma, SQL brut, etc.
• le schéma actuel ou les définitions de modèles
• le changement de schéma visé
• si un backfill de données est nécessaire
• la taille des tables ou la sensibilité au trafic
• la tolérance à l’indisponibilité
• les attentes en matière de rollback
• le moteur de base de données cible : PostgreSQL, MySQL, etc.
• le style de déploiement : one-shot, par phases, blue/green, canary

Sans ces éléments, le modèle peut produire une migration apparemment valide, mais dangereuse pour la production.

Transformer un objectif vague en prompt database-migration solide

Prompt faible :

Create a migration to rename a column.

Prompt plus solide :

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

La seconde version donne à la skill ce qu’il lui faut pour privilégier une approche plus sûre de type expand-migrate-contract plutôt qu’un renommage direct risqué.

Le meilleur workflow pour de vraies migrations

Un flux d’usage database-migration pragmatique ressemble à ceci :

1. Demandez d’abord une stratégie de migration.
2. Passez en revue les risques, le comportement de verrouillage et les hypothèses de rollback.
3. Demandez ensuite le fichier de migration concret dans votre framework.
4. Si le rollout est progressif, demandez les adaptations nécessaires côté application.
5. Demandez les requêtes de vérification et les étapes de rollback.
6. Testez en staging avec une volumétrie et une forme de données proches de la production avant de faire confiance au résultat.

Cet ordre compte, car un code de migration généré trop tôt intègre souvent un mauvais modèle de déploiement.

Les patterns ORM où la skill est la plus solide

Les éléments visibles du dépôt montrent des exemples explicites pour :

• les migrations Sequelize
• les migrations TypeORM

La description mentionne aussi un usage plus large sur différents ORM et plateformes, mais les exemples visibles sont clairement plus aboutis dans ces deux écosystèmes. Si vous utilisez une autre stack, demandez au modèle de traduire la même intention de migration vers votre toolchain, au lieu de supposer qu’il maîtrise nativement votre environnement au même niveau.

Quand demander explicitement des recommandations zero-downtime

Ne partez pas du principe que le modèle optimisera toujours spontanément la sécurité des migrations online. Dites-le clairement si l’un de ces cas s’applique :

• tables volumineuses
• fort volume d’écriture
• déploiements applicatifs et base de données indépendants
• renommage de colonnes ou changement de type
• backfills sur des chemins chauds
• changement de contraintes sous trafic de production

Pour un usage de database-migration par des équipes de Database Engineering, c’est souvent ce qui fait la différence entre une réponse de démonstration et une réponse réellement déployable.

Quels livrables demander à la skill

Pour un usage à forte confiance, demandez à la skill database-migration de renvoyer un ensemble complet, pas seulement un fichier :

• code de migration
• séquence de rollout
• séquence de rollback
• logique de backfill de données
• hypothèses et risques
• checklist de validation
• étapes de nettoyage post-migration

Cela évite de laisser de côté du travail opérationnel pourtant indispensable.

Alerte pratique sur les changements destructifs directs

La skill est surtout utile pour éviter les modifications risquées en une seule étape, comme :

• supprimer immédiatement d’anciennes colonnes
• renommer à chaud des colonnes critiques sans compatibilité intermédiaire
• changer des types sans stratégie de conversion
• ajouter des contraintes non null avant le backfill
• réécrire de très grandes tables sans anticiper l’impact des verrous

Si la première réponse fait l’une de ces choses sur un chemin de production, demandez une alternative par phases.

FAQ sur la skill database-migration

Cette skill database-migration sert-elle uniquement aux migrations ORM

Non. La skill est pensée pour les migrations de schéma et de données sur différents ORM et plateformes. En pratique, les exemples visibles sont orientés ORM, en particulier Sequelize et TypeORM ; vous obtiendrez donc les meilleurs résultats en indiquant précisément votre stack et en demandant, si besoin, une traduction vers du SQL ou vers votre framework.

La skill database-migration convient-elle aux débutants

Oui, avec des limites. Elle reste accessible grâce à des exemples concrets, mais elle suppose que vous sachiez évaluer si une migration est réellement sûre sur le plan opérationnel. Un débutant peut s’en servir pour préparer des fichiers de migration et des plans de rollout, mais ne doit pas considérer la première réponse comme prête pour la production sans relecture.

Quand ne faut-il pas utiliser database-migration

Évitez cette skill si votre besoin est purement conceptuel et ne concerne pas l’exécution concrète d’un changement de schéma ou de données. Elle est aussi peu adaptée si vous attendez, à partir du seul dépôt, une validation complète propre à votre environnement, car cette skill n’inclut pas de scripts, règles ou harnais de test supplémentaires dans le dossier exposé.

En quoi est-ce mieux que de demander à une IA d’écrire du SQL

La valeur du database-migration guide, c’est de cadrer la demande autour du cycle de vie complet d’une migration, pas seulement de la syntaxe. Un prompt SQL simple oublie souvent le rollback, les fenêtres de compatibilité, les backfills en plusieurs étapes et les conventions de migration propres aux ORM. Cette skill est plus pertinente dès que la sécurité du déploiement compte autant que la justesse du code.

Prend-elle en charge les déploiements zero-downtime

Oui, c’est clairement l’un des cas d’usage visés. Mais vous devez tout de même préciser ce que zero-downtime signifie dans votre environnement. La formule seule est trop large : le modèle a besoin de connaître votre ordre de déploiement, la forme du trafic en lecture/écriture et vos contraintes de compatibilité.

Comment améliorer la skill database-migration

Donnez à la skill le diff de schéma et les contraintes opérationnelles

Le moyen le plus rapide d’améliorer la qualité de sortie de database-migration consiste à fournir à la fois le changement de schéma et les contraintes d’exécution. Par exemple :

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

Cela pousse le modèle vers une conception de migration par étapes, plutôt qu’un simple alter trop simpliste.

Demandez une approche expand-migrate-contract quand la sécurité est critique

Si la première proposition paraît trop destructive, demandez explicitement un plan expand-migrate-contract. Cela améliore généralement les résultats pour :

• les renommages
• les conversions de type
• l’introduction de contraintes non null
• les découpages de table
• les changements de dénormalisation ou de normalisation

C’est l’un des moyens les plus fiables d’obtenir un meilleur usage de database-migration avec cette skill.

Exigez validation et rollback dès la première réponse

Un mode d’échec fréquent consiste à recevoir une migration up correcte, mais une migration down faible ou peu réaliste. Pour éviter cela, demandez :

• les conditions de rollback
• les avertissements sur les pertes de données
• les requêtes de vérification
• les critères de succès après chaque phase

Cela oblige le modèle à raisonner tôt sur la réversibilité.

Fournissez le style de migration déjà utilisé dans votre repo

Si votre projet a déjà ses propres conventions de migration, collez un ou deux fichiers représentatifs et demandez à la skill de s’y conformer. Cela améliore concrètement le nommage, la gestion des transactions, le style des timestamps et les idiomes du framework. C’est particulièrement utile pour Sequelize et TypeORM, où les équipes ont souvent des conventions internes au-delà du comportement par défaut du framework.

Itérez sur le risque de verrouillage, pas seulement sur la justesse du code

Après la première sortie, posez des questions de suivi comme :

• Which steps may lock the table?
• Which steps can run while writes continue?
• What should be split into separate deploys?
• Which part is irreversible after backfill?
• What monitoring should we watch during rollout?

C’est souvent à ce moment-là que la skill database-migration devient vraiment utile pour un travail de Database Engineering, au-delà de la simple génération de boilerplate.

Surveillez ces modes d’échec fréquents

Soyez vigilant si la migration générée :

• suppose des tables minuscules
• omet le rollback
• supprime les anciens champs trop tôt
• combine changement de schéma et backfill massif dans une seule étape risquée
• ignore la compatibilité applicative pendant la transition
• utilise une syntaxe de framework qui ne correspond pas à votre version

Ce sont des raisons normales d’affiner le prompt, pas des signes que la skill est inutilisable.

Meilleure façon d’améliorer les résultats après le premier jet

Considérez la première réponse comme une proposition de migration, pas comme un artefact final. Puis demandez à la skill de la réviser en fonction de :

• la taille réelle de vos tables
• la situation de vos index
• l’ordre de déploiement prévu
• les retours de canary ou de staging
• les hypothèses invalidées pendant la revue

Cette boucle de feedback est la manière la plus concrète d’obtenir une vraie valeur de niveau production à partir du workflow d’installation et d’usage de database-migration.