Hibernate 5.x → 6.x QueryDSL 관련 이슈

개요

Spring Boot 2.7.x에서 Spring Boot 3.3.x로 버전 업그레이드를 진행하면서 발생한 여러 문제 중에서 QueryDSL과 관련된 이슈를 공유하고자 한다. (Hibernate 버전업 진행할 때 Migration Guides를 참고하면 도움 된다.)

먼저 Spring Boot가 3.x 버전대로 올라오면서 Hibernate도 기본적으로 6.1 버전이 적용된다. 이에 맞춰 Hibernate를 v6.5.3.Final로 업그레이드했으나 영향으로 이전까지 문제없이 동작하던 일부 QueryDSL 로직에서 에러가 발생하기 시작했다.

 

1. InvalidDataAccessApiUsageException: org.hibernate.query.sqm.AliasCollisionException

private final JPAQueryFactory queryFactory;
 
@Override
public List<Product> fetchAll() {
    return queryFactory
            .select(product)
            .from(product)
            .join(product.category, code).fetchJoin()
            .join(product.brand, code).fetchJoin()
            .fetch();
}

Hibernate 5.x 환경에서는 위 코드가 정상적으로 실행되었지만, Hibernate 6.x로 업그레이드한 이후에는 런타임 시 다음과 같은 예외가 발생한다.

InvalidDataAccessApiUsageException: org.hibernate.query.sqm.AliasCollisionException

Hibernate6에서 JPQL/HQL 쿼리의 alias(별칭) 관련 제약이 강화되었기 때문인데, Hibernate5에서는 동일한 Q타입(code)을 두 번 재사용해도 자동으로 회피했지만, 이제는 중복된 별칭을 엄격하게 금지하기 때문에 발생한다. 그래서 Hibernate6에서는 SQL로 변환하는 시점에서 에러가 발생한다.

해결방법

private final JPAQueryFactory queryFactory;
 
@Override
public List<Product> fetchAll() {
    QCode categoryCode = new QCode("categoryCode");
    QCode brandCode = new QCode("brandCode");
 
    return queryFactory
            .select(product)
            .from(product)
            .join(product.category, categoryCode).fetchJoin()
            .join(product.brand, brandCode).fetchJoin()
            .fetch();
}

중복 alias를 방지하기 위해서는 위와 같이 각각의 join마다 별도의 Q타입을 선언하고 서로 다른 alias를 부여해 주면 정상적으로 잘 동작한다.

 

이전에는 왜 동작했는가?

QueryDSL을 사용할 때 같은 Q타입 인스턴스를 여러 번 재사용하면 동일한 alias로 인식되지만 Hibernate 5에서는 alias 충돌에 대해 엄격한 검사를 하지 않았고, QueryDSL이 SQL 생성 시 내부적으로 물리 alias를 자동으로 다르게 지정하면서 정상적으로 동작했다. 

select ...
from product product0_
join system_code systemcode1_ on product0_.category_id = systemcode1_.id
join system_code systemcode2_ on product0_.brand_id = systemcode2_.id

그러나 Hibernate6부터는 파서가 엄격하게 별칭 중복을 금지하도록 변경되었기 때문에 더 이상 통하지 않는다. (Hibernate6에서 "파서가 엄격하게 별칭 중복을 금지" 한다고 정확히 명시한 문서는 찾지 못했으나 Hibernate 6에서는 새로운 sqmSQM(parser)과 결과 매핑 방식 도입으로 SQL도 더 간결하게 생성되는데, 중복된 JPQL 별칭이 있으면 Hibernate도 SQL에서 별칭을 겹치게 내보낼 가능성이 있다는 점에서 유추했다.)

참고로 이 이슈에 대해 Hibernate 팀에서는 애초에 중복 alias 사용이 명시적으로 허용된 문법이 아니기 때문에 Hibernate6에서는 에러로 처리하는 것이 더 일관된 동작이라고 판단한 것으로 보인다.(그래서 따로 언급 안 한 것일 수도..?)

https://discourse.hibernate.org/t/duplicate-alias-when-using-hibernate-6-and-querydsl/7705

 

2. NoSuchMethodError: org.hibernate.ScrollableResults.get(int)

@Override
public Map<Long, ProductDetail> fetchProductDetailsByProductId() {
    QProductDetail detail = QProductDetail.productDetail;
    QProduct product = QProduct.product;
 
    return queryFactory
            .select(product.id)
            .from(detail)
            .leftJoin(detail.product, product)
            .transform(
                groupBy(product.id).as(detail)
            );
}

java.lang.NoSuchMethodError: 'java.lang.Object org.hibernate.ScrollableResults.get(int)'
	at com.querydsl.jpa.ScrollableResultsIterator.next(ScrollableResultsIterator.java:70)
	at com.querydsl.core.group.GroupByMap.transform(GroupByMap.java:57)

.transform(groupBy().as())를 사용하는 QueryDSL 코드에서 오류가 발생했다. 원인은 Hibernate6 부터 ScrollableResults.get(int) 메서드가 제거되었는데, QueryDSL의 .transform(groupBy().as()) 내부 로직에서는 여전히 해당 메서드를 사용하고 있기 때문에 NoSuchMethodError가 발생한다. 

• Hibernate v5.6.5 #ScrollableResults.java#L140
• Hibernate v6.0 #ScrollableResults.java

실제 코드 부분을 확인하면 v5.6.5에는 있었던 Object get(int i); 메서드가 v6.0부터는 보이지 않고, 이 외에도 다른 메서드들도 사라진 것을 확인할 수 있다.

 

해결방법

해결 방법은 크게 세 가지가 있다.

1. .transform(groupBy().as())를 사용하지 않고, List<Tuple>로 조회한 뒤 직접 Map으로 변환하는 방식
2. JPQLTemplates를 사용하여 내부 실행 방식 변경
3. Hibernate5Templates은 계속 사용하면서 QueryHandler만 교체

첫 번째 방법은 말 그대로 .transform()을 아예 사용하지 않고, 쿼리 결과를 List<Tuple> 형태로 받아와서 직접 가공하여 Map으로 변환하는 방식이다.

List<Tuple> results = queryFactory
        .select(product.id, detail)
        .from(detail)
        .leftJoin(detail.product, product)
        .fetch();
 
// 이후 수작업으로 Map<Long, ProductDetail> 형태로 변환

두 번째 방법은 QueryDSL의 기본 실행 방식을 JPA 표준으로 변경하여 Hibernate 내부 API 호출을 피하는 방식이다.(다만 index(), class(), function(), cast() 등 Hibernate5Templates에서만 지원하던 일부 DSL 기능이 제한될 수 있다.)

public JPAQueryFactory jpaQueryFactory() {
    return new JPAQueryFactory(JPQLTemplates.DEFAULT, entityManager);
}

세 번째 방법은 Hibernate 스타일의 쿼리 문법은 그대로 유지하면서 실행 시에만 JPA 표준 방식으로 처리되도록 QueryHandler만 교체하는 방법이다.

public JPAQueryFactory jpaQueryFactory() {
    return new JPAQueryFactory(new CustomHibernate5Templates(), entityManager);
}
 
/**
 * transform()을 사용하기 위해 HibernateQueryHandler 대신
 * DefaultQueryHandler를 사용하도록 강제 지정
 */
public static class CustomHibernate5Templates extends Hibernate5Templates {
    @Override
    public QueryHandler getQueryHandler() {
        return DefaultQueryHandler.DEFAULT;
    }
}

다만 이 방식은 일시적인 회피책으로 쓸 수 있지만 내부적으로 여전히 Hibernate 스타일의 문법 및 구문 해석기를 사용하기 때문에 향후 업데이트에서 문제가 다시 발생할 가능성이 있음은 인지하자.

두 번째와 세 번째 방법 모두 개별 클래스에서만 사용할 수도 있고, 전역 설정으로 Bean 등록하여 전체에 적용할 수도 있다. 이슈 관련해서는 QueryDSL issues #3428를 참고하면 도움 될 것이다.

 

왜 Template이나 Handler를 바꾸면 해결되는가?

기본적으로 Hibernate5 이상 환경에서는 별도의 설정을 하지 않으면 Hibernate5Templates가 사용된다.(JPAProvider.java#L59)

JPAProvider.java

그리고 Hibernate5Templates는 내부적으로 HibernateHandler를 사용하여 HibernateQuery 객체를 생성하고 scroll() 메서드를 통해 ScrollableResults.get(int)를 호출한다. 다만 이 메서드는 Hibernate6에서 제거되었기 때문에 해당 핸들러가 그대로 사용될 경우 런타임 예외가 발생하게 된다.(Hibernate6버전이 나온 지 한참 됐음에도 아직도 업데이트가 느려 Hibernate5Templates를 사용하기 때문 아닐까..?)

QueryDSL에서 사용하는 템플릿 클래스는 다음과 같은 상속 구조를 가지고 있다.

Templates
  └── JPQLTemplates              ← JPA 표준용 템플릿
        └── HQLTemplates         ← Hibernate 4 확장용
              └── Hibernate5Templates ← Hibernate 5+ 확장용

그리고 각 템플릿은 다음과 같은 QueryHandler를 사용한다.

JPQLTemplates	DefaultQueryHandler	JPA 표준 쿼리 생성 및 실행 방식 사용
HQLTemplates	HibernateHandler	Hibernate 고유 쿼리 방식 사용
Hibernate5Templates	HibernateHandler	Hibernate 5+ 확장 쿼리 방식 사용

HQLTemplates.java

JPQLTemplates.java

결국 문제의 핵심은, Hibernate5Templates가 사용하는 HibernateHandler가 생성한 HibernateQuery가 transform() 실행 시 scroll()을 호출하고, 그 내부에서 Hibernate6에서 제거된 ScrollableResults.get(int)를 참조한다는 점이다.

따라서 DefaultQueryHandler를 사용하는 JPQLTemplates를 사용하거나 Hibernate5Templates를 사용하더라도 QueryHandler를 DefaultQueryHandler로 변경하면 DefaultQueryHandler는 scroll()을 사용하지 않고 .list()나 .getResultList() 같은 JPA 표준 API를 통해 결과를 처리하기 때문에 에러가 발생하지 않는다.