Format des 'changelogs' Liquibase (XML, YAML, JSON, SQL)

La flexibilité des formats de changelog Liquibase

Liquibase se distingue par sa grande flexibilité quant au format utilisé pour décrire les changements de schéma de base de données. Un fichier 'changelog' est le coeur de Liquibase ; il contient une liste ordonnée de 'changesets'. Chaque changeset représente une modification atomique de la base de données (création de table, ajout de colonne, insertion de données, etc.) et est identifié de manière unique par un auteur (`author`) et un identifiant (`id`).

Cette flexibilité permet aux équipes de choisir le format qui correspond le mieux à leurs préférences, à leurs outils existants et à la complexité de leurs migrations. Que vous soyez plus à l'aise avec la structure rigoureuse du XML, la lisibilité du YAML, la familiarité du JSON pour les développeurs web, ou la puissance directe du SQL, Liquibase offre une option adaptée.

Comprendre les spécificités de chaque format est essentiel pour exploiter pleinement la puissance de Liquibase et garantir la clarté et la maintenabilité de vos scripts de migration au sein de votre application Spring Boot.

Le format XML : la référence historique

Le format XML est le format originel et le plus mature de Liquibase. Il offre une structure très explicite et est bien supporté par divers outils d'édition et de validation. La structure de base repose sur la balise racine `` qui contient une série de balises ``.

Chaque `` possède les attributs `author` et `id` obligatoires. A l'intérieur d'un changeset, vous utilisez des balises spécifiques à Liquibase (appelées 'Change Types') pour décrire les modifications, comme ``, ``, ``, etc. Ces balises offrent un niveau d'abstraction par rapport au SQL spécifique à la base de données, bien qu'il soit aussi possible d'inclure du SQL brut avec la balise ``.

Bien que parfois jugé verbeux, le XML garantit une structure claire et réduit les risques d'erreurs de syntaxe grâce à la validation via des schémas XSD. C'est souvent un choix privilégié dans les environnements d'entreprise exigeant une grande rigueur.

Exemple de création de table en XML :

Le format YAML : concision et lisibilité

YAML (YAML Ain't Markup Language) est devenu très populaire pour les fichiers de configuration en raison de sa syntaxe épurée et de sa lisibilité. Liquibase supporte pleinement YAML pour définir les changelogs.

La structure YAML repose sur l'indentation pour définir la hiérarchie. Le fichier commence généralement par `databaseChangeLog:` suivi d'une liste (`-`) de `changeSet:`. Chaque changeset contient les clés `id:` et `author:`, puis une liste de `changes:` qui décrivent les modifications à l'aide des 'Change Types' de Liquibase, similaires à ceux utilisés en XML mais avec une syntaxe clé-valeur.

Le principal avantage du YAML est sa concision par rapport au XML, ce qui le rend plus facile à lire et à écrire pour de nombreux développeurs. Cependant, il est sensible à l'indentation, ce qui peut parfois entraîner des erreurs si l'on n'est pas vigilant.

Exemple de création de table en YAML :

databaseChangeLog:
  - changeSet:
      id: 1
      author: certiquizz
      changes:
        - createTable:
            tableName: utilisateur
            columns:
              - column:
                  name: id
                  type: BIGINT
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: nom
                  type: VARCHAR(255)
                  constraints:
                    nullable: false
              - column:
                  name: email
                  type: VARCHAR(255)
                  constraints:
                    nullable: false
                    unique: true

Le format JSON : familier pour le web

JSON (JavaScript Object Notation) est un autre format largement utilisé, notamment dans les API web. Liquibase permet également de définir les changelogs en JSON, offrant une alternative aux développeurs familiers avec cette syntaxe.

La structure JSON est très similaire à celle de YAML, utilisant des objets (`{}`) et des tableaux (`[]`). Le document racine est un objet contenant une clé `databaseChangeLog` dont la valeur est un tableau d'objets `changeSet`. Chaque objet `changeSet` contient les paires clé-valeur `id`, `author` et un tableau `changes` décrivant les modifications.

Le JSON est bien structuré et largement supporté. Il peut être légèrement plus verbeux que le YAML en raison de l'utilisation systématique des accolades, des guillemets pour les clés et des virgules, mais reste généralement plus concis que le XML.

Exemple de création de table en JSON :

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "certiquizz",
        "changes": [
          {
            "createTable": {
              "tableName": "utilisateur",
              "columns": [
                {
                  "column": {
                    "name": "id",
                    "type": "BIGINT",
                    "autoIncrement": true,
                    "constraints": {
                      "primaryKey": true,
                      "nullable": false
                    }
                  }
                },
                {
                  "column": {
                    "name": "nom",
                    "type": "VARCHAR(255)",
                    "constraints": {
                      "nullable": false
                    }
                  }
                },
                {
                  "column": {
                    "name": "email",
                    "type": "VARCHAR(255)",
                    "constraints": {
                      "nullable": false,
                      "unique": true
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Le format SQL formaté : le contrôle direct

Pour ceux qui préfèrent écrire directement du SQL, Liquibase propose le format 'SQL formaté'. Il s'agit de fichiers `.sql` standard, mais avec des commentaires spécialement formatés que Liquibase interprète pour identifier les changesets et leurs métadonnées.

Le fichier doit commencer par le commentaire `--liquibase formatted sql`. Chaque changeset est ensuite défini par un commentaire de la forme `--changeset auteur:id [attributs optionnels]`. Le SQL qui suit ce commentaire, jusqu'au prochain commentaire `--changeset` ou la fin du fichier, constitue le corps du changeset.

Ce format donne un contrôle total sur le SQL exécuté et est souvent apprécié par les administrateurs de bases de données (DBA). L'inconvénient est qu'il perd une partie de l'abstraction offerte par les autres formats ; le SQL écrit peut être spécifique au SGBD cible, rendant les migrations moins portables entre différentes bases de données. Il faut aussi gérer manuellement la syntaxe SQL correcte pour chaque opération.

Exemple de création de table en SQL formaté :

--liquibase formatted sql

--changeset certiquizz:1
CREATE TABLE utilisateur (
    id BIGINT AUTO_INCREMENT NOT NULL,
    nom VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    CONSTRAINT PK_UTILISATEUR PRIMARY KEY (id),
    CONSTRAINT UQ_UTILISATEUR_EMAIL UNIQUE (email)
);

--changeset certiquizz:2 comment:"Ajout d'une colonne date_creation"
ALTER TABLE utilisateur ADD COLUMN date_creation TIMESTAMP;

Quel format choisir pour votre projet Spring Boot ?

Le choix du format dépend de plusieurs facteurs :

• Préférences de l'équipe : Optez pour le format avec lequel votre équipe est la plus à l'aise et productive.
• Lisibilité vs Rigueur : YAML et JSON sont souvent considérés comme plus lisibles, tandis que XML offre une validation plus stricte.
• Besoin d'abstraction : XML, YAML et JSON offrent une abstraction par rapport au SQL, facilitant la portabilité entre SGBD. Le SQL formaté donne un contrôle direct mais peut lier davantage à un SGBD spécifique.
• Outillage : Vérifiez la disponibilité et la qualité des outils (validation, autocomplétion dans les IDE) pour chaque format.
• Complexité des migrations : Pour des logiques de migration complexes, les formats structurés (XML, YAML, JSON) peuvent être plus faciles à gérer que le SQL brut.

Il est important de noter que Spring Boot s'intègre de manière transparente avec tous ces formats. La configuration dans `application.properties` ou `application.yml` (par exemple, `spring.liquibase.change-log=classpath:/db/changelog/db.changelog-master.yaml`) indiquera simplement à Liquibase où trouver le fichier maître, quel que soit son format.

La recommandation générale est de choisir un format et de s'y tenir pour assurer la cohérence au sein du projet. YAML est souvent un bon compromis entre lisibilité et structure pour de nombreux projets modernes, mais XML reste une valeur sûre pour sa robustesse, tandis que le SQL formaté peut être idéal si l'équipe possède une forte expertise SQL et cible un SGBD unique.