btpxpress-backend/MIGRATION_HIBERNATE.md

Migration vers Hibernate (sans Flyway)

📋 Résumé des changements

Ce document explique les modifications apportées pour désactiver Flyway et laisser Hibernate gérer automatiquement la création des tables et le chargement des données.

---

✅ Changements effectués

1. Configuration Hibernate (application.properties)

Avant :

quarkus.hibernate-orm.database.generation=update
quarkus.flyway.migrate-at-start=true
quarkus.flyway.baseline-on-migrate=true
quarkus.flyway.baseline-version=0
quarkus.flyway.locations=classpath:db/migration

Après :

# Hibernate crée les tables automatiquement
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.log.sql=true

# Flyway DÉSACTIVÉ - Hibernate gère le schéma
quarkus.flyway.migrate-at-start=false

2. Fichier import.sql créé

Un nouveau fichier src/main/resources/import.sql a été créé. Ce fichier contient toutes les données de test et sera automatiquement exécuté par Hibernate après la création des tables.

Le fichier contient :

• ✅ Types de chantier
• ✅ Clients (entreprises et particuliers ivoiriens)
• ✅ Employés
• ✅ Équipes
• ✅ Affectation des employés aux équipes
• ✅ Marques de matériel
• ✅ Matériel BTP
• ✅ Chantiers
• ✅ Phases des chantiers
• ✅ Devis et lignes de devis
• ✅ Factures et lignes de factures

---

🚀 Comment ça fonctionne ?

Cycle de démarrage de l'application :

1. Hibernate démarre et lit les entités JPA
2. Hibernate crée les tables automatiquement (drop-and-create)
3. Hibernate exécute import.sql pour charger les données
4. L'application est prête avec une base de données complète

---

🔧 Modes de génération Hibernate

Vous pouvez ajuster le comportement avec la propriété quarkus.hibernate-orm.database.generation :

Mode	Description	Utilisation
drop-and-create	Supprime et recrée les tables à chaque démarrage	✅ Développement (mode actuel)
update	Met à jour le schéma sans supprimer les données	🔄 Développement avec persistance
create	Crée les tables si elles n'existent pas	🆕 Premier démarrage
validate	Valide le schéma sans modification	🏭 Production
none	Aucune action	🚫 Gestion manuelle

---

📝 Recommandations par environnement

Développement local (actuel)

quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.flyway.migrate-at-start=false

✅ Les tables sont recréées à chaque démarrage avec les données de test

Tests

%test.quarkus.hibernate-orm.database.generation=drop-and-create
%test.quarkus.flyway.migrate-at-start=false

✅ Déjà configuré dans application-test.yml

Production

%prod.quarkus.hibernate-orm.database.generation=validate
%prod.quarkus.flyway.migrate-at-start=false

⚠️ Important : En production, utilisez validate pour éviter toute modification accidentelle du schéma

---

🗂️ Fichiers de migration Flyway (conservés)

Les fichiers de migration Flyway dans src/main/resources/db/migration/ sont conservés mais non utilisés :

• V1__Initial_schema.sql
• V2__Sample_data.sql
• V3__create_auth_tables.sql
• V4__create_phase_templates_fixed.sql
• V5__Ivorian_test_data.sql

Vous pouvez les supprimer si vous ne prévoyez pas de réactiver Flyway.

---

🔄 Pour réactiver Flyway (si nécessaire)

Si vous souhaitez revenir à Flyway :

1. Modifier application.properties :

quarkus.hibernate-orm.database.generation=validate
quarkus.flyway.migrate-at-start=true
quarkus.flyway.baseline-on-migrate=true
quarkus.flyway.baseline-version=0
quarkus.flyway.locations=classpath:db/migration

2. Supprimer ou renommer import.sql :

mv src/main/resources/import.sql src/main/resources/import.sql.bak

---

🧪 Tester la configuration

Démarrer l'application :

./mvnw quarkus:dev

Vérifier les logs :

Vous devriez voir dans les logs :

Hibernate: drop table if exists clients cascade
Hibernate: drop table if exists chantiers cascade
...
Hibernate: create table clients (...)
Hibernate: create table chantiers (...)
...
Hibernate: insert into types_chantier (...)
Hibernate: insert into clients (...)
...

Accéder à la console H2 (en développement) :

http://localhost:8080/q/dev

---

❓ FAQ

Q : Pourquoi désactiver Flyway ?

R : Flyway et Hibernate peuvent entrer en conflit lorsqu'ils tentent tous deux de gérer le schéma de la base de données. En développement, Hibernate seul est plus simple et plus rapide.

Q : Les données sont-elles perdues à chaque redémarrage ?

R : Oui, avec drop-and-create. Pour conserver les données entre les redémarrages, utilisez update au lieu de drop-and-create.

Q : Comment passer en mode update ?

R : Modifiez application.properties :

quarkus.hibernate-orm.database.generation=update

Q : Le fichier import.sql est-il exécuté avec update ?

R : Oui, mais seulement au premier démarrage. Ensuite, il peut causer des erreurs de doublons. Pour éviter cela, commentez ou supprimez les lignes déjà insérées.

Q : Puis-je utiliser Hibernate en production ?

R : Oui, mais utilisez validate pour éviter toute modification du schéma. En production, il est recommandé de gérer les migrations avec Flyway ou Liquibase.

---

📚 Ressources

• Quarkus Hibernate ORM Guide
• Quarkus Flyway Guide
• Hibernate Schema Generation

---

✅ Résultat final

Votre application démarre maintenant avec :

• ✅ Hibernate crée automatiquement toutes les tables
• ✅ import.sql charge automatiquement les données de test
• ✅ Flyway est désactivé (pas de conflit)
• ✅ Base de données prête avec des données réalistes pour le marché ivoirien

Bon développement ! 🚀