Migrations Doctrine — règles, compatibilité MariaDB/SQLite, sécurité financière

Kohinos repose sur Doctrine ORM 2.14+ et DBAL 3.x (pas DBAL 4.x — l'API Schema::createTable() et la signature des plateformes ont changé). La cible prod est MariaDB, les tests tournent sur SQLite in-memory. Conséquence directe : toute migration doit fonctionner sur les deux moteurs, sous peine de casser la CI ou la prod. Et comme la base contient les soldes eMLc, les mandats SEPA et les engagements SSA, une migration ratée peut détruire de la monnaie locale. La règle est donc : relire, rendre réversible, tester sur les deux moteurs, ne pas faire de DML risqué.

Cycle de vie d'une migration

flowchart LR
  A["1. Modifier entité
(attributes PHP 8)"] --> B["2. doctrine:migrations:diff"]
  B --> C["3. Relire le SQL généré"]
  C --> D["4. Compléter down() réversible"]
  D --> E["5. migrate (env=dev MariaDB)"]
  E --> F["6. migrate prev + migrate (idempotence)"]
  F --> G["7. migrate (env=test SQLite)"]
  G --> H["8. tests ciblés + schema:validate"]
  H --> I["9. CHANGELOG.md + commit"]
    

Commandes de référence

# Générer (jamais commiter sans relecture)
php bin/console doctrine:migrations:diff

# Appliquer sur dev (MariaDB)
php bin/console doctrine:migrations:migrate --no-interaction

# Rollback la dernière puis rejouer (vérifie down() + idempotence)
php bin/console doctrine:migrations:migrate prev --no-interaction
php bin/console doctrine:migrations:migrate --no-interaction

# Appliquer sur SQLite (env de test)
php bin/console doctrine:database:create --env=test
php bin/console doctrine:migrations:migrate --env=test --no-interaction

# Valider la cohérence schéma ⇄ entités
php bin/console doctrine:schema:validate

La config est dans config/packages/doctrine_migrations.yaml : les migrations vivent sous src/Migrations/, la table de tracking est migration_versions, et un décorateur maison (App\Utils\MigrationFactoryDecorator) injecte les services nécessaires aux migrations qui font appel au container.

Incompatibilités SQLite ⇄ MariaDB

SQLite est un moteur volontairement minimaliste : certaines opérations DDL courantes sur MariaDB y sont émulées par recréation de table, d'autres sont silencieusement ignorées. Les pièges les plus fréquents rencontrés sur Kohinos :

Pattern de guard plateforme à utiliser quand on ne peut vraiment pas écrire du SQL portable :

public function up(Schema $schema): void
{
    $platform = $this->connection->getDatabasePlatform()->getName();

    if ($platform === 'mysql') {
        $this->addSql('ALTER TABLE flux ADD FULLTEXT INDEX idx_flux_reference (reference)');
        return;
    }

    // SQLite (tests) : on saute, l'index FULLTEXT n'a pas de sens en in-memory.
}

Règles dures

Migrations IBAN chiffrés — exemple type

Les IBAN SepaMandate::iban sont chiffrés via libsodium. Une mauvaise migration ré-encrypterait deux fois et casserait les futurs prélèvements. Pattern de migration sûr :

# 1. Aperçu sans écriture
php bin/console app:migrate-iban-encryption --dry-run

# 2. Vérifier le rapport généré dans var/log/iban-migration-preview-*.json
# Champs attendus : total_mandates, already_encrypted, to_encrypt, errors[]

# 3. Window double-encryption : la commande accepte les deux formats pendant la migration
#    - cleartext  : KOHINOS-detected (prefix bytes 'FR' ou 'BE')
#    - chiffré v1 : prefix sodium "ENC1:" + base64
#    On ne touche QUE les cleartext, on tague le résultat "ENC1:".

# 4. Exécution réelle
php bin/console app:migrate-iban-encryption

# 5. Vérification post-migration
#    - aucun IBAN cleartext restant
#    - tous les SepaMandate.status restent inchangés
#    - les RecurringSepaPurchaseRequest associés sont toujours résoluble par UMR
php bin/console kohinos:sepa:verify-encryption

Le DDL (ajout de colonne iban_encryption_version) est dans une migration Doctrine, mais la conversion des données est dans une commande Symfony dédiée — c'est l'application stricte de la règle "pas de DML dans up()".

Tests sur SQLite in-memory

La config de test (config/packages/test/doctrine.yaml) bascule le driver sur pdo_sqlite avec memory: true. Toutes les migrations sont rejouées depuis zéro à chaque php bin/console app:init-test-database --env=test --purge. Cas de blocage déjà rencontrés :

• Foreign keys désactivées : SQLite par défaut n'applique pas les FK. Si la migration ajoute une FK et qu'un test compte sur le rejet, le test passe en mémoire mais échoue en prod. La fixture doit donc aussi contrôler la cohérence référentielle au niveau applicatif.
• Pragmas SQLite : si une migration émet PRAGMA, l'envelopper dans le guard de plateforme — MariaDB le rejette.
• Recréation de table sur ALTER : certains tests Sonata Admin chargent ~5 000 lignes au setUp. Une migration CHANGE COLUMN en SQLite peut faire grimper le temps de test à plusieurs secondes. Préférer scinder migration structurelle et data backfill.
• Types DECIMAL(10, 2) : SQLite stocke en NUMERIC avec arithmétique flottante. Les invariants monétaires doivent utiliser BigDecimal côté PHP, jamais comparer des floats SQLite avec ===.

Doctrine attributes uniquement

// ❌ INTERDIT
/** @ORM\Column(type="string") @Gedmo\Slug(fields={"name"}) */

// ✅ OBLIGATOIRE
#[ORM\Column(length: 100)]
#[Gedmo\Slug(fields: ['name'])]

Anti-patterns

Checklist pré-commit migration

Pour aller plus loin