SpringBoot升级3.1.4后Hibernate枚举映射Integer列验证失败

问题描述 #

我原本运行SpringBoot v2.x版本，升级至3.1.4并更新所有依赖后，应用启动时出现Schema验证失败的问题。

实体类中原本将PostgreSQL数据库里integer类型的status列映射为枚举类型StatusEnum，代码如下：

@Column(name = "status") 
var status: StatusEnum,

在SpringBoot 2.x中该映射完全正常，但升级到3.x后启动报错：

nested exception is org.hibernate.tool.schema.spi.SchemaManagementException: Schema-validation: wrong column type encountered in column [status] in table [xxx]; found [int4 (Types#INTEGER)], but expecting [smallint (Types#TINYINT)]

尝试通过columnDefinition强制指定列类型，修改后的代码：

@Column(name = "status", columnDefinition = "INTEGER") 
var status: StatusEnum,

但仍然报错：

Schema-validation: wrong column type encountered in column [status] in table [xxx]; found [int4 (Types#INTEGER)], but expecting [integer (Types#TINYINT)]

试过将columnDefinition设置为integer、int4、int2等值，都无法解决问题，难道必须修改数据库列类型？当前application.yml中设置的Hibernate方言为org.hibernate.dialect.PostgreSQLDialect。

解决方案 #

1. 显式指定枚举映射类型为整数（推荐） #

SpringBoot 3.x对应Hibernate 6.x，枚举默认映射行为有变化，会优先尝试更小的整数类型。显式指定ORDINAL并明确列类型可覆盖该默认行为：

@Column(name = "status", columnDefinition = "integer")
@Enumerated(EnumType.ORDINAL)
var status: StatusEnum,

2. 升级适配PostgreSQL的新版方言 #

替换application.yml中的旧方言为对应PostgreSQL版本的新版方言（比如PostgreSQL 10+用PostgreSQL10Dialect）：

spring:
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL10Dialect

新版方言对数据库类型映射更精准，能避免类型不匹配问题。

3. 自定义枚举类型映射 #

通过Hibernate的@Type注解强制指定枚举映射到INTEGER类型：

import org.hibernate.type.EnumType
import jakarta.persistence.Column
import jakarta.persistence.Enumerated
import jakarta.persistence.Entity

@Entity
class YourEntity {
    // 其他字段...

    @Column(name = "status")
    @Enumerated(EnumType.ORDINAL)
    @Type(type = "org.hibernate.type.EnumType", parameters = [
        org.hibernate.annotations.Parameter(name = "enumClass", value = "com.yourpackage.StatusEnum"),
        org.hibernate.annotations.Parameter(name = "type", value = "4") // 4对应JDBC Types.INTEGER
    ])
    var status: StatusEnum? = null
}

4. 临时关闭Schema验证（不推荐） #

若需临时启动应用，可在application.yml中关闭验证，但仅作为临时方案：

spring:
  jpa:
    hibernate:
      ddl-auto: none
    properties:
      hibernate:
        schema_update:
          validate: false

内容的提问来源于stack exchange，提问作者Zed