Floor — qu’est-ce que c’est, ORM sur SQLite dans Flutter

Qu’est-ce que Floor ?

Floor est une bibliothèque ORM pour Flutter et Dart construite sur SQLite. Elle utilise des annotations pour décrire les entités (Entity), les Data Access Objects (DAO) et la base de données (Database). La génération de code est effectuée via build_runner et floor_generator — le compilateur crée des implémentations DAO et une classe de gestion de base de données. Contrairement à sqflite brut, Floor élimine complètement le besoin de conversion manuelle de ResultSet en objets Dart en mappant automatiquement les colonnes vers les champs Entity par réflexion de types.

Floor suit le patron Repository + DAO familier aux développeurs Android avec Room. Chaque table est représentée par une classe Dart avec l’annotation @Entity, les requêtes SQL sont regroupées dans des interfaces avec l’annotation @dao, et la base de données est assemblée dans une classe abstraite avec @Database. Cette approche sépare strictement le modèle de données de la logique de requêtes.

Selon Flutter Pulse (2023), Floor est choisi dans 28 % des projets Flutter nécessitant une base de données locale. Les principales raisons de ce choix sont la familiarité avec SQL (pas besoin d’apprendre un nouveau langage de requêtes) et la vérification des requêtes à la compilation. De plus, Floor génère un code lisible facile à déboguer par rapport aux ORM plus abstraits avec DSL personnalisés, ce qui abaisse la barrière à l’entrée pour les nouveaux développeurs dans l’équipe.

Architecture de Floor

Floor se compose de trois couches : Entity (modèle de table), DAO (interface de requêtes) et Database (point d’entrée). Le générateur crée des implémentations _$_Entity pour le mappage de champs et _$_Dao pour l’exécution SQL. Lorsque Entity ou DAO change, il suffit de redémarrer build_runner — le code se met à jour automatiquement. Pour la migration entre versions de schéma, Floor utilise des numéros de version séquentiels, garantissant l’intégrité des données lors de la mise à jour de l’application sur les appareils des utilisateurs.

Comment Floor fonctionne-t-il dans Flutter ?

Floor utilise SQLite via le paquet sqflite pour les builds natifs et sqlite3 pour le bureau et le web. Au démarrage de l’application, Floor crée ou ouvre le fichier SQLite, applique les migrations et prépare les méthodes DAO pour exécuter les requêtes. Toutes les opérations sont effectuées de manière asynchrone via Future et Stream.

La génération de code dans Floor fonctionne comme suit : l’analyseur lit les annotations des fichiers source, crée un AST (Arbre Syntaxique Abstrait) des modèles et requêtes, puis génère des fichiers Dart avec le préfixe _$. Le code généré inclut les mappeurs ResultSet → Entity et vice versa.

Sécurité des threads

Floor travaille avec SQLite dans un seul isolate. Toutes les requêtes sont exécutées de manière asynchrone, mais les écritures concurrentes sont verrouillées au niveau SQLite. Pour les transactions, l’annotation @transaction est utilisée, garantissant l’atomicité d’un groupe de requêtes et le rollback en cas d’erreur.

Floor vs Drift : comparaison d’ORM pour Flutter

Floor et Drift sont tous deux des ORM sur SQLite, mais ils diffèrent par leur philosophie. Floor est plus proche de Room d’Android, Drift est plus réactif avec une API Stream intégrée et une compilation de requêtes via des fichiers SQL. Le choix entre eux dépend de l’expérience de l’équipe et de la réactivité requise.

Quand choisir Floor

Floor est le choix pour les équipes déjà familières avec SQL et Android Room. Si les développeurs ont l’habitude d’écrire des requêtes SQL manuellement et souhaitent une enveloppe minimale sur SQLite — Floor offre le typage sans apprendre un nouveau DSL. Il est également plus facile à déboguer car le code généré est lisible et prévisible.

Quand Drift est meilleur

Drift offre une réactivité plus puissante et supporte davantage de plateformes. Si l’application utilise activement Stream pour mettre à jour l’UI, nécessite des requêtes complexes avec JOIN et sous-requêtes ou cible le web — Drift est préférable. Cependant, sa barrière à l’entrée est plus élevée en raison de la nécessité d’apprendre son propre DSL.

Exemples de code avec Floor

Floor est construit autour d’annotations. Vous trouverez ci-dessous un exemple complet d’Entity, DAO et Database pour une application de liste de tâches. Après avoir exécuté build_runner, les classes générées sont prêtes à l’emploi.

Définition d’Entity et DAO

La classe TaskEntity avec l’annotation @Entity est mappée sur la table task. Un champ avec @primaryKey devient la clé primaire. L’interface TaskDao contient des méthodes pour les opérations sur la table — chaque méthode est annotée avec @Query, @Insert, @Update ou @Delete.

@entity
class TaskEntity {
    @PrimaryKey(autoGenerate: true)
    final int id;
    final String title;
    final bool isCompleted;
    final int priority;

    TaskEntity({this.id, required this.title,
        this.isCompleted = false, this.priority = 0});
}

@dao
abstract class TaskDao {
    @Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
    Future<List<TaskEntity>> getAllTasks();

    @Insert
    Future<int> insertTask(TaskEntity task);

    @Update
    Future<void> updateTask(TaskEntity task);

    @Query('SELECT * FROM TaskEntity WHERE isCompleted = :status')
    Stream<List<TaskEntity>> watchTasks(bool status);
}

Initialisation de la base de données

Une classe abstraite avec l’annotation @Database lie Entity et DAO. La méthode databaseBuilder crée une instance de base de données. Après avoir appelé build, la base de données est prête : Floor ouvre le fichier SQLite, applique les migrations et retourne le DAO pour le travail.

@Database(version: 1, entities: [TaskEntity])
abstract class AppDatabase extends FloorDatabase {
    TaskDao get taskDao;
}

// Utilisation
final database = await $FloorAppDatabase.databaseBuilder('app.db').build();
final taskDao = database.taskDao;
final tasks = await taskDao.getAllTasks();

Requêtes réactives via Stream

Floor prend en charge le retour de Stream depuis les méthodes DAO. Lors de toute modification dans la table, le Stream émet une nouvelle liste. Cela s’intègre avec StreamBuilder dans Flutter — l’UI se met automatiquement à jour lors de l’ajout, la modification ou la suppression d’enregistrements.

@Query('SELECT * FROM TaskEntity ORDER BY priority DESC')
Stream<List<TaskEntity>> watchAllTasks();

// Dans le widget Flutter
StreamBuilder<List<TaskEntity>>(
    stream: taskDao.watchAllTasks(),
    builder: (context, snapshot) {
        final tasks = snapshot.data ?? [];
        return ListView.builder(
            itemCount: tasks.length,
            itemBuilder: (_, i) => TaskTile(tasks[i]),
        );
    },
)

Migrations et versionnage dans Floor

Floor prend en charge le versionnage de base de données via le paramètre version dans l’annotation @Database. Lorsque Entity change (ajout ou suppression de champs), vous devez incrémenter la version et ajouter une migration. Une migration est une fonction Dart qui reçoit une transaction et exécute des requêtes SQL ALTER TABLE.

Exemple de migration

Supposons qu’à la version 2 nous ayons ajouté un champ dueDate à TaskEntity. La migration est effectuée via une requête SQL ALTER TABLE. Si une migration n’est pas spécifiée, Floor appelle MigrationStrategy où vous pouvez définir un fallback (par exemple, recréer la table avec perte de données).

Tester les requêtes Floor

Floor ne fournit pas de framework mock intégré, mais la base de données peut facilement être remplacée dans les tests. Créez un inMemoryDatabaseBuilder — il crée une base de données SQLite en mémoire identique en schéma à la production. Après chaque test, nettoyez les données via deleteDatabase pour isoler les scénarios de test.

Transactions et opérations par lots dans Floor

Floor prend en charge les transactions via l’annotation @transaction sur les méthodes DAO. À l’intérieur d’une transaction, plusieurs requêtes sont exécutées séquentiellement avec garantie de rollback en cas d’erreur. L’insertion par lots via @Insert avec un paramètre List optimise l’insertion de plusieurs enregistrements en un seul appel — c’est plusieurs fois plus rapide que d’insérer un enregistrement à la fois dans une boucle. Pour les opérations en masse, utilisez des insertions par lots de 100 à 200 enregistrements : c’est l’équilibre optimal entre vitesse d’exécution et consommation de RAM sur les appareils mobiles aux ressources limitées.

final migration1to2 = Migration(1, 2, (database) async {
    await database.execute(
        'ALTER TABLE TaskEntity ADD COLUMN dueDate TEXT'
    );
});

final database = await $FloorAppDatabase.databaseBuilder('app.db')
    .addMigrations([migration1to2])
    .build();