Passer au contenu principal

​
Qu’est-ce qu’une migration

Une migration s’apparente à un système de contrôle de version pour la base de données. Elle permet à une équipe de partager et gérer le schéma de la base. Vous avez sans doute déjà connu la situation où, après un pull du code, il faut demander à ses collègues d’« ajouter manuellement une colonne à leur base locale ». Les migrations résolvent ce problème. Les fichiers de migration sont stockés dans database/migrations. Chaque nom de fichier contient un horodatage qui détermine l’ordre d’exécution.

​
Créer un fichier de migration

Utilisez la commande Artisan make:migration. 
php artisan make:migration create_posts_table
Laravel déduit le nom de la table à partir du nom de la migration et génère un stub adapté. create_posts_table produit un stub pour créer la table posts.

​
Structure d’une migration

Une classe de migration possède deux méthodes : up et down.
  • up : ajoute les tables, colonnes et index à la base.
  • down : annule les opérations de up. Appelée lors du rollback.
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Exécute la migration.
     */
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamps();
        });
    }

    /**
     * Annule la migration.
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

​
Méthodes de définition de colonne

Blueprint propose de nombreux types de colonnes.
MéthodeDescription
$table->id()Clé primaire auto-incrémentée (alias de bigIncrements('id'))
$table->string('name')Équivalent VARCHAR (255 par défaut)
$table->text('body')Colonne TEXT
$table->integer('count')Colonne INTEGER
$table->boolean('active')Booléen (TINYINT)
$table->timestamp('published_at')Colonne TIMESTAMP
$table->timestamps()Ajoute created_at et updated_at
$table->softDeletes()Ajoute deleted_at pour la suppression logique
$table->foreignId('user_id')Colonne BIGINT UNSIGNED pour clé étrangère

​
Modificateurs de colonne

Utilisez les méthodes chaînées pour ajouter des modificateurs. 
$table->string('email')->unique();
$table->string('name')->nullable();
$table->integer('votes')->default(0);
$table->string('title')->after('id'); // Positionné après une colonne

​
Exécuter les migrations

migrate exécute toutes les migrations en attente. 
php artisan migrate
migrate:status liste les migrations exécutées et celles en attente. 
php artisan migrate:status
En production, une invite de confirmation apparaît. Pour l’ignorer, utilisez --force, mais soyez prudent car certaines opérations peuvent effacer des données.

​
Rollback

migrate:rollback annule le dernier lot de migrations. 
php artisan migrate:rollback
L’option --step limite le nombre de migrations à annuler. 
# Annule les 5 dernières migrations
php artisan migrate:rollback --step=5
migrate:refresh annule toutes les migrations puis les réexécute. 
php artisan migrate:refresh
migrate:refresh recrée toutes les tables et supprime les données. Pratique pour réinitialiser la base en développement.

​
Exemple : création de la table posts

Voyons la création d’une table posts pour gérer des articles de blog.

​
1. Génération de la migration

php artisan make:migration create_posts_table

​
2. Édition de la migration

Ouvrez database/migrations/xxxx_xx_xx_xxxxxx_create_posts_table.php. 
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();
            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
            $table->string('title');
            $table->text('body');
            $table->boolean('published')->default(false);
            $table->timestamp('published_at')->nullable();
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

​
3. Exécution

php artisan migrate
La table posts est créée.

​
4. Ajouter une colonne après coup

Pour ajouter une colonne à une table existante, créez une nouvelle migration sans modifier l’existante. 
php artisan make:migration add_excerpt_to_posts_table

public function up(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->string('excerpt')->nullable()->after('title');
    });
}

public function down(): void
{
    Schema::table('posts', function (Blueprint $table) {
        $table->dropColumn('excerpt');
    });
}
N’éditez pas directement des migrations déjà exécutées. Cela crée des incohérences avec les autres environnements ou la production. Ajoutez toujours vos changements dans une nouvelle migration.

​
Événements de migration

Chaque opération de migration déclenche un événement. Tous héritent de Illuminate\Database\Events\MigrationEvent.
ClasseDescription
Illuminate\Database\Events\DatabaseRefreshedAprès migrate:refresh
Illuminate\Database\Events\MigrationsStartedJuste avant l’exécution du lot
Illuminate\Database\Events\MigrationsEndedAprès l’exécution du lot
Illuminate\Database\Events\MigrationStartedJuste avant chaque migration
Illuminate\Database\Events\MigrationEndedAprès chaque migration
Illuminate\Database\Events\NoPendingMigrationsAucun changement à exécuter
Illuminate\Database\Events\SchemaDumpedAprès un dump du schéma
Illuminate\Database\Events\SchemaLoadedAprès le chargement d’un dump
Par exemple, écoutez MigrationsEnded pour vider le cache à la fin : 
use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;

Event::listen(MigrationsEnded::class, function () {
    Cache::flush();
});

​
Prochaines étapes

Seeding de base de données

Alimentez les tables créées par vos migrations avec des données d’exemple.

Introduction à Eloquent

Manipulez les tables issues des migrations avec l’ORM Eloquent.
Dernière modification le 13 juillet 2026

Sujets connexes

Tests de base de donnéesSeeding de base de donnéesConfiguration de la base de donnéesTester des packages Laravel avec Orchestra TestbenchTests de navigateur (Dusk)