Migrations de base données fr FR

Résumé : Cette page explique l'approche de StartER concernant l'évolution de la base de données : édition déclarative du schéma pendant le prototypage, et scripts de migration successifs (forward-only) pour le déploiement en production.

Ce que vous apprendrez :

Créer des fichiers de migration incrémentaux pour les changements de schéma
Exécuter les migrations avec la commande CLI fournie
Comprendre quand utiliser les migrations vs. la réinitialisation de la base

Deux modes, une seule source de vérité

StartER est un framework de prototypage. La plupart du temps, votre application s'exécute sur localhost en mode développement. Lorsque vous êtes prêt à déployer, vous optez pour un workflow différent, mais schema.sql reste la base dans les deux cas.

	Développement	Production
Commande	`npm run database:reset`	`npm run database:migrate`
Comportement	Supprime tout, rejoue tous les fichiers SQL	Applique uniquement les fichiers SQL non appliqués
`schema.sql`	Modifiable librement	Gelé après le premier déploiement
`seeder.sql`	Chargé (données de test)	Ignoré
Scripts de migration	Rejoués depuis le début	Appliqués successivement (forward-only)
Données	Perdues (volontaire : nouveau départ)	Préservées

Pendant le prototypage : modifiez librement `schema.sql`

En développement, schema.sql est votre terrain de jeu. Ajoutez des tables, renommez des colonnes, modifiez les types, etc. Quand vous voulez voir le résultat :

npm run database:reset

Cette commande supprime toutes les tables et rejoue chaque fichier SQL depuis le début : schema.sql d'abord, puis tous les scripts de migration dans src/database/migrations/, et enfin seeder.sql. Vous obtenez toujours une base de données propre reflétant l'état actuel de vos fichiers.

Tip

C'est le workflow que vous utiliserez 99 % du temps. Aucun script de migration requis, pas de surcharge mentale.

Lors du déploiement : migrations successives (forward-only)

Si vous choisissez de déployer votre application en production, les règles changent. Les bases de données de production contiennent de vraies données qui ne peuvent pas être supprimées et recréées.

Une fois que schema.sql a été appliqué en production (lors du premier déploiement), il devient gelé. Toutes les modifications ultérieures du schéma doivent passer par des scripts de migration situés dans src/database/migrations/.

Écrire un script de migration

Les scripts de migration sont de simples fichiers .sql placés dans src/database/migrations/. Le framework n'impose aucune convention de nommage : les fichiers sont exécutés par ordre alphabétique (ordre du système de fichiers). Une pratique courante consiste à utiliser un préfixe de date ou de séquence :

src/database/migrations/
  2026-07-10_add_category_table.sql
  2026-07-15_add_status_to_item.sql

Exemple de migration (ajout d'une table category) :

-- src/database/migrations/2026-07-10_add_category_table.sql

CREATE TABLE category (
  id INTEGER PRIMARY KEY NOT NULL,
  name VARCHAR(255) NOT NULL
);

ALTER TABLE item ADD COLUMN category_id INTEGER REFERENCES category(id);

Appliquer les migrations

npm run database:migrate

Cette commande :

Sauvegarde le fichier de base de données (temporaire : supprimé après exécution)
Parcourt schema.sql + tous les fichiers de migrations/ (ordre alphabétique)
Ignore les fichiers déjà appliqués (suivis dans une table _migrations)
Applique les nouveaux fichiers dans une transaction (tout ou rien)
Supprime le fichier temporaire de sauvegarde

Lors du premier déploiement, schema.sql et tous les scripts de migration existants sont appliqués. Lors des déploiements suivants, seuls les nouveaux scripts de migration sont appliqués.

Tip

Utilisez l'option -n pour le mode non-interactif dans vos pipelines CI/CD :

npm run database:migrate -- -n

Que se passe-t-il si vous modifiez un fichier déjà appliqué ?

Si vous modifiez schema.sql ou un script de migration après son application, la commande database:migrate suivante vous avertira :

⚠️  'schema.sql' was modified since it was applied.
    These changes will NOT take effect.
    Revert your change or write a new migration script.

Le système de migration utilise des checksums (empreintes numériques) pour détecter les modifications. Il s'agit d'un signal pédagogique : il vous explique pourquoi votre modification ne s'applique pas et vous indique comment procéder à la place.

Pour corriger cela : annulez la modification du fichier déjà appliqué et écrivez un nouveau script de migration dans src/database/migrations/ qui applique le changement souhaité.

La table `_migrations`

Les commandes database:reset et database:migrate maintiennent toutes deux une table _migrations dans la base de données :

CREATE TABLE _migrations (
  filename TEXT PRIMARY KEY,
  checksum TEXT NOT NULL,
  applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

database:reset la supprime et la recrée (en y enregistrant tous les fichiers rejoués)
database:migrate la lit pour déterminer quels fichiers ont déjà été appliqués

Cela signifie que vous pouvez tester le workflow de migration de production localement : lancez database:reset pour démarrer sur une base propre, ajoutez un nouveau script de migration, puis lancez database:migrate pour vérifier qu'il s'applique correctement.