Migration Guide from Hibernate 6.0 to 6.1

Migrating from Hibernate 6.0 to 6.1 involves several important changes and updates. This guide will walk you through the critical changes, providing detailed steps for a smooth transition.
Key Changes and Migration Steps
Basic Array/Collection Mapping
In Hibernate 6.1, basic arrays (other than byte[]
/Byte[]
and char[]
/Character[]
) and basic collections (only subtypes of Collection
) now map to the SQL type SqlTypes.ARRAY
by default. This change maps to the SQL standard array
type if supported by the database, or falls back to SqlTypes.JSON
, SqlTypes.XML
, or SqlTypes.VARBINARY
based on the database capabilities.
Migration Steps
Rename the Existing Column:
ALTER TABLE tbl RENAME COLUMN array_col TO array_col_old;
Add the New Column:
ALTER TABLE tbl ADD COLUMN array_col DATATYPE array;
Retrieve Existing Data:
SELECT t.primary_key, t.array_col_old FROM table t;
- Deserialize and Reinsert Data: For each result, deserialize the old representation and reinsert it into the new column.
- Drop the Old Column:
ALTER TABLE tbl DROP COLUMN array_col_old;
Alternatively, to revert to pre-6.1 behavior, annotate your array property with @JdbcTypeCode(SqlTypes.VARBINARY)
:
@Basic
@JdbcTypeCode(SqlTypes.VARBINARY)
double[] myArray;
Enum Mapping Changes
Enums now map to the type code SqlType.SMALLINT
by default, replacing the previous TINYINT
. This change corrects the mismatch as Java allows up to 32K enum entries, whereas TINYINT
is limited to 255.
Migration Steps
Alter the Column Type:
ALTER TABLE tbl ALTER COLUMN enum_col SMALLINT;
Depending on your database dialect, the command might differ slightly. Ensure that the schema validation step handles the transition from TINYINT
to SMALLINT
.
Handling Specific Database Dialects
Certain dialects may produce a different schema now due to the change in default types:
- Cachè
- Ingres
- Teradata
- TimesTen
- H2
- HSQL
- MySQL
- MariaDB
- Oracle
Ensure to review and test your schema changes thoroughly on these databases.
Detailed Changes
JDBC Type Code Handling
Hibernate 6.1 introduces a new method for determining preferred SQL types for arrays:
org.hibernate.dialect.Dialect.getPreferredSqlTypeCodeForArray
This method helps the migration to native array or JSON/XML types by determining the best type supported by the database.
Improved Schema Validation
Schema validation now checks for the appropriate use of SqlTypes.ARRAY
and SMALLINT
for enums, ensuring that any discrepancies are highlighted during the migration process.
Updating Entity Mappings
Review and update your entity classes to align with the new type mappings introduced in Hibernate 6.1. Ensure that all annotations reflect the updated type codes where necessary.
Example Entity Update
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import org.hibernate.annotations.JdbcTypeCode;
import org.hibernate.type.SqlTypes;
@Entity
@Table(name = "my_table")
public class MyEntity {
@Id
private Long id;
@Basic
@JdbcTypeCode(SqlTypes.ARRAY)
private double[] myArray;
private String name;
// Getters and setters
}
Conclusion
Migrating to Hibernate 6.1 involves understanding and implementing changes in array/collection mappings, enum type mappings, and adapting to improved schema validation. By following the steps outlined in this guide, you can ensure a smooth and efficient transition to Hibernate 6.1, leveraging the latest features and improvements.
This tutorial was generated using ChatGPT, specifically the Master Spring TER model. For more information, visit Master Spring TER.
For further reading, consider exploring the following resources:
- Hibernate 6.1 Documentation
- Hibernate Migration Guide
- Java Persistence API (JPA) Documentation