Databasemigraties

Wat zijn migraties

Migraties zijn een soort versiebeheer voor je database. Ze stellen een team in staat om de definitie van het databaseschema van de applicatie te delen en te beheren. Je hebt vast weleens meegemaakt dat je na het pullen van de broncode aan teamleden moest vertellen: “voeg handmatig een kolom toe aan je lokale database”. Migraties lossen dat probleem op. Migratiebestanden staan in de directory database/migrations. Elke bestandsnaam bevat een timestamp die Laravel gebruikt om de uitvoeringsvolgorde van de migraties te bepalen.

Een migratiebestand aanmaken

Met het Artisan-commando make:migration genereer je een nieuw migratiebestand.

php artisan make:migration create_posts_table

Laravel leidt uit de migratienaam de tabelnaam af en genereert een passende stub. Heet de migratie create_posts_table, dan staat de code om de tabel posts aan te maken al voor je klaar.

De structuur van een migratie

Een migratieklasse heeft twee methoden: up en down.

De up-methode: voegt tabellen, kolommen en indexen toe aan de database.
De down-methode: maakt de bewerkingen van up ongedaan. Wordt aangeroepen bij een rollback.

<?php

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

return new class extends Migration
{
    /**
     * Voer de migratie uit
     */
    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();
        });
    }

    /**
     * Maak de migratie ongedaan
     */
    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

De belangrijkste kolomdefinitiemethoden

De Blueprint-klasse biedt een groot aantal kolomtypen.

Methode	Beschrijving
`$table->id()`	Auto-incrementele primaire sleutel (alias van `bigIncrements('id')`)
`$table->string('name')`	Kolom vergelijkbaar met VARCHAR (standaard 255 tekens)
`$table->text('body')`	TEXT-kolom
`$table->integer('count')`	INTEGER-kolom
`$table->boolean('active')`	Slaat een booleaanse waarde op als TINYINT
`$table->timestamp('published_at')`	TIMESTAMP-kolom
`$table->timestamps()`	Voegt `created_at` en `updated_at` in één keer toe
`$table->softDeletes()`	Voegt een `deleted_at`-kolom toe voor soft deletes
`$table->foreignId('user_id')`	`BIGINT UNSIGNED`-kolom voor foreign keys

Kolommodifiers

Aan kolomdefinities voeg je modifiers toe via een methodchain.

$table->string('email')->unique();
$table->string('name')->nullable();
$table->integer('votes')->default(0);
$table->string('title')->after('id'); // Plaatsen na de opgegeven kolom

Vectorkolommen en -indexen

De methode vector maakt een vector-kolom voor het opslaan van embeddingvectoren. Stel dimensions in op de uitvoerdimensie van de embeddingprovider die je gebruikt.

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

Vectorkolommen zijn beschikbaar op PostgreSQL-verbindingen met de pgvector-extensie en op MariaDB 11.7 of nieuwer. Activeer op PostgreSQL pgvector voordat je een vectorkolom aanmaakt.

Schema::ensureVectorExtensionExists();

Om zoekopdrachten op vectorgelijkenis te versnellen, voeg je een index toe aan de vector-kolom. Deze index gebruikt de cosinusafstand.

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

Gebruik dropVectorIndex om een bestaande vectorindex te verwijderen.

$table->dropVectorIndex('documents_embedding_vectorindex');

Online index aanmaken

Wanneer je een index aanmaakt op een grote tabel, wordt de tabel meestal vergrendeld terwijl de index wordt opgebouwd, waardoor lees- en schrijfacties moeten wachten. In MySQL kun je met de inplace-modifier op een index- of foreign key-definitie de bewerking uitvoeren met het INPLACE-algoritme.

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

Combineer inplace met de lock-modifier om het tabellenslot tijdens de bewerking te bepalen. Met none blijven lezen en schrijven mogelijk voor bewerkingen die MySQL toestaat.

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

Deze functionaliteit is MySQL-specifiek. Controleer in de documentatie voor online DDL-bewerkingen van MySQL of de bewerking die je uitvoert het INPLACE-algoritme en de opgegeven lock-modus ondersteunt. Om inplace te gebruiken bij foreign key-bewerkingen, moet je eerst de foreign key-constraints uitschakelen.

Migraties uitvoeren

Met het commando migrate voer je alle nog niet uitgevoerde migraties uit.

php artisan migrate

Om te zien welke migraties al zijn uitgevoerd en welke nog niet, gebruik je migrate:status.

php artisan migrate:status

Voer je migraties uit in productie, dan verschijnt er een bevestigingsprompt. Wil je zonder bevestiging uitvoeren, gebruik dan de flag --force — maar wees voorzichtig, want sommige bewerkingen kunnen data laten verdwijnen.

Rollback

Om de laatste batch migraties terug te draaien gebruik je migrate:rollback.

php artisan migrate:rollback

Wil je een specifiek aantal stappen terugdraaien, geef dan de optie --step op.

# De laatste 5 migraties terugdraaien
php artisan migrate:rollback --step=5

Om alle migraties terug te draaien en daarna opnieuw uit te voeren gebruik je migrate:refresh.

php artisan migrate:refresh

migrate:refresh bouwt alle tabellen opnieuw op, waardoor bestaande data verloren gaat. Handig om de database tijdens de ontwikkeling te resetten.

Praktijkvoorbeeld: de posts-tabel aanmaken

Aan de hand van een posts-tabel voor blogposts lopen we het hele proces door.

1. Het migratiebestand genereren

php artisan make:migration create_posts_table

2. De migratie bewerken

Open en bewerk 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. De migratie uitvoeren

php artisan migrate

Na uitvoering is de tabel posts in de database aangemaakt.

4. Later een kolom toevoegen

Wil je na het aanmaken van de tabel een nieuwe kolom toevoegen, bewerk dan niet de bestaande migratie, maar maak een nieuwe migratie aan.

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');
    });
}

Vermijd het direct bewerken van bestaande migratiebestanden. Dat verstoort de consistentie met andere teamleden en de productieomgeving. Voeg wijzigingen altijd toe als nieuwe migratie.

Migratie-events

Bij elke migratiebewerking worden events uitgezonden. Alle events erven over van Illuminate\Database\Events\MigrationEvent.

Klasse	Beschrijving
`Illuminate\Database\Events\DatabaseRefreshed`	Na afronding van het commando `migrate:refresh`
`Illuminate\Database\Events\MigrationsStarted`	Vlak voordat een batch migraties wordt uitgevoerd
`Illuminate\Database\Events\MigrationsEnded`	Na afronding van een batch migraties
`Illuminate\Database\Events\MigrationStarted`	Vlak voordat een enkele migratie wordt uitgevoerd
`Illuminate\Database\Events\MigrationEnded`	Na afronding van een enkele migratie
`Illuminate\Database\Events\NoPendingMigrations`	Wanneer een migratiecommando vaststelt dat er geen openstaande migraties zijn
`Illuminate\Database\Events\SchemaDumped`	Na afronding van een databaseschemadump
`Illuminate\Database\Events\SchemaLoaded`	Na het laden van een bestaande schemadump

Je kunt bijvoorbeeld luisteren naar het event MigrationsEnded en na afronding van de migraties de cache legen.

use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Event;

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

Volgende stappen

Databaseseeding

Leer hoe je voorbeelddata plaatst in de tabellen die je met migraties hebt aangemaakt.

Introductie tot Eloquent

Leer hoe je de tabellen die je met migraties hebt aangemaakt bewerkt met de Eloquent ORM.

Aan de slag

Basis

Request-verwerking

Database

Authenticatie

Helpers en externe communicatie

Testen en deployment

AI-ontwikkelondersteuning

Wat zijn migraties

Een migratiebestand aanmaken

De structuur van een migratie

De belangrijkste kolomdefinitiemethoden

Kolommodifiers

Vectorkolommen en -indexen

Online index aanmaken

Migraties uitvoeren

Rollback

Praktijkvoorbeeld: de posts-tabel aanmaken

1. Het migratiebestand genereren

2. De migratie bewerken

3. De migratie uitvoeren

4. Later een kolom toevoegen

Migratie-events

Volgende stappen

Databaseseeding

Introductie tot Eloquent

​Wat zijn migraties

​Een migratiebestand aanmaken

​De structuur van een migratie

​De belangrijkste kolomdefinitiemethoden

​Kolommodifiers

​Vectorkolommen en -indexen

​Online index aanmaken

​Migraties uitvoeren

​Rollback

​Praktijkvoorbeeld: de posts-tabel aanmaken

​1. Het migratiebestand genereren

​2. De migratie bewerken

​3. De migratie uitvoeren

​4. Later een kolom toevoegen

​Migratie-events

​Volgende stappen

Databaseseeding

Introductie tot Eloquent

Wat zijn migraties

Een migratiebestand aanmaken

De structuur van een migratie

De belangrijkste kolomdefinitiemethoden

Kolommodifiers

Vectorkolommen en -indexen

Online index aanmaken

Migraties uitvoeren

Rollback

Praktijkvoorbeeld: de posts-tabel aanmaken

1. Het migratiebestand genereren

2. De migratie bewerken

3. De migratie uitvoeren

4. Later een kolom toevoegen

Migratie-events

Volgende stappen