# Concept

Puisque le but de l'ORM est de faire correspondre des objets PHP avec la base de données, il est nécessaire de créer la structure associée dans la base.
À chaque modification de la structure de la base par la création, modification ou suppression d'une entité, il est nécessaire de générer une migration.

Chaque migration Doctrine est une classe PHP contenant les requêtes SQL pour appliquer ces changements mais les requêtes pour les annuler également.
Doctrine va tenir le compte des migrations exécutées en les enregistrant dans une table dédiées, afin de ne pas exécuter une migration plusieurs fois.

# Génération de la migration

Générez une migration avec la commande make:migration:

php bin/console make:migration
[output]
[output]  Success! 
[output]
[output] Next: Review the new migration "migrations/Version20230211153052.php"
[output] Then: Run the migration with php bin/console doctrine:migrations:migrate
[output] See https://symfony.com/doc/current/bundles/DoctrineMigrationsBundle/index.html

En comparant l'état actuel de la base avec les entités, les requêtes SQL ont été générées automatiquement. Ouvrez le fichier situé dans le dossier /migrations/. La méthode up() applique les changements et down() annule:

// ...
    public function up(Schema $schema): void
    {
        // this up() migration is auto-generated, please modify it to your needs
        $this->addSql('CREATE SEQUENCE event_id_seq INCREMENT BY 1 MINVALUE 1 START 1');
        $this->addSql('CREATE TABLE event (id INT NOT NULL, title VARCHAR(255) NOT NULL, description TEXT DEFAULT NULL, start_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL, end_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL, PRIMARY KEY(id))');
    }

    public function down(Schema $schema): void
    {
        // this down() migration is auto-generated, please modify it to your needs
        $this->addSql('CREATE SCHEMA public');
        $this->addSql('DROP SEQUENCE event_id_seq CASCADE');
        $this->addSql('DROP TABLE event');
    }
// ...

Note: les requêtes dépendent du SGBD utilisé. Ici les requêtes générées pour PostgreSQL 15.

# Exécution

Lancer l'exécution de la migration:

php bin/console doctrine:migrations:migrate
[output]
[output] WARNING! You are about to execute a migration in database "sf5_events" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
[output] > yes
[output]
[output][notice] Migrating up to DoctrineMigrations\Version20230211153052
[output][notice] finished in 24.4ms, used 18M memory, 1 migrations executed, 2 sql queries

Doctrine a créé la table doctrine_migration_versions et enregistré l'exécution de la première migration:

Elle ne sera pas exécuté une seconde fois si on relance la commande:

php bin/console doctrine:migrations:migrate
[output]
[output] WARNING! You are about to execute a migration in database "sf5_events" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
[output] > yes
[output]
[output] [OK] Already at the latest version ("DoctrineMigrations\Version20230211153052")