FbExpert — guide des fonctionnalités

1 Vue d’ensemble

FbExpert est un atelier Firebird : il explore un schéma, édite du SQL, exporte et importe des bases (structure et données) et accompagne une migration inter-versions pilotée par un contrat JSON.

Architecture

2 Installation

Les kits Firebird (clients/binaires) et les paramètres fournis sont installés par deux scripts équivalents.

Windows — tools/fetch-kits.ps1

.\tools\fetch-kits.ps1                  # kit 5.0 + snippets + options de formatage
.\tools\fetch-kits.ps1 -Kit 5.0,4.0     # plusieurs kits
.\tools\fetch-kits.ps1 -SettingsOnly    # paramètres seulement
.\tools\fetch-kits.ps1 -ForceSnippets   # réinstalle les snippets fournis
.\tools\fetch-kits.ps1 -ForceFormat     # réinstalle les options de formatage
.\tools\fetch-kits.ps1 -NoSnippets      # kits + options, sans snippets
.\tools\fetch-kits.ps1 -NoFormat        # kits + snippets, sans options

-SnippetsOnly reste accepté comme alias de -SettingsOnly.

Linux — tools/fetch-kits.sh

./tools/fetch-kits.sh                   # kit 5.0 + snippets + options
./tools/fetch-kits.sh -k 5.0,4.0
./tools/fetch-kits.sh --settings-only   # alias : --snippets-only
./tools/fetch-kits.sh --force-format
./tools/fetch-kits.sh --no-format

Prérequis Linux : bash 4+, curl, tar, python3, sha256sum.

3 Données utilisateur

Windows : %LOCALAPPDATA%\FbExpert\ — Linux : ${XDG_DATA_HOME:-$HOME/.local/share}/FbExpert/.

4 Explorateur de schéma

• Arborescence des bases, dossiers, tables, vues, procédures, fonctions, triggers, générateurs, domaines, exceptions, rôles, index et contraintes.
• Détail d’objet : colonnes, paramètres, contraintes, index, dépendances, DDL, commentaires.
• Recherche, filtre par type, pagination, rafraîchissement, détection de version moteur.
• Connexion embarquée ou serveur, gestion des identifiants, test de connexion, mise en ligne (gfix -online).

5 Éditeur SQL

Exécution de scripts

Chaque instruction est validée séparément : les objets créés sont visibles par les instructions suivantes. SET TERM est géré ; COMMIT, ROLLBACK, SET SQL DIALECT et SET TRANSACTION sont ignorés.

CREATE TABLE T (ID INTEGER NOT NULL PRIMARY KEY, NOM VARCHAR(30));

SET TERM ^ ;
CREATE PROCEDURE P (X INTEGER) RETURNS (N INTEGER) AS
BEGIN
  N = X + 1;
  SUSPEND;
END^
SET TERM ; ^

CREATE VIEW V AS SELECT ID, NOM FROM T;
INSERT INTO T (ID, NOM) VALUES (1, 'OK');
SELECT ID, NOM FROM T;

Le bouton « Exécuter » accepte ce script complet et affiche les lignes du dernier SELECT.

Correctifs d’éditeur

• Fin de lignes normalisées en LF avant tout calcul de position (snippets, curseur, sélection).
• EXECUTE BLOCK AS DECLARE … ; BEGIN … END n’est plus coupé au premier ; des déclarations.
• La popup ne reste plus vide après un snippet : le catalogue est chargé à l’ouverture et sur Ctrl+Espace.

6 Snippets

Le catalogue est stocké dans sql-snippets.json. Les snippets fournis sont fusionnés sans écraser les personnalisations ; « Réinitialiser les snippets fournis » restaure les définitions d’origine.

Les marqueurs {{TABLE}}, {{COLUMN}}, {{TYPE}}… sont remplacés à l’insertion ; le premier est sélectionné.

Deux endroits pour insérer : catégorie « Snippets » de l’auto-complétion, ou sélecteur « Snippet (Firebird x.y) » à côté de l’éditeur.

7 Formatage SQL

Bouton Formater + Options… dans l’éditeur d’objet et le panneau Script SQL.

SELECT
	 rdb$relation_name
	,rdb$view_blr
FROM rdb$relations r
LEFT JOIN rdb$fields f ON f.rdb$field_name = r.rdb$relation_name
WHERE rdb$view_blr IS NOT NULL
ORDER BY 1

Options enregistrées dans %LOCALAPPDATA%\FbExpert\sql-format.json ; « Réinitialiser » revient au style standard.

8 Export

• Export structure seule ou structure + données, vers un dossier avec manifeste et dumps binaires (FBDUMP).
• DDL fidèle : domaines, tables, vues, procédures, fonctions, triggers, packages, index, contraintes, commentaires, états ACTIVE/INACTIVE.
• Dumps en flux (aucune table chargée en mémoire), lecture DDL parallèle bornée, cache de version.
• Tables externes : exportées en structure interne, données non exportées.
• Avancement (étape, compteur, durée, annulation) et bilan.

9 Import et ETL

Deux modes

Garanties

• Alignement colonnes/valeurs, conversion de charset, GUID (CHAR(16) CHARACTER SET OCTETS / BINARY(16)), fuseaux horaires.
• DDL validé instruction par instruction (les objets créés sont visibles ensuite).
• Mode Bloquer (rollback/base supprimée) ou Continuer par objet.
• Procédures/fonctions/triggers en échec définitif : corps d’origine commenté, cause en tête, objet conservé ; trigger créé INACTIVE ; package : en-tête conservé sans corps.
• Insertion par lots via EXECUTE BLOCK (option options.batchRows, défaut 200, plafond 1000 paramètres) avec reprise ligne par ligne en cas d’échec.
• Reprise après échec, dumps d’erreur, historique et journal.

10 Atelier de migration

Page /migration, organisée en onglets :

Filtres de l’analyse

Les mêmes filtres de type que l’onglet 2 : Tous, table, vue, procédure, fonction, trigger, domaine, générateur… avec compteurs, synchronisés dans les deux sens. Le filtre Inactifs apparaît pour les triggers.

Après une action

Analyse, import, correction ou « Appliquer la sélection » → retour automatique à l’onglet 4 (résultats/erreurs).

Édition des objets

• Vues, procédures, fonctions, triggers, packages, index et contraintes : SQL éditable, test à blanc, retour à l’original.
• Index/contraintes : le SQL éditable porte sur CREATE INDEX ou ALTER TABLE … ADD CONSTRAINT ; l’état INACTIVE est conservé.
• Triggers neutralisés : badge inactif et filtre dédié.

11 Champs et référentiels

Champs existants

• Renommage, type cible, nullabilité (source / NULL / NOT NULL), valeur par défaut (vide = source, x = sans défaut, ? = retour au source).
• Normalisation en table de référence (Enum…) avec clé identité ou texte, FK, casse/trim, NULL conservé.

Champ ajouté (absent de l’export)

Bouton + Ajouter un champ dans le panneau Champs :

ALTER TABLE "CLIENT" ADD "STATUT" SMALLINT DEFAULT 0 NOT NULL;

CREATE TRIGGER "BI_CLIENT_STATUT" FOR "CLIENT"
ACTIVE BEFORE INSERT POSITION 0 AS
BEGIN
  IF (NEW."STATUT" IS NULL) THEN NEW."STATUT" = 0;
END

Appliqué après la création des tables et avant le chargement. Un champ NOT NULL est refusé sans défaut (immédiat ou conditionnel).

Référentiels (lookup)

• Création d’une table LUT_… à partir des valeurs distinctes d’un champ, avec clé identité ou texte.
• Alimentation distincte, FK, aperçu, mode structure seule.
• Regroupement insensible à la casse et trim ; NULL conservé.

12 Transformations par table

Bouton Transformations… sur une table : stager des tables du dump complet (même non importées), exécuter un préambule, un script SQL libre, puis un postambule.

Exemple

-- Préambule
CREATE OR ALTER FUNCTION FBX_UPPER (X VARCHAR(30)) RETURNS VARCHAR(30)
AS BEGIN RETURN UPPER(X); END

-- Script (JETON n'est pas importée, seulement stagée)
EXECUTE BLOCK AS
DECLARE VARIABLE ID INTEGER;
DECLARE VARIABLE NOM VARCHAR(30);
BEGIN
  FOR SELECT C.ID, J.LIBELLE
        FROM CLIENT C
        JOIN FBX_STAGE_JETON J ON J.ID = C.ID
       INTO :ID, :NOM
  DO
    UPDATE CLIENT SET NOM = FBX_UPPER(:NOM), NOM2 = :NOM WHERE ID = :ID;
END

-- Postambule
ALTER TABLE CLIENT ADD CONSTRAINT CHK_NOM2 CHECK (NOM2 IS NOT NULL);

13 Assistant de transformation

Dans le même dialogue, l’assistant construit la règle à partir des métadonnées du dump :

• Champ cible (type, nullabilité) ;
• Table source du dump (auto-stagée) et champs d’entrée ;
• conditions cible ↔ source : =, !=, <>, <, <=, >, >=, LIKE, IS NULL, IS NOT NULL, condition calculée, combinaison AND/OR ;
• mode : expression SQL, fonction PSQL/UDR, EXECUTE BLOCK ;
• valeur si NULL / aucune ligne → COALESCE ;
• compatibilité : compare la famille du type de sortie déclaré avec celle du champ cible, et alerte si NOT NULL sans repli.

Exemple généré

UPDATE "RM_SOURCE_DATA" T
   SET "SOURCE_DATA" = COALESCE(
       (SELECT FBX_X(S."SOURCE_DATA")
          FROM "FBX_STAGE_RM_SOURCE_DATA" S
         WHERE T."GUID" = S."GUID"), 'N/C')
 WHERE EXISTS (SELECT 1 FROM "FBX_STAGE_RM_SOURCE_DATA" S
                WHERE T."GUID" = S."GUID");

Ou en EXECUTE BLOCK avec clé de mise à jour, variables :INn, :KEYV, :OUTV.

14 Historique et transferts

• Historique SQL : requêtes exécutées, succès/erreur, durée, lignes, base.
• Historique des transferts : export/import, dossier, base cible, résultat, durée, lignes, journal.
• Panneau « Transferts » et atelier « avant/après » partagent le même contexte.
• Base système FBEXPERT.FB5 (registre, historique) ; sauvegarde/nettoyage possible.

15 Tests et qualité

• Tests unitaires : contrat, transformations DDL, types, champs, snippets, formatage, découpage SQL, magasins JSON.
• Tests d’intégration réels sur moteur Firebird embarqué : import complet, versions 2.5 → 5.0, lots, triggers/index INACTIVE, packages, champs ajoutés, transformations.
• Les collections de tests sont sérialisées : les tests E2E modifient l’environnement global du kit Firebird.
• Build : 0 erreur / 0 avertissement.

16 Limites connues

• Champs calculés : le type est une expression SQL libre, sans conversion automatique.
• Champ ajouté : un homonyme déjà présent fait échouer l’ALTER TABLE (étape en erreur).
• Référence FK : la colonne visée doit être UNIQUE/PRIMARY KEY ; la valeur par défaut doit exister.
• Staging : les types viennent du DDL source ; un domaine absent de la cible fera échouer la création du staging.
• UDR : la bibliothèque doit être présente dans le kit ; la déclaration doit précéder le bloc.
• Transformations : règles au niveau table ; les presets réutilisables et le « Tester » sur base temporaire sont prévus au lot suivant.
• Expression SQL : la compatibilité de sortie est vérifiée par Firebird à l’exécution ; l’assistant ne peut pas typer une expression arbitraire.

17 Journal des évolutions

18 Maintenance de cette page

Checklist à chaque évolution

1. Ajouter la section ou compléter la fonctionnalité concernée dans ce fichier.
2. Mettre à jour la version et la date en tête (Version documentée, Dernière mise à jour).
3. Ajouter une ligne au journal des évolutions.
4. Mettre à jour les compteurs de tests/build si nécessaire.
5. Ajouter l’entrée correspondante dans BACKLOG.md (section 7.x).

Fichiers de référence

Page autonome : un seul fichier HTML, CSS et JavaScript inclus, aucune ressource externe. Elle peut être ouverte directement dans un navigateur ou imprimée en PDF.