Quarkus JUnit5测试H2数据库SQL语法错误及循环引用问题解决

关于「CIRCULAR REFERENCE」标记的说明 #

这里的CIRCULAR REFERENCE并不是指实体类之间存在循环引用关系，它是H2数据库在抛出语法错误时的内部标记，用来定位SQL语句中的错误位置（[*]指向的KEY就是问题点）。

错误根源 #

KEY是H2数据库的保留关键字，当你通过@ElementCollection定义Map集合并将键列名设为KEY时，Hibernate生成的SQL语句会直接使用KEY作为列名，导致H2解析SQL时触发语法错误。而Oracle数据库中KEY并非保留字，所以不会出现该问题。

解决方法 #

方案1：修改列名（推荐） #

直接将键列名改为非保留字，比如INDEX_KEY，通过@MapKeyColumn注解指定：

@ElementCollection
@CollectionTable(name = "FILENET_INDEXES")
@MapKeyColumn(name = "INDEX_KEY")
@Column(name = "INDEX_VALUE")
private Map<String, String> filenetIndexes;

方案2：强制给列名加引号（保留原列名） #

如果必须使用KEY作为列名，可以通过注解给列名添加双引号，让H2将其视为普通标识符：

@ElementCollection
@CollectionTable(name = "FILENET_INDEXES")
@MapKeyColumn(name = "\"KEY\"")
@Column(name = "INDEX_VALUE")
private Map<String, String> filenetIndexes;

这样Hibernate生成的SQL会将KEY用双引号包裹，避免触发保留字冲突。

方案3：全局设置Hibernate引号策略（适用于多个类似场景） #

在Quarkus配置文件（application.properties）中添加以下配置，让Hibernate对所有标识符自动添加引号：

quarkus.hibernate-orm.quoted-identifiers=true

该配置会让Hibernate生成的所有表名、列名都带上引号，彻底避免保留字冲突，但会导致SQL语句可读性略有下降。

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