Add enums module: enum mapping in Hibernate 7.4.17.Final (ORDINAL trap, STRING, PostgreSQL native enum, AttributeConverter, @EnumeratedValue), what release 2 reads and writes after a constant is inserted, appended or renamed, hbm2ddl=update limits, migrations (H2 2.4.240, PostgreSQL 18.6)

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_017ic4b5y3ArhRbakfu1ELsP
This commit is contained in:
Claude
2026-11-19 23:00:31 +05:30
parent 0db721805b
commit bd0f33a306
22 changed files with 1785 additions and 0 deletions
+43
View File
@@ -0,0 +1,43 @@
# What DDL does each enum mapping produce? (Enum: NEW, PAID, SHIPPED; table orders(id, status))
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== H2
-- no @Enumerated (JPA default)
column type: TINYINT
check: "STATUS" BETWEEN 0 AND 2
-- @Enumerated(ORDINAL)
column type: TINYINT
check: "STATUS" BETWEEN 0 AND 2
-- @Enumerated(STRING)
column type: ENUM
-- @Enumerated(STRING) + @JdbcTypeCode(NAMED_ENUM)
column type: CHARACTER VARYING
-- @Convert(AttributeConverter<Enum,String>)
column type: CHARACTER VARYING
check: "STATUS" IN('P', 'S', 'N')
-- @EnumeratedValue + @Enumerated(STRING)
column type: CHARACTER VARYING
check: "STATUS" IN('P', 'S', 'N')
== PostgreSQL 18
-- no @Enumerated (JPA default)
column type: smallint
check: CHECK (((status >= 0) AND (status <= 2)))
-- @Enumerated(ORDINAL)
column type: smallint
check: CHECK (((status >= 0) AND (status <= 2)))
-- @Enumerated(STRING)
column type: character varying(255)
check: CHECK (((status)::text = ANY ((ARRAY['NEW'::character varying, 'PAID'::character varying, 'SHIPPED'::character varying])::text[])))
-- @Enumerated(STRING) + @JdbcTypeCode(NAMED_ENUM)
column type: statusv1
enum labels: NEW, PAID, SHIPPED
-- @Convert(AttributeConverter<Enum,String>)
column type: character varying(255)
check: CHECK (((status)::text = ANY ((ARRAY['P'::character varying, 'S'::character varying, 'N'::character varying])::text[])))
-- @EnumeratedValue + @Enumerated(STRING)
column type: character varying(255)
check: CHECK (((status)::text = ANY ((ARRAY['P'::character varying, 'S'::character varying, 'N'::character varying])::text[])))
== @EnumeratedValue on a String code, without @Enumerated(STRING)
org.hibernate.MappingException: @EnumeratedValue for EnumType.ORDINAL must be placed on a field whose type is byte, short, or int: com.ankurm.enums.Variants$EvV1.code
+86
View File
@@ -0,0 +1,86 @@
# Release 1 wrote NEW, PAID, SHIPPED. Release 2 changes the enum; hbm2ddl = none
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== H2
-- ORDINAL, CANCELLED inserted in the middle (release 2 enum: NEW, CANCELLED, PAID, SHIPPED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, CANCELLED, PAID]
release 2 writes SHIPPED : FAILS org.hibernate.exception.ConstraintViolationException <- org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException
Check constraint violation: "CONSTRAINT_8: "; SQL statement:
-- ORDINAL, CANCELLED appended (release 2 enum: NEW, PAID, SHIPPED, CANCELLED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException
Check constraint violation: "CONSTRAINT_8: "; SQL statement:
-- ORDINAL, PAID renamed PAYMENT_RECEIVED (release 2 enum: NEW, PAYMENT_RECEIVED, SHIPPED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes PAYMENT_RECEIVED : OK, stored [1]
-- STRING, CANCELLED inserted in the middle (release 2 enum: NEW, CANCELLED, PAID, SHIPPED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.DataException <- org.h2.jdbc.JdbcSQLDataException
Value not permitted for column "('NEW', 'PAID', 'SHIPPED')": "CANCELLED"; SQL statement:
-- STRING, CANCELLED appended (release 2 enum: NEW, PAID, SHIPPED, CANCELLED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.DataException <- org.h2.jdbc.JdbcSQLDataException
Value not permitted for column "('NEW', 'PAID', 'SHIPPED')": "CANCELLED"; SQL statement:
-- STRING, PAID renamed PAYMENT_RECEIVED (release 2 enum: NEW, PAYMENT_RECEIVED, SHIPPED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : FAILS java.lang.IllegalArgumentException
No enum constant com.ankurm.enums.Variants.StatusRen.PAID
release 2 writes PAYMENT_RECEIVED : FAILS org.hibernate.exception.DataException <- org.h2.jdbc.JdbcSQLDataException
Value not permitted for column "('NEW', 'PAID', 'SHIPPED')": "PAYMENT_RECEIVED"; SQL statement:
-- CONVERTER (codes N/P/S), CANCELLED inserted + PAID renamed (release 2 enum: NEW, CANCELLED(C), PAYMENT_RECEIVED(P), SHIPPED)
stored by release 1 : [1 | N, 2 | P, 3 | S]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException
Check constraint violation: "CONSTRAINT_8: "; SQL statement:
-- @EnumeratedValue (codes N/P/S), CANCELLED inserted + PAID renamed (release 2 enum: NEW, CANCELLED(C), PAYMENT_RECEIVED(P), SHIPPED)
stored by release 1 : [1 | N, 2 | P, 3 | S]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException
Check constraint violation: "CONSTRAINT_8: "; SQL statement:
== PostgreSQL 18
-- ORDINAL, CANCELLED inserted in the middle (release 2 enum: NEW, CANCELLED, PAID, SHIPPED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, CANCELLED, PAID]
release 2 writes SHIPPED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- ORDINAL, CANCELLED appended (release 2 enum: NEW, PAID, SHIPPED, CANCELLED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- ORDINAL, PAID renamed PAYMENT_RECEIVED (release 2 enum: NEW, PAYMENT_RECEIVED, SHIPPED)
stored by release 1 : [1 | 0, 2 | 1, 3 | 2]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes PAYMENT_RECEIVED : OK, stored [1]
-- STRING, CANCELLED inserted in the middle (release 2 enum: NEW, CANCELLED, PAID, SHIPPED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- STRING, CANCELLED appended (release 2 enum: NEW, PAID, SHIPPED, CANCELLED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- STRING, PAID renamed PAYMENT_RECEIVED (release 2 enum: NEW, PAYMENT_RECEIVED, SHIPPED)
stored by release 1 : [1 | NEW, 2 | PAID, 3 | SHIPPED]
release 2 reads : FAILS java.lang.IllegalArgumentException
No enum constant com.ankurm.enums.Variants.StatusRen.PAID
release 2 writes PAYMENT_RECEIVED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- CONVERTER (codes N/P/S), CANCELLED inserted + PAID renamed (release 2 enum: NEW, CANCELLED(C), PAYMENT_RECEIVED(P), SHIPPED)
stored by release 1 : [1 | N, 2 | P, 3 | S]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- @EnumeratedValue (codes N/P/S), CANCELLED inserted + PAID renamed (release 2 enum: NEW, CANCELLED(C), PAYMENT_RECEIVED(P), SHIPPED)
stored by release 1 : [1 | N, 2 | P, 3 | S]
release 2 reads : [NEW, PAYMENT_RECEIVED, SHIPPED]
release 2 writes CANCELLED : FAILS org.hibernate.exception.ConstraintViolationException <- org.postgresql.util.PSQLException
ERROR: new row for relation "orders" violates check constraint "orders_status_check"
+21
View File
@@ -0,0 +1,21 @@
# PostgreSQL native enum (CREATE TYPE ... AS ENUM): ordering, ALTER TYPE, and what cannot be undone
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== Ordering. Enum declared as NEW, PAID, SHIPPED, CANCELLED (the order a workflow would use)
-- type created by Hibernate (hbm2ddl = create)
enum labels in sort order: [CANCELLED, NEW, PAID, SHIPPED]
order by status : [CANCELLED, NEW, PAID, SHIPPED]
-- type written by hand, labels in workflow order
order by status : [NEW, PAID, SHIPPED, CANCELLED]
== Release 2 needs CANCELLED, but the database type was created from release 1's NEW, PAID, SHIPPED
write CANCELLED before ALTER TYPE : org.hibernate.exception.DataException <- org.postgresql.util.PSQLException
ERROR: invalid input value for enum statusv1: "CANCELLED"
after ALTER TYPE statusv1 ADD VALUE 'CANCELLED' : OK, rows [1 | PAID, 10 | CANCELLED]
labels now (appended at the end): [NEW, PAID, SHIPPED, CANCELLED]
ADD VALUE 'ON_HOLD' BEFORE 'PAID' : labels [NEW, ON_HOLD, PAID, SHIPPED, CANCELLED]
RENAME VALUE 'PAID' TO 'PAYMENT_RECEIVED' : row 1 is now [PAYMENT_RECEIVED]
ALTER TYPE ... DROP VALUE : ERROR: dropping an enum value is not implemented
== ADD VALUE inside a transaction: usable only after commit
ADD VALUE then INSERT using it in ONE transaction : ERROR: unsafe use of new value "CANCELLED" of enum type statusv1
+15
View File
@@ -0,0 +1,15 @@
# hibernate.type.prefer_native_enum_types on plain @Enumerated(STRING)
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== H2
-- prefer_native_enum_types=false
column type: ENUM
-- prefer_native_enum_types=true
column type: ENUM
== PostgreSQL 18
-- prefer_native_enum_types=false
column type: character varying(255)
check: CHECK (((status)::text = ANY ((ARRAY['NEW'::character varying, 'PAID'::character varying, 'SHIPPED'::character varying])::text[])))
-- prefer_native_enum_types=true
column type: statusv1
+24
View File
@@ -0,0 +1,24 @@
# Adding CANCELLED, then starting release 2 with hbm2ddl=update: is the schema fixed?
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== H2
-- ORDINAL
after update: column type: TINYINT
after update: check: "STATUS" BETWEEN 0 AND 2
write CANCELLED : FAILS Check constraint violation: "CONSTRAINT_8: "; SQL statement:
-- STRING
after update: column type: ENUM
write CANCELLED : FAILS Value not permitted for column "('NEW', 'PAID', 'SHIPPED')": "CANCELLED"; SQL statement:
== PostgreSQL 18
-- ORDINAL
after update: column type: smallint
after update: check: CHECK (((status >= 0) AND (status <= 2)))
write CANCELLED : FAILS ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- STRING
after update: column type: character varying(255)
after update: check: CHECK (((status)::text = ANY ((ARRAY['NEW'::character varying, 'PAID'::character varying, 'SHIPPED'::character varying])::text[])))
write CANCELLED : FAILS ERROR: new row for relation "orders" violates check constraint "orders_status_check"
-- NAMED_ENUM
after update: column type: statusv1
write CANCELLED : FAILS ERROR: invalid input value for enum statusv1: "CANCELLED"
+21
View File
@@ -0,0 +1,21 @@
# The migration each enum change needs (PostgreSQL 18), and release 2 afterwards
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== ORDINAL: insert CANCELLED between NEW and PAID
migration : drop check; UPDATE orders SET status = status + 1 WHERE status >= 1; add check (status between 0 and 3)
stored : [1 | 0, 2 | 2, 3 | 3]
release 2 reads : [NEW, PAID, SHIPPED]
release 2 writes CANCELLED : OK, stored [1]
== STRING: append CANCELLED
migration : drop check; add check (status in ('NEW', 'PAID', 'SHIPPED', 'CANCELLED'))
release 2 writes CANCELLED : OK, rows [1 | PAID, 10 | CANCELLED]
== STRING: rename PAID to PAYMENT_RECEIVED
migration : drop check; UPDATE ... SET status = 'PAYMENT_RECEIVED' WHERE status = 'PAID'; add check
release 2 reads : [NEW, PAYMENT_RECEIVED]
== CONVERTER or @EnumeratedValue: insert CANCELLED and rename PAID (codes unchanged)
migration : drop check; add check (status in ('N', 'C', 'P', 'S')); no UPDATE, no data touched
release 2 reads : [PAYMENT_RECEIVED]
release 2 writes CANCELLED : OK, stored [C]
+26
View File
@@ -0,0 +1,26 @@
# HQL on enum attributes: SQL sent, ORDER BY, and a bad value in the column (PostgreSQL 18)
# Hibernate ORM 7.4.17.Final, H2 2.4.240 and PostgreSQL 18.6, JDK 25
== The SQL Hibernate sends for from X o where o.status = :s (parameter = PAID / PAYMENT_RECEIVED)
-- ORDINAL
sql> select ov1_0.id,ov1_0.status from orders ov1_0 where ov1_0.status=?
-- STRING
sql> select sv1_0.id,sv1_0.status from orders sv1_0 where sv1_0.status=?
-- NAMED_ENUM
sql> select nv1_0.id,nv1_0.status from orders nv1_0 where nv1_0.status=?
-- CONVERTER
sql> select cv1_0.id,cv1_0.status from orders cv1_0 where cv1_0.status=?
-- CONVERTER, enum literal in the HQL text
sql> select cv1_0.id,cv1_0.status from orders cv1_0 where cv1_0.status='P'
== ORDER BY status on NEW, SHIPPED, CANCELLED, PAID stored under each mapping
ORDINAL (enum NEW, PAID, SHIPPED, CANCELLED) : [NEW, PAID, SHIPPED, CANCELLED]
STRING : [CANCELLED, NEW, PAID, SHIPPED]
CONVERTER (codes C, N, P, S, stored values) : [C, N, P, S]
== A value the enum does not know, in the column
insert 'X' with Hibernate's generated check in place : ERROR: new row for relation "orders" violates check constraint "orders_status_check"
read after the check is dropped and 'X' is inserted : jakarta.persistence.PersistenceException <- java.lang.IllegalArgumentException
Unknown CodedV1 code 'X'
ORDINAL with the check dropped and ordinal 7 stored : java.lang.ArrayIndexOutOfBoundsException
Index 7 out of bounds for length 3