fix(entity): make @Version column nullable so hbm2ddl=update can add it to populated tables

BaseEntity.version was a primitive int -> NOT NULL column. Adopting BaseEntity/LongIdEntity/
UuidEntity/StringIdEntity on an existing populated table made hbm2ddl=update emit
"add column version integer not null", which fails the H2/MySQL table rebuild on existing rows
(logged as a WARNING and swallowed, leaving the column missing and later writes broken).

- version is now Integer (nullable column), defaulted to 0 so a freshly constructed detached
  entity still carries version 0 and merges cleanly (createOrUpdate path).
- public int getVersion() unchanged and null-safe (legacy rows read as 0); toString via getter.
- @Version on Integer is permitted by the JPA spec; no @column(nullable=false)/columnDefinition.
- Audited: LongIdEntity/UuidEntity/StringIdEntity don't shadow version. JEHibernateRevisionEntity
  keeps int id / long timestamp (dedicated Envers table created whole, PK/timestamp correctly
  non-null) — flagged, not changed.
- VersionMigrationTest: update adds nullable column to a populated table, existing rows read 0,
  fresh schema starts at 0, optimistic locking still throws, stricter NOT NULL column still works.

Bump to 4.0.1.

Author: JExcellence

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to JEHibernate are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.1] — 2026-08-06
+
+### Fixed
+
+- **fix(entity): make @Version column nullable so hbm2ddl=update can add it to populated tables.**
+  `BaseEntity.version` was a primitive `int`, which maps to a `NOT NULL` column. When a consumer
+  adopted `BaseEntity`/`LongIdEntity`/`UuidEntity`/`StringIdEntity` on an existing table with rows,
+  `hbm2ddl.auto=update` emitted `add column version integer not null`, which fails the H2/MySQL table
+  rebuild on the existing rows (Hibernate logged it as a WARNING and continued, leaving the column
+  missing and later inserts/updates broken). The field is now `Integer` (nullable column) defaulted
+  to `0`; the public accessor stays `int getVersion()` and is null-safe (rows predating the column
+  read as `0`). No API change. `@Version` on `Integer` is permitted by the JPA spec. Optimistic
+  locking, fresh-schema creation, and pre-existing stricter (`NOT NULL DEFAULT 0`) columns are
+  unaffected — covered by `VersionMigrationTest`.
+
 ## [4.0.0] — 2026-06-02
 
 Major release. The library is now a **multi-module build** and the connection-pool and

build.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 
 allprojects {
     group = "de.jexcellence.hibernate"
-    version = "4.0.0"
+    version = "4.0.1"
 }
 
 // ── Shared configuration for every JEHibernate module ───────────────────────

jehibernate-core/src/main/java/de/jexcellence/jehibernate/entity/base/BaseEntity.java

@@ -87,9 +87,23 @@ public abstract class BaseEntity<I> implements Identifiable<I>, Serializable {
      */
     private final transient UUID identityToken = UUID.randomUUID();
 
+    /**
+     * Optimistic-locking version. Nullable ({@code Integer}, not {@code int}) so that
+     * {@code hbm2ddl.auto=update} can add this column to an already-populated table: a primitive
+     * {@code int} maps to {@code NOT NULL}, which H2/MySQL/MariaDB/PostgreSQL cannot satisfy for the
+     * existing rows during the table rebuild. Hibernate assigns {@code 0} on persist, so {@code null}
+     * only ever appears on rows that predate the column. {@code @Version} on {@code Integer} is
+     * permitted by the JPA spec.
+     * <p>
+     * Defaulted to {@code 0} (not left {@code null}) so a freshly constructed, detached entity —
+     * e.g. {@code new X(); x.setId(existingId)} passed to {@code createOrUpdate}/{@code merge} —
+     * carries version {@code 0} and matches an existing row's {@code where … and version=0}. The
+     * default does not affect column nullability (the {@code Integer} type does); rows loaded from
+     * the DB with a {@code null} version overwrite this default and read as {@code 0} via the getter.
+     */
     @Version
-    private int version;
-    
+    private Integer version = 0;
+
     @CreationTimestamp
     @Column(updatable = false)
     private Instant createdAt;
@@ -116,10 +130,16 @@ protected void onPreUpdate() {
         updatedAt = Instant.now();
     }
 
+    /**
+     * Returns the optimistic-locking version. Null-safe: rows that predate the version column
+     * (added later via {@code hbm2ddl.auto=update}) read as {@code 0}.
+     *
+     * @return the version, or {@code 0} if not yet set
+     */
     public int getVersion() {
-        return version;
+        return version == null ? 0 : version;
     }
-    
+
     protected void setVersion(int version) {
         this.version = version;
     }
@@ -162,7 +182,7 @@ public int hashCode() {
     public String toString() {
         return getClass().getSimpleName() + "{" +
             "id=" + getId() +
-            ", version=" + version +
+            ", version=" + getVersion() +
             ", createdAt=" + createdAt +
             ", updatedAt=" + updatedAt +
             '}';

jehibernate-core/src/test/java/de/jexcellence/versiontest/VersionMigrationTest.java

@@ -0,0 +1,171 @@
+package de.jexcellence.versiontest;
+
+import de.jexcellence.jehibernate.config.DatabaseType;
+import de.jexcellence.jehibernate.core.JEHibernate;
+import de.jexcellence.jehibernate.migration.MigrationConfig;
+import de.jexcellence.jehibernate.migration.MigrationTool;
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.OptimisticLockException;
+import jakarta.persistence.RollbackException;
+import org.junit.jupiter.api.Test;
+
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.util.function.Consumer;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Verifies that the {@code @Version} column is nullable so {@code hbm2ddl.auto=update} can add it to
+ * an already-populated table (the primitive {@code int} → {@code NOT NULL} DDL would otherwise fail
+ * the H2 table rebuild), while optimistic locking and fresh-schema creation keep working.
+ * <p>
+ * Isolated package so {@code VersionedThing} does not leak into other suites' package scans.
+ */
+class VersionMigrationTest {
+
+    private static final MigrationConfig MIGRATION_OFF =
+        new MigrationConfig(false, MigrationTool.NONE, "classpath:db/migration");
+
+    private static JEHibernate build(String url, String ddlAuto) {
+        return JEHibernate.builder()
+            .configuration(config -> config
+                .database(DatabaseType.H2)
+                .url(url)
+                .credentials("sa", "")
+                .ddlAuto(ddlAuto)
+                .migration(MIGRATION_OFF))
+            .scanPackages("de.jexcellence.versiontest")
+            .build();
+    }
+
+    private static void jdbc(String url, Consumer<Statement> work) {
+        try (Connection connection = DriverManager.getConnection(url, "sa", "");
+             Statement statement = connection.createStatement()) {
+            work.accept(statement);
+        } catch (SQLException e) {
+            throw new IllegalStateException(e);
+        }
+    }
+
+    private static String isNullable(String url, String table, String column) {
+        try (Connection connection = DriverManager.getConnection(url, "sa", "");
+             Statement statement = connection.createStatement();
+             ResultSet rs = statement.executeQuery(
+                 "SELECT IS_NULLABLE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME='"
+                     + table + "' AND COLUMN_NAME='" + column + "'")) {
+            return rs.next() ? rs.getString(1) : null;
+        } catch (SQLException e) {
+            throw new IllegalStateException(e);
+        }
+    }
+
+    @Test
+    void updateAddsNullableVersionColumnToPopulatedTable() {
+        String url = "jdbc:h2:mem:versionmig;DB_CLOSE_DELAY=-1";
+
+        // A pre-existing, populated table WITHOUT the version column (as an older schema would have).
+        jdbc(url, s -> {
+            try {
+                s.execute("CREATE TABLE versioned_thing ("
+                    + "id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))");
+                s.execute("INSERT INTO versioned_thing (name) VALUES ('alice')");
+                s.execute("INSERT INTO versioned_thing (name) VALUES ('bob')");
+            } catch (SQLException e) {
+                throw new IllegalStateException(e);
+            }
+        });
+
+        try (JEHibernate jeHibernate = build(url, "update")) {
+            var repo = jeHibernate.repositories().get(VersionedThingRepository.class);
+
+            // The ALTER succeeded (no silent DDL warning), the two existing rows survived, and they
+            // read version 0 (the DB value is null; the null-safe getter returns 0).
+            var all = repo.findAll();
+            assertThat(all).hasSize(2);
+            assertThat(all).allMatch(t -> t.getVersion() == 0);
+
+            // The column exists and is nullable.
+            assertThat(isNullable(url, "VERSIONED_THING", "VERSION")).isEqualTo("YES");
+        }
+    }
+
+    @Test
+    void freshSchemaCreatesNullableVersionStartingAtZero() {
+        String url = "jdbc:h2:mem:versionfresh;DB_CLOSE_DELAY=-1";
+
+        try (JEHibernate jeHibernate = build(url, "create-drop")) {
+            var repo = jeHibernate.repositories().get(VersionedThingRepository.class);
+
+            VersionedThing saved = repo.create(new VersionedThing("fresh"));
+            assertThat(saved.getVersion()).isZero();                 // first persist starts at 0
+            assertThat(isNullable(url, "VERSIONED_THING", "VERSION")).isEqualTo("YES");
+        }
+    }
+
+    @Test
+    void optimisticLockingStillWorks() {
+        String url = "jdbc:h2:mem:versionlock;DB_CLOSE_DELAY=-1";
+
+        try (JEHibernate jeHibernate = build(url, "create-drop")) {
+            var repo = jeHibernate.repositories().get(VersionedThingRepository.class);
+            Long id = repo.create(new VersionedThing("x")).getId();
+
+            EntityManagerFactory emf = jeHibernate.getEntityManagerFactory();
+            EntityManager em1 = emf.createEntityManager();
+            EntityManager em2 = emf.createEntityManager();
+            try {
+                VersionedThing v1 = em1.find(VersionedThing.class, id);
+                VersionedThing v2 = em2.find(VersionedThing.class, id);
+
+                em1.getTransaction().begin();
+                v1.setName("one");
+                em1.getTransaction().commit();                       // version 0 -> 1
+
+                em2.getTransaction().begin();
+                v2.setName("two");                                   // still holds version 0
+                // The stale update matches 0 rows via "where id=? and version=?" and fails. Hibernate
+                // may surface this as OptimisticLockException directly or wrapped in RollbackException.
+                assertThatThrownBy(() -> em2.getTransaction().commit())
+                    .isInstanceOfAny(OptimisticLockException.class, RollbackException.class);
+            } finally {
+                em1.close();
+                em2.close();
+            }
+
+            assertThat(repo.findById(id)).get().extracting(VersionedThing::getVersion).isEqualTo(1);
+        }
+    }
+
+    @Test
+    void stricterExistingNotNullVersionColumnStillWorks() {
+        String url = "jdbc:h2:mem:versionstrict;DB_CLOSE_DELAY=-1";
+
+        // A DB where the column already exists as NOT NULL DEFAULT 0 — Hibernate never writes null on
+        // persist, so a stricter existing column is harmless.
+        jdbc(url, s -> {
+            try {
+                s.execute("CREATE TABLE versioned_thing ("
+                    + "id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255), "
+                    + "version INTEGER NOT NULL DEFAULT 0, created_at TIMESTAMP, updated_at TIMESTAMP)");
+                s.execute("INSERT INTO versioned_thing (name) VALUES ('legacy')");
+            } catch (SQLException e) {
+                throw new IllegalStateException(e);
+            }
+        });
+
+        try (JEHibernate jeHibernate = build(url, "update")) {
+            var repo = jeHibernate.repositories().get(VersionedThingRepository.class);
+            assertThat(repo.count()).isEqualTo(1);
+
+            VersionedThing created = repo.create(new VersionedThing("new"));
+            assertThat(created.getVersion()).isZero();
+            assertThat(repo.count()).isEqualTo(2);
+        }
+    }
+}

jehibernate-core/src/test/java/de/jexcellence/versiontest/VersionedThing.java

@@ -0,0 +1,36 @@
+package de.jexcellence.versiontest;
+
+import de.jexcellence.jehibernate.entity.base.LongIdEntity;
+import de.jexcellence.jehibernate.repository.base.AbstractCrudRepository;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EntityManagerFactory;
+import jakarta.persistence.Table;
+
+import java.util.concurrent.ExecutorService;
+
+@Entity
+@Table(name = "versioned_thing")
+public class VersionedThing extends LongIdEntity {
+
+    private String name;
+
+    protected VersionedThing() {}
+
+    public VersionedThing(String name) {
+        this.name = name;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+}
+
+class VersionedThingRepository extends AbstractCrudRepository<VersionedThing, Long> {
+    VersionedThingRepository(ExecutorService executor, EntityManagerFactory emf, Class<VersionedThing> entityClass) {
+        super(executor, emf, entityClass);
+    }
+}