Migrations de base de données

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éthode	Description
`$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

Colonnes et index vectoriels

La méthode vector crée une colonne vector pour stocker des vecteurs d’embedding. Renseigne dans dimensions la dimension de sortie du fournisseur d’embedding que tu utilises.

$table->vector('embedding', dimensions: 1536);

Les colonnes vectorielles sont disponibles sur les connexions PostgreSQL utilisant l’extension pgvector et sur MariaDB 11.7 ou version ultérieure. Sur PostgreSQL, active pgvector avant de créer une colonne vectorielle.

Schema::ensureVectorExtensionExists();

Pour accélérer les recherches par similarité vectorielle, ajoute un index à la colonne vector. Cet index utilise la distance cosinus.

$table->vector('embedding', dimensions: 1536)->index();

Pour supprimer un index vectoriel existant, utilise dropVectorIndex.

$table->dropVectorIndex('documents_embedding_vectorindex');

Création d’index en ligne

Lorsque vous créez un index sur une grande table, la table est habituellement verrouillée pendant la construction de l’index, ce qui fait attendre les lectures et les écritures. Sur MySQL, ajoutez le modificateur inplace à la définition d’un index ou d’une clé étrangère pour exécuter l’opération avec l’algorithme INPLACE.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace();
    $table->foreign('team_id')
        ->references('id')
        ->on('teams')
        ->inplace();
});

Combinez inplace avec le modificateur lock pour contrôler le verrou de table pendant l’opération. Avec none, les lectures et les écritures restent disponibles pour les opérations que MySQL autorise.

Schema::table('users', function (Blueprint $table) {
    $table->index('email')->inplace()->lock('none');
});

Cette fonctionnalité est spécifique à MySQL. Consultez la documentation des opérations DDL en ligne de MySQL pour vérifier que l’opération que vous exécutez prend en charge l’algorithme INPLACE et le mode de verrou indiqué. Pour utiliser inplace sur des opérations de clé étrangère, désactivez au préalable les contraintes de clé étrangère.

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.

Classe	Description
`Illuminate\Database\Events\DatabaseRefreshed`	Après `migrate:refresh`
`Illuminate\Database\Events\MigrationsStarted`	Juste avant l’exécution du lot
`Illuminate\Database\Events\MigrationsEnded`	Après l’exécution du lot
`Illuminate\Database\Events\MigrationStarted`	Juste avant chaque migration
`Illuminate\Database\Events\MigrationEnded`	Après chaque migration
`Illuminate\Database\Events\NoPendingMigrations`	Aucun changement à exécuter
`Illuminate\Database\Events\SchemaDumped`	Après un dump du schéma
`Illuminate\Database\Events\SchemaLoaded`	Aprè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();
});

Pour commencer

Bases

Traitement des requêtes

Base de données

Authentification

Helpers et communication externe

Tests et déploiement

Assistance au développement IA

Qu’est-ce qu’une migration

Créer un fichier de migration

Structure d’une migration

Méthodes de définition de colonne

Modificateurs de colonne

Colonnes et index vectoriels

Création d’index en ligne

Exécuter les migrations

Rollback

Exemple : création de la table posts

1. Génération de la migration

2. Édition de la migration

3. Exécution

4. Ajouter une colonne après coup

Événements de migration

Prochaines étapes

Seeding de base de données

Introduction à Eloquent

​Qu’est-ce qu’une migration

​Créer un fichier de migration

​Structure d’une migration

​Méthodes de définition de colonne

​Modificateurs de colonne

​Colonnes et index vectoriels

​Création d’index en ligne

​Exécuter les migrations

​Rollback

​Exemple : création de la table posts

​1. Génération de la migration

​2. Édition de la migration

​3. Exécution

​4. Ajouter une colonne après coup

​Événements de migration

​Prochaines étapes

Seeding de base de données

Introduction à Eloquent

Qu’est-ce qu’une migration

Créer un fichier de migration

Structure d’une migration

Méthodes de définition de colonne

Modificateurs de colonne

Colonnes et index vectoriels

Création d’index en ligne

Exécuter les migrations

Rollback

Exemple : création de la table posts

1. Génération de la migration

2. Édition de la migration

3. Exécution

4. Ajouter une colonne après coup

Événements de migration

Prochaines étapes