Exécuter les migrations pour créer la structure de la base de données

Concrétiser votre schéma de base de données avec `php artisan migrate`

Après avoir défini la structure de vos tables dans les fichiers de migration, l'étape cruciale suivante consiste à appliquer ces définitions à votre base de données réelle. C'est là qu'intervient la commande Artisan php artisan migrate. Cette commande est le mécanisme par lequel Laravel transforme vos fichiers de migration PHP en véritables tables, colonnes et index dans le système de gestion de base de données que vous avez choisi (MySQL, PostgreSQL, SQLite, etc.). Ce processus est essentiel pour établir la fondation sur laquelle reposeront les données de votre application. Ce sous-chapitre vous guidera à travers la configuration nécessaire, l'exécution de la commande migrate, et la compréhension de son fonctionnement, ainsi que quelques commandes associées pour gérer vos migrations.

Prérequis : Configuration de la connexion à la base de données

Avant de pouvoir exécuter les migrations, il est impératif que Laravel sache comment se connecter à votre serveur de base de données. Cette configuration s'effectue principalement dans le fichier .env, situé à la racine de votre projet Laravel. Ce fichier contient des variables d'environnement que Laravel utilise pour adapter son comportement à différents environnements (développement local, staging, production).

Les variables clés pour la connexion à la base de données sont :

• DB_CONNECTION: Le type de base de données que vous utilisez (par exemple, mysql, pgsql, sqlite, sqlsrv).
• DB_HOST: L'adresse de votre serveur de base de données (souvent 127.0.0.1 ou localhost en développement).
• DB_PORT: Le port sur lequel votre serveur de base de données écoute (par exemple, 3306 pour MySQL, 5432 pour PostgreSQL).
• DB_DATABASE: Le nom de la base de données que Laravel doit utiliser. Cette base de données doit généralement exister au préalable (Laravel ne la crée pas automatiquement, sauf pour SQLite où il peut créer le fichier).
• DB_USERNAME: Le nom d'utilisateur pour se connecter à la base de données.
• DB_PASSWORD: Le mot de passe associé à l'utilisateur.

Voici un exemple de configuration pour une base de données MySQL locale dans le fichier .env :

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mon_projet_laravel
DB_USERNAME=root
DB_PASSWORD=votremotdepasse

Assurez-vous que la base de données (mon_projet_laravel dans cet exemple) a été créée sur votre serveur MySQL et que l'utilisateur (root) a les permissions nécessaires pour créer des tables et y écrire. Pour SQLite, la configuration est plus simple, car elle pointe souvent vers un fichier :

DB_CONNECTION=sqlite
DB_DATABASE=/chemin/vers/votre/projet/database/database.sqlite

Si le fichier database.sqlite n'existe pas, Laravel tentera de le créer lors de la première migration.

Exécution de la commande `php artisan migrate`

Une fois votre fichier .env correctement configuré et votre base de données accessible, vous pouvez exécuter les migrations. Ouvrez votre terminal à la racine de votre projet Laravel et tapez la commande suivante :

php artisan migrate

Lorsque vous exécutez cette commande, Laravel effectue plusieurs opérations :

1. Il vérifie s'il existe une table nommée migrations dans votre base de données. Si ce n'est pas le cas, il la crée. Cette table est essentielle car elle permet à Laravel de suivre quelles migrations ont déjà été exécutées. Elle contient généralement deux colonnes principales : id et migration (le nom du fichier de migration) et batch (un numéro de lot indiquant quelles migrations ont été exécutées ensemble).
2. Laravel scanne ensuite le répertoire database/migrations/ pour trouver tous les fichiers de migration.
3. Il compare la liste des fichiers de migration trouvés avec les enregistrements de la table migrations pour déterminer quelles migrations n'ont pas encore été appliquées.
4. Pour chaque nouvelle migration (celles qui ne sont pas encore dans la table migrations), Laravel exécute la méthode up() définie dans le fichier de migration correspondant.
5. Si la méthode up() s'exécute sans erreur, un nouvel enregistrement est ajouté à la table migrations pour marquer cette migration comme étant exécutée.

Le terminal affichera la progression, indiquant quelles migrations sont en cours d'exécution et lesquelles ont été exécutées avec succès. Par exemple :

INFO  Running migrations.
  2014_10_12_000000_create_users_table .................................... 15ms DONE
  2014_10_12_100000_create_password_reset_tokens_table ................... 18ms DONE
  2019_08_19_000000_create_failed_jobs_table ............................. 12ms DONE
  2019_12_14_000001_create_personal_access_tokens_table .................. 25ms DONE
  2023_10_27_103000_create_products_table ................................ 10ms DONE

Si une erreur se produit pendant l'exécution d'une migration (par exemple, une erreur de syntaxe SQL ou une violation de contrainte), le processus s'arrêtera et aucune des migrations suivantes dans la file d'attente ne sera exécutée. Vous devrez corriger l'erreur dans le fichier de migration concerné avant de pouvoir réessayer.

Commandes de migration utiles et gestion des erreurs

Outre la commande de base php artisan migrate, Laravel fournit plusieurs autres commandes Artisan pour gérer vos migrations et résoudre les problèmes courants :

• php artisan migrate:status: Affiche le statut de chaque migration (si elle a été exécutée ou non, et son numéro de lot). C'est très utile pour savoir où vous en êtes.
• php artisan migrate:rollback: Annule la dernière "fournée" (batch) de migrations. Cela signifie qu'il exécute la méthode down() de toutes les migrations qui ont été exécutées lors du dernier appel à php artisan migrate. Vous pouvez spécifier le nombre de lots à annuler avec l'option --step=N.

# Annuler le dernier lot de migrations
php artisan migrate:rollback

# Annuler les 3 derniers lots de migrations
php artisan migrate:rollback --step=3

• php artisan migrate:reset: Annule toutes les migrations de votre application en exécutant la méthode down() de chaque migration enregistrée dans la table migrations. Attention, cela supprime la structure de vos tables.
• php artisan migrate:refresh: Annule toutes les migrations (rollback) puis les réexécute toutes (migrate). C'est une commande pratique pour reconstruire entièrement votre base de données à partir de zéro tout en exécutant la logique de vos méthodes down(). Vous pouvez y ajouter l'option --seed pour exécuter également les seeders après la reconstruction.

php artisan migrate:refresh

# Reconstruire et populer la base de données
php artisan migrate:refresh --seed

• php artisan migrate:fresh: Supprime toutes les tables de la base de données, puis exécute toutes les migrations. C'est plus rapide que migrate:refresh car cela ne passe pas par l'exécution des méthodes down(). Utilisez cette commande si vous souhaitez une réinitialisation complète et rapide. Elle peut aussi être combinée avec --seed.

php artisan migrate:fresh

# Réinitialiser complètement et populer la base de données
php artisan migrate:fresh --seed

Gestion des erreurs : Si une migration échoue, Laravel affiche généralement un message d'erreur indiquant le problème. Les erreurs courantes incluent des problèmes de connexion à la base de données, des erreurs de syntaxe dans la méthode up(), ou des violations de contraintes (par exemple, essayer de créer une table qui existe déjà sans vérifier au préalable). Il est crucial de lire attentivement le message d'erreur pour diagnostiquer le problème. Souvent, il faudra corriger le fichier de migration, potentiellement annuler une migration partielle (si possible), puis relancer php artisan migrate. Pour les erreurs complexes, consulter les logs de Laravel (storage/logs/laravel.log) peut fournir plus de détails.

En résumé, l'exécution des migrations est une étape fondamentale du cycle de développement Laravel. Elle assure que votre base de données est synchronisée avec la définition de votre schéma dans le code, facilitant la collaboration et le déploiement.