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:
@@ -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
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"
|
||||
@@ -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]
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user