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