Aller au contenu principal

Gestion des migrations

Ajouter des changements à la base de données sans casser l’existant

Notions théoriques​

Pourquoi gérer les migrations ?​

Lorsque la structure d’une base de données évolue (ajout de table, modification de colonnes, suppression de contraintes...), il est crucial de garder une trace de chaque modification, de pouvoir les rejouer sur d'autres environnements (comme la production), et surtout de ne rien casser.

Ce processus s’appelle une migration.

info

Une migration est un fichier SQL ou un script qui décrit une modification du schéma de la base de données.

Les migrations permettent de :

  • versionner les changements de schéma
  • partager les évolutions de la base avec une équipe
  • mettre à jour plusieurs environnements de manière cohérente (local, staging, production)
  • revenir en arrière si besoin (rollback)

Migrations dans un projet Supabase local​

Même sans utiliser la CLI Supabase, il est possible de gérer les migrations manuellement dans un projet local basé sur Docker. Cela consiste à :

  1. Écrire des fichiers SQL dans un dossier migrations/
  2. Appliquer ces fichiers dans la base locale via psql
  3. Versionner les fichiers avec Git
  4. Appliquer les mêmes fichiers sur la base distante
remarque

Ce processus est indépendant de tout framework JavaScript.

Structure recommandée​

Créer un dossier dans le projet local :

/migrations
    001_create_announcements.sql
    002_add_index_on_username.sql
    ...

Chaque fichier contient une ou plusieurs instructions SQL, par exemple :

CREATE TABLE announcements (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
astuce

Préfixer les fichiers avec un numéro permet de les exécuter dans l’ordre.

Application des migrations​

L’application se fait avec psql, en se connectant à la base locale :

psql -U postgres -h localhost -p 54322 -d postgres -f migrations/001_create_announcements.sql

Pour appliquer toutes les migrations :

for f in migrations/*.sql; do
  psql -U postgres -h localhost -p 54322 -d postgres -f "$f"
done

Synchronisation avec la base distante​

Une fois que les migrations ont été testées en local, il est possible de les appliquer à la base distante :

psql --dbname=postgresql://USER:PASSWORD@HOST:PORT/DBNAME -f migrations/001_create_announcements.sql

Bonnes pratiques​

astuce

Toujours tester une migration en local avant de la pousser en production.

remarque

Une migration doit être idempotente : elle ne doit pas échouer si elle est exécutée plusieurs fois.

attention

Ne jamais modifier une migration déjà appliquée. Créer une nouvelle migration pour corriger.

info

Versionner le dossier supabase/migrations avec Git pour suivre l’évolution du schéma de la base.

  • Créer un fichier par migration
  • Ne jamais modifier un fichier déjà appliqué
  • Nommer clairement chaque fichier
  • Utiliser Git pour versionner les migrations
  • Documenter les effets de chaque migration
  • Appliquer d’abord en staging avant production
info

Il existe des outils comme Flyway ou Sqitch pour automatiser ce processus, mais ici on reste sur une gestion manuelle, simple et pédagogique.

Exemple pratique​

Il est possible de créer une migration pour ajouter une nouvelle table announcements dans un projet Supabase local.

Étape 1 : Créer le dossier des migrations​

mkdir migrations

Étape 2 : Créer un fichier SQL​

Créer un fichier 001_create_announcements.sql dans le dossier migrations/.

Contenu du fichier :

CREATE TABLE announcements (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
remarque

Cette table permet de stocker des annonces avec un titre, un contenu, et une date de création.

Étape 3 : Appliquer la migration en local​

Lancer la commande :

psql -U postgres -h localhost -p 54322 -d postgres -f migrations/001_create_announcements.sql

Vérifier que la table a bien été créée :

psql -U postgres -h localhost -p 54322 -d postgres -c "\dt"

Étape 4 : Ajouter une migration de test​

Créer un fichier 002_insert_test_announcement.sql :

INSERT INTO announcements (title, content)
VALUES ('Annonce test', 'Ceci est une annonce fictive.');

Appliquer la migration :

psql -U postgres -h localhost -p 54322 -d postgres -f migrations/002_insert_test_announcement.sql

Vérifier que l’annonce est bien présente :

psql -U postgres -h localhost -p 54322 -d postgres -c "SELECT * FROM announcements;"

Étape 5 : Versionner avec Git​

git init
git add migrations/
git commit -m "Ajout de la table announcements via migration"
astuce

Toujours versionner les fichiers .sql pour garder une trace des évolutions du schéma.

Test de mémorisation/compréhension​


Quel est le rôle principal d’un fichier de migration ?


Quelle commande applique un fichier SQL dans une base locale ?


Pourquoi numéroter les fichiers de migration ?


Quel port est utilisé par Supabase local pour PostgreSQL ?


Quel outil permet de versionner les fichiers de migration ?


Que contient typiquement un fichier de migration ?


Quelle commande permet de vérifier les tables dans PostgreSQL ?


Pourquoi appliquer une migration en local avant la production ?


Quel type de clé est utilisé pour l’id dans la table announcements ?


Quelle commande permet d’exécuter plusieurs migrations automatiquement ?


TP pour réfléchir et résoudre des problèmes​

TODO