Hibernate Envers — audit et historisation des entités JPA

1📖 Glossaire — le vocabulaire de base

• Révision — numéro global, créé une fois par transaction qui modifie au moins une entité auditée.
• REVINFO — table qui liste les révisions : numéro, timestamp, et métadonnées custom éventuelles.
• Table d'audit (_AUD) — copie de la table métier : mêmes colonnes auditées + REV + REVTYPE, avec (id, rev) en clé primaire.
• REVTYPE — type de l'opération : 0 = ADD (insert), 1 = MOD (update), 2 = DEL (delete).
• Revision entity — entité JPA qui mappe REVINFO. On peut la remplacer pour ajouter des colonnes (modified_by, etc.).
• Audit strategy — façon dont Envers écrit et lit l'historique : DefaultAuditStrategy ou ValidityAuditStrategy.

2Mise en place sur un projet Spring Boot

Il faut deux dépendances. Depuis Spring Data 3.0, Spring Data Envers fait partie de Spring Data JPA : @EnableEnversRepositories et RevisionRepository sont donc déjà fournis. Il reste à ajouter le module Hibernate :

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-envers</artifactId> <!-- ✓ version gérée par le BOM Boot -->
</dependency>

On annote ensuite l'entité. @Audited sur la classe audite tous les champs. @NotAudited exclut un champ.

@Entity
@Audited
public class Product {

    @Id @GeneratedValue
    private Long id;

    private String name;

    private BigDecimal price;

    @NotAudited                      // ✓ pas copié dans l'audit
    private String internalNote;
}

Envers génère deux tables :

create table revinfo (
    rev      integer generated by default as identity primary key,
    revtstmp bigint                  -- date de la révision (epoch millis)
);

create table product_aud (
    id      bigint  not null,
    rev     integer not null references revinfo(rev),
    revtype smallint,                -- 0 = ADD, 1 = MOD, 2 = DEL
    name    varchar(255),
    price   numeric(38,2),
    primary key (id, rev)            -- ⚠️ pas de colonne internal_note
);

• revinfo : la liste des révisions, une ligne par transaction.
• product_aud : une ligne par version du produit, rattachée à sa révision.

Les réglages passent par les propriétés Hibernate (préfixe spring.jpa.properties. dans Boot) :

spring:
  jpa:
    properties:
      org.hibernate.envers.audit_table_suffix: _aud        # défaut _AUD
      org.hibernate.envers.revision_field_name: rev
      org.hibernate.envers.revision_type_field_name: revtype
      org.hibernate.envers.store_data_at_delete: true      # copie complète au DELETE
      org.hibernate.envers.global_with_modified_flag: true # colonnes *_mod (bool par champ)

3Sous le capot : une révision par transaction

Envers écoute les événements Hibernate (post-insert, post-update, post-delete). Au premier événement de la transaction, il insère une ligne dans revinfo. Ensuite, chaque entité modifiée ajoute sa copie dans sa table _aud, avec ce numéro de révision. Tout est écrit dans la même transaction JDBC.

sequenceDiagram
    participant S as ProductService
    participant H as Hibernate (Session)
    participant E as Envers (listeners)
    participant DB as PostgreSQL

    S->>H: update produit A + insert produit B
    S->>H: commit (flush)
    H->>DB: UPDATE product A / INSERT product B
    H->>E: événements post-update / post-insert
    E->>DB: INSERT revinfo (rev 42, une seule fois)
    E->>DB: INSERT product_aud (A, rev 42, revtype 1)
    E->>DB: INSERT product_aud (B, rev 42, revtype 0)
    DB-->>S: COMMIT
    Note over DB: métier + audit dans la même transaction :<br/>rollback métier = rollback audit

Exemple concret. Trois transactions sur le même produit : création, changement de prix, suppression. Voici ce que contiennent les tables :

-- revinfo
rev | revtstmp
 40 | 1755600000000
 41 | 1755600300000
 42 | 1755600600000

-- product_aud
id | rev | revtype | name        | price
 7 |  40 |    0    | Perceuse    | 89.90     -- ADD
 7 |  41 |    1    | Perceuse    | 79.90     -- MOD (baisse de prix)
 7 |  42 |    2    | Perceuse    | 79.90     -- DEL (avec store_data_at_delete)

4Révision custom : stocker « qui »

Par défaut, revinfo contient juste le numéro et le timestamp. Pour savoir qui a fait le changement, il faut deux choses : une revision entity custom (qui ajoute la colonne) et un RevisionListener (qui la remplit à chaque révision).

@Entity
@Table(name = "revinfo")
@RevisionEntity(UserRevisionListener.class)
public class UserRevisionEntity extends DefaultRevisionEntity {

    @Column(name = "modified_by")
    private String modifiedBy;

    // getters / setters
}

public class UserRevisionListener implements RevisionListener {

    @Override
    public void newRevision(Object revisionEntity) {
        var rev = (UserRevisionEntity) revisionEntity;
        // ⚠️ instancié par Envers, pas par Spring : pas d'injection possible
        rev.setModifiedBy(CurrentUserHolder.get());   // ThreadLocal, SecurityContext...
    }
}

Attention : ce listener est créé par Envers, pas par Spring. On ne peut pas y injecter de bean. La solution habituelle : lire un ThreadLocal ou le SecurityContextHolder, accessibles en statique.

Le schéma final ressemble à ça :

erDiagram
    PRODUCT {
        bigint id PK
        varchar name
        numeric price
        varchar internal_note "NotAudited"
    }
    REVINFO {
        int rev PK
        bigint revtstmp
        varchar modified_by "custom"
    }
    PRODUCT_AUD {
        bigint id PK
        int rev PK
        smallint revtype "0 ADD / 1 MOD / 2 DEL"
        varchar name
        numeric price
    }
    PRODUCT_AUD }o--|| REVINFO : "rev FK"
    PRODUCT ||..o{ PRODUCT_AUD : "versions"

5Lire l'historique

Deux APIs, selon le besoin.

AuditReader (API Envers native)

AuditReader reader = AuditReaderFactory.get(entityManager);

// État du produit 7 à la révision 41
Product atRev41 = reader.find(Product.class, 7L, 41);

// État du produit 7 à une date donnée
Number rev = reader.getRevisionNumberForDate(
        LocalDate.of(2026, 6, 1).atStartOfDay(ZoneOffset.UTC).toInstant());
Product atDate = reader.find(Product.class, 7L, rev);

// Historique complet, suppressions incluses
List<Object[]> history = reader.createQuery()
        .forRevisionsOfEntity(Product.class, false, true)  // ✓ true = inclure les DEL
        .add(AuditEntity.id().eq(7L))
        .addOrder(AuditEntity.revisionNumber().asc())
        .getResultList();

for (Object[] row : history) {
    Product snapshot           = (Product) row[0];
    UserRevisionEntity revInfo = (UserRevisionEntity) row[1];
    RevisionType type          = (RevisionType) row[2];   // ADD / MOD / DEL
}

// Avec les modified flags : révisions qui ont changé le prix
List<?> priceChanges = reader.createQuery()
        .forRevisionsOfEntity(Product.class, false, true)
        .add(AuditEntity.id().eq(7L))
        .add(AuditEntity.property("price").hasChanged())
        .getResultList();

forRevisionsOfEntity retourne des triplets : la copie de l'entité, la révision (avec modifiedBy si custom), et le type d'opération.

RevisionRepository (Spring Data)

@SpringBootApplication
@EnableEnversRepositories
public class ShopApplication { }

public interface ProductRepository
        extends JpaRepository<Product, Long>,
                RevisionRepository<Product, Long, Integer> {  // entité, id, type de rev
}

Revisions<Integer, Product> revisions = productRepository.findRevisions(7L);

revisions.forEach(r -> log.info("rev {} ({}) : {}",
        r.getRequiredRevisionNumber(),
        r.getMetadata().getRevisionType(),   // INSERT / UPDATE / DELETE
        r.getEntity()));

Optional<Revision<Integer, Product>> last =
        productRepository.findLastChangeRevision(7L);

RevisionRepository suffit pour les cas simples : historique d'un id, dernière révision. Pour filtrer par champ ou croiser des entités, il faut AuditReader.

6Stratégies d'audit : Default vs Validity

Reprenons le produit 7 de la section 3. Trois versions : rev 40 (création à 89.90), rev 41 (prix baissé à 79.90), rev 42 (suppression). La question à laquelle les deux stratégies répondent différemment : « quel était l'état du produit 7 à la révision 41 ? »

Avec DefaultAuditStrategy (le défaut), la table ne stocke que la révision de début de chaque version :

-- product_aud (Default)
id | rev | revtype | price
 7 |  40 |    0    | 89.90
 7 |  41 |    1    | 79.90
 7 |  42 |    2    | 79.90

Aucune ligne ne dit jusqu'à quand elle est valable. Pour trouver la bonne, la requête doit calculer « la plus grande révision ≤ 41 » :

select *
from product_aud a
where a.id = 7
  and a.rev = (select max(b.rev)          -- ⚠️ sous-select
               from product_aud b
               where b.id = 7 and b.rev <= 41);

Ce sous-select tourne pour chaque entité lue. Pour un produit, ça va. Pour reconstituer l'état de 500 produits sur une table d'audit de plusieurs millions de lignes, c'est lent.

Avec ValidityAuditStrategy, chaque ligne stocke aussi sa révision de fin (revend) :

-- product_aud (Validity)
id | rev | revend | revtype | price
 7 |  40 |   41   |    0    | 89.90    -- valable de la rev 40 à la rev 41 (exclue)
 7 |  41 |   42   |    1    | 79.90    -- valable de la rev 41 à la rev 42 (exclue)
 7 |  42 |  null  |    2    | 79.90    -- dernière version

La ligne dit elle-même quand elle cesse d'être valable. La requête devient un filtre direct :

select *
from product_aud
where id = 7
  and rev <= 41
  and (revend > 41 or revend is null);   -- ✓ pas de sous-select

Le prix à payer se voit à l'écriture. Au moment d'écrire la rev 41, Envers fait deux choses : un INSERT pour la nouvelle ligne, et un UPDATE sur la ligne rev 40 pour poser revend = 41. Chaque écriture coûte donc deux opérations, et l'historique est modifié après coup.

En résumé : Default stocke seulement le début, donc la lecture doit recalculer la fin à chaque fois. Validity paie ce calcul au moment de l'écriture pour que la lecture soit directe.

Activation :

org.hibernate.envers.audit_strategy: >
  org.hibernate.envers.strategy.internal.ValidityAuditStrategy
org.hibernate.envers.audit_strategy_validity_store_revend_timestamp: true

Quand le choisir : Validity si l'historique est lu souvent (écran « versions », reporting) ou très gros. Default si l'audit est surtout écrit et rarement lu. Le choix se fait avant la mise en prod : en changer ensuite demande un recalcul manuel des revend.

7Relations et collections

Règle de base : une relation auditée doit pointer vers une entité auditée. Sinon Envers refuse de démarrer (MappingException). Quand la cible n'a pas besoin d'historique, on audite seulement la FK :

@Entity
@Audited
public class Product {

    @ManyToOne
    @Audited(targetAuditMode = RelationTargetAuditMode.NOT_AUDITED) // ✓ FK auditée, cible non
    private Category category;

    @OneToMany(mappedBy = "product")
    @NotAudited                          // ✓ à historiser côté Review si besoin
    private List<Review> reviews;
}

Pour les collections (@OneToMany et @ManyToMany avec table de jointure), Envers crée aussi une table d'audit pour la jointure (product_tags_aud). Chaque ajout ou retrait dans la collection y est enregistré.

Conséquence : auditer une classe entière peut créer beaucoup de tables et de volume. Mieux vaut décider champ par champ ce qui est audité, avec @NotAudited sur le reste.

8Pièges de prod

DDL par migration, jamais ddl-auto. En prod, le schéma est géré par Flyway ou Liquibase. Les tables _aud et revinfo font partie des migrations. À chaque évolution d'une entité auditée, il faut deux ALTER : un sur la table normale, un sur la table _aud. Si on oublie le deuxième, les écritures échouent au premier flush.

Volumétrie. Chaque update stocke une copie complète de la ligne, pas seulement les champs modifiés. Une table souvent modifiée produit donc une table _aud bien plus grosse que la table de départ. À prévoir dès le début : une politique de purge ou d'archivage (on peut supprimer par plage de rev sans rien casser), du partitionnement si le volume est très gros, et des index en plus de la PK (id, rev) si on requête par date ou par auteur.

Performance d'écriture. L'audit ajoute des écritures à chaque transaction : les copies _aud plus la ligne revinfo. Une transaction écrit environ deux fois plus. C'est le prix pour avoir l'audit dans la même transaction que le métier. Si ce coût est trop élevé sur un chemin critique, le CDC est l'alternative : la capture devient asynchrone et ne ralentit plus l'écriture.

9Tableau de synthèse : Envers face aux alternatives

Envers est le bon choix par défaut quand toutes les écritures passent par l'ORM et qu'on veut un historique requêtable avec le contexte applicatif (qui, quand). Le CDC est le bon choix quand il faut capturer toutes les écritures, y compris hors ORM, ou alimenter d'autres systèmes (voir pattern-outbox-publication-fiable-de-messages-depuis-une-transaction-db pour le volet publication). Les deux peuvent coexister : Envers pour l'audit métier, CDC pour la réplication technique.

Sources

• Hibernate User Guide — Envers — référence officielle : annotations, propriétés, stratégies, requêtes.
• Spring Data JPA — Envers — configuration @EnableEnversRepositories et RevisionRepository depuis la fusion dans Spring Data JPA 3.0.
• Spring Data Envers (projet archivé) — note de fusion dans Spring Data JPA à partir de la version 3.0.