Aller au contenu

Le backend SQLite dans Forge (forge-mvc-sqlite)

Ce document explique ce que fait l'opt-in forge-mvc-sqlite, ce qu'il expose, et comment on s'en sert.

forge-mvc-sqlite est un backend de base de données pour Forge : il fait fonctionner la couche BDD du cœur au-dessus de sqlite3 (bibliothèque standard), sans serveur ni dépendance externe.

Le cœur de Forge est agnostique BDD (ADR-054) : il découvre le backend installé par un entry point, et n'en utilise qu'un seul par projet.

1. Rôle du module

Le cœur sait générer du SQL et piloter db:init / db:apply / migration:*, mais il ne parle à aucune base directement : c'est le rôle d'un backend.

forge-mvc-sqlite fournit ce backend : une connexion sqlite3 adaptée aux attentes du cœur (curseur lignes-dict, lastrowid, autocommit) et un dialecte SQL propre à SQLite.

SQLite est sans serveur : la base est un simple fichier (DB_NAME). C'est le choix idéal en développement, en test et pour l'onboarding.

2. Vue d'ensemble rapide

Élément Valeur
Paquet forge-mvc-sqlite
Module forge_mvc_sqlite
Catégorie Bases de données (ADR-055)
Couche backend BDD opt-in exclusif (un seul par projet)
Dépend de forge-mvc (et sqlite3 de la bibliothèque standard)
Découverte entry point forge_mvc.db_backend nommé sqlite
Sélection automatique si seul installé ; sinon DB_BACKEND=sqlite
Provisioning aucun (sans serveur) : db:init crée le fichier
Base un fichier sur disque (chemin = DB_NAME)
Décision d'architecture ADR-054 (cœur agnostique BDD)
Installation pip install --pre forge-mvc-sqlite

3. Schémas UML

Les deux schémas suivants montrent deux vues complémentaires du backend.

Le diagramme de classe montre comment le cœur consomme le backend.

Le diagramme de séquence montre la résolution du backend puis une requête.

3.1 Diagramme de classe

Le diagramme de classe montre que le cœur résout un DatabaseBackend par entry point, et que forge-mvc-sqlite le fournit avec son dialecte.

classDiagram
    direction LR

    class DatabaseBackend {
        <<protocol, cœur>>
        +name
        +dialect
        +requires_provisioning
        +get_connection()
    }

    class SQLiteBackend {
        +name = "sqlite"
        +requires_provisioning = false
        +get_connection() connexion
    }

    class SQLiteDialect {
        +types SQLite
        +AUTOINCREMENT
        +CREATE INDEX séparés
    }

    class fichier {
        <<base>>
        +DB_NAME (fichier)
    }

    SQLiteBackend ..|> DatabaseBackend : implémente
    SQLiteBackend --> SQLiteDialect : dialecte
    SQLiteBackend --> fichier : ouvre

À retenir :

  • le cœur ne connaît que le contrat DatabaseBackend ;
  • forge-mvc-sqlite l'implémente au-dessus de sqlite3 ;
  • le dialecte traduit les types et la DDL en SQL SQLite ;
  • la base est un fichier, pas un service.

3.2 Diagramme de séquence

Le diagramme de séquence montre la découverte du backend puis une requête applicative.

sequenceDiagram
    participant App as Application / CLI
    participant Core as core.database
    participant Backend as forge-mvc-sqlite
    participant File as fichier SQLite

    App->>Core: première requête (ou db:init)
    Core->>Core: résout l'entry point forge_mvc.db_backend
    Core->>Backend: get_connection()
    Backend->>File: ouvre DB_NAME
    Backend-->>Core: connexion (lignes-dict, lastrowid)
    Core-->>App: résultat de la requête

À retenir :

  • le backend est résolu une fois, par entry point ;
  • s'il y a plusieurs backends installés, DB_BACKEND tranche ;
  • la connexion est adaptée au format attendu par le cœur ;
  • aucune étape réseau : c'est un fichier local.

4. Ce que fournit le backend

Élément Rôle
SQLiteBackend implémente le contrat DatabaseBackend du cœur
Adaptateur de connexion curseur dictionary=, lastrowid, autocommit au-dessus de sqlite3
SQLiteDialect types SQLite, INTEGER PRIMARY KEY AUTOINCREMENT, CREATE INDEX séparés
Entry point forge_mvc.db_backend = sqlite (découverte par le cœur)

L'API que vous utilisez reste celle du cœur : db:init, db:apply, migration:*, et core.database.db dans le code.

5. Contextes d'utilisation

Besoin Élément
Démarrer sans installer de serveur installer forge-mvc-sqlite
Forcer ce backend DB_BACKEND=sqlite
Créer la base forge db:init (crée le fichier)
Appliquer le schéma forge db:apply
Faire évoluer le schéma forge migration:make / migration:apply
Lire/écrire en code core.database.db

6. Exemple d'utilisation

pip install --pre forge-mvc-sqlite     # seul backend installé
forge db:init                          # crée le fichier SQLite + forge_migrations
forge db:apply                         # applique le schéma des entités

import core.database.db as db
rows = db.fetch_all("SELECT * FROM article", ())

Le code applicatif ne sait pas qu'il parle à SQLite : il utilise la couche BDD du cœur.

Aide-mémoire

Installer suffit :

  • un seul backend installé est choisi automatiquement ;
  • db:init crée le fichier, db:apply applique le schéma ;
  • le code utilise core.database.db, pas sqlite3.

7. Sans serveur, exclusif, et dialecte

SQLite n'a pas de serveur : requires_provisioning=False, donc db:init ne crée ni compte ni base distante, il prépare le fichier et la table forge_migrations.

Un seul backend BDD par projet : si plusieurs sont installés, fixez DB_BACKEND pour lever l'ambiguïté.

Idéal en développement et en test

Pas d'installation de serveur, une base = un fichier : on démarre en une commande.

Pour la production multi-utilisateurs, un backend serveur (MariaDB, PostgreSQL) est généralement préférable.

Dialecte SQLite

Le dialecte gère les spécificités : INTEGER PRIMARY KEY AUTOINCREMENT, CREATE INDEX en instructions séparées, affinités de types.

Le SQL généré reste lisible (principe 5).

Indépendance du cœur

Le cœur de Forge ne dépend pas de forge-mvc-sqlite : il le découvre par entry point (ADR-054).

Voir aussi