开启Hibernate batch_size后SQL Server插入报id空值错误的原因与最佳实践

为什么hibernate.jdbc.batch_size:20会引发该问题？ #

核心原因：手动主键与Hibernate批量插入的兼容性冲突 #

你的实体使用手动分配主键（即@Id字段由业务代码赋值，而非Hibernate/数据库自动生成），开启批量插入配置后，Hibernate的批量处理逻辑在多列实体场景下出现参数绑定异常：

• 场景1（仅主键列）：插入语句仅包含主键字段，Hibernate的批量处理逻辑无需处理复杂参数映射，主键值能正确绑定到SQL中，因此执行正常。
• 场景2（新增非主键列）：Hibernate在构建批量插入语句时，对于手动主键的实体，错误地遗漏了主键值的参数绑定，导致SQL Server接收到的id参数为NULL，触发主键非空约束报错。

为什么抛出BatchUpdateException？ #

开启batch_size配置后，Hibernate会强制通过JDBC的批量操作API（addBatch()/executeBatch()）执行所有插入语句——即使你只插入单条数据，也会被封装到批量执行流程中，因此抛出BatchUpdateException而非普通的SQLException。

规避问题的最佳实践 #

根据业务需求选择以下方案：

1. 临时快速解决：禁用批量插入 #

将hibernate.jdbc.batch_size设为0，关闭Hibernate的批量处理逻辑，回到单条语句执行模式。此方法无需修改实体或表结构，但会丢失批量操作带来的性能提升。

2. 推荐方案：改用主键生成器 #

如果业务允许，将手动主键改为Hibernate支持的主键生成策略（配合SQL Server的IDENTITY列），彻底解决批量插入与手动主键的兼容性问题：

• 实体类修改：

@Entity
@Table(name = "test")
data class Test(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    var id: Int? = null, // 改为可空，由数据库自动生成
    
    @Column(name = "group_name")
    val groupName: String
)

• 数据库表修改：

CREATE TABLE test(
  id INT IDENTITY(1,1) PRIMARY KEY,
  group_name VARCHAR(9)
)

这种方式下，Hibernate的批量插入逻辑可以稳定运行，同时获得批量操作的性能收益。

3. 保留手动主键的批量优化方案 #

若必须保留手动分配主键，可尝试以下优化：

• 升级SQL Server JDBC驱动：使用最新版本的驱动，可能已修复此类参数绑定Bug。
• 关闭插入排序：将hibernate.order_inserts设为false，避免Hibernate重排插入语句的列顺序，减少参数绑定出错概率，但会损失部分批量优化效果。
• 手动实现批量插入：使用Spring Data JPA的saveAll()方法批量插入，或编写原生SQL批量插入语句，绕过Hibernate自动批量处理逻辑。

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