Die Project-Entity aus Kapitel 19 existiert bisher NUR als PHP-Code – die Datenbank weiß noch NICHTS von einer project-Tabelle. Migrationen schließen diese Lücke NACHVOLLZIEHBAR und VERSIONIERT.

Warum Migrationen statt direktem Schema-Update?

Doctrine bietet ZWEI Wege, das Datenbankschema an die Entities anzupassen – beide erzeugen dasselbe Ergebnis, aber mit einem entscheidenden Unterschied:

Eine Migration erstellen

php bin/console make:migration

Doctrine vergleicht die AKTUELLEN Entity-Definitionen mit dem AKTUELLEN Datenbankschema und generiert automatisch das nötige SQL für die Differenz:

<?php

declare(strict_types=1);

namespace DoctrineMigrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class Version20260806120000 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $this->addSql('CREATE TABLE project (
            id SERIAL NOT NULL,
            name VARCHAR(255) NOT NULL,
            description TEXT DEFAULT NULL,
            created_at TIMESTAMP(0) NOT NULL,
            PRIMARY KEY(id)
        )');
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE project');
    }
}

up() wendet die Änderung AN, down() macht sie RÜCKGÄNGIG – beide sollten IMMER zueinander passen, damit sich eine Migration im Notfall sauber zurückrollen lässt.

Die Migration anwenden

php bin/console doctrine:migrations:migrate

Fragt zur Bestätigung nach (mit -n übersprungen, nützlich für automatisierte Deployments in Kapitel 48). Doctrine führt ALLE noch nicht angewendeten Migrationen in chronologischer Reihenfolge aus und protokolliert den Stand in einer internen doctrine_migration_versions-Tabelle.

Den aktuellen Migrationsstatus prüfen

php bin/console doctrine:migrations:status

Eine Migration rückgängig machen

php bin/console doctrine:migrations:migrate prev

Führt down() der ZULETZT angewendeten Migration aus – nützlich, wenn sich bei einer neuen Migration ein Fehler zeigt, BEVOR sie in Produktion geht.

Der Standard-Workflow ab jetzt

1. Entity anlegen oder ändern (wie in Kapitel 19).
2. php bin/console make:migration – Doctrine generiert das SQL automatisch.
3. Die generierte Migrationsdatei DURCHLESEN – Doctrine ist meist zuverlässig, aber gerade bei komplexeren Änderungen (z. B. Umbenennungen) lohnt sich eine manuelle Prüfung.
4. php bin/console doctrine:migrations:migrate – anwenden.
5. Migration UND Entity-Änderung GEMEINSAM committen – sie gehören untrennbar zusammen.