상어코딩

Spring Data JPA @Modifying — 벌크 쿼리와 영속성 컨텍스트 동기화

dding-shark — Tue, 21 Apr 2026 20:30:49 +0900

Spring Data JPA @Modifying — 벌크 쿼리와 영속성 컨텍스트 동기화

들어가며

"어제 데이터 마이그레이션 돌린 뒤 조회가 이상하다"는 리포트로 시작해 쿼리 로그를 파보면, 대개는 벌크 UPDATE 뒤에 같은 트랜잭션에서 조회한 엔티티가 옛 값으로 돌아오고 있다. Spring Data JPA의 @Modifying을 처음 쓰면 거의 반드시 밟는 함정이고, 원리는 단순한데 증상이 쉽게 눈에 띄지 않아서 "DB에는 반영됐는데 애플리케이션 로그만 이상하다"는 식으로 오진단되기 쉽다. 뿌리는 12편 영속성 컨텍스트에서 본 1차 캐시다. 벌크 쿼리는 그 캐시를 우회한다.

이 글은 @Modifying이 왜 존재하는지, 두 플래그(clearAutomatically / flushAutomatically)가 정확히 무엇을 켜고 끄는지, 벌크 쿼리가 영속성 컨텍스트를 우회하는 메커니즘, 그리고 실무에서 자주 넘어지는 네 가지 함정을 Spring Boot 3.x / Spring Data JPA 3.x / Hibernate 6.x 기준으로 정리한다. 특히 다음은 거의 모두가 한 번은 밟는다.

UPDATE JPQL을 @Query에 썼는데 @Modifying을 빼먹으면 런타임 예외가 난다 — SELECT 전제인 @Query가 쓰기 쿼리를 거부한다
벌크 UPDATE 뒤 같은 트랜잭션에서 조회가 stale이다 — clearAutomatically를 안 켰기 때문이고, DB는 이미 바뀌었는데 1차 캐시만 옛날 값이다
deleteByStatus(...) 파생 메서드가 느리다 — 이름이 주는 인상과 달리 벌크 DELETE가 아니라 SELECT 후 em.remove() 반복이다
벌크 UPDATE 뒤 @Version이 증가하지 않는다 — JPQL 벌크는 버전 자동 증가를 건너뛴다(39편)

이 글은 왜 → 플래그 → 메커니즘 → 주의 → 실무 순으로 읽으면 가장 자연스럽다.

1) @Modifying은 왜 필요한가
2) clearAutomatically / flushAutomatically: 기본값 false가 함정의 원인
3) 벌크 쿼리가 영속성 컨텍스트를 우회하는 메커니즘
4) 흔한 버그 시나리오: stale 엔티티
5) JPQL 벌크 vs Native 벌크: @SQLRestriction이 적용되지 않는다
6) @Version 자동 증가가 일어나지 않는다
7) 영향 받은 row 수 반환과 해석
8) 파생 delete vs @Modifying DELETE: cascade와 이벤트의 갈림길
9) saveAllAndFlush / deleteAllInBatch — 편리함의 뒷면
10) 트랜잭션 경계와 Service @Transactional
11) 실무에서 이렇게 읽고 쓴다
12) 한 줄 정리

1) @Modifying은 왜 필요한가

Spring Data JPA의 @Query는 기본적으로 SELECT 전제다. Repository 메서드에 @Query만 붙이면 해당 JPQL은 "읽기 쿼리"로 해석되고, 실행 결과를 반환 타입으로 매핑한다. 그런데 UPDATE나 DELETE JPQL은 결과 집합이 없다. 대신 영향 받은 row 수를 돌려주는 쓰기 쿼리다. 여기에 @Query만 붙이면 Spring Data JPA는 "SELECT로 해석했는데 SELECT가 아니다"라는 맥락에서 런타임 예외를 던진다.

// 피하기 — @Modifying 없이 UPDATE JPQL
@Query("update Order o set o.status = :s where o.createdAt < :d")
int updateOldOrders(@Param("s") Status s, @Param("d") LocalDateTime d);

이 코드는 앱을 띄우면 잘 뜬다. 메서드를 호출하는 순간 InvalidDataAccessApiUsageException 계열 예외가 나간다(구체 원인은 Query.executeUpdate()를 써야 하는데 getResultList()를 호출한 Hibernate 쪽 QueryExecutionRequestException이다). 해결은 간단하다. @Modifying을 붙여 "이건 쓰기 쿼리다"를 Spring Data JPA에 알려준다.

// 선호
@Modifying
@Query("update Order o set o.status = :s where o.createdAt < :d")
int updateOldOrders(@Param("s") Status s, @Param("d") LocalDateTime d);

반환 타입은 int, Integer, void 중 하나를 쓴다. int/Integer면 영향 받은 row 수가 돌아오고, void면 결과를 무시한다. 그리고 @Modifying 메서드는 트랜잭션이 필수다. Service 계층에 @Transactional이 있거나, 호출 스택 어디선가 트랜잭션이 열려 있어야 한다. 없으면 TransactionRequiredException이 뜬다.

여기서 틀리기 쉬운 지점이 있다. @Modifying을 붙였다고 끝난 게 아니다. 이 애노테이션은 "쓰기 쿼리임을 선언"만 할 뿐, 영속성 컨텍스트 동기화는 별도 플래그로 제어한다. 다음 섹션에서 그 플래그를 본다.

2) clearAutomatically / flushAutomatically: 기본값 false가 함정의 원인

@Modifying에는 두 개의 불리언 속성이 있다. 둘 다 기본값 false이고, 실무에서 대부분의 버그는 이 두 기본값을 모르고 쓰는 데서 나온다.

@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("update Order o set o.status = :s where o.createdAt < :d")
int updateOldOrders(@Param("s") Status s, @Param("d") LocalDateTime d);

속성	시점	역할	기본값
`flushAutomatically`	벌크 쿼리 실행 직전	영속성 컨텍스트의 pending 변경을 DB에 반영	`false`
`clearAutomatically`	벌크 쿼리 실행 직후	영속성 컨텍스트를 비워 stale 엔티티 제거	`false`

2-1) flushAutomatically가 필요한 상황

메모리에서 바꾼 엔티티가 있는데 그게 DB에 반영되기 전에 벌크 쿼리가 나가면, 벌크 쿼리는 옛 상태를 기준으로 실행된다.

// 같은 트랜잭션 안
User u = userRepo.findById(1L).orElseThrow();
u.setLastLoginAt(LocalDateTime.now());   // 1차 캐시에서만 변경, DB 미반영

userRepo.inactivateStaleUsers(cutoff);   // 벌크 UPDATE

위 코드에서 u.setLastLoginAt은 아직 DB로 flush되지 않았다. 벌크 UPDATE가 lastLoginAt < cutoff 조건으로 실행된다면, 방금 수정한 u는 DB에서 여전히 옛 lastLoginAt 값이므로 잘못된 대상에 포함될 수 있다. flushAutomatically = true는 이 벌크 쿼리 직전에 flush를 강제로 걸어 pending 변경을 먼저 DB에 반영한다.

물론 JPQL을 쓰면 FlushModeType AUTO 기본값이 이미 "JPQL 실행 직전 flush"를 걸기 때문에, 순수 JPQL 환경에서는 flushAutomatically가 중복일 수 있다. 하지만 FlushMode를 MANUAL/COMMIT으로 바꾼 경로나 네이티브 쿼리에서는 이 플래그가 진짜로 일을 한다. 실무에서 혼동 방지를 위해 그냥 같이 켜두는 편이 무난하다.

2-2) clearAutomatically가 필요한 상황

벌크 쿼리가 DB의 row를 바꿨는데 그 row에 해당하는 엔티티가 이미 1차 캐시에 있으면, 이제 캐시의 엔티티는 stale(옛 값) 상태다. clearAutomatically = true는 벌크 쿼리 **직후에 em.clear()**를 걸어 영속성 컨텍스트를 통째로 비운다. 이후 findById 같은 조회는 1차 캐시를 거치지 않고 DB로 다시 내려가 최신 값을 가져온다.

여기서 "왜 두 플래그 다 기본값이 false인가"라는 질문이 생긴다. 설계 관점에서는 "Spring Data JPA가 사용자의 영속성 컨텍스트를 임의로 건드리지 않는다"는 보수적 기본값이다. 하지만 실무에서는 둘 다 켜는 게 디폴트에 가깝다. 다음 섹션에서 그 이유를 메커니즘 관점에서 본다.

3) 벌크 쿼리가 영속성 컨텍스트를 우회하는 메커니즘

12편 영속성 컨텍스트에서 본 것처럼, JPA의 1차 캐시는 영속화된 엔티티 인스턴스를 그대로 들고 있는 Map이다. findById(1L)을 호출하면 먼저 1차 캐시를 보고, 있으면 DB 조회 없이 캐시의 인스턴스를 돌려준다. 이 캐시가 변경 감지(dirty checking)와 동일성 보장의 토대다.

벌크 쿼리는 이 구조를 정면으로 우회한다.

다이어그램의 핵심은 간단하다. 벌크 쿼리는 DB에 직접 SQL을 쏜다. 1차 캐시에 있는 엔티티 인스턴스를 찾아서 필드를 갱신하거나 하지 않는다. Hibernate는 그 벌크 쿼리가 어떤 row를 건드릴지 미리 알 방법이 없고, 안다 해도 캐시의 모든 인스턴스를 일일이 갱신하는 건 부담이 크다. 그래서 기본 동작은 "DB에만 반영하고 메모리는 건드리지 않는다"이다.

이 동작 자체를 "버그"로 생각하면 방향이 어긋난다. @Modifying의 clear/flush 플래그는 이 비동기를 수동으로 해소하는 레버다. 플래그를 안 켠 건 레버를 안 당긴 것뿐이고, 당기지 않은 채 조회를 계속하면 메모리와 DB가 두 개의 서로 다른 진실을 들고 있게 된다.

4) 흔한 버그 시나리오: stale 엔티티

말로만 설명하면 감이 안 오니 실제로 재현되는 패턴 세 가지를 본다.

4-1) 시나리오 1: 조회 후 벌크 UPDATE, 다시 조회

@Transactional
public void deactivateOld(LocalDateTime cutoff) {
    User u = userRepo.findById(1L).orElseThrow();   // 1차 캐시 로드, active=true
    userRepo.deactivateInactive(cutoff);            // 벌크 UPDATE (u 포함)

    if (u.isActive()) {
        log.info("여전히 active");   // 여기로 빠진다 (stale)
    }
}

@Modifying   // clearAutomatically 안 붙임
@Query("update User u set u.active = false where u.lastLoginAt < :d")
int deactivateInactive(@Param("d") LocalDateTime d);

DB 상의 user#1은 이미 active=false인데, u 인스턴스는 1차 캐시 히트로 active=true로 남아 있다. 로그는 "여전히 active"를 찍고, 디버거로 들여다봐도 값이 맞아 보여서 원인 추적이 오래 걸린다. 해결은 @Modifying(clearAutomatically = true) 또는 벌크 이후 명시적 em.refresh(u)다.

4-2) 시나리오 2: 벌크 이후 변경 감지가 동작하지 않는 것처럼 보임

@Transactional
public void patchAndBulk() {
    User u = userRepo.findById(1L).orElseThrow();
    u.setNickname("kim");   // 변경 감지 대상

    userRepo.bulkSomething(...);   // clearAutomatically = true

    // 여기서 u는 detached 상태
    u.setNickname("park");   // 이 변경은 flush되지 않는다
}

clearAutomatically = true가 편리하긴 하지만 부작용이 있다. em.clear()는 1차 캐시 전체를 비우므로, 벌크 쿼리 이전에 조회해서 수정 중이던 엔티티까지 detached 상태로 바뀐다. 커밋 시점에 변경 감지가 돌지 않아 setNickname("park")는 조용히 사라진다. 해법은 두 가지다. 하나는 벌크 쿼리를 트랜잭션의 가장 앞으로 옮겨 관리 중인 엔티티가 없을 때 실행하는 것. 다른 하나는 벌크 후 findById로 다시 로드해 관리 상태로 재진입시키는 것.

4-3) 시나리오 3: 네이티브 쿼리로 update 후 조회

@Modifying
@Query(value = "update orders set status = 'DONE' where created_at < ?1", nativeQuery = true)
int bulkCloseOld(LocalDateTime d);

네이티브 쿼리는 Hibernate 입장에서 "이 쿼리가 어떤 엔티티를 건드리는지" 정적으로 알 수 없다. 그래서 1차 캐시가 네이티브 UPDATE를 전혀 인지하지 못한다. JPQL 벌크보다 stale 위험이 더 큰 경로이고, 이 경우는 clearAutomatically = true를 거의 강제로 붙여야 한다.

5) JPQL 벌크 vs Native 벌크: @SQLRestriction이 적용되지 않는다

JPQL 벌크와 네이티브 벌크는 문법 차이만 있는 게 아니다. JPA 추상화 계층을 거치는지 여부가 가장 큰 차이다.

항목	JPQL 벌크	Native 벌크
대상	엔티티 이름	테이블 이름
파싱 주체	Hibernate	DB 드라이버
`@SQLRestriction`	자동 적용	수동 포함 필요
상속 전략	Hibernate가 해석	수동 처리
`@Filter`	적용	미적용
1차 캐시 인지	엔티티 이름으로 유추 가능	전혀 인지 못함
유연성	JPA 문법 범위 내	SQL 전체 기능

// JPQL 벌크 — @SQLRestriction 자동 반영
@Modifying(clearAutomatically = true)
@Query("update Order o set o.status = :s where o.amount > :a")
int bulkJpql(@Param("s") Status s, @Param("a") int a);

// Native 벌크 — soft-delete 조건 수동 포함
@Modifying(clearAutomatically = true)
@Query(value = "update orders set status = ?1 where amount > ?2 and deleted = false",
       nativeQuery = true)
int bulkNative(String s, int a);

40편 soft-delete에서 본 @SQLRestriction("deleted = false")는 JPQL이 생성하는 모든 쿼리에 자동으로 붙지만, 네이티브 쿼리에는 붙지 않는다. 네이티브로 벌크 UPDATE를 날리면 논리적으로 지워진(deleted=true) row까지 업데이트해버린다. 이 실수는 디버깅 때도 잘 안 보인다. "모든 row를 업데이트했다"는 결과만 보면 맞게 돌아간 것처럼 보이기 때문이다.

네이티브 쿼리를 써야 하는 상황은 실제로 존재한다. JPQL이 지원하지 않는 DB 고유 함수, ON CONFLICT, RETURNING 같은 문법이 필요하면 네이티브가 답이다. 다만 네이티브로 가는 순간 JPA의 안전망이 전부 빠진다는 걸 의식해야 한다. soft-delete 조건, 상속 디스크리미네이터, @Filter는 전부 수동으로 관리해야 한다.

5-1) JPQL 벌크 UPDATE가 건드리지 못하는 것

JPQL 벌크 UPDATE는 엔티티 필드만 다룰 수 있다. 연관 엔티티(ManyToOne, OneToOne)의 필드를 한 UPDATE 안에서 건드리려 하면 파싱 단계에서 막힌다.

// 피하기 — 컴파일/파싱 시점에 예외
@Modifying
@Query("update Order o set o.member.status = 'VIP' where o.amount > :a")
int upgradeMembers(@Param("a") int a);

이건 SQL로 치면 조인 UPDATE인데, JPA 표준 JPQL은 UPDATE에서 조인을 허용하지 않는다(Hibernate 일부 버전에서 부분적으로 허용되지만 표준 범위를 벗어난다). 해법은 서브쿼리로 우회하거나, 관련 엔티티 벌크 UPDATE를 별도 쿼리로 분리하는 것이다.

// 선호 — 서브쿼리 IN으로 우회
@Modifying(clearAutomatically = true)
@Query("""
    update Member m set m.status = 'VIP'
    where m.id in (select o.member.id from Order o where o.amount > :a)
""")
int upgradeMembers(@Param("a") int a);

네이티브 쿼리로 가면 DB 문법의 UPDATE JOIN을 쓸 수 있지만, 그 순간 §5의 안전망이 전부 빠진다는 점을 감수해야 한다.

5-2) FlushMode와의 상호작용

flushAutomatically가 하는 일은 벌크 쿼리 직전에 em.flush()를 강제로 호출하는 것이다. 그런데 JPA의 기본 FlushMode는 AUTO이고, 이미 JPQL 쿼리 실행 전에 flush를 거는 게 표준 동작이다. 그럼 flushAutomatically = true는 왜 필요한가.

FlushMode가 COMMIT 또는 MANUAL로 바뀌어 있을 때 — AUTO의 자동 flush가 꺼진 상태에서도 벌크 쿼리 직전에 flush를 보장
네이티브 쿼리일 때 — Hibernate는 네이티브 쿼리가 어떤 엔티티를 건드릴지 모르므로, AUTO FlushMode에서도 보수적으로만 flush를 걸거나 아예 걸지 않는다. flushAutomatically = true가 실질적으로 의미를 가지는 경로
트랜잭션 범위가 겹치는 복잡한 흐름 — 명시적 선언으로 "이 쿼리 직전은 반드시 flush"를 코드에 남기기

평문 FlushMode를 건드리지 않는 일반 서비스에서는 flushAutomatically = true가 중복처럼 보일 수 있지만, 네이티브 벌크나 FlushMode 커스터마이징이 섞이는 순간 진짜로 필요해진다. 켜두는 비용이 거의 없으므로 기본으로 붙이는 편이 안전하다.

6) @Version 자동 증가가 일어나지 않는다

39편 낙관적/비관적 락에서 본 @Version은 엔티티의 변경 감지 경로에서 자동으로 증가한다. 그런데 JPQL 벌크 UPDATE는 이 메커니즘을 건너뛴다. DB에 UPDATE 문을 직접 쏘므로 Hibernate의 버전 증가 로직이 끼어들 틈이 없다.

// 피하기 — @Version 증가 안 됨
@Modifying
@Query("update Order o set o.status = :s where o.createdAt < :d")
int bulkWithoutVersion(@Param("s") Status s, @Param("d") LocalDateTime d);

벌크 UPDATE 이후 DB에는 status가 바뀌었지만 version 컬럼은 그대로다. 이 상태로 다른 트랜잭션이 같은 row에 낙관적 락을 걸고 동시에 수정을 시도하면, 낙관적 락 충돌 탐지가 무의미해진다. 벌크로 바꾼 변경이 동시성 관점에서는 "일어나지 않은 일"처럼 취급된다.

해결은 두 가지다.

// 선호 1: Hibernate 확장 UPDATE VERSIONED
@Modifying
@Query("update versioned Order o set o.status = :s where o.createdAt < :d")
int bulkVersioned(@Param("s") Status s, @Param("d") LocalDateTime d);

// 선호 2: SET 절에 version 명시적 증가
@Modifying
@Query("update Order o set o.status = :s, o.version = o.version + 1 where o.createdAt < :d")
int bulkExplicitVersion(@Param("s") Status s, @Param("d") LocalDateTime d);

update versioned는 Hibernate 확장 문법으로, JPA 표준은 아니지만 Hibernate 6에서 문제없이 작동한다. "이 UPDATE에 걸리는 row들의 @Version도 함께 증가시켜라"를 선언한다. 표준을 유지하고 싶으면 두 번째 방식처럼 SET 절에 명시한다. 어느 쪽을 써도 좋지만, 낙관적 락을 쓰는 엔티티의 벌크 UPDATE는 버전 증가를 반드시 동반해야 한다는 규율을 잡는 게 핵심이다.

7) 영향 받은 row 수 반환과 해석

@Modifying 메서드의 반환 타입이 int면 영향 받은 row 수가 돌아온다. JDBC의 executeUpdate() 반환값이 그대로 전달된다.

@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("update Order o set o.status = :s where o.createdAt < :d")
int closeOldOrders(@Param("s") Status s, @Param("d") LocalDateTime d);

// 호출측
int affected = orderRepo.closeOldOrders(Status.CLOSED, cutoff);
log.info("닫힌 주문: {}건", affected);
if (affected == 0) {
    // 조건에 맞는 주문이 없었다 (에러 아님)
}

반환값이 0이라고 해서 예외 상황은 아니다. 단순히 조건에 맞는 row가 없었다는 뜻이다. 여기서 실수하기 쉬운 게 0을 낙관적 락 충돌로 오해하는 것이다. 낙관적 락 충돌은 OptimisticLockException으로 예외가 나가지, 벌크 쿼리의 영향 row 수 0으로 표현되지 않는다. 두 개념을 섞으면 에러 핸들링이 틀어진다.

반대로 "정확히 1건 업데이트되어야 한다"는 계약이 있는 경우는 반환값을 검증한다.

int affected = orderRepo.closeById(id);
if (affected != 1) {
    throw new IllegalStateException("예상 1건, 실제 " + affected + "건");
}

이 패턴은 "특정 조건 하에서만 변경"(conditional update, 예: where id = :id and status = 'OPEN')을 구현할 때 유용하다. JPA 수준의 낙관적 락 없이도 애플리케이션 레벨의 조건부 업데이트를 구현할 수 있다.

8) 파생 delete vs @Modifying DELETE: cascade와 이벤트의 갈림길

Spring Data JPA는 메서드 이름 파싱으로 deleteByXxx를 자동 생성한다. 이름만 보면 "조건 기반 벌크 DELETE"처럼 느껴진다. 실제 구현은 그렇지 않다.

public interface OrderRepository extends JpaRepository<Order, Long> {
    // 파생 메서드 — 이름만 보면 벌크 DELETE 같지만...
    void deleteByStatus(Status s);
}

파생된 deleteByStatus의 내부 동작은 SELECT → em.remove() 반복이다. 즉 다음 두 단계로 쪼개진다.

select o from Order o where o.status = :s — 조건에 맞는 엔티티를 전부 먼저 조회
조회된 엔티티 각각에 대해 entityManager.remove(order) 호출

이 방식의 장점은 @OneToMany(cascade = REMOVE)나 @PreRemove 이벤트 리스너가 정상 동작한다는 것이다. 자식 엔티티 cascade 삭제, 감사 로그 기록, 도메인 이벤트 발행 같은 훅이 전부 돌아간다. 단점은 성능이다. 조건에 맞는 row가 10000건이면 SELECT 한 번 + DELETE 10000번이다. 영속성 컨텍스트도 그만큼 부풀어 오른다.

반대로 @Modifying을 명시한 DELETE JPQL은 DB에 DELETE 한 방이다.

@Modifying(clearAutomatically = true)
@Query("delete from Order o where o.status = :s")
int bulkDelete(@Param("s") Status s);

이쪽은 SQL 한 번으로 끝난다. 대신 cascade = REMOVE도, @PreRemove도 동작하지 않는다. Hibernate가 엔티티 인스턴스를 거치지 않기 때문이다. 자식 엔티티는 DB의 외래키 제약(ON DELETE CASCADE)에 의존하거나, 자식을 먼저 지우는 쿼리를 별도로 날려야 한다.

비교 항목	파생 `deleteByXxx`	`@Modifying` DELETE
쿼리 수	SELECT 1 + DELETE N	DELETE 1
cascade = REMOVE	동작	동작 안 함
`@PreRemove` / `@PostRemove`	동작	동작 안 함
soft-delete (`@SQLDelete`)	적용	적용(JPQL 한정)
영속성 컨텍스트	엔티티 관리	우회 (clear 필요)
적합한 규모	~수백 건	수천~수만 건

여기서 틀리기 쉬운 건 "이름이 같은 deleteXxx끼리 당연히 같은 동작"이라는 가정이다. deleteById(1L)과 @Modifying DELETE는 완전히 다른 경로다. 도메인 이벤트에 의존하는 코드라면 파생 메서드를 쓰고, 대량 삭제가 목적이라면 @Modifying DELETE로 가되 cascade를 직접 책임진다.

9) saveAllAndFlush / deleteAllInBatch — 편리함의 뒷면

Spring Data JPA 3.x의 JpaRepository에는 saveAllAndFlush와 deleteAllInBatch가 있다. 둘 다 벌크 처리에 자주 거론되는데 동작 방식은 꽤 다르다.

9-1) saveAllAndFlush

orderRepo.saveAllAndFlush(orders);

내부 구현은 saveAll(orders) 후 em.flush()다. 13편 N+1 편의 saveAll 함정과 같은 문제를 공유한다. 즉 "한 번에 저장"처럼 보이지만 실제로는 save를 루프로 반복하고 마지막에 flush만 추가로 건다. JDBC batch insert는 hibernate.jdbc.batch_size + SEQUENCE 전략이 갖춰져 있어야만 자동으로 묶이고, IDENTITY 전략이면 아무리 메서드를 바꿔도 INSERT가 N번 나간다. saveAllAndFlush는 "flush 타이밍을 앞당기는" 목적에만 집중한다고 이해하는 편이 정확하다.

9-2) deleteAllInBatch

// 인자 있는 버전
orderRepo.deleteAllInBatch(orders);

// 인자 없는 버전 — 위험
orderRepo.deleteAllInBatch();

인자가 있는 deleteAllInBatch(Iterable)는 전달된 엔티티의 PK를 모아 한 방의 DELETE 쿼리로 처리한다. delete from orders where id in (?, ?, ...) 형태다. SELECT 선행이 없고 cascade/@PreRemove도 돌지 않는다. 성능은 파생 deleteByXxx보다 훨씬 빠르다.

문제는 인자 없는 deleteAllInBatch()다. delete from orders 한 방을 날린다. 테이블 전체 삭제다. 운영 환경에서 이걸 실수로 부르면 돌이킬 수 없다. 이름이 "batch"라서 "일괄 처리" 정도로 읽히지만, 실제로는 "조건 없는 전체 DELETE"다. 리포지토리 확장이나 테스트 코드에서 특히 조심해야 한다.

메서드	쿼리 형태	cascade/이벤트	위험도
`saveAll`	INSERT N회(배치 조건 충족 시 묶임)	`@PrePersist` 동작	낮음
`saveAllAndFlush`	INSERT N회 + flush	`@PrePersist` 동작	낮음
`deleteAll(entities)`	SELECT + DELETE N회	동작	낮음
`deleteAllInBatch(entities)`	`delete ... where id in (...)` 1회	동작 안 함	중간
`deleteAllInBatch()`	`delete from ...` 1회 (전체)	동작 안 함	높음

"빠르다"는 이유로 deleteAllInBatch를 남용하면 감사 로그나 cascade에 의존하던 도메인 로직이 조용히 무력화된다. 이 메서드는 테스트 픽스처 정리나 명확히 전체 정리가 목적인 배치에서만 쓰는 편이 안전하다.

10) 트랜잭션 경계와 Service @Transactional

@Modifying 메서드는 트랜잭션이 필수라고 §1에서 짚었다. 여기에 숨은 함정이 있다. Service 계층에 @Transactional을 안 달고 Repository의 @Modifying 메서드만 바로 호출해도 예외가 안 난다는 점이다.

// Service — @Transactional 없음
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepo;

    public void closeOld(LocalDateTime cutoff) {
        orderRepo.closeOldOrders(Status.CLOSED, cutoff);
        // 동작은 한다. 그런데 안전하지 않다.
    }
}

왜 동작하는가. SimpleJpaRepository의 기본 구현에 @Transactional이 이미 걸려 있기 때문이다. Repository 메서드가 트랜잭션을 열고, 메서드가 끝나면 닫는다. TransactionRequiredException이 안 나는 이유다.

문제는 경계가 Repository 메서드 한 번으로 끝난다는 것이다. Service에서 벌크 쿼리 전후로 다른 작업을 섞으면, 그 작업은 벌크 쿼리와 다른 트랜잭션에서 실행된다.

// 피하기
public void badFlow(LocalDateTime cutoff) {
    User u = userRepo.findById(1L).orElseThrow();  // 트랜잭션 1
    u.setNickname("kim");                           // 트랜잭션 1 (사실상 안 열림, OSIV 아니면)
    userRepo.bulkSomething(cutoff);                 // 트랜잭션 2
    someOtherRepo.save(...);                        // 트랜잭션 3
}

이 흐름은 원자성을 포기한 상태다. 벌크 쿼리는 성공했는데 그 다음 save가 실패하면 복원이 안 된다. "당연히 같이 묶였을 것"이라는 기대가 무너진다.

// 선호
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepo;

    @Transactional   // Service에서 명시적으로 경계를 연다
    public void closeOld(LocalDateTime cutoff) {
        orderRepo.closeOldOrders(Status.CLOSED, cutoff);
        // 이후 작업도 같은 트랜잭션에 묶인다
    }
}

규칙은 단순하다. Repository의 내부 트랜잭션에 의존하지 말고, 호출측 Service에 @Transactional을 명시한다. 이 규칙을 따르면 벌크 쿼리 전후의 모든 작업이 한 트랜잭션으로 묶이고, 원자성과 clearAutomatically의 효과가 예측 가능한 범위에 들어온다.

10-1) 읽기 전용과 쓰기의 경계 분리

조회 서비스와 쓰기 서비스를 분리하는 규율이 도움이 된다. 조회는 @Transactional(readOnly = true), 쓰기는 기본 @Transactional이다. @Modifying 메서드는 쓰기 경로에만 등장해야 하고, readOnly = true 트랜잭션 안에서 @Modifying을 부르면 Hibernate가 런타임에 거부하지는 않지만 의도와 맞지 않는 흐름이다. 리뷰어가 잡기 쉽도록 경계를 명시적으로 나눠두자.

10-2) 내부 호출과 프록시 우회

@Transactional은 AOP 프록시로 작동한다. 같은 클래스 내부에서 this.method() 로 호출하면 프록시를 거치지 않아 트랜잭션이 열리지 않는다. 아래 코드는 흔한 함정이다.

// 피하기 — 내부 호출로 @Transactional 우회
@Service
public class OrderService {

    public void publicEntry(LocalDateTime cutoff) {
        this.doBulk(cutoff);   // self-invocation: 프록시 우회
    }

    @Transactional
    public void doBulk(LocalDateTime cutoff) {
        orderRepo.closeOldOrders(Status.CLOSED, cutoff);
    }
}

publicEntry가 호출될 때 트랜잭션은 열리지 않고, doBulk의 @Transactional은 무시된다. @Modifying 메서드가 자체 트랜잭션으로 떨어지거나(SimpleJpaRepository 기본), 전파 설정에 따라 예외가 난다. 해결은 트랜잭션이 필요한 메서드를 외부 진입점으로 만들고, 내부에서 트랜잭션을 여는 우회가 필요하면 별도 빈으로 분리하거나 AopContext.currentProxy() 또는 자기 자신 주입 같은 트릭을 쓰는 것이다. 가장 깔끔한 건 진입점 자체를 트랜잭션 경계로 삼는 설계다.

11) 실무에서 이렇게 읽고 쓴다

@Modifying의 기본값은 clearAutomatically = true, flushAutomatically = true라고 몸에 새겨두자. 쓰기 쿼리를 뒤이어 조회하는 경로가 없어도 켜서 나쁠 것이 없고, 누락이 만드는 stale 버그는 디버깅 비용이 크다
Service 계층에 **명시적 @Transactional**을 붙여 Repository 내부 트랜잭션에 의존하지 말 것. 벌크 쿼리 전후가 한 트랜잭션에 묶여야 원자성과 clear의 효과가 예측된다
벌크 UPDATE 이후에도 같은 트랜잭션에서 해당 엔티티를 계속 써야 한다면, clearAutomatically 대신 em.refresh(entity) 또는 findById로 재조회하는 편이 안전하다. clear는 1차 캐시 전체를 비우므로 다른 변경까지 같이 날아간다는 점을 잊지 말 것
네이티브 벌크 쿼리는 @SQLRestriction, @Filter, 상속 디스크리미네이터가 적용되지 않는다. soft-delete를 쓰는 도메인이면 네이티브 UPDATE/DELETE는 WHERE 절에 deleted = false를 수동으로 포함하는 걸 코드 리뷰 체크리스트에 넣는다 (40편)
@Version을 쓰는 엔티티의 벌크 UPDATE는 반드시 버전을 함께 올리자. update versioned 또는 SET o.version = o.version + 1. 안 그러면 낙관적 락이 있어도 없는 것과 같다 (39편)
deleteAllInBatch() (인자 없는 버전)는 운영 Repository에서 숨기거나 아예 사용 금지로 규율한다. 테스트 픽스처 정리 경로에서만 제한적으로 허용
대량 삭제는 deleteAllInBatch(Iterable)의 IN 절 크기에 주의한다. Oracle은 IN 절 1000개 한도가 있고, MySQL/PostgreSQL도 실용상 수천 개가 한계다. 더 크면 청크 단위로 쪼갠다
파생 deleteByXxx가 느리다고 느껴지면 @Modifying DELETE로 바꾸기 전에 cascade와 이벤트 리스너 의존성을 먼저 점검한다. 이 의존성이 살아 있어야 하는 경로면 파생 메서드가 맞고, 아니면 @Modifying이 맞다

11-1) 테스트에서 stale 엔티티 잡기

@Modifying 플래그 누락은 유닛 테스트로도 잘 드러나지 않는다. 단위 테스트는 단일 메서드만 호출하고 끝나는 경우가 많아 "벌크 이후 같은 트랜잭션에서 다시 조회"라는 시나리오 자체가 만들어지지 않기 때문이다. 회귀 방지는 통합 테스트에서 의도적으로 그 흐름을 재현한다.

@SpringBootTest
@Transactional
class OrderBulkIT {

    @Autowired OrderRepository orderRepo;
    @PersistenceContext EntityManager em;

    @Test
    void 벌크_UPDATE_후_조회가_최신값을_반환한다() {
        // given
        Order o = orderRepo.save(new Order(Status.OPEN));
        em.flush();

        // when
        orderRepo.bulkClose(o.getCreatedAt().plusDays(1));

        // then — stale이면 여기서 터진다
        Order reloaded = orderRepo.findById(o.getId()).orElseThrow();
        assertThat(reloaded.getStatus()).isEqualTo(Status.CLOSED);
    }
}

@Modifying(clearAutomatically = true)가 빠져 있으면 reloaded는 1차 캐시에서 나와 Status.OPEN을 돌려준다. 이 테스트가 그 순간 빨갛게 뜨므로 PR 단계에서 누락이 잡힌다. 테스트 안에서 em.clear()를 직접 부르지 말 것이 핵심이다. em.clear()를 부르면 프로덕션 코드의 플래그 누락이 가려진다.

11-2) 대량 처리의 청크 분할

Oracle의 IN 절 1000개 제한 외에도, 수만 건 이상의 벌크 DELETE는 트랜잭션 로그와 락 범위를 급격히 키운다. 같은 트랜잭션에 10만 건 DELETE가 통째로 묶이면 다른 커넥션의 조회가 블로킹되거나 테이블 레벨 락이 길어진다. 실무에서는 청크 분할로 피한다.

@Service
@RequiredArgsConstructor
public class OrderCleanupService {

    private final OrderRepository orderRepo;

    public int cleanupChunked(LocalDateTime cutoff, int chunkSize) {
        int total = 0;
        int deleted;
        do {
            deleted = deleteChunk(cutoff, chunkSize);
            total += deleted;
        } while (deleted > 0);
        return total;
    }

    @Transactional
    protected int deleteChunk(LocalDateTime cutoff, int chunkSize) {
        return orderRepo.deleteOldOrdersLimit(cutoff, chunkSize);
    }
}

Repository 쪽은 LIMIT 문법이 DB에 따라 다르므로 네이티브로 적는 경우가 많다.

@Modifying(clearAutomatically = true)
@Query(value = """
    delete from orders
    where created_at < ?1
    limit ?2
    """, nativeQuery = true)
int deleteOldOrdersLimit(LocalDateTime cutoff, int limit);

청크마다 트랜잭션을 나누는 설계는 중간 실패 시 이미 삭제된 row를 되살리지 못한다는 트레이드오프가 있다. "전체 원자성"과 "운영 중 블로킹 최소화" 중 후자가 더 중요한 도메인(로그, 만료 세션, 감사 기록)에서는 청크 분할이 기본이다.

12) 한 줄 정리

@Modifying의 두 플래그 clearAutomatically / flushAutomatically는 기본값 false이고, 이걸 모른 채 벌크 쿼리를 쓰는 순간 영속성 컨텍스트와 DB가 다른 진실을 들고 있게 된다. 벌크 쿼리는 1차 캐시를 우회하도록 설계된 동작이므로 플래그로 수동 동기화를 걸어야 하고, 네이티브 쿼리는 @SQLRestriction/@Version까지 전부 수동으로 챙겨야 한다. 파생 deleteByXxx와 @Modifying DELETE는 이름이 비슷해도 완전히 다른 경로이며, cascade와 이벤트 의존성을 기준으로 갈라서 선택한다.

태그: Spring Data JPA, @Modifying, 벌크 쿼리, 영속성 컨텍스트, clearAutomatically, flushAutomatically, JPQL, Native Query, @Version, deleteAllInBatch

Hibernate StatelessSession과 ScrollableResults — 대량 처리에서 영속성 컨텍스트를 버리는 선택

dding-shark — Tue, 21 Apr 2026 20:30:12 +0900

Hibernate StatelessSession과 ScrollableResults — 대량 처리에서 영속성 컨텍스트를 버리는 선택

들어가며

100만 건짜리 정산 데이터를 하룻밤에 털어넣어야 하는 일이 생긴다. for 루프 안에서 memberRepository.save(...)를 돌리다 보면 어느 순간 힙이 차고 GC가 폭주하다가 끝내 OOM으로 멈춘다. "그러면 중간에 flush() + clear()를 섞으면 되잖아"라는 조언이 따라 나오고, 그걸 넣으면 메모리는 버티는데 이번엔 @PrePersist가 느리게 불리고, 이벤트 리스너가 중간에서 자기 할 일을 한다. 속도가 기대만큼 안 나온다. 이 지점에서 Hibernate는 영속성 컨텍스트를 통째로 버리는 선택지를 준비해 뒀다. 그 이름이 StatelessSession이고, 읽기 쪽 짝이 ScrollableResults다.

이 글은 12편 영속성 컨텍스트와 @Transactional의 대량 처리 관점 속편이다. 12편은 "트랜잭션 경계 안에서 EntityManager가 무슨 일을 하는지"를 그렸고, 여기서는 그 EntityManager를 내려놓거나 우회해야 하는 상황을 본다. 일반 Session이 들고 있는 세 가지 기능(1차 캐시·Dirty Checking·Write-Behind)은 100건짜리 트랜잭션에서는 편리함이지만, 100만 건짜리 배치에서는 전부 부담이 된다. 그 부담을 벗기로 결정했을 때 써야 하는 도구를 정리한다.

100만 건 insert에서 OOM — 1차 캐시 clear를 빠뜨려 엔티티가 힙에 쌓인다
StatelessSession으로 insert 했는데 BaseEntity의 @PrePersist가 안 불린다 — JPA Entity Listener가 우회된다
Stream<Order> Repository 메서드가 커서를 못 열고 전체 로딩된다 — @Transactional이 빠져 있다
MySQL에서 ScrollableResults가 스트리밍이 아니라 전체 로드한다 — FETCH_SIZE=Integer.MIN_VALUE가 필요하다

이 글은 왜 → 구조 → 도구별 선택지 → 드라이버 제약 → 이벤트·캐시 상호작용 → 실무 순으로, Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x (jakarta.persistence) 기준으로 정리한다.

1) 100만 건 처리가 왜 힘든가
2) 일반 Session의 메모리 구조 복습
3) StatelessSession 개요: 잃는 것과 얻는 것
4) StatelessSession의 네 가지 메서드
5) 대량 Insert 패턴 비교: 일반 Session vs StatelessSession
6) ScrollableResults: 커서 기반 스트리밍 조회
7) Stream Entity: Spring Data JPA 스타일
8) 드라이버별 ScrollableResults 제약: MySQL과 PostgreSQL
9) Entity Listener와 2차 캐시와의 상호작용
10) Spring Batch의 ItemWriter와 어떻게 맞물리나
11) 실무에서 이렇게 읽고 쓴다
12) 한 줄 정리

1) 100만 건 처리가 왜 힘든가

대량 처리의 "힘듦"은 크게 두 축에서 온다. 메모리와 오버헤드다. 메모리 축은 "엔티티가 힙에 쌓여서 OOM이 난다", 오버헤드 축은 "건당 부가 작업이 누적돼서 TPS가 안 나온다". 둘 다 일반 Session(=EntityManager)이 제공하는 기능이 원인이 된다. 즉, 평소에는 편리함이었던 것이 수량이 커지면 그대로 비용으로 전환된다. 이 전환 지점을 이해하는 것이 이 글 전체의 출발선이다.

구체적으로 건당 쌓이는 비용을 나열하면 이렇다. 엔티티 하나를 persist 할 때마다 (1) 1차 캐시에 인스턴스가 들어가고, (2) 필드 스냅샷이 한 부 더 복사되고, (3) action queue에 INSERT 액션이 적재되고, (4) @PrePersist·Envers·이벤트 리스너가 순서대로 돌고, (5) 2차 캐시가 켜져 있으면 캐시 정합성 처리가 뒤따른다. 건당 얼마 안 돼 보이지만 100만 번이면 힙에 100만 세트가 쌓인다.

일반 Session 건당 비용	100만 건 환산
엔티티 인스턴스 (1차 캐시)	100만 인스턴스 상주
스냅샷 필드 사본	엔티티 크기 × 100만
action queue 엔트리	큐 길이 100만
이벤트 리스너 호출	리스너 수 × 100만
2차 캐시 put/invalidate	캐시 put 100만

여기서 flush() + clear()를 주기적으로 섞으면 (1)·(2)·(3)은 주기마다 비워진다. 하지만 (4)·(5)는 호출 횟수 자체가 줄지 않는다. 이벤트 리스너가 무거운 프로젝트(감사 로그, 도메인 이벤트 발행)일수록 flush/clear 패턴의 개선폭이 기대보다 작다. 이 한계를 벗어나려면 건당 비용 자체를 줄이는 도구가 필요하다. 그게 StatelessSession이다.

한편 조회 쪽에도 같은 문제가 있다. 100만 row짜리 findAll()을 호출하면 JDBC 드라이버가 전체 결과를 메모리에 올린 뒤 Hibernate가 그걸 엔티티로 물들여 1차 캐시에 쌓는다. DB 커서로 천천히 흘려보내는 스트리밍이 필요하다 — 그게 ScrollableResults 쪽이다.

2) 일반 Session의 메모리 구조 복습

StatelessSession을 이해하려면 먼저 버릴 대상이 무엇인지 정확히 알아야 한다. 일반 Session이 가진 세 가지 기능을 12편 §1~§6에서 다뤘으니 간단히 되짚기만 한다. 1차 캐시, Dirty Checking(스냅샷), Write-Behind(action queue). 이 셋은 한 덩어리로 묶여 있고, 한 덩어리가 org.hibernate.Session의 영속성 컨텍스트다.

이 그림이 이 글 나머지 전부의 밑그림이다. 일반 Session은 엔티티 한 건을 받으면 그 건에 대한 다섯 개의 자료구조와 후크가 함께 움직인다. 편리하지만 건당 비용이 크고, 상주 메모리가 엔티티 수에 선형으로 증가한다. 반대편의 StatelessSession은 이 다섯을 전부 안 쓴다. 엔티티가 들어오면 즉시 SQL로 변환해서 JDBC에 넘기고 잊는다. 건당 비용이 SQL 실행 비용으로만 남는다.

"그러면 일반 Session을 쓰면서 flush/clear만 잘 해도 되지 않나"라는 질문이 당연히 나온다. 여기서 틀리기 쉽다. flush/clear는 (1)·(2)·(3)만 턴다. 이벤트 리스너 호출 횟수 자체는 줄지 않고, 스냅샷을 "찍었다가 비우는" 작업이 반복적으로 일어나 CPU도 절약이 크지 않다. 정말로 단순한 insert/update/delete라면 StatelessSession 쪽이 한 단계 더 싸다는 것이 핵심이다.

3) StatelessSession 개요: 잃는 것과 얻는 것

StatelessSession은 이름 그대로 상태가 없는 세션이다. Hibernate 공식 표현으로는 "a command-oriented API" — "명령 지향 API"다. 엔티티 객체를 "관리"하는 대신, 호출자가 insert/update/delete를 명시적으로 지시하면 그대로 SQL로 변환해서 즉시 보낸다. JDBC 한 꺼풀 위의 얇은 레이어라고 보면 가깝다.

// Spring Boot 3.x에서 StatelessSession 획득
@Autowired
private EntityManagerFactory emf;

public void bulkInsert(List<User> users) {
    SessionFactory sf = emf.unwrap(SessionFactory.class);
    try (StatelessSession ss = sf.openStatelessSession()) {
        Transaction tx = ss.beginTransaction();
        try {
            for (User u : users) {
                ss.insert(u);   // 즉시 INSERT
            }
            tx.commit();
        } catch (Exception e) {
            tx.rollback();
            throw e;
        }
    }
}

"얻는 것"부터 보자. 힙 상주량이 엔티티 수에 무관해진다. 스냅샷을 안 찍으니 CPU도 덜 쓴다. action queue를 안 타니 flush 시 일괄 처리 로직이 건너뛰어진다(단, JDBC 레벨 배치는 hibernate.jdbc.batch_size로 여전히 먹는다). 2차 캐시의 put/invalidate 비용도 없다. 종합하면 단순 CRUD의 건당 최소 비용에 수렴한다.

"잃는 것"이 더 길다. 표로 정리한다.

기능	일반 Session	StatelessSession
1차 캐시	O	X
Dirty Checking	O	X (insert/update 수동 호출)
Write-Behind	O	X (즉시 실행)
cascade	O	X (자식 엔티티 수동 insert)
JPA Entity Listener (`@PrePersist` 등)	O	X
Hibernate 이벤트	O	일부만
2차 캐시	O (put/invalidate)	X (우회)
Lazy 프록시	O	X (프록시 초기화 불가)

이 표의 함의가 큰 항목 두 개만 더 풀자. cascade가 작동 안 한다는 말은, Order 한 건을 insert할 때 자식 OrderItem들을 자동으로 넣어주지 않는다는 뜻이다. 호출자가 부모 insert 후 자식들을 각각 ss.insert(item)으로 돌려야 한다. 연관관계가 복잡한 도메인이라면 배치 코드가 도메인 로직을 재구성하는 꼴이 되므로, 이 비용을 받아들일 수 있는지 먼저 판단해야 한다.

JPA Entity Listener가 안 불린다는 항목은 특히 @EntityListeners(AuditingEntityListener.class) 또는 @PrePersist로 createdAt·updatedAt을 자동 세팅하는 프로젝트에서 크게 다가온다. StatelessSession으로 넣은 행은 createdAt이 null로 들어간다. 수동으로 세팅해 주거나, @PrePersist 대신 DB의 DEFAULT CURRENT_TIMESTAMP로 바꿔 두는 우회가 필요하다. 뒤 §9 Entity Listener와 2차 캐시와의 상호작용에서 다시 본다.

4) StatelessSession의 네 가지 메서드

StatelessSession이 제공하는 쓰기 메서드는 네 개다. 이름 그대로 읽으면 의미가 선명하다.

메서드	의미	비고
`insert(entity)`	INSERT 즉시	`batch_size`로 JDBC 배치 가능
`update(entity)`	UPDATE 즉시	모든 필드로 UPDATE
`delete(entity)`	DELETE 즉시	`@Id` 기준
`upsert(entity)`	MERGE 즉시	Hibernate 6.3+, DB 지원 필요

update는 12편에서 본 Dirty Checking이 아니라 "호출 시점에 전달받은 엔티티 전체 필드로 UPDATE를 만든다"는 의미다. 어떤 필드가 바뀌었는지 Hibernate가 알 방법이 없으므로(스냅샷이 없음), 기본적으로 모든 필드를 UPDATE한다. @DynamicUpdate는 StatelessSession에서는 의미를 가지지 않는다는 점도 참고해 두자.

upsert는 Hibernate 6.3에서 들어온 비교적 새 메서드다. 내부적으로 DB의 MERGE 구문(또는 ON CONFLICT)을 사용해 "있으면 UPDATE, 없으면 INSERT"를 단일 SQL로 처리한다. 주의할 점은 DB가 MERGE를 지원해야 한다는 것이고, MySQL처럼 직접 지원이 없으면 Hibernate가 대체 전략(예: ON DUPLICATE KEY UPDATE)을 쓴다. 대상 DB의 방언(Dialect)이 어떤 SQL을 생성하는지 한 번 로그로 확인해 두는 편이 안전하다.

StatelessSession으로 조회도 가능하다. createQuery, get(Class, id) 같은 메서드가 있고, JPQL도 돌아간다. 결과 엔티티는 detached 상태로 돌아오고, 동일성 보장도 없다(같은 ID를 두 번 조회하면 다른 인스턴스가 반환된다). 이 점이 12편 §4의 "1차 캐시 동일성"과 크게 달라지는 지점이다.

// 피하기: StatelessSession에서 동일성 기대
try (StatelessSession ss = sf.openStatelessSession()) {
    User a = ss.get(User.class, 1L);
    User b = ss.get(User.class, 1L);
    assert a == b;   // false. 매번 새 SELECT + 새 인스턴스
}

// 선호: 대량 스트리밍용으로만 쓰고, 단건 조회/수정은 일반 EntityManager

StatelessSession은 "같은 엔티티 그래프를 여러 번 읽고 고치는" 흐름에는 부적합하다. 한 방향 스트림(읽으면 쓰거나, 읽으면 잊거나)에 맞춰 설계돼 있다고 기억하면 된다.

5) 대량 Insert 패턴 비교: 일반 Session vs StatelessSession

구체적인 코드 두 벌로 체감해 보자. 10만 건을 넣는다고 가정한다.

5-1) 일반 EntityManager + flush/clear

@Service
public class BulkInsertService {

    @PersistenceContext
    private EntityManager em;

    @Transactional
    public void bulkInsertViaEm(List<UserRow> rows) {
        int batchSize = 100;   // hibernate.jdbc.batch_size와 맞춤
        for (int i = 0; i < rows.size(); i++) {
            em.persist(toEntity(rows.get(i)));
            if (i % batchSize == 0 && i > 0) {
                em.flush();    // action queue → JDBC 배치
                em.clear();    // 1차 캐시 비움
            }
        }
    }
}

이 코드의 동작을 12편 §6 Write-Behind 관점으로 풀면 이렇다. persist 100번이 action queue에 쌓이고, flush에서 JDBC 배치로 묶여 나가고, clear로 1차 캐시가 비워진다. 이걸 1000번 반복해서 10만 건을 넣는다. 메모리는 버티고, 배치 INSERT도 먹는다. 하지만 건당 스냅샷이 한 번 찍혔다가 비워지고, @PrePersist가 건마다 호출되고, 2차 캐시가 켜져 있으면 건마다 put이 일어난다.

주의: @GeneratedValue(strategy = IDENTITY)를 쓰는 엔티티라면 12편 §6에서 본 대로 배치 INSERT가 먹지 않는다. persist 시점에 ID를 받기 위해 즉시 SQL을 보낸다. 배치를 쓰려면 SEQUENCE 전략(또는 수동 할당)이어야 한다. MySQL처럼 시퀀스가 없는 DB에서는 수동 할당 + rewriteBatchedStatements=true로 우회한다.

5-2) StatelessSession

@Service
public class BulkInsertService {

    @Autowired
    private EntityManagerFactory emf;

    public void bulkInsertViaStateless(List<UserRow> rows) {
        SessionFactory sf = emf.unwrap(SessionFactory.class);
        try (StatelessSession ss = sf.openStatelessSession()) {
            Transaction tx = ss.beginTransaction();
            try {
                for (UserRow r : rows) {
                    User u = toEntity(r);
                    u.setCreatedAt(Instant.now());   // @PrePersist 안 불리므로 수동 세팅
                    ss.insert(u);                    // 즉시. batch_size=100이면 내부 배치
                }
                tx.commit();
            } catch (Exception e) {
                tx.rollback();
                throw e;
            }
        }
    }
}

두 가지만 지적한다. 첫째, @Transactional이 없다. StatelessSession은 Spring의 JpaTransactionManager와 묶이지 않는다 — 자체 Transaction 객체로 트랜잭션 경계를 관리한다. @Transactional 메서드 안에서 openStatelessSession을 열면 바깥 트랜잭션과 같은 JDBC 커넥션을 공유하지 않는다. 동일 커넥션이 필요하면 sf.openStatelessSession(conn) 오버로드로 명시적으로 커넥션을 넘겨주는 패턴을 써야 한다.

둘째, createdAt을 수동으로 세팅했다. @PrePersist가 우회되기 때문에 AuditingEntityListener도 BaseEntity의 @PrePersist도 실행되지 않는다. 이 자리가 실무에서 놓치기 쉬운 함정이다. 이어지는 §9 Entity Listener와 2차 캐시와의 상호작용에서 대안을 정리한다.

5-3) 비교

항목	일반 EM + flush/clear	StatelessSession
메모리 상주	batchSize 만큼	거의 0
스냅샷 비용	건당 발생	없음
action queue	사용	우회
JDBC 배치	`batch_size` + 전략에 따라	`batch_size`로 가능
`@PrePersist`	동작	비동작
cascade	동작	비동작
`@Transactional` 연동	자연스럽게 됨	수동 관리
권장 시나리오	복잡한 도메인 배치	단순 대량 insert/update/delete

단순하면 StatelessSession, 복잡하면 일반 EM + flush/clear. 이 한 줄이 선택 기준의 뼈대다. "단순"의 기준이 애매하면 체크리스트로 내려본다 — cascade 없이 부모만 있나, Entity Listener가 필요 없나, 2차 캐시에 의존 안 하나. 셋 다 "그렇다"면 StatelessSession이 훨씬 싸다.

6) ScrollableResults: 커서 기반 스트리밍 조회

조회 쪽 짝이 ScrollableResults다. DB 커서를 열어 둔 채로 row를 한 건씩 애플리케이션으로 흘려보낸다. Hibernate의 org.hibernate.query.Query에서 scroll() 메서드로 얻는다.

@Service
public class OrderProcessor {

    @PersistenceContext
    private EntityManager em;

    @Transactional(readOnly = true)
    public void processAll() {
        org.hibernate.query.Query<Order> q = em
            .createQuery("SELECT o FROM Order o WHERE o.status = :s", Order.class)
            .setParameter("s", Status.PENDING)
            .unwrap(org.hibernate.query.Query.class);

        q.setFetchSize(1000);

        try (ScrollableResults<Order> scroll = q.scroll(ScrollMode.FORWARD_ONLY)) {
            int i = 0;
            while (scroll.next()) {
                Order o = scroll.get();
                process(o);
                if (++i % 1000 == 0) {
                    em.flush();
                    em.clear();   // 1차 캐시 비움
                }
            }
        }
    }
}

핵심 파라미터는 두 개다. setFetchSize(1000)은 "JDBC 드라이버가 DB에서 한 번에 끌어올 row 수"다. ScrollMode.FORWARD_ONLY는 "커서가 앞으로만 간다"는 뜻으로, 가장 효율적인 모드다. Hibernate는 다른 모드(SCROLL_INSENSITIVE, SCROLL_SENSITIVE)도 지원하지만 DB·드라이버별 제약이 크고 대부분 FORWARD_ONLY로 충분하다.

여기서 틀리기 쉽다. ScrollableResults는 DB 쪽 메모리를 절약하는 게 아니다. DB는 일반 SELECT와 똑같이 결과 집합을 만든다. 다만 애플리케이션 쪽 JDBC 드라이버가 결과를 한꺼번에 받지 않고 fetchSize만큼씩 나눠 받는다. 그래서 애플리케이션 힙을 절약하는 효과가 핵심이다. 그리고 커서가 열려 있는 동안 트랜잭션이 살아 있어야 한다 — @Transactional(readOnly = true)이 반드시 필요하다.

또 하나, em.clear()가 없으면 스트리밍이 무의미해진다. 1000건을 받고 나면 그 1000건이 1차 캐시에 쌓인 채로 다음 1000건이 온다. 엔티티는 계속 누적되고 결국 OOM이다. "커서는 DB 스트리밍이지만 엔티티는 EntityManager에 쌓인다"는 게 처음엔 잘 안 그려지는데, 한 번 OOM을 맞으면 확실히 기억에 남는다. §8 드라이버별 ScrollableResults 제약: MySQL과 PostgreSQL에서 한 번 더 나온다.

ScrollableResults를 StatelessSession과 묶으면 어떨까. 가능하다. StatelessSession은 clear가 필요 없으니 스트리밍 코드가 더 단순해진다. 대신 엔티티가 detached 상태로 오므로 lazy 필드 접근은 불가능하다. 읽기 전용으로 "row → 가공 → 다른 저장소" 같은 흐름에 잘 맞는다.

try (StatelessSession ss = sf.openStatelessSession()) {
    org.hibernate.query.Query<Order> q = ss
        .createQuery("SELECT o FROM Order o WHERE o.status = :s", Order.class)
        .setParameter("s", Status.PENDING);
    q.setFetchSize(1000);
    try (ScrollableResults<Order> scroll = q.scroll(ScrollMode.FORWARD_ONLY)) {
        while (scroll.next()) {
            process(scroll.get());
            // em.clear() 불필요
        }
    }
}

7) Stream Entity: Spring Data JPA 스타일

Spring Data JPA는 ScrollableResults를 감싼 더 자바다운 API를 준비해 뒀다. Stream<Entity>를 반환하는 Repository 메서드다.

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT o FROM Order o WHERE o.status = :s")
    Stream<Order> streamByStatus(@Param("s") Status s);
}

사용 코드는 try-with-resources로 스트림을 닫아야 한다. 스트림을 닫으면 내부 ScrollableResults가 닫히고, 커서와 결과집합이 해제된다. 닫지 않으면 커넥션이 반환되지 않아 풀이 말라간다.

@Service
public class OrderService {

    @Autowired
    private OrderRepository orderRepo;

    @Autowired
    private EntityManager em;

    @Transactional(readOnly = true)
    public void processPending() {
        try (Stream<Order> stream = orderRepo.streamByStatus(Status.PENDING)) {
            int[] i = {0};
            stream.forEach(order -> {
                process(order);
                if (++i[0] % 1000 == 0) {
                    em.clear();
                }
            });
        }
    }
}

세 가지 포인트. 첫째, @Transactional(readOnly = true)가 반드시 메서드에 있어야 한다. 커서가 트랜잭션 수명에 묶여 있으므로, 트랜잭션 밖에서 스트림을 돌리면 예외가 터지거나(드라이버/설정에 따라) 아예 전체 로딩으로 떨어진다. 둘째, try-with-resources로 스트림을 닫는다. Spring Data의 Stream은 커서를 품고 있는 자원이므로 Java Stream의 close() 규약을 지켜야 한다. 셋째, em.clear()를 주기적으로 호출한다 — §6 ScrollableResults: 커서 기반 스트리밍 조회의 이유와 동일.

Stream<Entity>는 내부적으로 ScrollableResults를 쓰므로 드라이버 제약도 그대로 상속된다. MySQL에서 스트리밍이 안 되면 Stream도 안 된다. 다음 절에서 본다.

8) 드라이버별 ScrollableResults 제약: MySQL과 PostgreSQL

ScrollableResults와 Stream<Entity>의 가장 큰 함정이 드라이버 설정이다. Hibernate가 "스트리밍 쿼리"라고 마크해도, JDBC 드라이버가 실제로 커서 페치로 동작하는지는 드라이버마다 조건이 다르다.

8-1) MySQL (mysql-connector-j)

MySQL JDBC 드라이버는 기본적으로 전체 결과를 메모리에 올린다. 스트리밍을 하려면 두 방법 중 하나를 쓴다.

1. Statement.setFetchSize(Integer.MIN_VALUE)
   → 순수 JDBC 스트리밍 모드. 커서 없이 row 단위로 흘려받음.
   → Hibernate 6에서는 setFetchSize에 특수값을 줘야 발동.

2. useCursorFetch=true (커넥션 URL) + setFetchSize(N>0)
   → 서버 측 커서를 쓴다. 드라이버가 배치별로 가져옴.

1번은 "결과집합 전체를 한 번에 건내지 않고 row 하나씩 네트워크로 스트림"하는 옵션이다. Hibernate에서 이걸 쓸 때는 쿼리 레벨로 query.setFetchSize(Integer.MIN_VALUE)를 부르는 방식을 기본으로 둔다. 전역 프로퍼티 hibernate.jdbc.fetch_size=Integer.MIN_VALUE를 걸어도 동작은 하지만, 그 순간 모든 쿼리가 스트리밍 모드로 바뀌어 커넥션 잠금 범위가 전역으로 넓어진다. 커서가 열려 있는 동안 해당 커넥션에서는 다른 쿼리를 동시에 실행할 수 없으므로, 배치 경로에만 국소적으로 걸어 두는 편이 안전하다.

2번은 JDBC URL에 useCursorFetch=true를 붙이고 fetchSize를 양수로 지정하는 방식이다. 서버 측 커서를 사용하므로 1번보다 범용적이지만, DB 쪽 리소스를 더 쓴다.

# application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/app?useCursorFetch=true&rewriteBatchedStatements=true
  jpa:
    properties:
      hibernate:
        jdbc:
          fetch_size: 1000

rewriteBatchedStatements=true는 42편에서 본 배치 INSERT용 옵션이지만, useCursorFetch와 충돌하지 않으므로 같이 써도 된다. "읽기도 쓰기도 스트리밍"이 되는 접속 URL을 만드는 게 목표다.

8-2) PostgreSQL (pgjdbc)

PostgreSQL은 다르게 생겼다. fetchSize > 0이면 자동으로 서버 측 커서를 연다. 추가 URL 옵션이 필요 없다. 단 한 가지 조건이 있다: autoCommit이 false여야 한다. autoCommit 상태에서 커서를 열면 커밋 즉시 커서가 닫혀버리므로 배치 페치가 의미를 잃는다.

스프링에서는 @Transactional 메서드 안에서 실행하면 자동으로 autoCommit이 false가 되므로, 트랜잭션 경계를 제대로 그어 두면 설정만으로 스트리밍이 붙는다. 트랜잭션 없이 Repository의 Stream 메서드를 호출하는 실수가 가장 흔한 사고 지점이다.

8-3) 드라이버 제약 요약

DB	조건	설정 예
MySQL	`fetchSize = Integer.MIN_VALUE` (스트리밍)	`setFetchSize(Integer.MIN_VALUE)`
MySQL	`useCursorFetch=true` + `fetchSize > 0`	URL 옵션 + `setFetchSize(1000)`
PostgreSQL	`autoCommit=false` + `fetchSize > 0`	`@Transactional` + `setFetchSize(1000)`
Oracle	`fetchSize > 0`	`setFetchSize(1000)` (트랜잭션 권장)
H2	기본 지원	`setFetchSize(1000)`

여기서 틀리기 쉽다. "Hibernate 쪽에 setFetchSize만 주면 어떻게든 스트리밍 되겠지"는 착각이다. 드라이버가 실제로 커서/스트리밍 모드로 동작하는지 확인해야 한다. 확인 방법은 간단하다 — DB 쪽 프로파일러(MySQL performance_schema, PostgreSQL pg_stat_activity)에서 커서가 열리는지 보면 된다. 또는 아주 큰 테이블을 Stream으로 뽑을 때 JVM 힙 사용량을 모니터링해서, 메모리가 급격히 치솟으면 스트리밍이 안 되는 상태다.

9) Entity Listener와 2차 캐시와의 상호작용

StatelessSession이 우회하는 것 중에 가장 실무에 영향이 큰 둘이 JPA Entity Listener와 2차 캐시다. 각각 함정과 대응을 정리한다.

9-1) `@PrePersist`·`AuditingEntityListener`

BaseEntity에 @EntityListeners(AuditingEntityListener.class) + @CreatedDate + @LastModifiedDate로 자동 감사 필드를 쓰는 프로젝트가 많다. StatelessSession.insert는 이 리스너를 전혀 호출하지 않는다. 결과적으로 createdAt·updatedAt이 null로 들어간다. 제약조건 위반으로 실패하거나, 조용히 null이 박혀서 다음 날 장애로 드러난다.

// 피하기: 리스너에 의존한 채 StatelessSession 사용
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
abstract class BaseEntity {
    @CreatedDate private Instant createdAt;
    @LastModifiedDate private Instant updatedAt;
}

// StatelessSession에서 insert → createdAt == null

대응은 세 가지 중 하나다.

// 선호 1: 엔티티 생성 시점에 수동 세팅
User u = toEntity(r);
Instant now = Instant.now();
u.setCreatedAt(now);
u.setUpdatedAt(now);
ss.insert(u);

// 선호 2: DB DEFAULT로 옮기기
// CREATE TABLE user (
//   ...
//   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
// );
// 엔티티에서는 @Column(insertable = false) 또는 null 허용

// 선호 3: 대량 insert 대상 엔티티를 별도로 유지
// 감사 필드를 명시 필드로 (리스너 없이)

실무에서는 1번이 가장 흔하고 안전하다. 배치 경로에서만 필드를 명시적으로 세팅하면 일반 서비스 경로의 리스너는 그대로 살릴 수 있다.

Hibernate의 순수 이벤트 시스템(PreInsertEventListener 등)은 StatelessSession에서 일부 동작한다. 하지만 JPA 스펙이 정의한 @PrePersist·@PreUpdate·@PostLoad 같은 라이프사이클 콜백은 우회된다. 이 구분을 기억해 두자. "감사는 JPA 리스너", "물리적 인덱스 유지는 Hibernate 이벤트"라면 후자는 일부 살 수 있다는 뜻이다.

9-2) 2차 캐시

StatelessSession은 2차 캐시를 우회한다. insert·update·delete 어느 것도 캐시를 갱신하지 않고, get도 캐시를 읽지 않는다. 이 비대칭이 실무에서 stale 캐시 문제를 만든다.

[시나리오]
1. 일반 서비스 경로로 User(id=1)를 조회 → 2차 캐시에 적재
2. 배치가 StatelessSession으로 User(id=1)의 email을 UPDATE
3. 이후 일반 서비스 경로로 User(id=1) 조회 → 2차 캐시 hit → 옛 email 반환

대응은 배치 종료 후 캐시를 명시적으로 flush하는 것이다.

@Autowired
private EntityManagerFactory emf;

public void afterBulkUpdate() {
    SessionFactory sf = emf.unwrap(SessionFactory.class);
    sf.getCache().evictEntityData(User.class);   // 특정 엔티티만
    // 또는
    sf.getCache().evictAllRegions();              // 전체
}

덧붙여 배치 실행 중 CacheMode.IGNORE 같은 일반 Session 옵션은 StatelessSession에서 설정할 대상이 아니다 — StatelessSession은 애초에 캐시를 무시하는 모드이기 때문이다.

10) Spring Batch의 ItemWriter와 어떻게 맞물리나

Spring Batch는 청크(chunk) 단위로 "read → process → write"를 반복하는 프레임워크다. 재시작·스킵·재시도 같은 배치 특유의 요구를 지원한다. ItemWriter에 여러 구현이 있고, JPA 쪽은 두 가지가 흔하다.

JpaItemWriter — 기본적으로 EntityManager.merge + flush를 호출하고, usePersist=true 설정 시 persist로 전환된다. 즉 일반 Session + flush/clear 패턴.
JdbcBatchItemWriter — NamedParameterJdbcTemplate로 원시 SQL 배치. Hibernate를 거치지 않는다.

StatelessSession을 Spring Batch에서 쓰려면 **커스텀 ItemWriter**를 만들어야 한다. 공식 제공 writer에는 없다.

public class StatelessSessionItemWriter<T> implements ItemWriter<T> {

    private final SessionFactory sessionFactory;

    @Override
    public void write(Chunk<? extends T> chunk) {
        try (StatelessSession ss = sessionFactory.openStatelessSession()) {
            Transaction tx = ss.beginTransaction();
            try {
                for (T item : chunk) {
                    ss.insert(item);
                }
                tx.commit();
            } catch (Exception e) {
                tx.rollback();
                throw e;
            }
        }
    }
}

여기서 틀리기 쉽다. Spring Batch의 Step은 자체적으로 트랜잭션 경계를 관리한다(StepBuilder.chunk(size, transactionManager)). 그 트랜잭션과 StatelessSession의 내부 트랜잭션이 별개의 JDBC 커넥션으로 돌면, Step이 롤백해도 StatelessSession이 이미 커밋한 insert는 되돌아가지 않는다. 재시작 시 중복이 생길 수 있다.

해결은 같은 커넥션을 쓰게 하는 것이다.

// 선호: Step 트랜잭션과 같은 커넥션 사용
@Autowired
private DataSource dataSource;

@Override
public void write(Chunk<? extends T> chunk) throws SQLException {
    Connection conn = DataSourceUtils.getConnection(dataSource);
    try (StatelessSession ss = sessionFactory.openStatelessSession(conn)) {
        // Step의 트랜잭션 커넥션 재사용 → 바깥 트랜잭션에 얹힘
        for (T item : chunk) {
            ss.insert(item);
        }
        // tx.commit() 부르지 않음. Step이 커밋.
    }
}

sessionFactory.openStatelessSession(conn) 오버로드로 커넥션을 명시적으로 넘기면, StatelessSession이 자체 트랜잭션을 시작하지 않고 주어진 커넥션 위에서 동작한다. 이 패턴이 Spring Batch + StatelessSession의 정석이다.

선택지	장점	단점
`JpaItemWriter`	표준, 리스너 동작	느림, 메모리 부담
`JdbcBatchItemWriter`	가장 빠름	엔티티 매핑 따로
커스텀 `StatelessSessionItemWriter`	매핑 재사용 + 빠름	트랜잭션 연결 주의

**"단순 대량 insert는 StatelessSession, 복잡한 데이터 흐름/재시작 요구는 Spring Batch"**가 거친 기준이다. 둘을 결합해야 하는 상황(대량이면서도 재시작 필요)에서는 위의 커스텀 writer 패턴이 제일 현실적이다.

11) 실무에서 이렇게 읽고 쓴다

"이 배치에서 1차 캐시·Dirty Checking·Write-Behind 중 무엇이 필요한가"를 먼저 판단한다. 셋 다 필요 없다면 StatelessSession. 하나라도 필요하면 일반 EntityManager + flush/clear. 이 질문이 선택의 출발이다.
@PrePersist/@EntityListeners를 쓰는 엔티티를 StatelessSession으로 넣을 거면, 감사 필드를 수동 세팅하거나 DB DEFAULT로 내린다. null로 박혀서 조용히 장애가 되는 패턴을 한 번 맞아보면 다시는 안 잊는다.
ScrollableResults/Stream<Entity>를 쓰는 메서드에는 반드시 @Transactional(readOnly = true). 그리고 em.clear()를 주기적으로(보통 1000건) 부른다. "커서는 DB 쪽 스트림, 엔티티는 여전히 EM에 쌓인다"를 기억해 둔다.
MySQL에서 스트리밍이 안 된다면 fetchSize와 URL 옵션부터 본다. useCursorFetch=true 또는 Integer.MIN_VALUE 둘 중 하나가 필요하다. "설정만 바꾸면 공짜로 스트리밍"이 아니라, "드라이버가 어떤 모드로 돌고 있는지 확인"이 먼저다.
2차 캐시를 쓰는 프로젝트라면 StatelessSession으로 insert/update/delete 후 evictEntityData로 캐시를 털어준다. 안 털면 stale 응답이 다음 날 CS로 돌아온다.
Spring Batch와 묶을 때는 openStatelessSession(conn) 오버로드로 Step 트랜잭션 커넥션을 공유시킨다. 자체 트랜잭션을 열면 재시작 시 중복 insert 위험이 생긴다.
단건 조회·수정은 일반 EntityManager 그대로. StatelessSession은 "한 방향 대량 흐름"에만 꺼낸다. 같은 엔티티를 여러 번 고치는 흐름에서는 동일성 보장이 없어서 오히려 코드가 복잡해진다.

12) 한 줄 정리

StatelessSession은 영속성 컨텍스트의 세 기능(1차 캐시·Dirty Checking·Write-Behind)을 통째로 버리는 대신 건당 비용을 SQL 실행 비용에 수렴시키는 도구이고, 읽기 쪽 짝이 ScrollableResults·Stream<Entity>다. @PrePersist·cascade·2차 캐시가 모두 우회되므로, 이걸 대가로 받아들일 수 있는 단순 대량 흐름에서만 선택한다. 드라이버별 스트리밍 조건(MySQL useCursorFetch/Integer.MIN_VALUE, PostgreSQL autoCommit=false)을 확인하지 않으면 "스트리밍처럼 보이는 전체 로딩"이 된다는 점이 가장 자주 밟는 지뢰다.

태그: Hibernate, StatelessSession, ScrollableResults, Stream, Spring Data JPA, 배치, fetchSize, MySQL, Spring Batch, 2차 캐시

Hibernate Batch Insert/Update — JDBC batch와 영속성 컨텍스트가 만나는 지점

dding-shark — Tue, 21 Apr 2026 20:29:30 +0900

Hibernate Batch Insert/Update — JDBC batch와 영속성 컨텍스트가 만나는 지점

들어가며

"1만 건 insert가 20초 걸린다"는 리포트가 날아왔다. 로그를 열어 보니 INSERT가 정말로 1만 번 찍혀 있다. hibernate.jdbc.batch_size=100은 분명히 설정했는데, 배치로 묶여야 할 쿼리가 한 줄씩 순서대로 나가고 있다. 13편에서 다룬 N+1의 마지막에서 잠깐 언급한 "IDENTITY 전략은 JDBC batch insert를 비활성화한다"는 문장이 바로 이 장면이다. 이번 글은 그 문장을 본격적으로 풀어낸다.

Hibernate의 batch는 JDBC batch를 감싸는 상위 계층이다. 드라이버가 실제로 네트워크에 뭘 보내는지, Hibernate가 flush 시점에 무엇을 어떻게 모으는지, 그 사이에서 PK 생성 전략이나 @DynamicUpdate가 어떻게 batch를 깨는지를 순서대로 본다. 특히 다음 네 가지는 설정을 "맞췄다고 생각했는데" 실제로는 틀려 있는 경우가 압도적으로 많다.

batch_size=100 설정했는데 SQL이 여전히 row-by-row로 나간다 — PK가 GenerationType.IDENTITY라서 batch를 모을 수가 없다
MySQL 기본 설정에서 rewriteBatchedStatements 없이 batch 효과가 미미하다 — JDBC 레벨에서 batch는 만들어지지만 실제 네트워크에는 INSERT가 그대로 여러 번 나간다
batch 처리 중 OOM이 난다 — em.flush()만 호출하고 em.clear()를 빠뜨려 영속성 컨텍스트에 엔티티가 무한히 쌓인다
@DynamicUpdate를 붙인 엔티티는 batch로 묶이지 않는다 — 엔티티마다 UPDATE SQL 모양이 달라져 JDBC batch의 전제(같은 SQL 문자열) 자체가 깨진다

이 글은 JDBC batch의 기본 → Hibernate batch가 감싸는 방식 → 필수 설정 → IDENTITY 제약 → order_inserts/updates → 대량 persist 패턴 → 대량 update의 대안 → 드라이버별 옵션 → 측정 순으로 정리한다. Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x 기준이다.

1) 왜 row-by-row는 느린가: 네트워크 왕복의 누적
2) JDBC Batch의 기본: PreparedStatement.addBatch
3) Hibernate batch가 JDBC batch를 감싸는 방식
4) 필수 설정 3종: batch_size / order_inserts / order_updates
5) IDENTITY가 batch를 죽이는 이유
6) batch_versioned_data와 @DynamicUpdate 트레이드오프
7) 대량 persist: saveAll은 해답이 아니다, flush/clear 패턴
8) JPQL bulk UPDATE가 우선인 이유
9) JDBC 드라이버별 rewriteBatchedStatements
10) Hibernate Statistics + p6spy로 측정
11) StatelessSession 예고와 Spring Batch 분리
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) 왜 row-by-row는 느린가: 네트워크 왕복의 누적

"INSERT가 1만 번 찍힌다"가 왜 20초가 되는가. 병목은 CPU도, 디스크도 아니다. 네트워크 왕복(round trip) 이다. 애플리케이션과 DB가 한 대의 서버에 있어도 TCP 소켓을 통한 요청/응답 왕복은 수십 마이크로초 단위로 쌓인다. 원격 DB라면 1ms 이상도 흔하다. INSERT 1만 건을 한 줄씩 보내면 왕복만 10초 가까이 된다.

// 피하기: for문으로 한 건씩 insert를 날리는 경로
for (Order o : orders) {
    em.persist(o);
    em.flush();   // 매번 flush — 최악
}

이 패턴은 네트워크 왕복 × N에 추가로 매번 트랜잭션 로그 기록, 인덱스 유지, 트리거 실행 비용까지 전부 N번 낸다. DB가 한 번에 여러 건을 받으면 내부에서 버퍼링, 그룹 커밋, 트랜잭션 로그 일괄 기록 같은 최적화를 적용할 수 있는데, 한 건씩 보내면 이런 여지가 전부 사라진다.

해법의 방향은 두 층으로 나뉜다. JDBC 레벨에서는 addBatch() + executeBatch()로 드라이버가 여러 문장을 한 왕복에 전송하게 하고, DB 레벨에서는 드라이버가 여러 INSERT를 단일 multi-VALUES 문장으로 재작성하게 한다. Hibernate는 이 두 층 위에 다시 ORM 레벨의 배칭을 얹는다. 세 층이 합쳐져야 실제 배치가 먹힌다.

세 단계의 차이를 모르면 "batch 설정했는데 왜 안 빨라?"의 원인을 잘못 짚는다. Hibernate가 만들어주는 건 2번까지다. 3번은 드라이버 옵션으로 별도로 켜야 한다.

2) JDBC Batch의 기본: PreparedStatement.addBatch

JDBC의 batch는 Statement 또는 PreparedStatement에 addBatch()로 여러 문장을 쌓은 뒤 executeBatch()로 한 번에 보내는 API다. Hibernate도 이 API를 그대로 쓴다.

// 순수 JDBC 예시
String sql = "insert into orders(id, amount) values (?, ?)";
try (PreparedStatement ps = conn.prepareStatement(sql)) {
    for (Order o : orders) {
        ps.setLong(1, o.getId());
        ps.setInt(2, o.getAmount());
        ps.addBatch();
    }
    int[] counts = ps.executeBatch();
}

핵심 제약은 한 가지다. addBatch는 같은 SQL 문자열에 대해서만 파라미터를 바꿔 쌓을 수 있다. PreparedStatement 하나에 대한 API이므로 당연한 결과다. INSERT와 UPDATE를 섞을 수도 없고, 같은 INSERT라도 컬럼 목록이 다르면 묶을 수 없다. 이 제약이 뒤에서 본 order_inserts 와 @DynamicUpdate 함정의 근본 원인이 된다.

executeBatch의 반환은 int[]이고 각 자리의 값은 해당 문장이 영향 준 row 수(또는 SUCCESS_NO_INFO)다. 드라이버는 이 배열을 만들기 위해 내부적으로 결과를 하나씩 매칭하며, multi-VALUES로 재작성된 경우 원래의 개별 row 수를 잃어버릴 수 있다는 주의점이 따라온다. MySQL에서 rewriteBatchedStatements=true일 때 executeBatch 결과가 Statement.SUCCESS_NO_INFO로 바뀌는 이유가 이것이다. 영향 row 수에 의존하는 로직이 있다면 알고 있어야 한다.

3) Hibernate batch가 JDBC batch를 감싸는 방식

Hibernate의 batch는 "flush 시점에 쌓아둔 INSERT/UPDATE를 같은 SQL끼리 묶어 JDBC batch로 전송" 하는 상위 계층이다. 영속성 컨텍스트가 persist/merge/변경 감지로 만들어낸 쓰기 작업들을 flush 시점에 종류별로 분류하고, 같은 SQL 문자열이 연속되는 구간마다 addBatch를 쌓았다가 끊기는 지점에서 executeBatch를 호출한다.

3-1) 왜 "연속되는 구간"이 중요한가

JDBC batch는 같은 SQL 문자열만 모을 수 있다고 했다. Hibernate는 엔티티를 persist한 순서대로 SQL을 만들기 때문에, 엔티티 타입이 번갈아 나오면 batch가 중간에 끊긴다.

// persist 순서: Member → Order → Member → Order → ...
// Hibernate가 만드는 SQL: INSERT member, INSERT order, INSERT member, INSERT order, ...
// 같은 SQL이 연속되지 않아 batch가 매번 1건짜리로 끊어진다

이 문제를 푸는 설정이 §4의 order_inserts다. 같은 타입끼리 재정렬해 SQL이 연속되도록 만든다.

3-2) flush 시점과 batch_size의 관계

batch_size=100은 "한 executeBatch에 최대 100건 쌓는다"는 의미다. 쌓인 양이 batch_size에 도달하면 그 자리에서 executeBatch가 실행되고, flush가 끝날 때까지 쌓인 나머지는 마지막에 한꺼번에 flush된다. 중요한 건 batch_size는 "flush 시점까지 엔티티를 얼마나 쌓아두는가"를 결정하지 않는다는 점이다. 그건 애플리케이션 코드에서 직접 §7의 flush/clear 패턴으로 제어해야 한다.

4) 필수 설정 3종: batch_size / order_inserts / order_updates

Hibernate batch를 제대로 쓰려면 세 개가 한 세트다. 하나만 빼먹어도 batch가 반쪽만 작동한다.

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          batch_size: 100
        order_inserts: true
        order_updates: true
        batch_versioned_data: true

각 설정이 끄는/켜는 비용이 다르다.

설정	역할	없으면 어떻게 되나
`jdbc.batch_size`	flush 시 JDBC batch에 묶을 최대 statement 수	배치 자체가 안 된다. 설정 없으면 Hibernate는 매 statement마다 즉시 execute
`order_inserts`	같은 엔티티 타입의 INSERT를 연속 배치로 재정렬	엔티티 타입이 섞여 있으면 batch가 중간에 끊겨 크기가 1로 수렴
`order_updates`	같은 모양의 UPDATE를 연속 배치로 재정렬	`@DynamicUpdate`가 아니더라도 UPDATE 순서가 엔티티 타입별로 섞이면 batch 깨짐
`batch_versioned_data`	`@Version` 필드가 있는 엔티티도 UPDATE batch 허용	기본 `false`. 낙관적 잠금을 쓰는 엔티티는 batch 자체가 안 됨

4-1) batch_size는 얼마가 적당한가

경험적으로 50 ~ 200이 일반적이다. 너무 작으면 batch의 이득이 적고, 너무 크면 PreparedStatement에 바인딩되는 파라미터가 많아져 DB의 파라미터 한도나 패킷 크기 제한에 걸릴 수 있다. PostgreSQL은 protocol 레벨에서 바인딩 파라미터 32,767 제한이 확실히 걸리므로 컬럼 수 × batch_size가 이 한도를 넘지 않도록 계산한다. Oracle은 SQL 한 문장 내 expression 한도(대략 65k 수준)가 별도로 걸리므로 batch_size × 컬럼 수가 그 근처에 닿지 않도록 감안한다.

4-2) 전역 vs 엔티티별

jdbc.batch_size는 SessionFactory 글로벌 설정이다. 엔티티 타입별로 INSERT/UPDATE batch 크기를 바꾸는 공식 수단은 없고, 필요하면 session.setJdbcBatchSize(int)로 세션 범위에서 임시 조정한다. (조회 쪽 @BatchSize는 lazy loading IN-절 fetch 전용이라 여기서 말하는 batch와 완전히 다른 메커니즘이다 — 13편 §5 참조.)

5) IDENTITY가 batch를 죽이는 이유

여기가 이 글의 가장 중요한 함정이다. 13편에서 언급했던 내용을 구조적으로 다시 본다. batch_size=100을 설정하고도 SQL이 한 건씩 찍히는 케이스의 90%는 이 문제다.

5-1) IDENTITY의 타이밍

GenerationType.IDENTITY는 DB의 auto-increment(MySQL) 혹은 serial/identity 컬럼(PostgreSQL)에 PK 생성을 맡긴다. 구조적 제약은 단순하다.

Hibernate가 엔티티를 영속 상태로 만들려면 PK를 알아야 한다
IDENTITY는 INSERT를 실제로 실행해야만 DB가 PK를 돌려준다
그러므로 persist 호출 시점에 INSERT를 즉시 실행할 수밖에 없다

즉 IDENTITY 전략은 persist를 부를 때마다 SQL이 나가야 하는 구조다. flush까지 쌓아서 batch로 묶는 것 자체가 불가능하다. Hibernate는 이 상황에서 조용히 batch를 비활성화하고 row-by-row로 실행한다. 로그에 경고 같은 게 뜨지도 않는다. 설정은 다 켜져 있는데 왜 batch가 안 되는지를 찾다가 시간을 녹이는 전형적 구간이다.

5-2) 해결 — SEQUENCE 또는 애플리케이션 생성 PK

PostgreSQL/Oracle은 시퀀스를 지원하므로 SEQUENCE 전략으로 넘어가면 바로 해결된다.

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
@SequenceGenerator(name = "order_seq", sequenceName = "order_seq", allocationSize = 50)
private Long id;

allocationSize=50은 "시퀀스를 한 번 호출할 때 50개 ID를 미리 받아둔다"는 뜻이다. Hibernate는 nextval 한 번으로 50개를 확보하고, persist 호출 시 메모리에서 PK를 부여한 뒤 INSERT를 모아 batch로 내보낸다. batch와 시퀀스 호출 오버헤드 둘 다 줄인다.

MySQL은 전통적으로 SEQUENCE를 쓰지 않고 AUTO_INCREMENT 관행이다. 이 경로에서 batch가 필요하면 선택지는 두 가지뿐이다.

애플리케이션 레벨 PK 생성 — TSID, UUID v7, Snowflake ID 등. persist 전에 애플리케이션이 PK를 결정해 두면 IDENTITY의 제약이 없어진다
JdbcTemplate.batchUpdate로 내려가기 — JPA를 포기하고 순수 JDBC로 대량 insert

TSID/UUID 경로의 장단은 35편에서 다룬 바 있다. 이 글의 맥락에서 중요한 건 "MySQL + IDENTITY에서 batch를 기대하지 말라" 는 원칙이다.

INSERT 쪽 함정은 PK였다. UPDATE 경로에는 다른 축의 함정이 둘 있다 — @Version과 @DynamicUpdate.

6) batch_versioned_data와 @DynamicUpdate 트레이드오프

UPDATE 경로에는 두 개의 독립된 함정이 또 있다. 하나는 @Version, 다른 하나는 @DynamicUpdate다.

6-1) @Version과 batch_versioned_data

낙관적 잠금에 쓰는 @Version 필드가 있는 엔티티는 UPDATE에 where id = ? and version = ? 절이 붙는다. Hibernate의 기본 동작은 "version 값이 바인딩에 포함되면 batch로 묶지 않는다" 이다. 낙관적 잠금 실패를 정확히 잡으려면 row 단위 영향 수 확인이 필요한데, batch의 집계 결과로는 어떤 row가 version 불일치로 0건 영향을 받았는지 식별이 애매해지므로 Hibernate가 기본적으로 batch를 끈다. 이 보수적 동작을 명시적으로 뒤집는 스위치가 batch_versioned_data=true다.

hibernate:
  batch_versioned_data: true   # 기본 false

켜두면 @Version이 있어도 UPDATE가 batch로 묶인다. PostgreSQL/Oracle은 대체로 문제없다. MySQL도 최근 드라이버는 괜찮지만, 낙관적 잠금 실패(version 불일치로 0건 영향)가 섞인 batch의 결과 판별에서 드라이버별 미묘한 차이가 있을 수 있으니 운영 DB에서 한 번은 검증해보는 편이 안전하다.

6-2) @DynamicUpdate와 batch는 사실상 공존 불가

@DynamicUpdate는 "변경된 컬럼만 UPDATE SQL에 포함"시키는 Hibernate 확장이다. 넓은 엔티티에서 한두 컬럼만 바꿀 때 UPDATE 페이로드를 줄이는 효과가 있다. 문제는 §2에서 본 JDBC batch의 전제와 정면으로 충돌한다.

JDBC batch: 같은 SQL 문자열만 묶을 수 있다
@DynamicUpdate: 엔티티마다 변경된 컬럼이 다르므로 UPDATE SQL 문자열도 다르다

결과는 예상대로다. @DynamicUpdate 엔티티의 UPDATE는 거의 batch로 안 묶인다. 변경 컬럼이 우연히 같은 엔티티들만 연속으로 나와야 하는데, 실무에서 그런 일관성은 기대하기 어렵다. batch와 @DynamicUpdate는 트레이드오프이고, 대량 업데이트가 중요한 엔티티라면 @DynamicUpdate를 떼는 편이 맞다. 반대로 "대량이 아닌데 컬럼이 100개 넘는 엔티티"라면 @DynamicUpdate의 이득이 더 크다. 용도에 맞춰 고른다.

7) 대량 persist: saveAll은 해답이 아니다, flush/clear 패턴

13편 §13에서 다뤘지만 여기서 한 번 더 짚는다. JpaRepository.saveAll은 내부적으로 for문으로 save를 반복할 뿐이다. batch 최적화를 보장하지 않는다.

// SimpleJpaRepository의 실제 구현
public <S extends T> List<S> saveAll(Iterable<S> entities) {
    List<S> result = new ArrayList<>();
    for (S entity : entities) {
        result.add(save(entity));
    }
    return result;
}

saveAll이 batch로 묶이는 건 Hibernate가 flush 시점에 쌓인 INSERT를 batch로 보낼 수 있는 조건이 갖춰진 경우뿐이다. 그 조건은 §4의 설정 3종 + §5의 PK 전략이다.

7-1) 메모리 폭발을 막는 flush/clear

saveAll을 크게 한 번에 호출하면 또 다른 함정이 뒤따른다. 영속성 컨텍스트가 엔티티로 가득 차 OOM이 난다. Hibernate는 persist된 엔티티를 1차 캐시에 보관하고 변경 감지를 위한 스냅샷을 들고 있다. 10만 건을 영속화하면 10만 개의 스냅샷이 힙에 쌓인다.

// 선호: 주기적으로 flush + clear
int BATCH = 500;   // batch_size의 몇 배 정도로 잡는 편
for (int i = 0; i < orders.size(); i++) {
    em.persist(orders.get(i));
    if (i > 0 && i % BATCH == 0) {
        em.flush();   // 쌓인 INSERT를 JDBC batch로 내보낸다
        em.clear();   // 1차 캐시를 비운다 — 이걸 빠뜨리면 OOM
    }
}
em.flush();
em.clear();

flush와 clear는 쌍이다. flush만 하면 메모리가 안 줄고, clear만 하면 변경이 반영되지 않는다. 여기서 틀리기 쉬운 지점이 하나 더 있다. BATCH 주기는 hibernate.jdbc.batch_size의 정수배로 맞추는 편이 유리하다. batch_size가 100인데 주기가 150이면 50건이 batch로 못 묶이고 남아 마지막 flush에서 짧게 나간다. 주기적 flush 간격을 잘못 잡으면 batch 효율이 떨어진다.

7-2) clearAutomatically는 벌크 쿼리 전용

Spring Data JPA의 @Modifying(clearAutomatically = true)은 JPQL 벌크 연산 뒤에 영속성 컨텍스트를 비워주는 플래그다. saveAll 경로에는 적용되지 않는다. 루프 안에서 직접 em.clear()를 불러야 한다.

8) JPQL bulk UPDATE가 우선인 이유

대량으로 같은 방식의 업데이트를 걸어야 하는 경우, batch로 여러 UPDATE를 묶는 것보다 JPQL 단일 UPDATE가 언제나 빠르다. 이유는 명확하다. batch로 묶어도 여전히 N개의 UPDATE 문장이 DB에 도달하지만, JPQL bulk UPDATE는 DB 쪽에서 한 문장으로 처리된다. 네트워크 왕복도 1회, 트랜잭션 로그도 훨씬 간결하다.

// 피하기: 엔티티 단위로 상태를 바꾸는 루프
List<Order> list = orderRepository.findOldPendings(date);
for (Order o : list) {
    o.markShipped();   // dirty checking으로 UPDATE
}
// flush 시점에 N건의 UPDATE가 batch로 나가긴 하지만 여전히 N문장

// 선호: JPQL bulk UPDATE
@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("""
    update Order o
       set o.status = :shipped
     where o.status = :pending and o.createdAt < :d
""")
int markShipped(@Param("shipped") OrderStatus shipped,
                @Param("pending") OrderStatus pending,
                @Param("d") LocalDateTime d);

DB 한 문장으로 끝나고, 영향 row 수가 반환된다.

8-1) bulk UPDATE의 주의점

공짜는 아니다. 몇 가지 비용이 따라온다.

2차 캐시 우회 — bulk UPDATE는 영속성 컨텍스트 1차 캐시와 Hibernate 2차 캐시를 우회한다. 같은 트랜잭션 내에서 이후 조회가 옛 값을 돌려줄 수 있고, 2차 캐시에 있는 엔티티는 무효화해야 한다. clearAutomatically=true로 1차 캐시를 비우고, 2차 캐시가 있다면 해당 region을 evict한다
@Version 자동 증가 안 됨 — 엔티티 단위 UPDATE가 아니므로 Hibernate가 version 컬럼을 자동으로 올리지 않는다. 필요하면 JPQL에 명시한다 — set o.version = o.version + 1
엔티티 라이프사이클 콜백 생략 — @PreUpdate/@PostUpdate가 호출되지 않는다. 이 훅에 의존하는 로직이 있으면 bulk는 적합하지 않다

즉 bulk UPDATE는 "엔티티 로직이 필요 없고 같은 변경을 많은 row에 적용"할 때 최선이다. 엔티티 메서드를 통한 도메인 로직이 끼면 batch로 묶인 UPDATE 쪽이 맞다.

8-2) bulk DELETE도 같은 논리

@Modifying(clearAutomatically = true)
@Query("delete from Order o where o.status = 'CANCELED' and o.canceledAt < :d")
int purgeCanceled(@Param("d") LocalDateTime d);

삭제도 엔티티 단위로 돌면 N번의 DELETE가 나가지만 JPQL bulk DELETE는 한 문장이다. 단, @OneToMany(cascade = CascadeType.REMOVE) 같은 ORM 레벨 cascade는 bulk에서 작동하지 않는다. FK 제약이 걸려 있으면 먼저 자식 bulk DELETE, 그 다음 부모 bulk DELETE 순으로 두 문장을 직접 작성한다.

9) JDBC 드라이버별 rewriteBatchedStatements

여기가 설정해놓고도 "그런데 왜 빠르지 않지?"로 가장 많이 막히는 지점이다. Hibernate가 JDBC batch로 문장을 보내도, 드라이버가 네트워크에는 INSERT를 여전히 하나씩 보내는 경우가 있다. 드라이버별 multi-VALUES 재작성 옵션을 별도로 켜야 한다.

9-1) MySQL / MariaDB

jdbc:mysql://host:3306/db?rewriteBatchedStatements=true

rewriteBatchedStatements=true를 반드시 켜야 JDBC batch의 INSERT가 INSERT ... VALUES (...), (...), (...) 한 문장으로 재작성된다. 기본값은 false다. 안 켜면 JDBC 레벨에서는 batch지만 실제 네트워크에는 INSERT가 그대로 여러 번 나간다. §1에서 본 세 단계의 2번에서 멈춘다.

MySQL에서 이 옵션을 켰을 때의 주의는 §2 끝에서 언급한 executeBatch 반환이 SUCCESS_NO_INFO로 바뀌는 것 외에도, UPDATE에는 적용되지 않는다는 점이다. MySQL 드라이버의 재작성은 INSERT만 대상이다.

9-2) PostgreSQL

jdbc:postgresql://host:5432/db?reWriteBatchedInserts=true

pgjdbc 9.4.1209 이상은 reWriteBatchedInserts=true(대소문자 주의)로 같은 재작성을 지원한다. 기본 꺼짐. INSERT만 적용되고 UPDATE/DELETE에는 안 붙는다.

9-3) Oracle

Oracle 드라이버는 기본으로 JDBC batch를 잘 지원한다. oracle.jdbc.defaultExecuteBatch로 배치 크기의 기본값을 바꿀 수 있지만, Hibernate가 executeBatch를 명시적으로 호출하므로 일반적으로 따로 손대지 않는다.

9-4) 드라이버 설정 없이 batch가 "보이는" 착각

Hibernate SQL 로그를 보면 batch가 묶인 것처럼 보일 수 있다. Hibernate는 addBatch 호출 단위로 로그를 찍기 때문이다. 실제 네트워크에 뭐가 나갔는지는 드라이버 로그를 봐야 확인된다. p6spy는 JDBC 드라이버 앞단 프록시이므로 드라이버가 받은 것까지는 보여주지만, multi-VALUES로 재작성된 실제 와이어 프로토콜은 드라이버 내부에서 일어난다. MySQL에서는 general_log, PostgreSQL에서는 log_statement=all로 DB 서버 로그를 켜고 보는 게 가장 확실하다.

10) Hibernate Statistics + p6spy로 측정

batch가 실제로 먹히는지는 숫자로 봐야 한다. 설정만 켜고 "되겠지" 하는 건 십중팔구 틀린다.

10-1) Hibernate Statistics

spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true
logging:
  level:
    org.hibernate.stat: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE

Statistics 객체에서 batch 관련 핵심 지표는 다음과 같다.

메서드	의미
`getEntityInsertCount()`	Hibernate가 수행한 엔티티 INSERT 수
`getEntityUpdateCount()`	엔티티 UPDATE 수
`getPrepareStatementCount()`	JDBC `PreparedStatement` 준비 횟수
`getQueryExecutionCount()`	쿼리 실행 횟수

엔티티 INSERT 수가 1만인데 PreparedStatement 준비 횟수가 1~10 수준이라면 batch가 제대로 먹힌 것이다. INSERT 수와 준비 횟수가 비슷하게 1만에 근접하면 batch가 전혀 안 된 것이다.

@Test
void 대량_저장이_batch로_묶인다() {
    Statistics stats = sessionFactory.getStatistics();
    stats.clear();

    List<Order> orders = IntStream.range(0, 1000)
        .mapToObj(i -> new Order(...))
        .toList();
    orderRepository.saveAll(orders);
    em.flush();

    assertThat(stats.getEntityInsertCount()).isEqualTo(1000);
    // batch_size=100이면 준비 횟수는 10 수준이어야 한다
    assertThat(stats.getPrepareStatementCount()).isLessThanOrEqualTo(15);
}

회귀 방지용으로 이런 테스트를 남겨두는 게 가장 확실하다. 누군가 PK를 IDENTITY로 바꾸거나 @DynamicUpdate를 붙이면 이 테스트가 빨갛게 바뀐다.

10-2) p6spy로 실제 SQL 확인

testImplementation("com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.9.1")

p6spy는 JDBC 드라이버 앞단에 프록시를 끼워 실행 시점의 완성된 SQL + 실행 시간을 찍는다. Hibernate 레벨 로그와 달리 바인딩 파라미터가 모두 치환되고, 실행 지연도 함께 보인다. "batch가 먹히는지"보다 "한 왕복에 얼마나 걸렸는지"를 확인하는 용도로 유용하다.

한 가지 주의. p6spy는 드라이버의 addBatch/executeBatch 호출을 중계하므로 Hibernate가 쌓은 batch의 각 addBatch 호출이 개별 SQL처럼 보일 수 있다(드라이버가 무엇을 와이어로 보냈는지는 앞서 언급한 대로 별도 문제다). 로그를 읽을 때 "addBatch 로그 여러 줄 = 한 번의 executeBatch"로 해석해야 한다.

11) StatelessSession 예고와 Spring Batch 분리

여기까지가 영속성 컨텍스트를 유지하는 일반 batch의 한계다. 더 극단적인 대량 처리가 필요하면 선택지는 두 가지로 갈린다.

11-1) StatelessSession

// [다음 편(43)](./43_hibernate-stateless-session-scrollable.md)에서 깊게 다룬다
try (StatelessSession ss = sessionFactory.openStatelessSession()) {
    Transaction tx = ss.beginTransaction();
    for (Order o : orders) {
        ss.insert(o);
    }
    tx.commit();
}

StatelessSession은 영속성 컨텍스트가 없는 Hibernate 세션이다. 1차 캐시도, 변경 감지 스냅샷도, dirty checking도 없다. flush/clear가 필요 없고 메모리 발자국이 거의 일정하다. 대신 가벼운 대가가 있다 — cascading 무시, event listener 무시, @PrePersist/@PostPersist 등 JPA 라이프사이클 콜백 무시. 도메인 이벤트 발행 같은 로직이 엔티티 라이프사이클에 묶여 있다면 StatelessSession 경로에서는 수동으로 옮겨야 한다. 자세한 동작은 다음 글에서 다룬다.

11-2) Spring Batch로 chunk 처리

수십만 ~ 수백만 건 규모는 애초에 별도 배치 잡으로 분리하는 편이 낫다. Spring Batch는 reader / processor / writer를 chunk 단위로 묶어 커밋 간격을 제어하고, 재시작/스킵/재시도 같은 운영 기능을 제공한다. 일반 API 트랜잭션과 같은 애플리케이션에서 돌더라도 트랜잭션 경계와 타임아웃이 분리된다.

배치 잡 설계에서 중요한 건 세 가지다.

트랜잭션 경계 분리 — @Transactional(propagation = Propagation.REQUIRES_NEW) 또는 PROPAGATION_NEVER + 수동 관리. 긴 배치가 일반 요청 트랜잭션에 묶이면 타임아웃이 터진다
2차 캐시 비활성 — 배치 실행 구간에는 CacheMode.IGNORE로 읽기/쓰기 모두 2차 캐시를 건너뛰게 한다. 캐시가 오염된다
재시작 가능성 — chunk 단위로 커밋하면 중간에 실패해도 마지막 성공 지점부터 재시작할 수 있다

"API 컨트롤러에서 대량 데이터를 한 트랜잭션에 꽂는다"는 설계는 가급적 피한다. 데이터가 커지면 이 경로는 시한폭탄이다.

12) 실무에서 이렇게 읽고 쓴다

"batch_size 올렸는데 안 빨라요" 리포트가 오면 첫 질문은 "PK 전략이 뭐예요?" 다. MySQL + IDENTITY면 batch는 구조적으로 안 된다. 설정 아무리 만져도 헛수고다
측정 없이 최적화하지 않는다. generate_statistics=true 켜고 getEntityInsertCount() / getPrepareStatementCount() 비율로 batch 효율을 숫자로 확인한다. 이 비율이 1에 가까우면 batch가 전혀 안 된 것이다
MySQL 드라이버 URL에 rewriteBatchedStatements=true가 빠져 있는 환경이 절반 이상이다. 기본 설정 템플릿에 박아두고 운영 DB에서 한 번 확인한다
대량 persist는 em.flush() + em.clear() 주기적 호출이 필수다. 주기는 batch_size의 정수배로. 빠뜨리면 OOM이고, 간격을 잘못 잡으면 batch 효율이 떨어진다
엔티티 단위 로직이 필요 없는 대량 업데이트는 JPQL bulk UPDATE 우선. 2차 캐시와 @Version은 별도 관리. 엔티티 라이프사이클 콜백에 의존하는 경로면 batch UPDATE로 남긴다
@DynamicUpdate와 batch는 공존이 어렵다. 넓은 엔티티 + 소량 변경 빈번이면 @DynamicUpdate, 대량 업데이트면 뗀다. 둘 다 필요하면 엔티티를 분리하는 게 맞다
진짜 대량(수만 건 이상)은 JPA를 벗어난다. JdbcTemplate.batchUpdate, StatelessSession, Spring Batch 중 하나로 내려간다. "ORM으로 모든 걸 해결한다"는 기대를 버리는 순간부터 쉬워진다
배치 작업은 별도 서비스/잡으로 분리. API 트랜잭션과 타임아웃·전파 속성·캐시 모드가 다르다. 이 분리를 안 해두면 배치가 커질 때마다 API가 같이 아프다

13) 한 줄 정리

Hibernate batch는 JDBC batch를 감싸는 상위 계층이고, 제대로 작동하려면 batch_size + order_inserts/updates + rewriteBatchedStatements 세 층이 전부 맞아야 한다. GenerationType.IDENTITY는 이 체인을 근본적으로 끊어버리고, @DynamicUpdate는 batch와 트레이드오프 관계에 있으며, saveAll은 이름만큼 batch를 보장하지 않는다. 대량 경로는 엔티티 단위 로직이 필요한가 / 같은 변경을 많은 row에 반복하는가로 분기해, 전자는 flush/clear 루프로, 후자는 JPQL bulk UPDATE로 간다.

태그: Hibernate, JDBC Batch, batch_size, order_inserts, IDENTITY, SEQUENCE, saveAll, rewriteBatchedStatements, Spring Data JPA, bulk UPDATE

JPA AttributeConverter와 커스텀 타입 — Enum·JSON·암호화 필드 매핑

dding-shark — Tue, 21 Apr 2026 20:28:58 +0900

JPA AttributeConverter와 커스텀 타입 — Enum·JSON·암호화 필드 매핑

들어가며

엔티티 필드와 DB 컬럼이 1:1로 딱 떨어질 때는 매핑이 고민거리가 아니다. String name은 VARCHAR(64)로 가고, BigDecimal price는 NUMERIC으로 간다. 그런데 현실의 도메인은 이 깔끔한 대응에서 자주 빗나간다. enum을 숫자 대신 코드 문자열로 저장하고 싶고, 복잡한 설정 객체를 JSON 컬럼 하나에 담고 싶고, 주민번호는 암호화해서 넣어야 한다. 이럴 때 Hibernate와 직접 대화하는 고리가 AttributeConverter다. 필드 타입과 컬럼 타입 사이에 얇은 어댑터를 끼워 넣어, 객체 모델은 도메인 언어 그대로 두고 DB에는 원하는 형태로 저장하게 만드는 표준 JPA 장치다.

이 글은 34편 연관 매핑과 35편 식별자 생성에 이어, 한 엔티티 안의 필드 값 자체를 어떻게 변환해 저장할 것인가를 다룬다. Enum 기본 저장 전략의 함정, Hibernate 6의 @JdbcTypeCode(SqlTypes.JSON), 커스텀 JSON Converter, 암호화 필드가 검색 쿼리를 어떻게 망가뜨리는지, Money 같은 VO는 Converter와 @Embeddable 중 어느 쪽이 맞는지 — 이 다섯 축이 오늘 정리할 주제다.

@Enumerated 없이 enum 필드를 그냥 쓰면 ORDINAL로 저장된다 — 스펙 기본값 함정. enum 순서 한 번 바꾸면 데이터가 뒤섞인다.
Hibernate 5에서 hibernate-types-52로 JSON을 매핑하던 코드를 6으로 올리면 @JdbcTypeCode(SqlTypes.JSON)로 바꿀 수 있다 — 서드파티 의존을 뺄 수 있는 지점이다.
암호화 필드에 LIKE로 검색을 했는데 아무것도 안 나온다 — 암호문끼리는 패턴 매칭이 안 된다는 걸 매핑 이후에 깨닫는다.
@Convert를 @Id에 붙였더니 Hibernate가 예외를 던진다 — Converter는 PK·버전·연관관계에 쓸 수 없다.

이 글은 왜 → 계약 → 적용 방식 → Enum → JSON → 암호화 → VO → 한계 → 쿼리와 DynamicUpdate → 다른 SqlTypes → 실무 순으로, Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x / Jackson 2.x 기준으로 정리한다.

1) 컬럼과 필드가 1:1이 아닐 때
2) AttributeConverter 계약: 두 메서드가 전부다
3) @Convert vs @Converter(autoApply=true)
4) Enum 저장: EnumType.STRING과 코드값 Converter
5) Hibernate 6 @JdbcTypeCode(SqlTypes.JSON): 표준 JSON 매핑
6) 커스텀 JSON Converter: 직렬화 로직 제어
7) 암호화 필드와 검색 불가 함정
8) Money·Email 같은 VO: Converter vs @Embeddable
9) @Convert의 한계: @Id·@Version·연관관계 금지
10) JSON 쿼리와 @DynamicUpdate
11) @JdbcTypeCode의 다른 SqlTypes: ARRAY·UUID·INET
12) 실무 체크리스트
13) 한 줄 정리

1) 컬럼과 필드가 1:1이 아닐 때

JPA 매핑의 기본 가정은 단순하다 — 필드 하나 = 컬럼 하나, 타입은 JDBC가 아는 범위. Hibernate가 기본 제공하는 타입(String, Integer, BigDecimal, LocalDateTime, UUID 등)은 이 가정에 그대로 들어맞는다. 그런데 도메인 모델을 그리다 보면 이 범위를 자꾸 벗어난다. OrderStatus enum을 'P', 'A', 'X' 같은 한 글자 코드로 넣고 싶고, 사용자 설정을 JSON으로 통째로 저장하고 싶고, 전화번호는 AES로 암호화해야 한다.

해결 고리는 두 가지다. 첫째, Hibernate가 네이티브로 지원하는 고급 타입 — @Enumerated(EnumType.STRING), @JdbcTypeCode(SqlTypes.JSON) 같이 어노테이션 하나로 끝나는 경우. 둘째, AttributeConverter 인터페이스로 변환 로직을 직접 작성 — enum을 코드값으로 저장하거나, 암호화하거나, VO를 단일 컬럼에 압축할 때. 이 두 도구는 경쟁이 아니라 보완 관계다. Hibernate 기본으로 해결되면 그쪽이 간결하고, 안 되면 Converter로 내려간다.

// 필드 타입 X → 컬럼 타입 Y 사이의 어댑터
public interface AttributeConverter<X, Y> {
    Y convertToDatabaseColumn(X attribute);
    X convertToEntityAttribute(Y dbData);
}

X가 엔티티 필드 타입이고 Y가 DB 컬럼 타입이다. Y는 보통 String, Integer, Long처럼 JDBC가 바로 아는 기본 타입이어야 한다. Converter는 값 변환 전용이고, 연관관계·식별자·버전 같은 특수 필드에는 개입하지 않는다는 점이 출발 전제다. 이 경계는 §9 @Convert의 한계에서 자세히 다룬다.

2) AttributeConverter 계약: 두 메서드가 전부다

AttributeConverter<X, Y>는 제네릭 인터페이스고, 구현해야 할 메서드는 정확히 두 개다. 계약 자체가 단순하기 때문에 Converter를 읽을 때는 변환 방향 두 개만 머리에 두면 된다.

@Converter
public class BooleanToYNConverter implements AttributeConverter<Boolean, String> {

    @Override
    public String convertToDatabaseColumn(Boolean attribute) {
        if (attribute == null) return null;
        return attribute ? "Y" : "N";
    }

    @Override
    public Boolean convertToEntityAttribute(String dbData) {
        if (dbData == null) return null;
        return "Y".equals(dbData);
    }
}

위 컨버터는 Boolean 필드를 'Y'/'N' 한 글자 컬럼으로 저장한다. 레거시 DB에서 흔히 보는 패턴이다. 두 메서드가 대칭이어야 한다는 점이 중요하다 — convertToDatabaseColumn(true)가 "Y"면 convertToEntityAttribute("Y")가 true를 돌려줘야 한다. 이 왕복(round-trip) 일관성이 깨지면 저장과 조회가 맞지 않아 엔티티 상태가 DB와 달라진다.

여기서 틀리기 쉬운 지점이 null 처리다. 필드가 nullable이면 두 메서드 모두 앞부분에서 null을 체크해 null을 그대로 돌려줘야 한다. Converter가 null을 받아 NPE를 던지면 DB에는 잘 들어가 있는 row가 엔티티로 올라오면서 조회 자체가 실패한다. 반대로 non-null 필드로 강제한다면 최소한 Objects.requireNonNull로 의도를 드러내는 편이 낫다.

// 피하기: null 무방비
public String convertToDatabaseColumn(Boolean attr) {
    return attr ? "Y" : "N";   // null 들어오면 NPE
}

// 선호: null-safe
public String convertToDatabaseColumn(Boolean attr) {
    return attr == null ? null : (attr ? "Y" : "N");
}

Converter는 Hibernate가 엔티티 저장 직전과 DB row 로드 직후에 호출한다. 영속성 컨텍스트 안에서 필드를 바꿔도 Converter가 매번 도는 건 아니고, 실제 SQL이 나가는 시점(flush)과 SELECT 결과 매핑 시점에만 돈다. 그래서 Converter 구현을 무거운 로직(예: 원격 호출)으로 채우는 건 안전하지 않다. 순수한 값 변환에 국한해야 한다.

3) @Convert vs @Converter(autoApply=true)

Converter를 엔티티에 적용하는 방식은 두 가지다. 필드별 명시와 자동 적용. 이 둘의 차이는 단순히 문법이 아니라 가독성과 의도 파악의 문제다.

// 방식 1: 필드별 @Convert (명시적)
@Entity
public class Order {
    @Id @GeneratedValue
    private Long id;

    @Convert(converter = BooleanToYNConverter.class)
    private Boolean paid;

    @Convert(converter = BooleanToYNConverter.class)
    private Boolean shipped;
}

// 방식 2: @Converter(autoApply = true) (자동 적용)
@Converter(autoApply = true)
public class BooleanToYNConverter implements AttributeConverter<Boolean, String> {
    // ...
}

// 자동 적용이면 엔티티에서는 아무것도 안 써도 됨
@Entity
public class Order {
    private Boolean paid;     // BooleanToYNConverter가 자동으로 걸린다
    private Boolean shipped;
}

autoApply = true는 해당 X 타입(위 예에서는 Boolean)의 모든 필드에 자동으로 Converter를 적용한다. 프로젝트 전체에서 Boolean을 전부 'Y'/'N'으로 저장하기로 정했다면 편하다. 그런데 편한 만큼 함정도 있다 — 어떤 엔티티 코드만 보고는 Converter가 걸려 있는지 알 수 없다. 새 필드를 추가하다가 의도하지 않게 변환이 일어날 수도 있다.

방식	장점	단점	언제
`@Convert(converter=...)`	엔티티 코드만 봐도 명시적	필드마다 반복	일부 필드만 변환
`@Converter(autoApply=true)`	중복 제거, 정책 일관성	엔티티 코드에 단서 없음	프로젝트 전역 정책

권장은 기본을 명시적 @Convert로 두고, 정말 전역 정책이 명확할 때만 autoApply를 쓰는 것이다. 특히 enum 코드 매핑 Converter는 autoApply = true가 자연스럽다(한 enum 타입은 한 가지 방식으로만 저장한다는 게 자명하니까). 반면 암호화 Converter는 autoApply = false로 두고 @Convert로 필드별 명시가 맞다 — 어떤 필드가 암호화되는지 엔티티에서 바로 보여야 한다.

한 엔티티에서 autoApply를 일시적으로 끄고 싶을 때는 @Convert(disableConversion = true)를 쓸 수 있다. 드문 케이스지만 알아두면 유용하다.

@Entity
public class LegacyRow {
    // autoApply로 전역 Converter가 걸려 있어도 이 필드는 변환 제외
    @Convert(disableConversion = true)
    private Boolean rawFlag;
}

4) Enum 저장: EnumType.STRING과 코드값 Converter

4-1) @Enumerated 기본값의 함정

Jakarta Persistence가 enum을 저장하는 방식은 두 가지다 — EnumType.ORDINAL과 EnumType.STRING. 이름 그대로 순서(정수)로 저장할지, 문자열로 저장할지다. 그런데 명시하지 않으면 기본값이 ORDINAL이라는 게 함정이다.

// 피하기: @Enumerated 미명시 → ORDINAL로 저장
@Entity
public class Order {
    private OrderStatus status;   // 위험
}

public enum OrderStatus {
    PENDING,   // 0
    PAID,      // 1
    CANCELLED  // 2
}

위 코드로 PAID를 저장하면 DB에는 1이 들어간다. 문제는 시간이 지나 enum에 값을 추가할 때다. PENDING 앞에 DRAFT를 끼워 넣으면? 기존 DB의 1은 이제 PAID가 아니라 PENDING을 의미하게 된다. 데이터 손상 없이 enum 순서를 바꿀 수 없다.

해결은 두 가지다. 기본은 EnumType.STRING, 컬럼 길이나 코드값이 중요하면 AttributeConverter.

// 선호: EnumType.STRING — 이름 그대로 저장
@Entity
public class Order {
    @Enumerated(EnumType.STRING)
    @Column(length = 20)
    private OrderStatus status;   // 'PENDING', 'PAID', 'CANCELLED' 저장
}

EnumType.STRING은 enum 이름을 그대로 저장한다. 순서가 바뀌어도 안전하고, DB만 봐도 값의 의미를 알 수 있다. 단점은 컬럼이 VARCHAR가 돼야 하고, enum 이름이 길면 저장 공간도 늘어난다는 점. 대부분의 도메인에서는 충분히 수용 가능한 비용이다.

4-2) 코드값 매핑이 필요하면 Converter

enum 이름이 너무 길거나, 레거시 시스템과 호환을 위해 3~4글자 코드로 저장해야 할 때는 EnumType.STRING으로는 부족하다. 이때 AttributeConverter로 내려간다.

public enum OrderStatus {
    PENDING("P"),
    PAID("A"),        // Accepted
    CANCELLED("X");

    private final String code;

    OrderStatus(String code) {
        this.code = code;
    }

    public String getCode() {
        return code;
    }
}

@Converter(autoApply = true)
public class OrderStatusConverter implements AttributeConverter<OrderStatus, String> {

    @Override
    public String convertToDatabaseColumn(OrderStatus status) {
        return status == null ? null : status.getCode();
    }

    @Override
    public OrderStatus convertToEntityAttribute(String code) {
        if (code == null) return null;
        return Arrays.stream(OrderStatus.values())
                .filter(s -> s.getCode().equals(code))
                .findFirst()
                .orElseThrow(() ->
                    new IllegalArgumentException("Unknown OrderStatus code: " + code));
    }
}

이제 DB에는 'P', 'A', 'X'가 저장되고, 엔티티에서는 OrderStatus enum으로 다룬다. autoApply = true라 엔티티 필드에 추가 어노테이션이 필요 없다. 주의할 부분은 없는 코드를 만났을 때의 동작이다. 위 구현은 IllegalArgumentException을 던져 조회 자체를 실패시킨다. DB에 예상 못한 값이 들어있으면 부팅 직후가 아니라 그 row를 조회하는 순간 폭발한다. 이게 맞는 동작이긴 하다 — 데이터 무결성을 묵살하는 것보다는 낫다.

@startuml
title AttributeConverter 동작: 저장과 로드 왕복

entity "Order (Entity)" as Entity {
  status : OrderStatus
}
component "OrderStatusConverter" as Converter
database "orders (Table)" as DB {
  status : VARCHAR(4)
}

Entity -> Converter : convertToDatabaseColumn(PAID)
note right
  flush 시점
  필드 값 → DB 값
end note
Converter -> DB : INSERT status = 'A'

DB -> Converter : SELECT status → 'A'
note right
  SELECT 결과 매핑
  DB 값 → 필드 값
end note
Converter -> Entity : convertToEntityAttribute("A") = PAID

@enduml

이 다이어그램이 보여주는 건 두 가지다. 첫째, Converter는 flush와 SELECT 결과 매핑이라는 두 경계에서만 동작한다. 둘째, 왕복이 대칭이어야 한다 — PAID → 'A' → PAID로 돌아와야 한다.

5) Hibernate 6 @JdbcTypeCode(SqlTypes.JSON): 표준 JSON 매핑

5-1) 네이티브 JSON 매핑의 등장

Hibernate 5 시대에는 JSON 컬럼을 엔티티 필드로 매핑하려면 hibernate-types-52 같은 서드파티 라이브러리를 썼다. @TypeDef + @Type(type = "jsonb") 조합이 흔했다. Hibernate 6부터는 이 기능이 코어에 들어왔다 — @JdbcTypeCode(SqlTypes.JSON).

import org.hibernate.annotations.JdbcTypeCode;
import org.hibernate.type.SqlTypes;

@Entity
public class Product {
    @Id @GeneratedValue
    private Long id;

    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")        // PostgreSQL jsonb
    private Map<String, Object> metadata;

    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")
    private ProductSpec spec;                   // 임의 POJO도 가능
}

public record ProductSpec(
    String manufacturer,
    int warrantyMonths,
    List<String> tags
) {}

@JdbcTypeCode(SqlTypes.JSON)을 붙이면 Hibernate가 필드를 JSON 컬럼으로 인식한다. PostgreSQL에서는 jsonb, MySQL 8+에서는 JSON, 다른 DB는 TEXT 등으로 자동 매핑된다. 직렬화는 클래스패스에 있는 Jackson(ObjectMapper)을 써서 Hibernate가 자동으로 처리한다. Spring Boot 3.x는 Jackson이 기본 포함이므로 별도 설정이 거의 없다.

Map<String, Object> 같은 동적 구조도 되고, ProductSpec 같은 record/POJO도 된다. 엔티티가 아니어야 한다는 제약만 있다. 엔티티를 JSON 필드에 박으면 영속성 컨텍스트 추적 대상이 되지 않는 이상한 엔티티가 생긴다.

5-2) jsonb vs json 컬럼

PostgreSQL에서는 json과 jsonb 두 타입이 있다. 차이는 확실하다.

타입	저장 형태	인덱스	속도	공간
`json`	원본 텍스트 그대로	기본 인덱스 제한적	저장 빠름	공백 유지해 큼
`jsonb`	파싱된 바이너리	GIN 인덱스 가능	조회 빠름	공백 제거돼 작음

실무에서는 거의 항상 jsonb다. GIN 인덱스로 JSON 내부 키에 인덱스를 걸 수 있고, 조회 시 매번 파싱하지 않으니 빠르다. columnDefinition = "jsonb"로 명시해두면 DDL 자동 생성 시 jsonb로 잡힌다.

5-3) Hibernate 5 → 6 마이그레이션 포인트

Hibernate 5에서 hibernate-types를 썼던 코드는 Hibernate 6으로 올라가면서 아래처럼 단순해진다.

// Hibernate 5 (hibernate-types-52 의존)
@TypeDef(name = "jsonb", typeClass = JsonBinaryType.class)
@Entity
public class Product {
    @Type(type = "jsonb")
    @Column(columnDefinition = "jsonb")
    private Map<String, Object> metadata;
}

// Hibernate 6 (서드파티 제거)
@Entity
public class Product {
    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")
    private Map<String, Object> metadata;
}

hibernate-types 의존을 빼면 버전 호환 문제와 라이브러리 관리 부담이 한 겹 사라진다. Hibernate 6으로 업그레이드할 계획이 있으면 이 지점을 같이 정리하는 게 자연스럽다.

6) 커스텀 JSON Converter: 직렬화 로직 제어

@JdbcTypeCode(SqlTypes.JSON)이 표준이긴 한데, 특정 상황에서는 JSON 직렬화 로직을 직접 제어해야 할 때가 있다. 예를 들어 Jackson 기본 직렬화가 맞지 않는 필드(커스텀 ObjectMapper 설정, 특정 필드 제외, 암호화된 JSON 등)를 다룰 때. 이때는 AttributeConverter로 내려가는 게 맞다.

@Converter
public class JsonMapConverter implements AttributeConverter<Map<String, Object>, String> {

    private static final ObjectMapper MAPPER = new ObjectMapper()
            .registerModule(new JavaTimeModule())
            .setSerializationInclusion(JsonInclude.Include.NON_NULL);

    @Override
    public String convertToDatabaseColumn(Map<String, Object> attribute) {
        if (attribute == null) return null;
        try {
            return MAPPER.writeValueAsString(attribute);
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("Failed to serialize metadata", e);
        }
    }

    @Override
    public Map<String, Object> convertToEntityAttribute(String dbData) {
        if (dbData == null || dbData.isBlank()) return null;
        try {
            return MAPPER.readValue(dbData, new TypeReference<Map<String, Object>>() {});
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("Failed to deserialize metadata: " + dbData, e);
        }
    }
}

@Entity
public class Product {
    @Convert(converter = JsonMapConverter.class)
    @Column(columnDefinition = "TEXT")     // 또는 "jsonb"
    private Map<String, Object> metadata;
}

이 형태의 장점은 ObjectMapper 설정을 내가 쥐고 있다는 것이다. JavaTimeModule 등록, NON_NULL 직렬화 정책, 커스텀 시리얼라이저 등 원하는 대로 조립할 수 있다. 단점은 컬럼이 String으로 매핑된다는 점 — DB에 jsonb로 저장하려면 컬럼 정의는 맞추더라도 Hibernate 입장에서는 그냥 텍스트다. PostgreSQL의 JSON 경로 쿼리 같은 네이티브 기능을 쓰려면 별도 함수 호출이 필요하다.

언제 Converter 방식을 고르는가. Jackson 직렬화를 세밀하게 제어해야 하거나, Hibernate 버전이 6 미만이거나, JSON 안의 특정 필드를 엔티티 레벨에서 미리 가공해야 할 때다. 그 외엔 @JdbcTypeCode(SqlTypes.JSON)이 간결하고 네이티브 기능 활용이 쉽다.

예외 처리에서 틀리기 쉬운 지점이 있다. JsonProcessingException을 RuntimeException으로 그대로 감싸면 원인 정보가 사라지기 쉽다. 원본 DB 문자열이나 실패 컨텍스트를 메시지에 넣어두면 나중에 어떤 row가 문제인지 역추적이 된다.

7) 암호화 필드와 검색 불가 함정

개인정보(PII) 컬럼을 DB에 평문으로 저장하면 안 되는 규정이 점점 늘어난다. 주민번호, 전화번호, 이메일, 계좌번호 같은 필드. 이를 애플리케이션 레벨에서 암호화해 저장하는 표준 방법이 AttributeConverter다.

@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

    private final CryptoService crypto;

    public EncryptedStringConverter(CryptoService crypto) {
        this.crypto = crypto;
    }

    @Override
    public String convertToDatabaseColumn(String plaintext) {
        return plaintext == null ? null : crypto.encrypt(plaintext);
    }

    @Override
    public String convertToEntityAttribute(String ciphertext) {
        return ciphertext == null ? null : crypto.decrypt(ciphertext);
    }
}

@Entity
public class User {
    @Id @GeneratedValue
    private Long id;

    @Convert(converter = EncryptedStringConverter.class)
    @Column(length = 512)                    // 암호문은 평문보다 길다
    private String ssn;

    @Convert(converter = EncryptedStringConverter.class)
    @Column(length = 256)
    private String phoneNumber;
}

암호화 알고리즘은 AES/GCM 권장이다. IV(Initialization Vector)를 매번 새로 생성하고 암호문에 포함해 저장하면 같은 평문이 매번 다른 암호문이 된다. 키는 애플리케이션 코드에 박지 말고 KMS(AWS KMS, HashiCorp Vault 등)에서 읽어온다. Converter는 Spring Bean이 아니므로 @Converter에 CryptoService를 직접 주입할 수는 없는데, Hibernate가 Converter 인스턴스화 시 Spring의 AutowireCapableBeanFactory를 연결해주는 설정을 붙이거나, static holder 패턴으로 우회한다.

7-1) LIKE 검색이 작동하지 않는다

여기서 틀리기 쉬운 지점이 본격적으로 나온다. 암호화 필드는 평문 검색이 불가능하다.

// 피하기: 암호화 필드에 LIKE 검색 — 아무것도 안 나온다
@Query("select u from User u where u.phoneNumber like concat('%', :suffix, '%')")
List<User> findByPhoneSuffix(String suffix);

DB에는 "A7kZ3xQ9..." 같은 암호문이 들어있으니 LIKE '%1234%' 패턴은 걸릴 리가 없다. = 정확 일치 검색도 AES/GCM처럼 매번 IV가 달라지는 알고리즘에서는 같은 평문도 매번 다른 암호문이 되므로 동등 비교조차 안 된다.

해결은 세 갈래다.

검색 불가를 받아들이고 업무 플로우를 재설계한다. 전화번호로 유저를 찾는 대신 유저 ID로 찾는다.
결정적 암호화(deterministic encryption)를 쓴다. 같은 평문이 항상 같은 암호문이 되도록 IV를 고정하거나 생략. 보안성은 살짝 떨어지지만 = 검색이 가능해진다.
해시 컬럼을 별도로 둔다. phone_hash = SHA256(phoneNumber) 같은 컬럼을 추가하고 검색에 쓴다. 해시는 역변환 불가이므로 복호화할 필요가 없다.

// 선호 3: 해시 컬럼 병행
@Entity
public class User {
    @Convert(converter = EncryptedStringConverter.class)
    private String phoneNumber;

    @Column(length = 64)
    private String phoneHash;     // SHA-256 hex. = 검색용 인덱스

    public void setPhoneNumber(String raw) {
        this.phoneNumber = raw;
        this.phoneHash = raw == null ? null : sha256Hex(raw);
    }
}

해시 컬럼에는 인덱스를 걸 수 있고 = 검색이 가능하다. 부분 일치가 필요한 경우는 방법이 까다로워지는데, 전화번호 끝 4자리 검색 같은 패턴은 해시를 여러 개(전화번호 전체 해시, 끝 4자리 해시) 저장하는 식으로 푼다.

7-2) toString·로그 노출 방지

암호화를 아무리 잘해도 애플리케이션 로그나 에러 메시지에 복호화된 평문이 찍히면 끝이다. Lombok을 쓰면 @ToString에서 암호화 필드를 제외한다.

@Entity
@Getter @Setter
@ToString(exclude = {"ssn", "phoneNumber"})   // 로그에 평문이 안 찍힌다
public class User {
    @Convert(converter = EncryptedStringConverter.class)
    private String ssn;

    @Convert(converter = EncryptedStringConverter.class)
    private String phoneNumber;
}

Jackson으로 JSON 응답을 만들 때도 @JsonIgnore나 마스킹 시리얼라이저를 붙인다. 암호화는 저장에서의 보호고, 노출 방지는 별도 관심사다.

8) Money·Email 같은 VO: Converter vs @Embeddable

8-1) 선택지는 둘

Money(amount, currency), Email(address), Address(...) 같은 값 객체(VO, Value Object)를 엔티티에 포함시킬 때 선택지가 두 개 있다. @Embeddable로 여러 컬럼에 펼치거나, AttributeConverter로 단일 컬럼에 압축하거나.

public record Money(BigDecimal amount, String currency) {}

// 방식 A: @Embeddable — 두 컬럼
@Embeddable
public class MoneyEmbeddable {
    @Column(name = "price_amount")
    private BigDecimal amount;

    @Column(name = "price_currency", length = 3)
    private String currency;
    // getter, equals, hashCode 필요
}

@Entity
public class Product {
    @Embedded
    private MoneyEmbeddable price;
}

// 방식 B: Converter — 한 컬럼에 "1000 KRW"
@Converter(autoApply = true)
public class MoneyConverter implements AttributeConverter<Money, String> {

    @Override
    public String convertToDatabaseColumn(Money money) {
        return money == null ? null : money.amount() + " " + money.currency();
    }

    @Override
    public Money convertToEntityAttribute(String dbData) {
        if (dbData == null || dbData.isBlank()) return null;
        String[] parts = dbData.split(" ");
        return new Money(new BigDecimal(parts[0]), parts[1]);
    }
}

@Entity
public class Product {
    @Column(length = 32)
    private Money price;   // "1000 KRW"로 저장
}

8-2) 언제 어느 쪽인가

판단 기준	@Embeddable	AttributeConverter
각 구성 요소를 개별 쿼리로 필터링해야 하나	가능 (`WHERE amount > 1000`)	불가 (문자열 파싱 필요)
각 구성 요소에 인덱스를 걸어야 하나	가능	불가
JPQL/Criteria에서 분해해 접근해야 하나	가능 (`m.amount`)	불가
컬럼 개수를 줄이고 단일 문자열로 관리	컬럼 여러 개 생성	한 컬럼
VO가 record로 간결하게 표현	일반 클래스 필요(equals/hashCode)	record 그대로 가능

실무 판단의 핵심은 쿼리 요구사항이다. amount 값으로 범위 검색을 하거나 집계를 돌려야 한다면 @Embeddable이 압도적으로 유리하다. 반면 VO를 단순히 엔티티에 붙어 다니는 불투명 값으로 다룬다면(저장만 하고 그 필드로 쿼리할 일이 거의 없음) Converter가 컬럼 수를 줄여준다.

record와 불변 VO를 선호한다면 Converter가 더 자연스럽다. @Embeddable은 Jakarta Persistence 스펙상 기본 생성자가 필요해 record를 그대로는 쓸 수 없다(Hibernate 6은 일부 지원이 있지만 제한적). Converter는 내부에서 record 생성자를 직접 호출하니 제약이 없다.

9) @Convert의 한계: @Id·@Version·연관관계 금지

@Convert는 값 변환에 특화된 도구라, 값 아닌 필드에는 쓸 수 없다. Jakarta Persistence 3.x 스펙이 명시적으로 금지하는 영역을 먼저 정리해두는 게 사고를 예방하는 가장 빠른 길이다.

금지 대상	이유
`@Id` 필드	PK는 영속성 컨텍스트 동일성 식별에 쓰이므로 변환 개입 금지
`@Version` 필드	낙관적 락 버전 증가는 Hibernate가 직접 관리
`@ManyToOne`/`@OneToOne` 등 연관관계	FK 변환은 ID Generation·연관 매핑 영역
`@Temporal` 붙은 필드	날짜 타입은 별도 처리 경로가 있음
`@Enumerated` 붙은 필드	`@Enumerated`와 `@Convert`는 같은 필드에 공존 불가

// 피하기: @Id에 Converter 붙이면 Hibernate가 예외
@Entity
public class Order {
    @Id
    @Convert(converter = MyIdConverter.class)   // 부팅 시 예외
    private OrderId id;
}

PK 변환이 필요하면 @Convert 대신 @IdClass / @EmbeddedId / @GenericGenerator / 커스텀 IdentifierGenerator로 내려가야 한다. 35편 식별자 생성에서 이 경로를 다뤘다.

연관관계 변환이 필요한 경우(예: FK 컬럼 값을 암호화하거나 커스텀 포맷으로 저장)도 Converter로는 안 된다. 이 요구 자체가 드물고, 거의 항상 도메인 모델 재검토가 맞는 답이다. FK 컬럼을 직접 조작해야 한다는 건 엔티티 경계가 잘못 그려졌다는 신호에 가깝다.

JPQL에서 Converter를 타지 않는 케이스도 주의해야 한다. Hibernate 6에서는 많이 개선됐지만, 일부 버전에서 WHERE o.status = :status 같은 파라미터 바인딩이 Converter를 거치지 않고 날것의 값으로 나가는 경우가 있었다. 증상은 "엔티티로 조회는 되는데 where 절이 안 먹는다"는 형태다. Hibernate 6.2 이후는 대부분 해결됐으나, 의심되면 실제 나가는 SQL을 로그로 찍어 확인하는 게 가장 빠르다.

10) JSON 쿼리와 @DynamicUpdate

10-1) JSON 경로 쿼리

Hibernate 6은 JSON 경로 표현식을 JPQL에서 일부 지원한다. PostgreSQL의 경우 function(...)을 통해 네이티브 함수를 호출할 수 있다.

// JSON 내부 키로 필터링 (PostgreSQL jsonb_extract_path_text)
@Query("""
    select p from Product p
    where function('jsonb_extract_path_text', p.metadata, 'category') = :category
    """)
List<Product> findByMetadataCategory(@Param("category") String category);

metadata 컬럼이 jsonb이고 @JdbcTypeCode(SqlTypes.JSON)으로 매핑된 상태. JSON 안의 category 키가 특정 값과 일치하는 row를 찾는다. Querydsl에서는 Native Template 형태로 비슷하게 표현한다.

성능은 GIN 인덱스가 붙어 있으면 빠르고, 없으면 풀스캔이라 느리다. JSON 컬럼에 자주 조회되는 키가 있다면 다음처럼 표현식 인덱스를 걸어둔다.

CREATE INDEX idx_product_metadata_category
ON product USING GIN ((metadata->'category'));

10-2) @DynamicUpdate와 JSON 필드

JSON 필드를 갖는 엔티티에 특히 추천하는 한 가지 옵션이 @DynamicUpdate다.

@Entity
@DynamicUpdate
public class Product {
    @Id @GeneratedValue
    private Long id;

    private String name;
    private BigDecimal price;

    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")
    private Map<String, Object> metadata;   // 수백 KB가 될 수도
}

기본 Hibernate는 엔티티를 UPDATE 할 때 모든 컬럼을 UPDATE 구문에 포함한다. 한 필드만 바뀌었어도 전부 다시 쓴다. name만 바꿨는데 metadata에 수백 KB JSON이 들어있다면, 매번 그 JSON을 통째로 다시 쓰는 셈이다. 네트워크와 디스크 I/O가 무의미하게 커진다.

@DynamicUpdate를 붙이면 Hibernate가 실제 바뀐 필드만 포함한 UPDATE 문을 런타임에 생성한다. 대신 SQL 캐싱 효과가 줄어 작은 엔티티에는 오히려 손해일 수 있다. JSON이나 대용량 컬럼이 있는 엔티티에 선택적으로 붙인다는 게 권장이다.

옵션	UPDATE 컬럼	SQL 캐싱	대용량 컬럼 영향
기본	모든 컬럼	효율적 (동일 SQL 재사용)	매 UPDATE마다 전체 재저장
`@DynamicUpdate`	변경된 컬럼만	매번 새 SQL 생성	변경 없으면 제외됨

11) @JdbcTypeCode의 다른 SqlTypes: ARRAY·UUID·INET

@JdbcTypeCode는 JSON만을 위한 게 아니다. Hibernate 6은 여러 특수 SQL 타입을 표준화된 방식으로 노출한다. PostgreSQL을 쓰는 경우 특히 실용적인 타입들이 있다.

SqlTypes	DB 타입	엔티티 필드 타입	용도
`JSON`	`jsonb` / `JSON`	`Map`, POJO, record	구조화 데이터
`ARRAY`	PostgreSQL `text[]`, `int[]`	`String[]`, `List<String>`	태그, 다중 값
`UUID`	PostgreSQL `uuid`	`java.util.UUID`	식별자
`INET`	PostgreSQL `inet`	`InetAddress`	IP 주소
`INTERVAL_SECOND`	PostgreSQL `interval`	`Duration`	시간 간격
`XML`	`xml`	`String`, POJO	XML 컬럼

@Entity
public class Post {
    @Id @GeneratedValue
    private Long id;

    // PostgreSQL 배열 컬럼
    @JdbcTypeCode(SqlTypes.ARRAY)
    @Column(columnDefinition = "text[]")
    private List<String> tags;

    // UUID 네이티브
    @JdbcTypeCode(SqlTypes.UUID)
    @Column(columnDefinition = "uuid")
    private UUID publicId;

    // INET 주소
    @JdbcTypeCode(SqlTypes.INET)
    @Column(columnDefinition = "inet")
    private InetAddress authorIp;
}

배열 타입은 특히 간단한 태그 시스템 같은 경우에 편하다. 별도 조인 테이블을 만들 만큼 무겁지 않고, 순서가 필요 없다면 text[]에 넣고 GIN 인덱스로 검색한다. Hibernate 5까지는 이걸 쓰려면 hibernate-types에 의존했다.

UUID는 PostgreSQL의 네이티브 uuid 타입이 16바이트로 저장돼 VARCHAR(36)으로 저장하는 것보다 절반 이하 공간을 쓴다. MySQL처럼 네이티브 UUID가 없는 DB에서는 BINARY(16) + 변환 유틸로 해결해야 한다.

DB가 이 타입들을 네이티브로 지원하지 않으면 @JdbcTypeCode가 기대대로 동작하지 않으니 DB 벤더 매뉴얼과 Hibernate 방언(dialect) 지원 여부를 먼저 확인해야 한다. 이식성이 중요한 프로젝트라면 @JdbcTypeCode의 특수 타입 대신 기본 타입 + Converter가 안전할 수 있다.

12) 실무 체크리스트

@Enumerated는 항상 EnumType.STRING. 기본값이 ORDINAL이라는 스펙 함정을 깜빡하지 않는다. 레거시 코드에서 @Enumerated 미명시된 enum 필드는 리팩터링 대상 1호다. 코드값 매핑이 필요하면 @Converter(autoApply=true)로 내려간다.
JSON 매핑은 Hibernate 6의 @JdbcTypeCode(SqlTypes.JSON) 우선. hibernate-types 의존이 남아 있다면 6.x 업그레이드와 함께 제거한다. 직렬화 로직을 세밀하게 제어해야 할 때만 커스텀 AttributeConverter로 내려간다.
암호화 필드에는 검색 요구사항을 먼저 확인한다. LIKE 검색이 필요하면 암호화 자체가 부적합하거나, 해시 컬럼을 병행해야 한다. 키 관리는 KMS에서. @ToString(exclude=...)와 @JsonIgnore로 로그·응답 노출까지 같이 막는다.
Converter는 PK·버전·연관관계에 쓸 수 없다. 이 경계를 넘는 요구는 거의 항상 도메인 재설계의 신호다. @EmbeddedId, @IdClass, 커스텀 IdentifierGenerator 쪽 루트를 찾는다.
VO 매핑은 쿼리 요구로 판단. 구성 요소로 WHERE 절이나 인덱스를 쓸 일이 있으면 @Embeddable, 단순 저장이면 Converter. record와 불변성을 선호하면 Converter가 자연스럽다.
대용량 JSON 필드가 있는 엔티티에는 @DynamicUpdate를 고려한다. 작은 엔티티에 일괄 적용하면 오히려 손해니 선택적으로. 한 필드만 자주 바뀌는 엔티티에서 UPDATE 크기가 눈에 띄게 줄어든다.
@Converter(autoApply = true)는 enum 코드 매핑처럼 정책이 명확할 때만. 암호화 Converter는 명시적 @Convert로 필드마다 적는다. 엔티티 코드만 봐도 변환 여부를 판단할 수 있어야 리뷰 비용이 낮다.
Converter 예외는 원인 컨텍스트를 남긴다. JSON 파싱 실패 시 원본 문자열이나 row ID 같은 단서를 메시지에 포함. RuntimeException으로 감싸만 두면 어떤 row가 깨졌는지 역추적이 어렵다.
PostgreSQL을 쓰면 @JdbcTypeCode의 ARRAY/UUID/INET을 적극 활용한다. 네이티브 타입의 공간·성능 이점을 덤으로 얻는다. DB 벤더가 바뀔 가능성이 있는 프로젝트라면 이식성 손해와의 트레이드오프를 계산해둔다.

13) 한 줄 정리

AttributeConverter는 필드 타입과 컬럼 타입 사이의 얇은 어댑터로, 값 변환에 한정해 쓰는 도구다. Enum은 EnumType.STRING 또는 코드값 Converter로, JSON은 Hibernate 6 @JdbcTypeCode(SqlTypes.JSON)으로, 암호화는 @Convert에 검색 제약을 함께 설계해야 사고가 없다. Converter는 PK·버전·연관관계에 쓸 수 없고, VO 매핑은 쿼리 요구로 @Embeddable과 Converter 중에서 고르는 판단이 된다.

태그: JPA, Hibernate, AttributeConverter, Enumerated, JdbcTypeCode, JSON 매핑, 암호화 필드, Embeddable, DynamicUpdate, Spring Boot 3

JPA Auditing과 Soft Delete — @CreatedDate·@AuditorAware·@SQLDelete

dding-shark — Tue, 21 Apr 2026 20:28:33 +0900

JPA Auditing과 Soft Delete — @CreatedDate·@AuditorAware·@SQLDelete

들어가며

엔티티마다 createdAt, updatedAt, createdBy, updatedBy 필드를 직접 세팅하는 코드를 한 번이라도 짜본 사람은 안다. 서비스 계층 어디에선가는 setCreatedAt(LocalDateTime.now())가 빠져 있고, 어떤 엔티티는 updatedBy가 계속 null로 남는다. 반대쪽에서는 "삭제된 회원"이라는 상태가 운영상 필요한데 DELETE 쿼리로 날려버려서 주문 이력의 FK가 끊어지고, 정산팀이 새벽에 전화를 걸어온다. 이 두 문제는 별개로 보이지만 같은 결에 있다 — 엔티티의 생성·수정·삭제라는 라이프사이클을 서비스 코드에 흩어놓지 말고 영속성 계층에 공통 인프라로 박자는 얘기다.

Spring Data JPA의 Auditing과 Hibernate의 Soft Delete 지원은 이 결을 구현한 두 축이다. 한쪽은 생성/수정 시각과 사용자 정보를 자동으로 채우고, 다른 쪽은 DELETE를 논리적 플래그로 바꾼다. 이 둘을 엔티티 한쪽에서 조합해두면, 서비스 계층은 도메인 로직에만 집중하고 감사 추적과 복구 가능성은 인프라가 책임진다. 그런데 실무에서는 이 구성이 자주 깨진다. 아래 네 가지는 거의 매번 밟는다.

@CreatedDate가 작동하지 않는다 — @EntityListeners(AuditingEntityListener.class)를 BaseEntity에 안 붙여서 리스너가 한 번도 호출되지 않는다
Soft delete 후 같은 이메일로 재가입이 안 된다 — unique 제약이 삭제된 행까지 포함해서 중복으로 잡는다
@Where를 썼더니 Hibernate 6.3에서 deprecated 경고가 뜬다 — @SQLRestriction으로 교체해야 한다
AuditorAware가 스케줄러 스레드에서 null을 반환한다 — SecurityContext가 없는 경로를 생각 못 한다

이 글은 10편 ApplicationEvent와 @Async, 21편 Security 컨텍스트 전파, 34편 연관 매핑과 자매편이다. 10편이 비동기 이벤트 버스를 봤다면 여기서는 그 비동기 스레드에서 AuditorAware가 어떻게 깨지는지를 보고, 21편이 SecurityContext 전파 자체를 봤다면 여기서는 그 SecurityContext가 감사 데이터의 출처로 쓰일 때의 경계 문제를 본다. 34편이 FK의 양쪽을 봤다면 여기서는 soft delete된 부모의 자식 관계가 어떻게 dangling되는지를 본다. 전체 순서는 왜 공통인가 → Auditing 구성 → AuditorAware → 시간 타입 → BaseEntity → Envers → Soft Delete 설계 → @SQLDelete/@SQLRestriction → Hibernate 6.4 @SoftDelete → @FilterDef → 실무 순으로 정리한다. 버전은 Spring Boot 3.x / Spring Data JPA 3.x / Hibernate 6.x / Jakarta Persistence 3.x 기준이다.

1) Audit 정보는 왜 공통 인프라인가
2) @EnableJpaAuditing과 4가지 애너테이션
3) AuditorAware 구현과 Security 컨텍스트
4) DateTimeProvider와 테스트 시계 고정
5) BaseEntity 패턴: @MappedSuperclass와 EntityListeners
6) 시간 타입 선택: LocalDateTime vs OffsetDateTime vs Instant
7) Hibernate Envers: 전면 감사 로그의 비용과 이득
8) Soft Delete 설계 동기와 함정
9) @SQLDelete + @SQLRestriction (Hibernate 6.3+)
10) Hibernate 6.4+ @SoftDelete 신규 애너테이션
11) @FilterDef + @Filter로 동적 필터
12) 실무 체크리스트
13) 한 줄 정리

1) Audit 정보는 왜 공통 인프라인가

"언제 생겼고 언제 바뀌었는지, 누가 만들었고 누가 바꿨는지" — 이 네 가지는 도메인 로직이 아니다. 주문이라는 개념이 존재하기 위해 꼭 필요한 속성도 아니고, 주문 금액 계산에 관여하지도 않는다. 그런데 운영에 들어가면 이 네 가지가 없는 엔티티는 대부분 쓸모없는 엔티티다. 장애가 났을 때 "누가 언제 건드렸는지"를 모르면 원인을 추적할 수가 없다. 기술적으로는 도메인이지만 의미적으로는 인프라인 셈이다.

이걸 서비스 계층에 흩뿌리면 어떤 일이 벌어지는지 한 번 보자.

// 피하기: 서비스에서 직접 세팅
@Transactional
public Order place(OrderCommand cmd, String userId) {
    Order order = Order.from(cmd);
    order.setCreatedAt(LocalDateTime.now());
    order.setCreatedBy(userId);
    order.setUpdatedAt(LocalDateTime.now());
    order.setUpdatedBy(userId);
    return orderRepository.save(order);
}

@Transactional
public void updateStatus(Long orderId, OrderStatus status, String userId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.changeStatus(status);
    order.setUpdatedAt(LocalDateTime.now());   // 이거 매번 쓰면 까먹는다
    order.setUpdatedBy(userId);
    // createdBy는 건드리면 안 되는데 실수로 건드리면?
}

세 가지 문제가 한 번에 드러난다. 첫째, 같은 코드가 모든 CUD 메서드에 중복된다. 엔티티가 100개면 이 코드가 수백 줄로 흩어진다. 둘째, 한 군데라도 빠뜨리면 조용히 깨진다 — updatedBy가 영원히 처음 값인 채로 남아도 컴파일 에러가 안 난다. 셋째, createdBy를 실수로 update 경로에서 덮어쓸 수 있다. 도메인 불변을 코드 규율로만 지키겠다는 얘기인데, 규율은 항상 어긋난다.

Spring Data JPA의 Auditing은 이 네 가지를 프레임워크 레벨에서 자동화한다. 엔티티의 라이프사이클 이벤트(@PrePersist, @PreUpdate)에 리스너를 걸어두고, @CreatedDate/@LastModifiedDate/@CreatedBy/@LastModifiedBy 애너테이션이 붙은 필드를 찾아서 값을 주입한다. 서비스 코드는 한 줄도 바뀌지 않고, 엔티티는 상속으로 네 필드를 받는다. 이게 영속성 이벤트에 인프라를 붙이는 스프링의 전형적인 접근이다.

Soft Delete도 같은 맥락이다. "삭제됐다"는 상태를 도메인 필드로 표현하되, 조회 시 자동으로 제외하고 em.remove() 호출을 UPDATE로 바꾸는 일은 서비스가 책임질 일이 아니다. Hibernate가 @SQLDelete/@SQLRestriction으로 이걸 처리해준다. 네 축 — 생성/수정/삭제의 시각/주체 — 중 셋을 영속성 계층으로 내리면, 서비스는 본질적인 도메인 로직만 남는다.

2) @EnableJpaAuditing과 4가지 애너테이션

Auditing 기능을 켜려면 @EnableJpaAuditing 하나만 추가하면 된다. 기본적으로는 @Configuration 클래스에 붙이거나, Spring Boot의 메인 클래스에 붙인다. 이 어노테이션 하나가 AuditingEntityListener와 관련 빈들을 자동으로 등록한다.

@Configuration
@EnableJpaAuditing(
    auditorAwareRef = "auditorProvider",
    dateTimeProviderRef = "dateTimeProvider",
    modifyOnCreate = true
)
public class JpaAuditingConfig {

    @Bean
    public AuditorAware<String> auditorProvider() {
        return () -> Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
                .filter(Authentication::isAuthenticated)
                .map(Authentication::getName);
    }

    @Bean
    public DateTimeProvider dateTimeProvider() {
        return () -> Optional.of(OffsetDateTime.now());
    }
}

속성 세 가지를 알아두면 디버깅이 쉬워진다. auditorAwareRef는 "누가 만들었는가"를 제공하는 빈 이름이다. 지정하지 않으면 @CreatedBy/@LastModifiedBy는 항상 null로 남는다. dateTimeProviderRef는 시각 제공자의 이름이고, 지정하지 않으면 Spring Data의 기본 CurrentDateTimeProvider가 LocalDateTime.now()를 쓴다. modifyOnCreate는 엔티티가 최초로 persist될 때 @LastModifiedDate/@LastModifiedBy도 같이 채울 것인가다. 기본 true일 때 persist 시점에 @LastModifiedDate/@LastModifiedBy가 함께 채워지므로 INSERT 행에서 createdAt == updatedAt이 된다. false로 주면 최초 INSERT 시 @LastModifiedDate가 null로 남고, 첫 UPDATE가 일어나는 시점에야 처음 채워진다.

4가지 애너테이션의 의미는 단순하다.

애너테이션	채워지는 시점	값의 출처
`@CreatedDate`	`@PrePersist` (최초 저장)	`DateTimeProvider`
`@LastModifiedDate`	`@PrePersist` + `@PreUpdate`	`DateTimeProvider`
`@CreatedBy`	`@PrePersist`	`AuditorAware.getCurrentAuditor()`
`@LastModifiedBy`	`@PrePersist` + `@PreUpdate`	`AuditorAware.getCurrentAuditor()`

여기서 틀리기 쉬운 포인트 두 개. 첫째, @EntityListeners(AuditingEntityListener.class)를 엔티티(또는 공통 BaseEntity)에 반드시 붙여야 한다. @EnableJpaAuditing만 선언하고 이걸 빼면 애너테이션이 아무 일도 하지 않는다. 스프링은 리스너 등록을 자동으로 해주지만, 엔티티 쪽에 "이 리스너 써라"라는 선언이 없으면 JPA가 호출해주지 않는다. 둘째, @CreatedDate와 @CreatedBy에는 @Column(updatable = false)를 붙여야 한다. 그렇지 않으면 UPDATE 시점에 @LastModifiedDate 로직이 엉뚱한 경로로 타면서 createdAt이 덮어써질 수 있다. 보수적으로 updatable = false를 고정해두는 게 안전하다.

3) AuditorAware 구현과 Security 컨텍스트

AuditorAware<T>는 한 줄짜리 인터페이스다. Optional<T> getCurrentAuditor()를 구현하면 된다. 제네릭 T는 @CreatedBy/@LastModifiedBy 필드 타입과 일치해야 한다. 문자열 로그인 ID면 String, 사용자 엔티티 참조면 User, UUID면 UUID. 프로젝트 컨벤션에 맞게 선택한다.

Spring Security와 같이 쓰는 경우 구현은 거의 정해진 형태다.

@Bean
public AuditorAware<String> auditorProvider() {
    return () -> Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
            .filter(Authentication::isAuthenticated)
            .filter(auth -> !(auth instanceof AnonymousAuthenticationToken))
            .map(Authentication::getName);
}

세 개의 filter가 각자 다른 경계를 막는다. 첫 번째는 SecurityContext에 Authentication 자체가 없는 경우(인증 전 경로, 필터 전), 두 번째는 인증 객체는 있지만 비인증 상태인 경우(만료된 세션), 세 번째는 익명 사용자다. 이 세 경우 모두 Optional.empty()를 반환하면 Auditor 필드는 null로 남는다.

여기서 진짜 함정은 인증이 없는 정상 경로에 있다. 스케줄러, @Async 스레드, 배치 잡, 메시지 리스너 같은 곳은 SecurityContext가 비어 있는 게 정상이다. 이 경로에서 엔티티를 저장하는데 createdBy가 null이면 감사 추적이 끊긴다. 해결은 fallback 값을 명시하는 것.

@Bean
public AuditorAware<String> auditorProvider() {
    return () -> {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !auth.isAuthenticated() || auth instanceof AnonymousAuthenticationToken) {
            return Optional.of("SYSTEM");   // 인증 없는 경로는 SYSTEM으로
        }
        return Optional.of(auth.getName());
    };
}

SYSTEM이라는 특수 문자열을 쓰면, 감사 로그를 뒤질 때 "SYSTEM이 바꾼 건 배치잡이 건드린 것"으로 쉽게 구분할 수 있다. 더 세밀하게 하려면 BATCH, SCHEDULER 등을 구분해도 된다. 중요한 건 null을 남기지 않는 것이다. 감사 로그에서 null은 "이 경로를 아직 생각 못 했다"는 신호로 해석된다.

@Async나 @Scheduled 같은 별도 스레드에서 인증 사용자를 그대로 쓰고 싶으면 SecurityContext 전파를 별도로 설정해야 한다 — 이 얘기는 21편 Security 컨텍스트 전파에서 자세히 다뤘다. DelegatingSecurityContextExecutor로 TaskExecutor를 감싸거나, SecurityContextHolder의 전략을 MODE_INHERITABLETHREADLOCAL로 바꾸는 식이다. AuditorAware는 이 전파가 제대로 되어 있다는 전제 위에서 동작한다.

주체(who) 쪽의 주입 경로가 정리됐으면, 시각(when) 쪽도 같은 주입 원칙이 필요하다. 다음 섹션에서 DateTimeProvider와 Clock 주입을 본다.

4) DateTimeProvider와 테스트 시계 고정

DateTimeProvider는 선택 인프라다. 지정하지 않으면 CurrentDateTimeProvider가 LocalDateTime.now()를 호출한다. 문제는 이 기본값이 테스트하기 어렵다는 점이다. 시각이 매번 달라지니 "2분 전에 만들어진 엔티티"를 검증하려면 시간 비교에 tolerance를 넣어야 하고, 경계값 테스트("자정 직전에 생성된 엔티티가 자정 이후 쿼리에 잡히는가") 같은 건 재현이 어렵다.

해법은 DateTimeProvider에 Clock을 주입하는 형태다.

@Bean
public DateTimeProvider dateTimeProvider(Clock clock) {
    return () -> Optional.of(OffsetDateTime.now(clock));
}

@Bean
@Profile("!test")
public Clock systemClock() {
    return Clock.systemDefaultZone();
}

@Bean
@Profile("test")
public Clock fixedClock() {
    return Clock.fixed(Instant.parse("2026-04-20T00:00:00Z"), ZoneOffset.UTC);
}

이렇게 해두면 테스트에서는 시간이 항상 2026-04-20T00:00:00Z로 고정된다. @CreatedDate가 박히는 시각이 예측 가능해지니 assertion도 정확해지고, 시점 의존 버그(자정 경계, 월말 경계)도 쉽게 재현할 수 있다. 운영 환경에선 @Profile 없이 Clock.systemDefaultZone()만 주입된다.

테스트 중간에 시간을 움직이고 싶으면 MutableClock 같은 간단한 구현을 쓴다.

public class MutableClock extends Clock {
    private Instant now;
    private final ZoneId zone;

    public MutableClock(Instant start, ZoneId zone) {
        this.now = start;
        this.zone = zone;
    }

    public void plusMinutes(long minutes) {
        this.now = now.plus(minutes, ChronoUnit.MINUTES);
    }

    @Override public Instant instant() { return now; }
    @Override public ZoneId getZone() { return zone; }
    @Override public Clock withZone(ZoneId zone) { return new MutableClock(now, zone); }
}

테스트 코드에서 clock.plusMinutes(10) 한 줄로 "10분이 지난 것"을 흉내 낼 수 있다. @Scheduled나 만료 로직 테스트에서 특히 유용하다. 운영 코드가 new Date()나 LocalDateTime.now() 대신 Clock을 통과하는 습관이면 시간 관련 모든 테스트가 깔끔해진다.

5) BaseEntity 패턴: @MappedSuperclass와 EntityListeners

네 필드를 모든 엔티티에 중복으로 선언하는 건 낭비다. Java 상속의 일반 패턴처럼, 공통 조상 클래스를 두고 나머지가 상속받는다. JPA에서 이 역할을 하는 건 @MappedSuperclass다.

@Getter
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {

    @CreatedDate
    @Column(updatable = false, nullable = false)
    private OffsetDateTime createdAt;

    @LastModifiedDate
    @Column(nullable = false)
    private OffsetDateTime updatedAt;

    @CreatedBy
    @Column(updatable = false, length = 50)
    private String createdBy;

    @LastModifiedBy
    @Column(length = 50)
    private String updatedBy;
}

@Entity
@Table(name = "orders")
public class Order extends BaseEntity {
    @Id @GeneratedValue
    private Long id;

    @Enumerated(EnumType.STRING)
    private OrderStatus status;
    // 네 필드 안 써도 됨 — 상속으로 주어짐
}

@MappedSuperclass는 엔티티가 아니라 매핑 정보 모음이라는 선언이다. 자체적으로는 테이블이 없고, 상속받은 엔티티의 테이블에 컬럼이 합쳐진다. 즉 orders 테이블에는 created_at, updated_at, created_by, updated_by 네 컬럼이 자동으로 포함된다. 별도 조인 테이블도 없고, 상속 전략(JOINED, SINGLE_TABLE) 고민도 필요 없다.

두 애너테이션이 핵심이다. @MappedSuperclass가 없으면 테이블이 두 개로 쪼개지거나 상속 전략이 엉킨다. 그리고 @EntityListeners(AuditingEntityListener.class)가 없으면 Audit 애너테이션이 전부 무시된다. 이 둘은 짝이다.

한 가지 더. BaseEntity를 abstract로 두면 실수로 인스턴스화하는 걸 막을 수 있다. 또 @Getter만 주고 @Setter는 열지 않는 편이 안전하다. 감사 필드는 외부에서 직접 바꿀 일이 없다.

BaseEntity를 여러 개로 나누는 경우도 있다. TimeEntity(생성/수정 시각만)와 AuditEntity(+생성/수정자)로 분리해서, 사용자 정보가 의미 없는 테이블(예: 로그성 테이블)은 TimeEntity만 상속하는 식이다. 프로젝트 규모와 규칙에 따라 선택하면 된다.

6) 시간 타입 선택: LocalDateTime vs OffsetDateTime vs Instant

감사 시각 필드의 타입을 무엇으로 잡을지는 의외로 프로젝트의 운명을 가른다. 세 후보가 있다.

타입	타임존 정보	DB 컬럼 타입	적합성
`LocalDateTime`	없음 (서버 tz 의존)	`TIMESTAMP`	권장 X
`OffsetDateTime`	UTC offset 포함	`TIMESTAMP WITH TIME ZONE`	권장
`Instant`	항상 UTC epoch	`TIMESTAMP`/`TIMESTAMPTZ`	권장

LocalDateTime이 기본으로 많이 쓰이지만 운영에 들어가면 문제가 쌓인다. 서버 JVM의 TimeZone 설정, OS의 TZ 환경변수, DB 드라이버의 tz 변환 — 이 셋이 어긋나는 순간 시각이 몇 시간씩 틀어진다. 한국 시간으로 만들어진 엔티티가 미국 리전 서버에서 읽힐 때 LocalDateTime은 "누구의 시각인가"라는 정보가 없어서 해석이 달라진다. 특히 감사 로그는 절대 시각이어야 하는데 상대 시각으로 저장되면 사후 추적이 깨진다.

OffsetDateTime은 UTC 오프셋을 명시적으로 붙인 타입이다. 이 값이 PostgreSQL의 TIMESTAMP WITH TIME ZONE 컬럼과 잘 맞고, Hibernate 6은 이걸 1급으로 지원한다. 2026-04-20T09:00:00+09:00처럼 오프셋이 저장되니 어느 리전에서 읽어도 해석이 같다. 실무 추천은 여기다.

Instant는 한 발 더 나가서 "타임존은 DB 안에 안 두고 그냥 UTC epoch milli로 저장한다"는 선택이다. 가장 단순하고, 비교 연산이 빠르고, tz 이슈가 원천적으로 없다. 표시할 때만 ZonedDateTime.ofInstant(instant, userZone)로 변환한다. 로그성 데이터, 이벤트 소싱처럼 "찍힌 순간만 중요"한 경우 가장 깔끔하다.

Hibernate 6의 권장 설정은 이렇다.

spring:
  jpa:
    properties:
      hibernate:
        timezone:
          default_storage: NORMALIZE_UTC   # DB에 저장할 때 UTC로 정규화
        jdbc:
          time_zone: UTC

default_storage=NORMALIZE_UTC는 OffsetDateTime을 DB에 저장할 때 UTC로 변환해서 넣는다. 저장 시점에 타임존을 일원화하니 쿼리 비교가 단순해지고, 리전이 다른 서버 간에도 일관된다. 기본 DEFAULT 동작은 DB/드라이버에 따라 달라서 예측이 어렵다 — 운영 들어가기 전에 이 설정을 명시하는 게 안전하다.

권장 요약: 새 프로젝트는 OffsetDateTime 또는 Instant + NORMALIZE_UTC 조합. 기존 LocalDateTime 코드라면 당장 바꿀 필요는 없지만, 리전 확장 또는 UTC 정책이 들어오는 시점에 마이그레이션을 계획해야 한다.

7) Hibernate Envers: 전면 감사 로그의 비용과 이득

@CreatedDate/@LastModifiedDate는 "마지막으로 언제 누가 바꿨는지" 까지만 기록한다. 그 사이에 몇 번이 바뀌었는지, 이전 값은 무엇이었는지는 알 수 없다. 이 한계를 넘고 싶으면 Hibernate Envers가 선택지다.

Envers는 @Audited 애너테이션이 붙은 엔티티의 모든 변경을 별도 테이블에 히스토리로 쌓는다.

@Entity
@Audited
public class Order extends BaseEntity {
    @Id @GeneratedValue
    private Long id;

    @Enumerated(EnumType.STRING)
    private OrderStatus status;
}

이 한 줄을 붙이면 Hibernate가 추가 테이블을 만든다. orders_AUD(히스토리)와 REVINFO(revision 번호 메타)다. orders에 UPDATE가 나갈 때마다 orders_AUD에 이전 행 전체가 쌓이고, REVINFO에 revision 번호와 timestamp가 들어간다. 나중에 AuditReader로 특정 revision의 엔티티 상태를 재구성할 수 있다.

AuditReader reader = AuditReaderFactory.get(entityManager);

// 어떤 revision들이 있는지
List<Number> revisions = reader.getRevisions(Order.class, orderId);

// 특정 revision 시점의 엔티티 상태
Order snapshot = reader.find(Order.class, orderId, revisions.get(3));

Envers의 이득은 분명하다. **"6번째 바뀌었을 때 상태"**를 재구성할 수 있고, 누가 몇 번 건드렸는지, 어떤 필드가 시간에 따라 어떻게 변했는지 전부 추적된다. 감사 요구가 강한 도메인 — 금융, 의료, 법적 기록 — 에서는 사실상 필수다.

대신 비용도 크다. 테이블이 두 배 이상으로 늘어나고, 모든 UPDATE마다 INSERT가 추가로 나가고, 스키마 변경 시 _AUD 테이블 마이그레이션도 같이 해야 한다. 성능 영향은 트래픽이 많을수록 체감되며, 특히 @Audited를 @OneToMany 컬렉션에 붙이면 컬렉션 수정 시 history 기록이 폭주한다.

실무 권장은 필요한 범위만 선별 적용이다. 주문 상태 변화는 전체 이력이 중요하니 Order에만 @Audited, 로그성 테이블은 제외. 감사 요구가 약한 도메인은 Envers 대신 10편의 ApplicationEvent + @Async 조합으로 AuditLog 테이블에 직접 쓰는 방식이 가볍다. 변경 이벤트를 발행하고 별도 리스너가 로그를 쌓는 구조는 스키마가 단순하고 성능 튜닝도 쉽다.

// Envers 대신 이벤트 기반으로 가는 패턴
@EventListener
@Async
public void onOrderStatusChanged(OrderStatusChanged event) {
    auditLogRepository.save(new AuditLog(
        "Order", event.orderId(), event.oldStatus(), event.newStatus(),
        event.changedBy(), event.changedAt()
    ));
}

Envers와 이 방식의 선택 기준은 "전 필드 이력이 필요한가, 특정 전이만 이력으로 남기면 되는가" 다. 대부분의 서비스는 후자다.

8) Soft Delete 설계 동기와 함정

Soft delete는 "DELETE를 하지 말고 플래그로 상태만 바꾸자"는 패턴이다. deleted 컬럼을 true로 세우거나, deleted_at에 시각을 박는 식이다. 물리 삭제(hard delete)와 비교하면 장단이 뚜렷하다.

측면	Hard Delete	Soft Delete
데이터 복구	불가 (백업 복원 필요)	`UPDATE`로 가능
FK 무결성	`ON DELETE CASCADE` 필요	참조 유지
스토리지	행이 사라짐	계속 쌓임
조회 쿼리	단순	매번 `WHERE deleted = false`
GDPR/개인정보	물리 삭제가 요건과 직결	별도 anonymize 필요

실무에서 soft delete가 유효한 경우는 "삭제됐지만 과거 참조가 유효해야 하는" 도메인이다. 주문, 결제, 계약 같은 엔티티는 사용자가 탈퇴해도 이력이 남아야 한다. 반대로 일회성 로그, 세션, 캐시 같은 건 hard delete가 맞다. 모든 엔티티에 일괄 soft delete를 거는 건 과잉이다.

설계 동기를 인정하고 나면 함정이 따라온다. 네 개가 자주 나온다.

8-1) Unique 제약과의 충돌

가장 흔한 함정이다. users.email에 UNIQUE 제약이 걸려 있으면, soft delete된 사용자도 그 이메일을 점유하고 있다. 같은 이메일로 재가입하려 들면 DB가 거부한다.

-- users 테이블
id | email              | deleted
 1 | alice@example.com  | true    -- soft delete됨
 2 | alice@example.com  | false   -- 재가입 → UNIQUE 위반

해결은 두 가지다. PostgreSQL이면 partial unique index를 쓴다.

CREATE UNIQUE INDEX users_email_active_uniq
  ON users (email)
  WHERE deleted = false;

이러면 deleted = false인 행만 unique 대상이 된다. 삭제된 행은 몇 개든 있어도 괜찮다. MySQL처럼 partial index를 지원하지 않으면 복합 unique로 우회한다 — UNIQUE (email, deleted_at)처럼 deleted_at이 null이 아닌 행끼리만 중복이 의미를 가지게 만든다. 단 NULL의 중복 처리는 DB마다 달라서 사전에 확인이 필요하다.

8-2) @OneToMany cascade와 soft delete

부모가 soft delete될 때 자식은 어떻게 되나. CascadeType.REMOVE는 em.remove(parent)에서 트리거되는데, soft delete는 em.remove()를 호출하지 않는다 — 서비스가 parent.setDeleted(true)로 플래그만 세운다. 결과적으로 cascade가 발동하지 않는다. 자식은 부모가 삭제되어도 계속 조회된다.

해결은 자식도 soft delete 플래그를 가지고, 도메인 서비스가 부모와 자식을 함께 플래그 처리하는 것. 또는 @SQLDelete를 쓰는 경우(§9) em.remove(parent)가 UPDATE로 바뀌고 cascade가 그대로 작동하게 만들 수 있다.

8-3) Native query는 @SQLRestriction을 무시

Hibernate의 @SQLRestriction은 Hibernate가 자동 생성하는 모든 SQL(JPQL, Criteria, repository 메서드, 연관 lazy 로딩 포함)에 덧붙는다. Native query에는 적용되지 않는다. entityManager.createNativeQuery("SELECT ... FROM orders")를 직접 쓰면 이 필터가 무시되면서 삭제된 데이터가 조용히 섞여 나온다.

Native query를 쓰는 경로에서는 WHERE 절을 직접 써야 한다는 규율이 필요하다. 리포팅/어드민 기능에서 많이 밟는다.

8-4) 복원(Undelete)이 번거로워진다

@SQLRestriction이 조회를 막기 때문에, 복원하려면 먼저 삭제된 엔티티를 읽어야 하는데 읽히지를 않는다. 결국 native query로 WHERE deleted = true를 강제해서 읽고, UPDATE로 복원한다. 관리자 UI에서 "복원" 버튼이 있는 서비스는 이 경로가 필요하다 — §11의 @FilterDef로 유연하게 처리할 수도 있다.

네 가지 함정을 의식하지 않고 soft delete를 도입하면, 몇 달 뒤에 "재가입 안 됨", "삭제된 데이터가 어드민에 보임", "복원 기능이 안 만들어진다" 같은 티켓이 줄줄이 올라온다. 도메인별로 soft delete가 필요한가를 먼저 판단하고, 필요한 곳에만 신중하게 적용한다.

9) @SQLDelete + @SQLRestriction (Hibernate 6.3+)

Hibernate는 soft delete를 지원하기 위한 두 어노테이션을 제공한다. @SQLDelete는 DELETE 쿼리를 다른 SQL로 교체하고, @SQLRestriction은 모든 조회에 자동으로 WHERE 절을 덧붙인다.

@Entity
@Table(name = "orders")
@SQLDelete(sql = "UPDATE orders SET deleted = true, deleted_at = NOW() WHERE id = ?")
@SQLRestriction("deleted = false")
public class Order extends BaseEntity {
    @Id @GeneratedValue
    private Long id;

    private boolean deleted = false;

    private OffsetDateTime deletedAt;
}

두 어노테이션의 분업은 명확하다.

어노테이션	역할	동작 시점
`@SQLDelete`	`em.remove()`의 SQL을 교체	JPA DELETE 호출 시
`@SQLRestriction`	모든 SELECT에 `WHERE` 자동 추가	JPQL/Criteria 조회 시

@SQLDelete의 ?는 PK 하나의 위치 파라미터다. 복합 키나 optimistic lock의 version 컬럼까지 쓰려면 ? 개수와 순서를 맞춰야 한다. Hibernate 6 기준 ?는 엔티티의 @Id 컬럼(복합키면 매핑 순서), 그 뒤에 @Version 컬럼 순으로 위치 바인딩된다. 잘못 쓰면 "삭제는 됐는데 엉뚱한 행이 지워진다" 같은 재앙이 일어난다.

@SQLRestriction은 Hibernate 6.3에서 도입된 이름이다. 이전에는 @Where(clause = "deleted = false")를 썼는데, @Where는 deprecated 예정이다. 새 코드는 @SQLRestriction으로 쓰고, 레거시는 점진적으로 교체한다. 이름만 바뀌고 의미는 같다.

// 사용
orderRepository.findById(1L);      // SELECT ... WHERE id=1 AND deleted=false
em.remove(order);                   // UPDATE orders SET deleted=true, deleted_at=NOW() WHERE id=?

서비스 코드는 그대로다. em.remove()라고 쓰지만 실제로는 UPDATE가 나가고, findById로 조회하면 삭제된 엔티티는 결과에서 빠진다. 이 투명성이 @SQLDelete + @SQLRestriction 조합의 핵심 가치다.

주의할 경계 두 가지.

첫째, @SQLDelete/@SQLRestriction은 JPA 스펙이 아니라 Hibernate 전용이다. 다른 JPA 구현체(EclipseLink 등)로 바꾸는 순간 작동하지 않는다. 이 글처럼 Hibernate 고정 환경에서는 문제 없지만, "JPA 호환성을 유지하고 싶다"는 요구가 있으면 이 방식은 선택에서 빠진다.

둘째, 조인 쿼리에서 이상한 중복이 발생할 수 있다. 부모와 자식 양쪽에 @SQLRestriction이 걸려 있으면 fetch join 할 때 WHERE child.deleted = false AND parent.deleted = false가 붙는데, 이게 LEFT JOIN과 결합되면 의도와 다른 결과가 나올 때가 있다. 복잡한 쿼리는 실제 발행 SQL을 찍어보면서 검증한다.

Hibernate 6.3 미만에서는 @SQLRestriction이 없으니 @Where로 써야 한다.

// Hibernate 6.3 이전 fallback
@Where(clause = "deleted = false")

@Where는 deprecated 표시가 붙어 있지만 당장 없어지지는 않는다. 다만 새 코드에서 굳이 쓸 이유는 없다.

10) Hibernate 6.4+ @SoftDelete 신규 애너테이션

Hibernate 6.4에서 @SoftDelete 어노테이션이 도입됐다. @SQLDelete + @SQLRestriction 조합을 한 어노테이션으로 대체하는 Hibernate가 공식 지원하는 축약형이다.

@Entity
@Table(name = "orders")
@SoftDelete(columnName = "deleted", strategy = SoftDeleteType.DELETED)
public class Order extends BaseEntity {
    @Id @GeneratedValue
    private Long id;
    // deleted 컬럼은 Hibernate가 자동으로 관리 — 필드 선언 불필요
}

두 파라미터가 있다. columnName은 soft delete 플래그 컬럼명(기본 deleted). strategy는 플래그의 해석 방향을 정한다.

전략	플래그가 `true`면	자동으로 붙는 `WHERE` 절
`SoftDeleteType.DELETED`	"삭제됨"으로 간주	`WHERE deleted = false`
`SoftDeleteType.ACTIVE`	"활성"으로 간주	`WHERE is_active = true`

레거시 스키마에서 is_active 컬럼을 쓰는 경우 ACTIVE 전략이 유용하다.

// 레거시 스키마: is_active 컬럼
@Entity
@SoftDelete(columnName = "is_active", strategy = SoftDeleteType.ACTIVE)
public class LegacyEntity { ... }

@SoftDelete의 이득은 보일러플레이트 감소와 Hibernate 공식 지원이다. @SQLDelete의 SQL을 직접 쓸 필요가 없고, WHERE 절도 자동으로 붙는다. 복합 키 엔티티에서도 PK 순서 신경쓸 필요 없다.

대신 한계가 있다. Hibernate 6.4 기준으로 기능이 아직 성숙 중이라서, 복잡한 필터 조건은 표현할 수 없다. 예를 들어 "deleted가 false이고, tenant_id가 특정 값인 것만" 같은 다중 조건 필터는 여전히 @SQLRestriction이 필요하다. deleted_at 같은 부가 컬럼을 같이 업데이트하고 싶으면 @SQLDelete의 자유도가 더 높다.

// 복잡한 조건 — @SQLRestriction 유지
@SQLDelete(sql = "UPDATE orders SET deleted = true, deleted_at = NOW(), deleted_by = current_user WHERE id = ?")
@SQLRestriction("deleted = false AND tenant_id = current_setting('app.tenant_id')::bigint")

여기서 current_user는 DB 접속 계정이지 애플리케이션 로그인 사용자가 아니다. 감사 대상이 "누가 로그인해서 지웠는가"라면 이 값은 쓸모가 없으니, 애플리케이션 사용자를 기록하려면 @SQLDelete 대신 엔티티 메서드에서 deletedBy 필드를 세팅하고 normal UPDATE로 내보내는 편이 맞다.

권장: 단순한 soft delete 플래그만 있고 추가 로직이 필요 없으면 @SoftDelete. deleted_at·deleted_by 같은 부가 정보를 같이 관리하거나 멀티 테넌시 필터 같은 조건이 붙으면 @SQLDelete + @SQLRestriction 조합. Hibernate 6.3 이하에서는 선택지가 @SQLDelete + @SQLRestriction 하나뿐이다.

11) @FilterDef + @Filter로 동적 필터

@SQLRestriction은 항상 적용되는 정적 필터다. 켜고 끌 수가 없다. 관리자 UI에서 "삭제된 데이터도 함께 보기"를 지원하려면 별도 경로가 필요한데, @SQLRestriction을 쓰면 이게 불가능하다.

Hibernate의 @FilterDef + @Filter 는 세션 단위로 on/off 가능한 동적 필터를 정의한다.

@Entity
@FilterDef(
    name = "deletedFilter",
    parameters = @ParamDef(name = "isDeleted", type = "java.lang.Boolean"),
    defaultCondition = "deleted = :isDeleted"
)
@Filter(name = "deletedFilter")
public class Order extends BaseEntity {
    @Id @GeneratedValue
    private Long id;

    private boolean deleted = false;
}

@FilterDef가 필터의 정의(이름, 파라미터, 조건식), @Filter가 이 엔티티에 필터를 적용하겠다는 선언이다. 기본 상태에서는 필터가 비활성이고, 쿼리 실행 전에 Session에서 enableFilter를 호출해야 적용된다.

@Service
public class OrderQueryService {

    @PersistenceContext
    private EntityManager em;

    public List<Order> findActive() {
        Session session = em.unwrap(Session.class);
        session.enableFilter("deletedFilter")
               .setParameter("isDeleted", false);

        return em.createQuery("select o from Order o", Order.class).getResultList();
    }

    public List<Order> findAllIncludingDeleted() {
        // 필터 활성화 안 함 — 모든 Order 조회
        return em.createQuery("select o from Order o", Order.class).getResultList();
    }
}

이 조합의 강점은 컨텍스트에 따라 필터를 바꿀 수 있다는 것이다. 일반 사용자 API는 필터 ON, 관리자 API는 필터 OFF. 트랜잭션 중에 필터를 끄고 삭제된 데이터를 복구한 뒤 다시 켜는 식의 세밀한 제어도 가능하다. @SQLRestriction의 강제성과 정반대의 유연함이다.

권장 사용 패턴:

기본 서비스 경로에는 @SQLRestriction(항상 삭제된 데이터 제외)
관리자 경로나 복원 API에는 @FilterDef + @Filter(동적 제어)

두 어노테이션을 같이 쓰면 동시 적용 시 두 조건이 AND로 결합되어 의도와 다르게 결과가 빌 수 있으므로 팀 컨벤션상 하나만 선택하는 편이 깔끔하다. @FilterDef만 쓰면 모든 리포지토리 메서드에 필터 활성화 코드를 넣어야 해서 번거롭다. 대부분의 프로젝트는 @SQLRestriction 기본 + 관리자 전용 네이티브 쿼리 조합으로 충분하다.

12) 실무 체크리스트

실무에서 Auditing과 Soft Delete를 도입할 때 챙겨야 할 체크리스트를 섹션별로 정리한다.

@EnableJpaAuditing + @EntityListeners(AuditingEntityListener.class) 한 쌍을 항상 함께 확인. 둘 중 하나만 있으면 아무 일도 일어나지 않는다. BaseEntity에 리스너를 붙이고, @Configuration 클래스에 @EnableJpaAuditing을 선언한다.
AuditorAware는 fallback을 반드시 포함. SYSTEM, BATCH, SCHEDULER 같은 특수 문자열로 인증 없는 경로를 구분한다. null을 반환하게 두지 않는다.
@CreatedDate와 @CreatedBy에는 @Column(updatable = false) 고정. 생성 정보는 엔티티의 수명 동안 불변이어야 한다. 도메인 규율로만 지키려고 하면 언젠가 깨진다.
시간 타입은 OffsetDateTime 또는 Instant 권장. LocalDateTime은 레거시 코드에서만 유지하고 새 엔티티에는 쓰지 않는다. hibernate.timezone.default_storage=NORMALIZE_UTC를 같이 설정한다.
Soft delete는 도메인별 선택. 주문/결제/계약 같은 이력이 중요한 도메인에만 적용하고, 로그성/세션성 테이블은 hard delete를 유지한다. "모든 엔티티에 soft delete"는 과잉이다.
@SQLRestriction을 쓸 때는 unique 제약 전략을 먼저 정한다. PostgreSQL은 partial unique index, MySQL은 복합 unique 또는 재가입 허용 정책. 운영 투입 전에 결정하지 않으면 며칠 안에 재가입 불가 티켓이 올라온다.
Native query 경로에는 WHERE deleted = false를 직접 쓴다. @SQLRestriction이 무시되는 걸 코드 리뷰 체크리스트에 박아둔다. 특히 리포팅·어드민·배치 경로에서 누락되기 쉽다.
Hibernate 6.4+라면 단순 케이스는 @SoftDelete 고려. 플래그 외에 deleted_at·deleted_by 같은 부가 정보가 필요하면 @SQLDelete + @SQLRestriction 조합이 낫다. 선택 기준을 팀 컨벤션으로 문서화.
Envers는 감사 요구가 강한 도메인 한정. 금융/의료/법적 기록처럼 전 필드 이력이 필요한 경우에만 쓴다. 일반 서비스는 이벤트 기반 audit log가 가볍다.
Clock을 통해 시각을 주입하는 습관. DateTimeProvider가 Clock에 의존하게 두면 테스트에서 시간이 고정되고, 운영에서도 tz 정책을 한 곳에서 제어할 수 있다. LocalDateTime.now() 직접 호출은 점진적으로 제거.
BaseEntity의 Setter는 열지 않는다. @Getter만 주고 감사 필드를 외부에서 수정하지 못하게 막는다. Lombok @Data는 34편에서 본 양방향 순환 참조 리스크까지 겹치니 BaseEntity에는 절대 쓰지 않는다.

13) 한 줄 정리

JPA Auditing과 Soft Delete는 "생성·수정·삭제라는 라이프사이클을 서비스가 아니라 영속성 계층이 책임지도록 내리는" 동일한 설계 결이다. @EnableJpaAuditing + AuditorAware + BaseEntity(@MappedSuperclass + @EntityListeners) 한 세트를 기본으로 두고, soft delete는 도메인별로 선택적으로 @SQLDelete + @SQLRestriction(Hibernate 6.3+) 또는 @SoftDelete(6.4+)를 붙인다. AuditorAware의 fallback과 unique 제약 전략, native query의 필터 누락은 설계 단계에서 결정하지 않으면 반드시 운영 이슈로 돌아온다.

태그: JPA, Spring Data JPA, Hibernate, Auditing, @CreatedDate, @AuditorAware, Soft Delete, @SQLDelete, @SQLRestriction, @SoftDelete, Envers

JPA Locking — @Version Optimistic과 @Lock Pessimistic의 경계

dding-shark — Tue, 21 Apr 2026 20:27:54 +0900

JPA Locking — @Version Optimistic과 @Lock Pessimistic의 경계

들어가며

재고 수량을 줄이는 코드를 짰다. stock.setQuantity(stock.getQuantity() - 1) 한 줄이다. 동시에 두 개의 요청이 들어오면 둘 다 재고가 10인 줄 알고 각자 -1을 해서 9로 UPDATE한다. DB에는 9가 남지만, 실제로는 두 건이 팔렸으니 8이 맞다. 한 건이 사라진 셈이다. 이걸 분실된 갱신(Lost Update) 이라고 부르고, 거의 모든 동시성 사고의 출발점이다.

JPA는 이 문제를 두 갈래로 풀어준다. 한쪽은 낙관적 잠금(Optimistic Locking) 으로, @Version 컬럼에 번호를 달아두고 "내가 읽은 이후에 누군가 건드렸으면 예외로 알려줘"라고 DB에게 부탁한다. 다른 한쪽은 비관적 잠금(Pessimistic Locking) 으로, SELECT ... FOR UPDATE로 DB에 아예 물리적 락을 걸어버린다. 이름 그대로 하나는 "충돌이 잘 안 날 거야"라고 낙관하고, 하나는 "충돌 날 테니 미리 잠가두자"라고 비관한다. 어느 쪽을 어디에 쓸지는 충돌 빈도와 실패 비용의 비율로 결정한다.

이 글은 8편 @Transactional 심화와 12편 영속성 컨텍스트를 깔고 간다. 트랜잭션 경계 안에서 EM이 무엇을 하는지가 아니라, 그 경계 안에서 동시에 들어온 다른 경계와 어떻게 부딪히는지를 본다.

findById에 @Lock을 붙이려다 어노테이션이 안 먹는다 — 기본 메서드에는 붙일 수 없다
@Version 붙였는데 detached 엔티티를 merge하자마자 OptimisticLockException이 난다 — 버전 숫자가 옛날 값이다
PESSIMISTIC_WRITE를 걸었더니 데드락이 잦다 — 락 획득 순서가 제각각이다
SKIP LOCKED로 메시지 큐 소비를 구현하려는데 DB마다 지원이 다르다 — JPA 표준 힌트로는 한계가 있다

이 글은 문제 → 두 전략 → LockModeType → @Lock → 타임아웃/NOWAIT/SKIP LOCKED → 예외 처리 → 데드락 → 경합 심한 도메인 → 함정 → 실무 순으로, Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x 기준으로 정리한다.

1) Lost Update 문제와 Locking의 두 갈래
2) @Version과 Optimistic Locking 원리
3) @Version 타입 선택: Long을 권장하는 이유
4) LockModeType 6종의 의미
5) @Lock 어노테이션과 Repository 메서드
6) PESSIMISTIC_WRITE와 SELECT ... FOR UPDATE
7) 락 타임아웃과 NOWAIT / SKIP LOCKED
8) OptimisticLockException 재시도 패턴
9) 데드락 회피: 락 순서와 보유 시간
10) 경합 심한 도메인의 락 선택: Stock / Counter
11) 함정 종합
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) Lost Update 문제와 Locking의 두 갈래

동시성 버그는 이름이 붙은 세 가지 유형으로 자주 정리된다. 분실된 갱신(Lost Update), 더티 리드(Dirty Read), 그리고 반복 불가능한 읽기 / 팬텀 리드(Non-Repeatable / Phantom Read) 다. 이 중 Dirty Read와 Non-Repeatable Read는 DB의 격리 수준(Isolation Level) 설정으로 대부분 해결된다 — 상세는 8편 §4에서 다뤘다. 격리 수준으로 잘 막히지 않는 게 Lost Update다. 애플리케이션이 "읽고-바꾸고-쓴다"라는 세 단계를 하나의 트랜잭션으로 묶어도, 두 트랜잭션이 각자 같은 값을 읽고 각자 써버리면 한 쪽의 변경이 사라진다. JPA Locking은 주로 이 Lost Update를 방어하기 위한 장치다.

두 갈래 중에 어디를 선택할지는 충돌 빈도와 실패 비용의 비율로 결정한다. 충돌이 드물고 재시도 비용이 낮으면 낙관적 잠금이 낫고, 충돌이 잦거나 재시도가 비즈니스적으로 곤란하면 비관적 잠금이 낫다. 재고 차감처럼 충돌이 빈번한 곳은 후자가, 사용자 프로필 수정처럼 동시 편집이 거의 없는 곳은 전자가 어울린다.

구분	Optimistic (`@Version`)	Pessimistic (`@Lock`)
원리	version 컬럼 비교로 충돌 감지	DB 락으로 충돌 예방
DB 락	없음	`FOR UPDATE` / `FOR SHARE`
실패 시점	commit 시 예외	대기 또는 타임아웃
성능	충돌 적을 때 우수	락 오버헤드 + 대기
확장성	높음 (분산 환경 유리)	낮음 (경합 시 병목)
예외	`OptimisticLockException`	`LockTimeoutException` 등
전형적 용도	프로필/주문 수정	재고 차감·좌석 예약

두 방식은 같이 쓸 수도 있다. @Version을 붙여둔 엔티티에 PESSIMISTIC_WRITE를 걸면, 락으로 물리적 경합을 막으면서 version으로 버전 불일치까지 이중으로 막는다. 다만 실무에서는 대개 둘 중 하나를 선택하는 쪽이 더 예측 가능하다. 섞어 쓰면 장애 시 원인 추적이 복잡해진다.

2) @Version과 Optimistic Locking 원리

@Version은 엔티티에 정수(또는 시각) 컬럼을 하나 붙여서 매 갱신마다 값을 1 증가시키는 아주 단순한 장치다. Hibernate가 이 컬럼을 UPDATE 문의 WHERE 절에 자동으로 끼워 넣는다. 그 결과 UPDATE가 성공하면 "내가 읽은 이후 아무도 안 건드렸다"가 보장되고, 실패(0 rows affected)하면 "누군가 먼저 바꿨다"가 증명된다.

@Entity
public class Order {

    @Id
    private Long id;

    private int quantity;

    @Version
    private Long version;   // 매 UPDATE마다 +1
}

동작을 분해하면 이렇다. 트랜잭션 A가 order 엔티티를 조회하면 version=5가 같이 딸려 온다. A가 quantity를 바꾸고 commit하면 Hibernate는 다음과 같이 쿼리를 만든다.

UPDATE orders
   SET quantity = ?, version = 6
 WHERE id = ? AND version = 5

이때 트랜잭션 B가 먼저 commit해서 version이 6으로 이미 올라가 있으면, A의 UPDATE는 WHERE version = 5 조건을 만족하지 못하고 0 rows affected가 된다. Hibernate는 이 결과를 보고 OptimisticLockException(Hibernate의 StaleObjectStateException이 원인)을 던진다. 스프링 래핑을 거치면 최종적으로 ObjectOptimisticLockingFailureException으로 전파된다. 즉 Optimistic Locking은 충돌을 방지하지 않는다. 감지할 뿐이다. 이 차이는 이후 모든 논의의 출발점이다.

이 그림에서 읽어야 할 건 두 가지다. 첫째, 낙관 쪽은 충돌이 commit 시점에 터지고, 비관 쪽은 lock 시점에 대기로 직렬화된다. 둘째, 낙관은 재시도 또는 사용자 통지라는 애플리케이션 측 대응 전략이 필수고, 비관은 대신 대기 시간과 데드락 위험을 감수한다. 구조를 바꾸지 않고 단순히 둘을 바꿔 달 수 있는 게 아니라, 서비스 흐름 자체가 다른 방향으로 설계된다.

JPQL 벌크 UPDATE는 version을 자동 증가시키지 않는다. Hibernate 확장 UPDATE VERSIONED Stock s SET ...를 쓰거나 SET s.version = s.version + 1을 명시해야 한다. Native Query도 마찬가지로 version = version + 1을 직접 넣지 않으면 이후 엔티티 버전이 DB와 어긋나기 시작한다.

3) @Version 타입 선택: Long을 권장하는 이유

@Version 필드의 타입은 JPA 스펙상 int, Integer, long, Long, short, Short, java.sql.Timestamp가 허용된다. Hibernate는 여기에 java.time.Instant / LocalDateTime 같은 시각 계열도 지원한다. 겉보기엔 선택지가 많지만, 실무에서 쓸만한 건 사실상 Long 하나다.

// 선호: Long
@Version
private Long version;

// 피하기: LocalDateTime
@Version
private LocalDateTime updatedAt;   // 같은 밀리초에 두 UPDATE가 들어오면 충돌 감지 실패

숫자 타입과 시각 타입의 차이는 해상도다. 숫자는 항상 1씩 증가하므로 "다른 값인지"를 비교하기만 하면 된다. 시각은 시스템 시계의 정밀도에 의존한다. JVM의 Instant는 밀리초 또는 마이크로초 단위이고, 같은 밀리초에 두 트랜잭션이 동시에 UPDATE를 날리면 두 쪽 다 똑같은 timestamp를 version에 쓰게 되어 충돌 감지가 실패할 수 있다. 경합이 심한 자리에 시각 기반 버전을 쓰는 건 위험하다.

오버플로도 사람들이 자주 걱정하지만 Long이면 사실상 무시해도 된다. 초당 1000번 갱신해도 Long.MAX_VALUE에 도달하려면 2억 년 이상 걸린다. Integer는 이론적으로 부족할 가능성이 있지만, 대부분의 OLTP 엔티티에서도 충분히 안전하다. 그래도 Long이 기본 권장인 이유는 한 번 정하면 마이그레이션이 번거롭기 때문이다.

한편 @Version 필드에는 @Convert로 커스텀 Converter를 붙이면 안 된다. Hibernate는 필드 원시 값을 직접 비교하는데, Converter가 중간에 끼면 비교 로직이 Converter 경유로 돌아가면서 예기치 않은 동등성 판단이 생길 수 있다. 특히 LocalDateTime에 timezone 변환 Converter가 끼면 같은 시각인데 다르게 비교되는 사고가 종종 보고된다. version 필드는 순수하게 두자가 원칙이다.

4) LockModeType 6종의 의미

Jakarta Persistence 3.x의 LockModeType은 겉보기엔 이름이 많지만, 두 갈래(Optimistic / Pessimistic) × 세 변주(기본 / FORCE_INCREMENT / READ-WRITE 구분)로 정리된다.

LockModeType	갈래	DB 락	version 증가	용도
`NONE`	—	없음	없음 (수정 시만)	기본. 잠금 명시 안 함
`OPTIMISTIC`	낙관	없음	버전 재검증만, 증가 없음	읽기만 하지만 시점 보장이 필요
`OPTIMISTIC_FORCE_INCREMENT`	낙관	없음	읽기만 해도 강제 +1	연관 엔티티 변경 시 부모 버전도 올리고 싶을 때
`PESSIMISTIC_READ`	비관	공유 락 (FOR SHARE)	없음	다른 트랜잭션의 쓰기만 차단, 읽기는 허용
`PESSIMISTIC_WRITE`	비관	배타 락 (FOR UPDATE)	없음	다른 트랜잭션의 읽기/쓰기 모두 차단
`PESSIMISTIC_FORCE_INCREMENT`	비관	배타 락	함께 +1	락으로 직렬화하면서 version도 증가

(READ/WRITE는 JPA 2.0 시절 alias로 남아 있으나 deprecated, 신규 코드에서는 쓰지 않는다.)

두 개씩 짝을 지어 의미를 잡으면 이해가 쉽다.

4-1) OPTIMISTIC vs OPTIMISTIC_FORCE_INCREMENT

OPTIMISTIC은 읽기만 했는데도 commit 시점에 "내가 읽은 version이 아직 그대로인지" 를 다시 확인한다. 평범한 SELECT는 읽은 뒤에 다른 트랜잭션이 바꿔도 모르는 채로 지나가지만, OPTIMISTIC 모드로 조회하면 commit 시 해당 row의 현재 version과 내가 읽은 version을 비교해서 다르면 예외가 난다. "쓰기는 안 하지만 내가 본 스냅샷 기준으로 결정하고 싶다"는 시나리오에 쓴다.

OPTIMISTIC_FORCE_INCREMENT는 한 걸음 더 나간다. 읽기만 했는데도 version을 강제로 +1 하고 그 변경을 내보낸다. 부모-자식 관계에서 자식만 바꿨을 때 부모 버전도 같이 올려서 "이 집계 엔티티가 바뀌었다"를 외부에 알리고 싶을 때 유용하다. Aggregate 패턴에서 가끔 본다.

4-2) PESSIMISTIC_READ vs PESSIMISTIC_WRITE

PESSIMISTIC_READ는 DB 수준의 공유 락을 건다. 같은 락을 여러 트랜잭션이 동시에 보유할 수 있고, 그 동안에는 아무도 쓰기를 하지 못한다. "읽는 동안 바뀌지 말아라"에 가깝다. PESSIMISTIC_WRITE는 배타 락이다. 한 트랜잭션만 보유할 수 있고, 다른 모두는 대기 또는 타임아웃된다. "읽는 순간부터 내가 쓸 때까지 아무도 접근 못 한다"에 해당한다.

MySQL InnoDB에서는 구현 매핑이 살짝 다르다. PESSIMISTIC_READ는 MySQL 8.0 미만에서는 LOCK IN SHARE MODE, 8.0 이상에서는 FOR SHARE로 번역된다. PESSIMISTIC_WRITE는 FOR UPDATE다. PostgreSQL은 둘 다 FOR SHARE / FOR UPDATE로 직역된다.

4-3) PESSIMISTIC_FORCE_INCREMENT

락으로 직렬화하는데도 version까지 함께 올리고 싶을 때 쓴다. 실무에서 흔하진 않지만, 비관적 잠금 중에도 "이 엔티티가 수정되었다"는 기록을 명시적으로 남기고 싶을 때 의미가 있다. 예를 들어 재고 차감을 PESSIMISTIC_WRITE로 직렬화하면서, 같은 엔티티를 별도 경로에서 OPTIMISTIC으로 읽는 흐름이 있다면 version이 올라가야 그 경로가 충돌을 감지할 수 있다.

5) @Lock 어노테이션과 Repository 메서드

Spring Data JPA에서 LockModeType을 지정하는 가장 흔한 방법은 @Lock 어노테이션이다. Repository 메서드 위에 붙여서 "이 쿼리는 이 락 모드로 실행된다"를 선언한다.

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT o FROM Order o WHERE o.id = :id")
    Optional<Order> findByIdForUpdate(@Param("id") Long id);
}

호출부는 평범한 Repository 메서드 호출 그대로다. 내부에서 Hibernate가 SELECT ... FOR UPDATE로 쿼리를 만들어 보낸다. 주의할 점은 이 메서드는 반드시 @Transactional 경계 안에서 호출되어야 한다는 것이다. 트랜잭션 밖에서 호출하면 TransactionRequiredException이 나거나, DB가 자동 commit 모드로 락을 걸었다가 즉시 풀어버린다. 결과적으로 의미 없는 락이 된다.

5-1) findById에는 @Lock을 붙일 수 없다

많이들 이 자리에서 막힌다. JpaRepository가 기본 제공하는 findById(id)에 @Lock(PESSIMISTIC_WRITE)를 덮어씌우고 싶은데, 어노테이션이 안 먹는다.

// 피하기: 기본 메서드를 override 하면서 @Lock
public interface OrderRepository extends JpaRepository<Order, Long> {

    @Override
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    Optional<Order> findById(Long id);   // 동작은 하지만 호출부에서 락 여부가 드러나지 않음
}

이게 애매한 이유는 Spring Data JPA의 SimpleJpaRepository가 findById를 자체 구현해버리기 때문이다. 기술적으로는 override + @Lock 조합이 Spring Data JPA에서 동작하지만, 호출부가 평범한 findById와 구분되지 않아 락이 걸리는 경로인지 드러나지 않는다. 그래서 실무에서는 별도 메서드를 권장한다.

// 선호: 별도 메서드
public interface OrderRepository extends JpaRepository<Order, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT o FROM Order o WHERE o.id = :id")
    Optional<Order> findByIdForUpdate(@Param("id") Long id);
}

이 쪽이 코드 의도도 더 선명하다. "락을 거는 조회"와 "평범한 조회"를 이름으로 구분할 수 있으니 호출부를 봐도 어느 쪽이 직렬화 영역인지 한눈에 보인다.

5-2) EntityManager 직접 호출

@Lock을 쓰지 않고 EM API로 락을 거는 방법도 있다. 동적으로 락 모드를 바꿔야 할 때나, 이미 managed 상태인 엔티티에 사후적으로 락을 걸고 싶을 때 쓴다.

// find 시점에 락 모드 지정
Order order = em.find(Order.class, id, LockModeType.PESSIMISTIC_WRITE);

// 이미 managed인 엔티티에 락 추가
Order order = em.find(Order.class, id);
em.lock(order, LockModeType.OPTIMISTIC);   // commit 시 version 재검증

em.lock의 뒤쪽 사용법은 특히 OPTIMISTIC과 궁합이 좋다. 1차 캐시에서 이미 꺼내온 엔티티에도 commit 시점 version 재검증을 추가로 부여할 수 있다.

6) PESSIMISTIC_WRITE와 SELECT ... FOR UPDATE

PESSIMISTIC_WRITE는 DB에 배타 락을 건다. 대부분의 RDB에서는 SELECT ... FOR UPDATE로 번역된다. 이 쿼리가 도는 동안 같은 row를 읽거나 쓰려는 다른 트랜잭션은 대기한다. 트랜잭션이 commit 또는 rollback되면 락이 풀리면서 대기 중이던 트랜잭션이 깨어난다.

@Transactional
public void decreaseStock(Long stockId, int quantity) {
    Stock stock = orderRepository.findByIdForUpdate(stockId)   // FOR UPDATE
        .orElseThrow();
    if (stock.getQuantity() < quantity) {
        throw new IllegalStateException("재고 부족");
    }
    stock.setQuantity(stock.getQuantity() - quantity);
    // 트랜잭션 종료 시 commit → 락 해제
}

이 흐름의 핵심은 락 획득부터 해제까지가 트랜잭션 경계와 정확히 일치한다는 점이다. 트랜잭션 길이가 곧 다른 트랜잭션을 대기시키는 시간이다. 락 안에서 외부 API를 호출하거나, 무거운 계산을 돌리거나, 사용자 입력을 기다리는 순간 직렬화 비용이 폭발한다. "락 안에서는 DB 작업만"이 기본 원칙이다.

6-1) readOnly 트랜잭션에서의 PESSIMISTIC_WRITE

@Transactional(readOnly = true) 안에서 PESSIMISTIC_WRITE를 거는 코드를 가끔 본다. readOnly의 의미는 JPA 쪽에서는 FlushMode=MANUAL이지만 JDBC 드라이버 쪽에서는 구현체에 따라 트랜잭션을 read-only 모드로 세팅할 수 있다 — 상세는 8편 §6. PostgreSQL처럼 read-only 트랜잭션에서 FOR UPDATE를 거부하는 DB도 있고, MySQL처럼 무시하고 진행하는 DB도 있다. 락이 필요하다면 readOnly를 빼는 게 맞다. 의도가 섞이면 나중에 디버깅이 힘들다.

6-2) 락 범위는 row 단위가 기본

FOR UPDATE의 락 범위는 DB마다 약간씩 다르지만, InnoDB·PostgreSQL 기준으로 조회된 row 단위가 기본이다. WHERE에 인덱스가 없으면 테이블 스캔이 일어나면서 불필요한 row까지 잠기는 참사가 벌어질 수 있다 — MySQL InnoDB에서는 특히 조심해야 한다. findByIdForUpdate처럼 PK 조회는 안전하지만, findByStatus(...) 같은 보조 인덱스 조회에 FOR UPDATE를 거는 패턴은 쿼리 플랜을 반드시 확인해야 한다.

7) 락 타임아웃과 NOWAIT / SKIP LOCKED

비관적 잠금에서 가장 먼저 설정해야 하는 게 대기 시간 상한이다. 무제한 대기는 곧 커넥션 풀 고갈로 이어진다. JPA는 표준 힌트 jakarta.persistence.lock.timeout을 제공한다(단위: ms).

public interface StockRepository extends JpaRepository<Stock, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000"))
    @Query("SELECT s FROM Stock s WHERE s.id = :id")
    Optional<Stock> findByIdForUpdate(@Param("id") Long id);
}

다만 이 힌트를 DB가 실제로 해석해 주는지는 구현에 따라 다르다. PostgreSQL은 세션 변수 lock_timeout을 함께 설정해야 의도대로 동작하고, MySQL InnoDB는 innodb_lock_wait_timeout을 기본으로 쓰면서 쿼리 수준 타임아웃을 상대적으로 덜 지원한다. 필요하면 트랜잭션 시작 시점에 명시적으로 세션 변수를 건다.

// PostgreSQL: 트랜잭션 스코프에서 lock_timeout 설정
@Transactional
public void someMethod() {
    em.createNativeQuery("SET LOCAL lock_timeout = '3s'").executeUpdate();
    // 이후 모든 락 획득은 3초 타임아웃 적용
}

7-1) NOWAIT: 즉시 실패

NOWAIT는 락을 즉시 얻지 못하면 예외다. 대기 없이 바로 실패 처리하고 싶을 때 쓴다. 사용자 요청에 즉시 응답해야 하는 API에서 "지금 선점할 수 있나?"라는 질문에 어울린다. Hibernate는 힌트 값 -2를 NOWAIT로 매핑한다.

@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "-2"))
@Query("SELECT s FROM Seat s WHERE s.id = :id")
Optional<Seat> findByIdNoWait(@Param("id") Long id);

7-2) SKIP LOCKED: 잠긴 건 건너뛰기

SKIP LOCKED는 이미 잠긴 row는 조회 결과에서 제외한다. 대기도 안 하고 예외도 안 던지고, 그냥 "다른 놈이 잡고 있으니 내가 잡을 수 있는 다른 걸 찾자"라는 의미다. 메시지 큐의 소비자 패턴에 특히 유용하다 — 여러 워커가 같은 테이블에서 작업을 하나씩 꺼낼 때 서로 다른 row를 집어간다. Hibernate는 -1을 SKIP LOCKED로 매핑한다.

// 대기 큐 테이블에서 처리할 작업 하나를 빼 간다
@Lock(LockModeType.PESSIMISTIC_WRITE)
@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "-1"))
@Query("SELECT j FROM Job j WHERE j.status = 'PENDING' ORDER BY j.createdAt ASC")
List<Job> findNextJobsSkipLocked(Pageable pageable);

다만 SKIP LOCKED는 DB별 지원 차이가 크다. PostgreSQL 9.5+, MySQL 8.0+, Oracle은 지원한다. MySQL 5.7 이하, 오래된 MariaDB 버전은 지원하지 않는다. Hibernate가 -1 힌트를 받아도 DB가 지원하지 않으면 무시하거나 다른 행동을 한다. 이 기능을 쓰기 전에 DB 버전과 방언(dialect)을 먼저 확인하는 게 안전하다.

힌트 값	의미	Hibernate 해석
양의 정수 (ms)	대기 상한	지원 DB에서 `lock_timeout` 설정
`0`	대기 없음 (일부 DB에서만)	즉시 실패 또는 NOWAIT로 번역
`-1`	SKIP LOCKED	DB 지원 시에만 유효
`-2`	NOWAIT	DB 지원 시에만 유효

8) OptimisticLockException 재시도 패턴

Optimistic Locking을 쓰면 필연적으로 OptimisticLockException 또는 그 하위 예외(ObjectOptimisticLockingFailureException 같은 스프링 래핑)를 다루게 된다. 이 예외는 누군가 먼저 바꿨으니 다시 시도하거나 사용자에게 알려달라는 신호다. 어떻게 처리할지는 도메인 성격에 따라 다르다.

8-1) 사용자에게 알리는 패턴

실시간 상호작용이 없는 사용자 수정(프로필, 설정 변경 등)에서는 재시도보다 통지가 낫다. 사용자가 본 시점의 데이터로 덮어쓰면 다른 사람의 변경이 사라지니, "다른 사용자가 먼저 수정했습니다. 최신 정보를 다시 불러오시겠습니까?"라는 식으로 화면에 안내한다.

@Transactional
public void updateProfile(Long userId, UpdateRequest req) {
    User user = userRepository.findById(userId).orElseThrow();
    user.update(req);
    // commit 시 OptimisticLockException 가능
}

// 호출부 (컨트롤러)
try {
    userService.updateProfile(userId, req);
} catch (ObjectOptimisticLockingFailureException e) {
    throw new StaleDataException("다른 사용자가 먼저 수정했습니다.");
}

8-2) 자동 재시도 패턴

반대로 재시도가 자연스러운 도메인(예: 내부 처리 잡)에서는 Spring Retry로 자동 재시도를 건다. 단 재시도 횟수 상한을 반드시 명시해야 한다. 무한 재시도는 경합이 심할수록 폭주한다.

@Retryable(
    retryFor = ObjectOptimisticLockingFailureException.class,
    maxAttempts = 3,
    backoff = @Backoff(delay = 50, multiplier = 2)
)
@Transactional
public void processJob(Long jobId) {
    Job job = jobRepository.findById(jobId).orElseThrow();
    job.process();
}

여기서 틀리기 쉽다. @Retryable은 @Transactional보다 바깥쪽에서 작동해야 한다. 같은 메서드에 둘 다 붙이면 순서가 엉켜서 재시도 시점에 트랜잭션이 이미 롤백되어 있지 않을 수 있다. 보통은 @Retryable을 가진 상위 메서드가 @Transactional 메서드를 호출하는 구조로 분리한다.

// 선호: 외부 메서드는 재시도, 내부 메서드가 트랜잭션
@Service
public class JobService {

    @Retryable(retryFor = ObjectOptimisticLockingFailureException.class, maxAttempts = 3)
    public void processJobWithRetry(Long jobId) {
        internalProcessJob(jobId);
    }

    @Transactional
    public void internalProcessJob(Long jobId) {
        Job job = jobRepository.findById(jobId).orElseThrow();
        job.process();
    }
}

8-3) 수동 재시도

Spring Retry를 추가하기 싫으면 try-catch + 반복문으로 충분하다.

int attempts = 3;
while (attempts-- > 0) {
    try {
        service.processJob(jobId);
        return;
    } catch (ObjectOptimisticLockingFailureException e) {
        if (attempts == 0) throw e;
        Thread.sleep(50);   // 단순 backoff
    }
}

단순해 보여도 이 패턴은 무한 루프에 빠지지 않도록 상한이 꼭 필요하고, 재시도 사이에 backoff도 필요하다. 바로 재시도하면 같은 경합 상황이 그대로 반복된다. 간격을 살짝 두는 것만으로도 충돌 확률이 크게 떨어진다.

9) 데드락 회피: 락 순서와 보유 시간

비관적 잠금을 쓰기 시작하면 곧 만나는 게 데드락이다. 트랜잭션 A가 X 락을 쥐고 Y를 기다리고, B가 Y를 쥐고 X를 기다리는 순환. DB는 데드락을 감지하면 한 쪽을 희생자(victim)로 골라 rollback하고 DeadlockLoserDataAccessException(스프링 래핑) 또는 드라이버별 데드락 예외를 던진다.

회피 원칙은 단순한데 지키기는 까다롭다.

9-1) 항상 같은 순서로 락을 획득한다

여러 row에 락을 걸 일이 있으면 id 오름차순처럼 고정된 순서로 획득한다.

// 피하기: 호출 순서가 제각각
@Transactional
public void transfer(Long fromId, Long toId, int amount) {
    Account from = accountRepository.findByIdForUpdate(fromId).orElseThrow();
    Account to = accountRepository.findByIdForUpdate(toId).orElseThrow();
    // fromId=1, toId=2인 트랜잭션과 fromId=2, toId=1인 트랜잭션이
    // 서로 반대 방향으로 락을 쥐면 데드락
}

// 선호: id 오름차순으로 정렬 후 락
@Transactional
public void transfer(Long fromId, Long toId, int amount) {
    Long firstId = Math.min(fromId, toId);
    Long secondId = Math.max(fromId, toId);
    accountRepository.findByIdForUpdate(firstId).orElseThrow();
    accountRepository.findByIdForUpdate(secondId).orElseThrow();
    // 이제 실제 작업
    Account from = accountRepository.findById(fromId).orElseThrow();
    Account to = accountRepository.findById(toId).orElseThrow();
    from.withdraw(amount);
    to.deposit(amount);
}

모든 경로에서 같은 규칙을 강제해야 효과가 있다. 일부 경로만 지키면 나머지 경로와의 교차에서 여전히 데드락이 난다.

9-2) 락 보유 시간을 최소화한다

락 안에서는 DB 작업만 한다. 외부 HTTP 호출, 메일 발송, 파일 I/O는 트랜잭션 밖으로 뺀다. 이벤트 방식으로 처리하고 싶다면 10편 스프링 이벤트의 @TransactionalEventListener(AFTER_COMMIT)가 유용하다 — commit 후에 부수 효과가 따라가도록.

// 피하기: 락 안에서 외부 호출
@Transactional
public void placeOrder(Long orderId) {
    Order order = orderRepository.findByIdForUpdate(orderId).orElseThrow();
    order.confirm();
    paymentClient.charge(order);    // 외부 API — 수 초 걸릴 수 있음
    mailSender.send(order);          // 마찬가지
}

// 선호: 락 안에서는 DB만, 부수 효과는 이벤트로
@Transactional
public void placeOrder(Long orderId) {
    Order order = orderRepository.findByIdForUpdate(orderId).orElseThrow();
    order.confirm();
    events.publishEvent(new OrderConfirmedEvent(orderId));
}
// 리스너에서 @TransactionalEventListener(AFTER_COMMIT)으로 charge/mail 처리

9-3) 대기 자체를 회피: SKIP LOCKED

일부 도메인에서는 대기 자체가 손해다. 대기 큐 소비자는 대기할 시간에 다음 작업을 가져오는 게 낫다. 이럴 때 SKIP LOCKED로 "다른 워커가 쥔 건 건너뛴다"를 구현하면 데드락 가능성 자체가 없어진다. 대신 동일한 작업을 두 워커가 동시에 처리하려는 경합 자체를 락 논리에서 자연스럽게 회피하는 셈이다.

10) 경합 심한 도메인의 락 선택: Stock / Counter

실무에서 락을 제대로 이해하고 있는지 가장 많이 시험받는 자리가 재고(Stock) 차감이다. 초당 수백 건이 같은 row를 건드리기 때문에 선택에 따라 성능이 10배씩 갈라진다.

10-1) 선택지 세 가지

첫째, PESSIMISTIC_WRITE + 비즈니스 로직을 트랜잭션 안에. 가장 이해하기 쉽고 정확하다. 단점은 락 획득 대기가 쌓이면 응답 지연이 급격히 늘어난다는 것. 초당 수백 건을 넘어가면 한계에 부딪힌다.

@Transactional
public void decreaseStock(Long stockId, int qty) {
    Stock stock = stockRepository.findByIdForUpdate(stockId).orElseThrow();
    if (stock.getQuantity() < qty) throw new OutOfStockException();
    stock.setQuantity(stock.getQuantity() - qty);
}

둘째, JPQL 단일 원자 UPDATE. 읽기-감소-쓰기 3단계를 DB 한 번에 밀어 넣는다. 락 경합이 있어도 InnoDB의 row-level 락이 자동으로 잡아주므로 추가 락 힌트가 필요 없다.

@Modifying
@Query("UPDATE Stock s SET s.quantity = s.quantity - :qty, s.version = s.version + 1 " +
       "WHERE s.id = :id AND s.quantity >= :qty")
int decreaseIfEnough(@Param("id") Long id, @Param("qty") int qty);

반환값이 1이면 성공, 0이면 재고 부족이다. 벌크 UPDATE는 version을 자동 증가시키지 않는다. JPQL에 SET s.version = s.version + 1을 직접 넣거나 UPDATE VERSIONED 확장을 써야 한다. 이 한 줄을 누락하면 이후 동일 엔티티를 낙관적 잠금 경로에서 다룰 때 버전이 어긋나 StaleObjectStateException이 터진다. 매우 빠르고 경합 상황에서도 정확하다. 단점은 엔티티 상태와 어긋난다는 점 — 1차 캐시에 있던 Stock 엔티티의 quantity 필드는 UPDATE 이후에도 옛날 값이다. 필요하면 em.clear() 또는 clearAutomatically = true를 @Modifying에 붙여 처리한다.

셋째, Optimistic Locking + 재시도. 경합이 있어도 일단 진행하고 충돌 시 재시도. 경합이 낮을 때는 비관보다 빠르지만, 경합이 높아지면 재시도 횟수가 폭증해서 비관보다 느려진다. 재고 차감 같은 hot-spot에는 잘 맞지 않는다.

전략	경합 낮음	경합 높음	정확성
PESSIMISTIC_WRITE	보통	대기 누적	높음
JPQL 원자 UPDATE	가장 빠름	빠름	높음
Optimistic + 재시도	빠름	재시도 폭증	높음(결국 성공)

10-2) Redis 같은 외부 카운터로 우회하는 경우

글 범위를 벗어나지만 언급은 해둔다. 극도로 높은 TPS가 필요한 재고 / 카운터는 Redis의 DECR 같은 원자 연산으로 offload하는 패턴을 쓴다. RDB는 최종 정합성을 위한 소스 오브 트루스로 남기고, 실시간 차감은 Redis에서 한다. JPA Locking의 범위를 넘어서는 주제라 여기서는 선택지만 언급한다.

11) 함정 종합

지금까지 조각조각 나온 함정을 한자리에 모은다. 디버깅할 때 체크리스트로 쓸 수 있도록.

11-1) detached 엔티티를 merge하면 OptimisticLockException

준영속 상태의 엔티티를 클라이언트에서 받아와 merge하면 전달받은 version도 옛날 값이다. 사용자가 화면에 띄워두고 다른 사람이 수정한 뒤에 저장을 누르면, merge 시 DB의 version이 이미 다음 값이므로 바로 예외가 난다. 이게 의도된 동작이긴 하지만, 클라이언트가 "편집 중"임을 오래 유지하는 UI에서는 자주 발생한다.

해법은 두 가지다. 하나는 편집 진입 시점에 최신 version을 함께 전달하고 저장 시 비교 로직을 명확히 하는 것. 다른 하나는 부분 수정은 merge가 아니라 서비스에서 find + setter로 처리하는 것 — 12편 §8에서 다룬 바와 같다.

11-2) findById에 @Lock 못 붙인다

이미 §5 @Lock 어노테이션과 Repository 메서드에서 다뤘지만 다시 강조할 만큼 자주 틀린다. JpaRepository.findById를 override하면서 @Lock을 얹는 조합은 기술적으로 동작하긴 하지만, 호출부에서 평범한 findById와 구분되지 않아 락이 걸리는 경로인지 코드에 드러나지 않는다. 별도 메서드(findByIdForUpdate 등)를 만든다가 답이다.

11-3) 벌크 UPDATE는 JPQL이든 Native든 version이 자동이 아니다

JPQL 벌크도 version은 자동이 아니다. JPQL이든 Native든 명시해야 하며, Hibernate의 UPDATE VERSIONED 확장이 JPQL 한정으로 있다.

// 위험: JPQL이지만 version이 그대로 남는다
@Modifying
@Query("UPDATE Stock s SET s.quantity = s.quantity - :qty WHERE s.id = :id")
int decreaseJpql(@Param("id") Long id, @Param("qty") int qty);

// 선호 (JPQL + 수동 증가)
@Modifying
@Query("UPDATE Stock s SET s.quantity = s.quantity - :qty, s.version = s.version + 1 " +
       "WHERE s.id = :id AND s.version = :expected")
int decreaseJpqlWithVersion(@Param("id") Long id,
                            @Param("qty") int qty,
                            @Param("expected") Long expected);

// 선호 (Hibernate 확장, JPQL 전용)
@Modifying
@Query("UPDATE VERSIONED Stock s SET s.quantity = s.quantity - :qty WHERE s.id = :id")
int decreaseVersioned(@Param("id") Long id, @Param("qty") int qty);

// 위험: Native — 직접 안 쓰면 version이 안 올라감
@Modifying
@Query(value = "UPDATE stock SET quantity = quantity - :qty, version = version + 1 " +
               "WHERE id = :id AND version = :expected",
       nativeQuery = true)
int decreaseNative(@Param("id") Long id,
                   @Param("qty") int qty,
                   @Param("expected") Long expected);

JPQL이든 Native든, SET ... version = version + 1을 직접 쓰지 않으면 version이 그대로 남는다. 이후 이 엔티티를 낙관적 잠금 경로에서 다루는 흐름에서 DB와 version이 어긋나 StaleObjectStateException이 터진다. JPQL에는 Hibernate 확장으로 UPDATE VERSIONED가 있어 한 줄 생략이 가능하지만, Native에는 그런 단축이 없다. WHERE에 AND version = :expected까지 붙여 두면 반환값 0이 "다른 트랜잭션이 먼저 갱신함"을 뜻하게 되고, 애플리케이션에서 이를 ObjectOptimisticLockingFailureException으로 전환해 재시도 루프에 태우는 흐름이 자연스러워진다.

11-4) readOnly 트랜잭션 안의 PESSIMISTIC_WRITE

§6-1에서 다룬 내용이다. @Transactional(readOnly = true)와 PESSIMISTIC_WRITE를 같이 쓰면 DB에 따라 거부당하거나 의도와 다르게 동작한다. 락이 필요하면 readOnly를 뺀다.

11-5) @Version 필드에 @Convert 금지

커스텀 Converter를 @Version 필드에 붙이면 값 비교 로직이 예기치 않은 방향으로 흘러간다. 특히 LocalDateTime + timezone Converter 조합은 같은 시각을 다르게 비교하는 사고를 쉽게 만든다. version 필드는 Converter 없이 원시 상태로 둔다.

11-6) @Version의 접근 제어자

@Version 필드는 가능하면 외부에서 setter로 변경하지 않도록 캡슐화한다. Hibernate가 관리하는 값이므로 사용자 코드가 건드리면 상태 관리가 깨진다.

// 선호: setter 없음 or private
@Entity
public class Order {
    @Id private Long id;

    @Version
    private Long version;
    // public setVersion() 만들지 말기
}

12) 실무에서 이렇게 읽고 쓴다

기본은 @Version 낙관적 잠금. 대부분의 엔티티에 @Version Long version 한 줄을 박아두면 Lost Update를 가장 가볍게 방어한다. DB 락이 없으므로 확장성에 해가 없고, 충돌이 실제로 나는 곳만 재시도·통지 로직을 더하면 된다.
경합이 확실한 자리에만 PESSIMISTIC_WRITE. 재고 차감·좌석 예약·중복 처리 방지 같은 직렬화가 비즈니스적으로 필수인 자리에만 비관 잠금을 건다. 그 외엔 낙관으로 충분하다.
findById에 @Lock을 붙이는 대신 findByIdForUpdate 별도 메서드를 만든다. 락이 걸리는 경로가 코드에서 한눈에 보이게 한다.
락 안에서는 외부 호출 금지. 결제 API, 이메일, 파일 I/O는 @TransactionalEventListener(AFTER_COMMIT)으로 commit 이후로 미룬다 — 10편 이벤트 참조.
데드락 회피의 첫 줄은 락 획득 순서 고정. 두 개 이상의 row에 락을 걸 때는 id 오름차순처럼 고정 규칙을 강제한다.
락 타임아웃은 DB 세션 변수로 보강. JPA 힌트만으로는 DB별 차이가 있어, PostgreSQL이라면 SET LOCAL lock_timeout을, MySQL이라면 innodb_lock_wait_timeout을 함께 본다.
경합 심한 카운터는 JPQL 원자 UPDATE. UPDATE ... SET qty = qty - :n WHERE ... AND qty >= :n은 락 힌트 없이도 빠르고 정확하다. 반환값으로 성공/실패를 판단한다.
Native Query에 @Version을 쓸 거면 수동 증가 필수. 누락하면 Optimistic 흐름이 망가진다.
saveAndFlush()는 락 테스트용으로만. 프로덕션 경로에 습관적으로 박히면 Write-Behind 이점이 사라진다 — 12편 §8-4.

13) 한 줄 정리

JPA Locking은 Lost Update를 두 방향으로 푼다 — @Version의 낙관은 충돌을 감지해 예외로 알려주고, @Lock의 비관은 DB 락으로 직렬화해 아예 막는다. 대부분의 엔티티에는 @Version을 얹고 충돌 시 재시도 또는 통지를 더하는 가벼운 방어가 기본이며, 경합이 확실한 재고·좌석 같은 자리에서만 PESSIMISTIC_WRITE로 직렬화한다. 락 안에서는 외부 호출을 피하고 락 획득 순서를 고정하는 두 습관이, 잠금 설계가 살아남는 가장 큰 차이를 만든다.

태그: JPA, Hibernate, Locking, @Version, @Lock, Optimistic Locking, Pessimistic Locking, Spring Data JPA, 동시성 제어

Hibernate 2차 캐시 — SessionFactory 스코프의 공유 캐시

dding-shark — Tue, 21 Apr 2026 20:27:07 +0900

Hibernate 2차 캐시 — SessionFactory 스코프의 공유 캐시

들어가며

JPA를 쓰다 보면 "같은 엔티티를 같은 트랜잭션 안에서 두 번 조회하면 SELECT가 한 번만 나간다"는 걸 먼저 배운다. 12편 영속성 컨텍스트와 @Transactional에서 정리한 1차 캐시 이야기다. 그런데 이 캐시는 트랜잭션이 끝나면 통째로 사라진다. 다음 요청이 들어오면 같은 엔티티를 또 SELECT로 읽는다. 이걸 애플리케이션 전체로 살려두려는 시도가 Hibernate 2차 캐시다. 스코프가 EntityManager가 아니라 SessionFactory가 되고, 수명이 트랜잭션이 아니라 애플리케이션 수명 전체가 된다.

이 글은 Spring Boot 3.x / Hibernate 6.x / JSR-107(JCache) 기준으로, 2차 캐시를 왜 쓰고, 어떻게 구성하며, 어디서 터지는지를 정리한다. 설정 한 줄로 쉽게 켜지지만 hit rate가 0%로 나오는 전형적 함정과, 분산 환경에서의 stale, 벌크 쿼리의 캐시 우회처럼 실제로 많이 밟는 지뢰를 중심으로 다룬다.

2차 캐시를 켰는데 hit rate가 0%다 — @Cacheable과 shared-cache-mode 둘 다 맞춰야 비로소 엔트리가 들어간다
분산 환경에서 로컬 Caffeine으로 실험했더니 노드 간 stale이 심각하다 — 로컬 캐시는 단일 인스턴스용이다
벌크 UPDATE JPQL 한 번에 캐시가 조용히 어긋났다 — 2차 캐시 자동 invalidation이 우회된다
Query Cache만 켰는데 효과가 없다 — 쿼리 캐시는 PK 목록만 저장해서 Entity Cache 없이는 빈 상자다

이 글은 스코프 비교 → 세 가지 캐시 → Provider 설정 → 활성화 애너테이션 → 동시성 전략 → shared-cache-mode → 컬렉션 캐시 → Query Cache → 벌크 쿼리 함정 → 통계 → Spring Cache 대안 → 실무 체크리스트 순으로 간다.

1) 1차 캐시 vs 2차 캐시: 스코프와 수명
2) 2차 캐시의 세 얼굴: Entity / Collection / Query
3) JCache + Caffeine / Redisson 설정
4) @Cacheable과 Hibernate @Cache(usage=...)
5) 네 가지 Concurrency Strategy
6) shared-cache-mode: ENABLE_SELECTIVE 권장
7) 컬렉션 캐시와 자식 엔티티 연쇄
8) Query Cache와 UpdateTimestamps
9) 벌크 쿼리의 2차 캐시 우회 함정
10) 통계로 hit rate 측정
11) 대안: Spring Cache + Redis
12) 실무 체크리스트
13) 한 줄 정리

1) 1차 캐시 vs 2차 캐시: 스코프와 수명

JPA의 캐시는 두 층으로 나뉜다. 1차 캐시는 EntityManager 안쪽, 2차 캐시는 SessionFactory 바깥쪽. 이름에 "1·2차"가 붙어 있지만 계층 관계보다 스코프와 수명의 차이로 읽는 쪽이 정확하다. 1차 캐시는 트랜잭션과 함께 사라지고, 2차 캐시는 애플리케이션이 살아 있는 한 계속 살아 있다.

구분	1차 캐시	2차 캐시
스코프	`EntityManager` (=영속성 컨텍스트)	`SessionFactory` (=애플리케이션)
수명	트랜잭션 종료 시 소멸	애플리케이션 수명 전체
공유	한 트랜잭션 내부 한정	여러 트랜잭션 / 여러 EntityManager가 공유
저장 구조	`Map<(타입, @Id), 엔티티>`	region 단위 Map (entity/collection/query region)
켜기	항상 켜짐 (끌 수 없음)	옵션 (`use_second_level_cache=true`)
주 효과	같은 트랜잭션 반복 조회 절약	여러 트랜잭션 반복 조회 절약

1차 캐시의 핵심 효과는 12편에서 본 엔티티 동일성(== 보장)이다. 2차 캐시는 동일성을 보장하지 않는다. 2차 캐시에서 꺼내올 때는 저장된 상태(dehydrated state, 즉 식별자 + 필드 값의 스냅샷)에서 엔티티를 재구성하므로, 서로 다른 트랜잭션에서 같은 ID를 조회해도 다른 인스턴스가 돌아온다. 대신 SELECT를 안 보낸다는 이득이 남는다. 조회 순서는 1차 → 2차 → DB다. 1차 캐시에 있으면 그걸 쓰고, 없으면 2차 캐시를 보고, 2차에도 없으면 그제야 DB로 SELECT가 나간다. 2차에서 hit이 나면 그 결과를 1차 캐시에도 복사해두므로, 같은 트랜잭션에서 두 번째 조회부터는 1차 캐시가 받아준다.

한 가지 오해를 먼저 정리한다. 2차 캐시는 "모든 엔티티에 자동 적용"되지 않는다. 활성화 플래그 하나만 켜놓고 끝이 아니라, @Cacheable 애너테이션으로 엔티티 단위로 opt-in해야 한다. §6 shared-cache-mode에서 다시 보겠지만, 기본 모드가 ENABLE_SELECTIVE여서 붙인 것만 대상이 된다. 이 전제를 놓치면 hit rate가 0%로 찍힌다.

2) 2차 캐시의 세 얼굴: Entity / Collection / Query

"2차 캐시"라는 한 단어로 묶이지만 안에서는 세 개의 서로 다른 region이 돈다. 구조·키·invalidation 규칙이 다 달라서 각각의 이름을 구분해두는 게 나중 디버깅을 훨씬 수월하게 한다.

2-1) Entity Cache

개별 엔티티를 PK 단위로 저장하는 캐시. 키는 (엔티티 타입, @Id), 값은 엔티티 자체가 아니라 dehydrated state(식별자 + 필드 스냅샷, 연관관계는 FK로만)다. 꺼낼 때 이 스냅샷에서 엔티티 인스턴스를 재조립한다. 가장 기본이자 가장 많이 쓰이는 캐시다.

@Entity
@Cacheable
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Product {
    @Id private Long id;
    private String name;
    private int price;
}

2-2) Collection Cache

@OneToMany, @ManyToMany 같은 컬렉션 관계를 캐시한다. 키는 (부모 엔티티 타입, 부모 @Id, 컬렉션 필드명), 값은 자식 PK 목록. 자식 엔티티 실체는 각자 Entity Cache에서 따로 관리된다. 그래서 컬렉션 캐시 단독으로는 효과가 반쪽이다. §7에서 자세히 본다.

2-3) Query Cache

JPQL/Criteria 쿼리 결과를 캐시한다. 키는 (쿼리 문자열 + 파라미터 값 해시), 값은 결과 엔티티의 PK 목록. 이것도 Entity Cache 없이는 빈 상자다. 다음에 같은 쿼리가 들어오면 PK 목록만 꺼내고, 각 엔티티는 Entity Cache를 거쳐 조립한다.

종류	키	값	동반 필요
Entity Cache	`(타입, @Id)`	dehydrated 엔티티	단독 사용 가능
Collection Cache	`(부모타입, 부모@Id, 필드)`	자식 PK 목록	자식의 Entity Cache
Query Cache	`(JPQL + 파라미터)`	결과 PK 목록	대상 엔티티의 Entity Cache

세 region은 역할이 겹치지 않는다. 예를 들어 "특정 카테고리의 상품 목록을 자주 조회한다"면 Query Cache로 목록을 캐시하고, 실제 Product 엔티티는 Entity Cache가 재료를 대준다. Query Cache만 켜놓고 Product에 @Cacheable을 안 붙이면 매번 PK 목록만 캐시 hit에 그치고 엔티티 로딩 SELECT는 그대로 나간다. 여기서 "쿼리 캐시 효과가 없다"는 착각이 자주 나온다.

3) JCache + Caffeine / Redisson 설정

Hibernate 6에서는 JCache (JSR-107) 기반 구성이 표준이다. 과거 EhCacheRegionFactory 같은 직접 바인딩은 deprecated 되고, 이제 region factory 자리에 JCacheRegionFactory를 꽂고, 그 아래 실제 provider(Caffeine, Redisson, Ehcache 3, Infinispan)를 JCache 규약으로 붙인다.

3-1) 공통 의존성 + 활성화

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.hibernate.orm:hibernate-jcache'
    implementation 'javax.cache:cache-api'
    // provider 중 하나
    implementation 'com.github.ben-manes.caffeine:jcache'  // 버전은 Spring Boot BOM에서 관리되지 않는 경우 명시
    // 또는 분산 캐시용
    // implementation 'org.redisson:redisson-hibernate-6'
}

spring:
  jpa:
    properties:
      hibernate:
        cache:
          use_second_level_cache: true
          use_query_cache: true
          region:
            factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
        javax:
          cache:
            provider: com.github.benmanes.caffeine.jcache.spi.CaffeineCachingProvider
        generate_statistics: true

use_second_level_cache가 켜지고, region factory로 JCacheRegionFactory가 지정되며, 그 아래 provider로 Caffeine이 선택된다. generate_statistics는 §10 통계에서 다시 쓴다. 한 가지 주의할 게 있다. artifact는 ben-manes(하이픈)이고 패키지는 benmanes(하이픈 없음)다. 철자 차이 때문에 provider FQCN을 com.github.ben-manes...로 적으면 ClassNotFoundException이 난다.

3-2) Provider 선택 기준

Provider	형태	적합 상황	주의
Caffeine	로컬 인메모리	단일 인스턴스 서비스	멀티 노드에서 stale
Redisson	분산(Redis)	다중 인스턴스	네트워크 왕복 비용
Ehcache 3	로컬 또는 cluster	기존 Ehcache 자산	구버전(2.x)은 deprecated
Infinispan	분산(JGroups)	JBoss/WildFly 계열	단독 서비스에선 과함

단일 인스턴스라면 Caffeine이 제일 가볍고 빠르다. 멀티 인스턴스 서비스에서 Caffeine을 쓰면 노드 A가 상품을 수정해도 노드 B의 로컬 캐시는 모른다. 분산 환경에서는 Redisson 같은 중앙 캐시로 올려야 한다. 이 판단을 안 하고 Caffeine으로 시작하면 실무에서 노드 간 stale이 조용히 쌓인다.

3-3) region 별 세부 설정 (Caffeine 예)

# caffeine-jcache 설정 (application.conf 또는 JCache 프로퍼티)
caffeine:
  jcache:
    caches:
      "com.example.Product":
        policy:
          maximum:
            size: 10000
        expireAfterWrite: 10m

region 단위로 max size, TTL 같은 정책을 분리한다. @Cache(region = "products-hot")으로 별도 region을 지정하면 다른 정책을 적용할 수도 있다. Hibernate 6에서 region prefix 관리가 이전 버전보다 간소해져서 굳이 수동 prefix를 박아 넣을 필요가 없다.

4) @Cacheable과 Hibernate @Cache(usage=...)

엔티티 쪽에서 해야 할 작업은 두 애너테이션을 같이 붙이는 것이다. 이름이 비슷해서 헷갈리지만 역할이 다르다.

import jakarta.persistence.Cacheable;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;

@Entity
@Cacheable                                              // (1) JPA 표준: 캐시 대상 표시
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)     // (2) Hibernate 전용: 동시성 전략
public class Product {
    @Id private Long id;
    private String name;
    private int price;
}

(1) jakarta.persistence.Cacheable은 "이 엔티티는 캐시 대상입니다"라고 선언만 한다. 동시성 정책 같은 건 없다. (2) org.hibernate.annotations.Cache는 Hibernate 확장으로, 실제 어떤 동시성 전략으로 캐시할지를 지정한다. @Cacheable만 붙이면 동시성 전략이 없어 캐시되지 않는다. 전역 기본값이 필요하면 hibernate.cache.default_cache_concurrency_strategy 프로퍼티로 지정할 수 있지만, 엔티티마다 명시하는 쪽이 명확하다.

@Cacheable은 boolean 인자를 받는다. @Cacheable(false)는 "이 엔티티는 캐시에서 제외"라는 의미다. §6 shared-cache-mode에서 DISABLE_SELECTIVE 모드를 쓸 때 의미가 생긴다.

애너테이션	출처	역할	빠지면?
`@Cacheable`	`jakarta.persistence`	캐시 대상 opt-in	2차 캐시에 안 들어감
`@Cache(usage=...)`	`org.hibernate.annotations`	동시성 전략 지정	전략 불명확 → 캐시 안정성 보장 X

둘이 같이 있어야 캐시가 제대로 작동한다. 단축된 표현으로 Hibernate @Cache 하나만 붙여도 Hibernate는 이를 캐시 대상으로 간주하지만, 표준에 맞추고 Spring 에코시스템과의 일관성을 지키려면 둘 다 붙이는 쪽이 권장된다.

5) 네 가지 Concurrency Strategy

@Cache(usage = ...)에 들어갈 전략은 네 가지다. 각각 동시 쓰기를 어떻게 다룰지가 다르다. 이 선택이 정합성과 성능의 트레이드오프를 결정한다.

5-1) READ_ONLY

읽기 전용. 캐시된 엔티티를 수정하려 하면 예외가 난다. 가장 단순하고 stale 위험이 없다 — 코드 테이블, 국가·통화 마스터, 불변 메타데이터처럼 애플리케이션 수명 동안 바뀌지 않는 데이터에 적합하다.

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
public class Country { ... }

5-2) NONSTRICT_READ_WRITE

쓰기 허용하지만 strict isolation을 보장하지 않는다. invalidation은 트랜잭션 완료 후에 일어나므로, 완료 전 찰나에 stale read가 가능하다. 성능이 최고지만 정합성이 느슨하다. "완전히 최신이 아니어도 큰 문제는 없다"는 도메인(조회 통계, 뉴스 피드 같은)에서만 쓸 수 있다.

5-3) READ_WRITE

soft lock 기반으로 동시성을 관리한다. 쓰기 트랜잭션이 들어오면 해당 캐시 엔트리를 lock 상태로 표시하고, 같은 엔트리에 접근하는 다른 트랜잭션은 DB에서 직접 읽게 한다. 커밋 후 unlock과 함께 캐시가 갱신된다. READ_COMMITTED 격리 수준과 유사한 안정성을 제공한다. 대부분의 쓰기 가능 엔티티가 이걸 쓴다.

5-4) TRANSACTIONAL

JTA 기반 분산 트랜잭션에 캐시 자체가 참여한다. 캐시와 DB가 같은 2PC 트랜잭션에 포함된다. Infinispan 같은 트랜잭션 지원 provider에서만 의미 있고, 스프링 기본 JPA/로컬 트랜잭션 환경에서는 거의 안 쓴다.

전략	쓰기 허용	isolation	성능	적합 데이터
READ_ONLY	불가 (예외)	최강	최고	불변 마스터
NONSTRICT_READ_WRITE	가능	약함 (stale 가능)	매우 빠름	통계·비필수 데이터
READ_WRITE	가능	READ_COMMITTED 수준	보통	일반 쓰기 엔티티
TRANSACTIONAL	가능	SERIALIZABLE	느림	JTA 분산 트랜잭션

실무에서 고를 선택지는 사실상 READ_ONLY 또는 READ_WRITE 둘이다. 전자는 확실히 안 바뀌는 것, 후자는 그 외 대부분. NONSTRICT가 매력적으로 보여도 운영 중 stale이 언제 어디서 튀어나올지 예측이 어려워서 지양한다.

6) shared-cache-mode: ENABLE_SELECTIVE 권장

Jakarta Persistence 표준은 캐시 대상 범위를 애플리케이션 단위로 한 번 더 제어하는 설정을 둔다. 이게 shared-cache-mode다.

spring:
  jpa:
    properties:
      jakarta:
        persistence:
          sharedCache:
            mode: ENABLE_SELECTIVE

모드	의미	실무 판단
`ALL`	모든 엔티티를 캐시	권장 안 함 (통제 상실)
`NONE`	2차 캐시 전체 비활성	켜지 않는 것과 같음
`ENABLE_SELECTIVE`	`@Cacheable(true)`만 캐시	Hibernate 권장
`DISABLE_SELECTIVE`	`@Cacheable(false)` 제외 전부 캐시	관리 불편
`UNSPECIFIED`	provider 기본값 사용 (Jakarta 스펙 기본)	애매함, 명시 권장

Jakarta Persistence 스펙 기본값은 UNSPECIFIED이고, 이 경우 provider에 따라 해석이 달라진다. 대부분 ENABLE_SELECTIVE를 명시하고, @Cacheable을 명시적으로 붙인 엔티티만 opt-in 한다. 이 모드가 아니면 엔티티에 @Cacheable을 붙였어도 캐시가 안 될 수 있고, 반대로 아무 것도 안 붙였는데 캐시에 들어갈 수도 있다.

여기서 틀리기 쉽다. "use_second_level_cache=true만 켜면 알아서 되겠지"라고 두면 ENABLE_SELECTIVE를 명시했어도 어느 엔티티에도 @Cacheable이 없으면 2차 캐시는 실제로 아무 것도 담지 않는다. hit rate 0%의 전형적 원인이다. 설정 한 줄만 바꾸면 해결된다는 점에서 허무한 버그다.

7) 컬렉션 캐시와 자식 엔티티 연쇄

컬렉션 캐시는 앞서 봤듯 자식 PK 목록만 저장한다. 부모 엔티티와 연관된 컬렉션 필드에 @Cache를 붙이면 대상이 된다.

@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Order {
    @Id private Long id;

    @OneToMany(mappedBy = "order")
    @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)   // 컬렉션 자체의 캐시
    private List<OrderItem> items;
}

// 자식도 반드시 같이 캐시 대상이어야 한다
@Entity
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class OrderItem {
    @Id private Long id;
    @ManyToOne private Order order;
    private String productName;
    private int quantity;
}

위에서 OrderItem에 @Cacheable을 안 붙이면 어떻게 되는가. order.getItems()를 호출할 때, 컬렉션 캐시는 hit해서 PK 목록 [101, 102, 103]을 돌려준다. 그런데 각 OrderItem이 Entity Cache에 없으니, 각 PK마다 SELECT가 나간다. PK 개수만큼의 N+1 SELECT가 발생한다. 이건 컬렉션 캐시를 안 쓴 것보다 오히려 나쁠 수 있다 — 원래라면 JOIN FETCH로 한 번에 가져왔을 걸 쪼개서 가져오는 셈이 된다.

상황	결과
컬렉션 캐시만, 자식 Entity Cache 없음	컬렉션 hit → 자식마다 SELECT (N+1)
컬렉션 캐시 없음, 자식 Entity Cache만	컬렉션은 매번 SELECT, 자식은 캐시 hit 가능
둘 다 있음	양쪽 hit, SELECT 없음

따라서 컬렉션 캐시를 쓰려면 자식 엔티티도 반드시 @Cacheable + @Cache(usage)가 있어야 한다. 대원칙은 "연관 엔티티도 캐시 대상이어야 컬렉션 캐시가 제값을 한다"로 기억하면 된다.

8) Query Cache와 UpdateTimestamps

Query Cache는 JPQL/Criteria 결과를 캐시한다. 기본으로 꺼져 있고, 쿼리 단위로 hint를 주거나 Spring Data에서 @QueryHints로 켠다.

// Plain JPA
TypedQuery<Product> q = em.createQuery(
    "select p from Product p where p.category = :cat", Product.class);
q.setParameter("cat", "BOOK");
q.setHint("org.hibernate.cacheable", true);
List<Product> list = q.getResultList();

// Spring Data JPA
public interface ProductRepository extends JpaRepository<Product, Long> {
    @QueryHints(@QueryHint(name = "org.hibernate.cacheable", value = "true"))
    List<Product> findByCategory(String category);
}

키는 쿼리 문자열과 파라미터 해시로 만들어진다. 같은 JPQL에 다른 파라미터면 다른 엔트리다. 값은 결과 엔티티의 PK 목록이다. 실제 엔티티 조립은 Entity Cache 또는 DB에서 한다.

8-1) UpdateTimestamps 캐시

Query Cache는 언제 invalid 해야 하는지를 스스로 판단해야 한다. Hibernate는 이를 위해 내부에 UpdateTimestampsCache라는 보조 캐시를 둔다. 테이블별로 마지막 쓰기 타임스탬프를 기록하는 region이다.

쿼리 캐시 hit 판단 흐름은 이렇다:

쿼리 캐시에서 key로 엔트리 조회 → 캐시된 시점 타임스탬프 T_cache 확인
이 쿼리가 건드리는 테이블 목록을 파악
각 테이블의 UpdateTimestampsCache 값 T_table 조회
T_cache >= max(T_table)이면 hit (여전히 유효)
하나라도 T_table > T_cache면 stale로 간주하고 DB 재조회

덕분에 어떤 쓰기가 일어나면 그 테이블과 연관된 모든 쿼리 캐시 엔트리가 자연히 무효화된다. 엔트리를 삭제하는 게 아니라, 타임스탬프 비교에서 탈락시키는 방식이다. 구현이 단순하고, invalidation을 region 단위가 아니라 테이블 단위로 묶어서 관리 부담을 낮춘다.

8-2) Query Cache가 효과를 보려면

Query Cache는 Entity Cache 없이는 거의 무의미하다. PK 목록만 돌려줘도, 각 엔티티 로딩에서 SELECT가 나가면 효과가 절반도 안 나온다. 그래서 Query Cache를 켤 때는 대상 엔티티에 @Cacheable이 걸려 있는지부터 확인한다. 둘이 같이 걸려야 전체 SELECT 0이 된다.

또 하나 실무 팁. 바뀌는 엔티티를 포함한 쿼리는 캐시 효율이 낮다. 쓰기가 잦으면 invalidation이 잦아 hit rate가 바닥이다. Query Cache는 조회 빈도 높고 쓰기 드문 쿼리에만 선택적으로 건다.

9) 벌크 쿼리의 2차 캐시 우회 함정

JPA에서 가장 조용하고 무서운 버그 중 하나가 여기서 나온다. JPQL 벌크 UPDATE/DELETE는 영속성 컨텍스트를 우회하고 DB에 직접 쿼리를 날린다. 같은 이유로 2차 캐시의 자동 invalidation도 일어나지 않는다.

// 피하기: 벌크 쿼리 후 캐시 그대로 두기
@Transactional
public void markAllShipped(Long customerId) {
    em.createQuery(
        "update Order o set o.status = 'SHIPPED' where o.customer.id = :cid")
        .setParameter("cid", customerId)
        .executeUpdate();
    // 이 시점: DB는 SHIPPED, 2차 캐시의 Order 엔트리는 여전히 이전 상태
    // 다음 요청에서 order.getStatus() → 캐시 hit → 잘못된 값
}

해법은 두 가지다. 명시적으로 해당 region을 비우거나, 벌크 쿼리를 피하고 managed 엔티티를 루프로 수정하거나.

// 선호 1: 벌크 후 캐시 수동 evict
@Transactional
public void markAllShipped(Long customerId) {
    em.createQuery("update Order o set o.status = 'SHIPPED' where o.customer.id = :cid")
        .setParameter("cid", customerId)
        .executeUpdate();
    em.getEntityManagerFactory().getCache().evict(Order.class);
    // 또는 특정 ID만: .evict(Order.class, orderId);
    // 또는 전부 날리기(거의 안 씀): .evictAll();
}

// 선호 2: managed 엔티티 루프 (작은 건수에 한해)
@Transactional
public void markAllShipped(Long customerId) {
    List<Order> orders = em.createQuery(
        "select o from Order o where o.customer.id = :cid", Order.class)
        .setParameter("cid", customerId)
        .getResultList();
    for (Order o : orders) o.setStatus("SHIPPED");
    // Dirty Checking → 개별 UPDATE → 2차 캐시 자동 invalidation
}

위 예시처럼 EntityManager에서 getEntityManagerFactory()를 꺼내 쓰는 방식도 동작하지만, 실무에서는 @PersistenceUnit으로 EntityManagerFactory를 직접 주입해 emf.getCache().evict(Order.class, id)를 호출하는 쪽이 더 흔하다.

방식	SQL 수	2차 캐시 동기화	적합 상황
벌크 JPQL + 수동 evict	1	개발자 책임	대량 업데이트
managed 엔티티 루프	N	자동	소량 업데이트
Native SQL	1	자동 안 됨	성능 최우선, 수동 evict 필수

벌크가 필요하지만 양이 크면 evict 경로가 현실적이다. "벌크 쓸 때는 캐시 evict"를 규칙으로 박아두는 게 낫다. 누락되면 stale이 캐시에 살아남아 다음 트랜잭션까지 오염된다.

Native SQL도 같은 문제를 안고 있다. Hibernate는 native query가 건드리는 테이블을 파싱으로 추론하려 시도하지만 한계가 있어, 안전을 원하면 @org.hibernate.annotations.NamedNativeQuery 또는 Query.unwrap(NativeQuery.class).addSynchronizedEntityClass(Order.class)로 명시한다.

10) 통계로 hit rate 측정

2차 캐시가 "돌아간다"와 "효과가 있다"는 다르다. hit rate를 실제로 측정해야 한다. Hibernate는 SessionFactory.getStatistics()로 hit/miss/put 카운트를 노출한다.

spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true

@Component
@RequiredArgsConstructor
public class CacheStatsReporter {
    private final EntityManagerFactory emf;

    public void report() {
        SessionFactory sf = emf.unwrap(SessionFactory.class);
        Statistics stats = sf.getStatistics();

        long hit = stats.getSecondLevelCacheHitCount();
        long miss = stats.getSecondLevelCacheMissCount();
        long put = stats.getSecondLevelCachePutCount();
        double rate = (hit + miss) == 0 ? 0.0 : (double) hit / (hit + miss);

        log.info("L2 cache hit={}, miss={}, put={}, hitRate={}", hit, miss, put, rate);
    }
}

region별 세부 통계도 뽑을 수 있다.

CacheRegionStatistics region = stats.getCacheRegionStatistics("com.example.Product");
log.info("Product region: hit={}, miss={}, elementCount={}",
    region.getHitCount(), region.getMissCount(), region.getElementCountInMemory());

10-1) 해석 가이드

패턴	해석	조치
hit=0, miss>0, put=0	`@Cacheable` 미부착 또는 mode 잘못	§4, §6 재확인
hit=0, miss>0, put>0	캐시에 들어가지만 hit이 안 됨	TTL 너무 짧거나 쓰기 잦아 invalidation
hit>miss	정상 동작	유지
put이 비정상적으로 큼	쓰기 반복으로 재적재	해당 엔티티 2차 캐시 부적합

hit rate가 0%면 설정 문제, hit rate가 낮으면 캐시 부적합. 이 둘을 구분하는 게 첫 번째 디버깅 포인트다.

Actuator를 통한 Micrometer 연동도 가능하지만, Hibernate 6의 micrometer 바인더는 별도 라이브러리(hibernate-micrometer)가 필요하다. 이걸 붙이면 /actuator/metrics에 hibernate.cache.requests, hibernate.cache.puts 등이 노출되어 Grafana에 그대로 연결된다.

11) 대안: Spring Cache + Redis

2차 캐시를 안 쓰고 서비스 계층에서 Spring Cache(@Cacheable on method)로 Redis에 캐싱하는 선택지도 실무에 많다. JPA 레이어 바깥에서 도는 캐시라서 성격이 완전히 다르다.

@Service
@RequiredArgsConstructor
public class ProductService {
    private final ProductRepository repo;

    @Cacheable(value = "products", key = "#id")
    public ProductDto findById(Long id) {
        Product p = repo.findById(id).orElseThrow();
        return ProductDto.from(p);
    }

    @CacheEvict(value = "products", key = "#id")
    @Transactional
    public void updateName(Long id, String newName) {
        Product p = repo.findById(id).orElseThrow();
        p.setName(newName);
    }
}

Hibernate 2차 캐시와 Spring Cache + Redis의 차이를 정리하면 이렇다.

비교	Hibernate 2차 캐시	Spring Cache + Redis
캐시 단위	엔티티 / 컬렉션 / 쿼리	메서드 반환값 (DTO 등)
자동 invalidation	엔티티 수정 시 자동 (벌크 제외)	수동 (`@CacheEvict`)
분산	provider에 따라 (Redisson 등)	Redis로 기본 분산
영속성 컨텍스트 연계	있음 (dehydrated state)	없음
시리얼라이즈 대상	엔티티 스냅샷	보통 DTO
JPA 지식 요구	높음	낮음

Spring Cache 쪽 장점은 명확하다. 비즈니스 단위(조회 메서드)에 직접 캐시를 건다. 반환 DTO를 그대로 캐시하므로 직렬화가 단순하고, Redis 분산 캐시를 표준처럼 붙일 수 있다. 단점은 invalidation이 수동이라는 점. 엔티티를 어디서 바꾸든 관련 @CacheEvict를 빼먹으면 stale이 남는다.

실무에서는 이 두 개를 섞어 쓴다. 마스터성 데이터(국가, 통화, 상품 카테고리 같은)는 Hibernate 2차 캐시로 엔티티 단위 캐싱, 비즈니스 응답 단위(/api/products/hot의 상위 100개 DTO 같은)는 Spring Cache + Redis로 메서드 캐싱. 성격에 맞춰 고르면 된다.

선택 기준을 굳이 한 줄로 요약하면: "엔티티를 그대로 재활용할 거면 2차 캐시, 조합된 응답 DTO를 재활용할 거면 Spring Cache".

12) 실무 체크리스트

"2차 캐시는 내 도메인에 맞나"부터 묻는다. Read-heavy이면서 변경이 드문 데이터(코드 테이블, 마스터)에만 실효성이 분명하다.
활성화 순서는 ① use_second_level_cache=true ② provider ③ @Cacheable + @Cache(usage=...) ④ shared-cache-mode=ENABLE_SELECTIVE. 하나만 빠져도 hit rate가 0%다.
엔티티의 equals/hashCode를 정확히 구현. 2차 캐시 재조립 시 인스턴스가 달라 Set 기반 비교가 깨진다.
분산 환경에서 로컬 Caffeine은 재앙. 노드마다 stale이 다르게 발생한다. 멀티 인스턴스라면 Redisson 같은 분산 캐시 provider로 가야 한다.
벌크 JPQL 뒤에는 수동 evict를 규칙으로. getCache().evict(...)가 빠지면 stale이 조용히 남는다. PR 리뷰의 고정 체크 항목.
Query Cache는 선택적으로. 쓰기 적은 조회 쿼리에만 @QueryHints로 opt-in. 전체 활성화는 invalidation 오버헤드 때문에 지양한다.
generate_statistics로 hit rate를 모니터링. hit rate가 20%를 못 넘는 region은 캐시에서 내리는 편이 낫다.
Hibernate 6부터는 JCache가 표준. 새 프로젝트는 JCacheRegionFactory + Caffeine 또는 Redisson 조합.

13) 한 줄 정리

2차 캐시는 SessionFactory 스코프에서 여러 EntityManager가 공유하는 애플리케이션 레벨 캐시이고, Entity·Collection·Query 세 region이 각자 다른 키로 돌아간다. 활성화 플래그만으로는 부족하고 @Cacheable + @Cache(usage) + shared-cache-mode + provider 조합 네 가지가 다 맞아야 비로소 엔트리가 쌓인다. Read-heavy·변경 드문 도메인에만 켜고, 벌크 쿼리 뒤 수동 evict를 규칙화하고, 분산 환경에선 로컬 캐시를 피한다 — 이 세 조건을 지키지 못하면 2차 캐시는 쉽게 버그로 돌아온다.

태그: Hibernate, JPA, 2차 캐시, JCache, Caffeine, Redisson, CacheConcurrencyStrategy, shared-cache-mode, Query Cache, Spring Cache

JPA 동적 쿼리 네 가지 — JPQL·Criteria·Querydsl·Specification

dding-shark — Tue, 21 Apr 2026 20:25:26 +0900

JPA 동적 쿼리 네 가지 — JPQL·Criteria·Querydsl·Specification

들어가며

검색 화면을 하나 만든다. 조건은 상태, 최소 금액, 기간, 회원 이름, 상품 카테고리 다섯 개. 각 조건은 있으면 where에 추가하고 없으면 뺀다. 처음에는 StringBuilder로 JPQL을 이어붙인다. 두 번째 요구사항이 들어와 조건이 여덟 개가 되는 순간 메서드가 100줄을 넘기고, AND 빼먹은 오타가 런타임에서 터진다. 이게 동적 쿼리 문제다. 조건의 개수가 코드 작성 시점에 확정되지 않는다는 딱 한 가지 특성 때문에, JPA는 JPQL 문자열 빌더, JPA Criteria API, Querydsl, Spring Data Specification 네 가지 도구를 동시에 유지한다.

이 글은 네 도구를 언제 무엇을 쓰는가의 관점에서 정리한다. "Querydsl 쓰면 된다"가 답이긴 한데, 왜 답인지를 설명하려면 나머지 세 가지가 어디서 부러지는지를 봐야 한다. 특히 다음 네 가지는 현장에서 가장 자주 밟는 함정이다.

검색 조건이 5개를 넘어가자 JPQL이 StringBuilder 지옥이 된다 — 파라미터 바인딩도 같이 분기돼 if문 한 덩어리가 두 배로 커진다
Criteria API로 도전했는데 가독성이 JPQL의 10배로 떨어졌다 — 3줄짜리 쿼리가 20줄이 되고, root.get("status")는 문자열이라 타입 안전도 반쪽짜리다
Querydsl을 도입하니 QClass가 생성 안 돼 빌드가 실패한다 — Boot 3 + Hibernate 6는 querydsl-jpa:5.x:jakarta classifier가 필수다
Specification을 여러 개 합성했는데 JOIN이 중복돼 결과가 부풀었다 — query.distinct(true) 누락이 거의 항상 원인이다

이 글은 왜 → 네 도구 각각 → QClass 생성과 호환 → 합성 함정 → 비교와 선택 → Projection/정렬/페이징 → 함정 종합 순으로, Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x / Querydsl 5.x / Spring Data JPA 3.x 기준으로 정리한다.

1) 동적 쿼리가 필요한 순간
2) JPQL 문자열 빌더: 가장 단순하지만 위험
3) JPA Criteria API: 타입 안전의 대가
4) Querydsl: 사실상 표준이 된 이유
5) QClass 생성과 Boot 3 + Hibernate 6 호환
6) Spring Data Specification: Criteria의 Spring 래퍼
7) Null 안전한 Specification 합성
8) Querydsl BooleanExpression 분리 패턴
9) 네 가지 비교와 선택 기준
10) DTO Projection과 동적 정렬/페이징
11) 함정 종합: metamodel / distinct / fetch join
12) 실무에서 이렇게 읽고 쓴다
13) 한 줄 정리

1) 동적 쿼리가 필요한 순간

정적 쿼리는 컴파일 시점에 SQL 형태가 확정된다. findByStatus(Status)는 where status = ? 한 줄로 끝난다. 반면 동적 쿼리는 조건의 유무와 개수가 런타임에 결정된다. 검색 API의 요청 DTO에 필드 다섯 개가 있고, 각 필드가 null일 수도 있고 아닐 수도 있으면 가능한 조합은 2의 5승, 32가지다. 이걸 32개의 정적 쿼리로 만들면 중복이 폭발하고, 하나로 묶으려면 조건을 동적으로 조립해야 한다.

JPA가 제공하는 선택지는 네 가지다. JPQL 문자열 빌더 / JPA Criteria API / Querydsl / Spring Data Specification. 각자 다른 시기에 다른 문제를 풀려고 추가됐고, 서로 완전히 대체하지 않기 때문에 지금도 네 가지가 공존한다. 이 순서를 기억하면 좋다 — JPQL은 원조이자 가장 단순한 방법, Criteria는 JPA 표준의 타입 안전 시도, Querydsl은 Criteria의 가독성 문제에 대한 외부 라이브러리의 답, Specification은 Spring Data가 Criteria를 다시 감싼 얇은 래퍼.

앞의 두 개는 표준에 속하고 뒤의 두 개는 외부/반(半)표준이다. 실무에서 "뭘 쓰지?"의 답이 이 네 개 사이에서 흔들리는 이유는, 표준이라고 해서 실전 가독성이 좋지도 않고 외부 라이브러리라고 해서 피해야 하는 것도 아니기 때문이다. 기준은 하나다 — 조건 조합의 복잡도에 비해 어느 도구가 코드를 얼마나 덜 깨뜨리는가.

2) JPQL 문자열 빌더: 가장 단순하지만 위험

JPQL을 문자열로 직접 만들어 붙이는 방식이다. StringBuilder에 조건마다 AND를 끼워 넣고, 파라미터 바인딩은 setParameter로 따로 건다.

public List<Order> search(OrderStatus status, BigDecimal minAmount, Long memberId) {
    StringBuilder jpql = new StringBuilder("select o from Order o where 1=1");

    if (status != null)    jpql.append(" and o.status = :status");
    if (minAmount != null) jpql.append(" and o.amount >= :min");
    if (memberId != null)  jpql.append(" and o.member.id = :mid");

    TypedQuery<Order> q = em.createQuery(jpql.toString(), Order.class);
    if (status != null)    q.setParameter("status", status);
    if (minAmount != null) q.setParameter("min", minAmount);
    if (memberId != null)  q.setParameter("mid", memberId);

    return q.getResultList();
}

동작은 한다. 단순한 검색 화면에서는 이 정도면 충분하다는 주장도 틀리지 않다. 문제는 조건이 늘 때마다 if가 두 배로 늘어난다는 점이다. 쿼리 조립에서 한 번, 파라미터 바인딩에서 한 번. 빼먹으면 IllegalArgumentException: could not locate named parameter가 런타임에 터진다.

2-1) where 1=1 관용구

where 1=1은 첫 조건 앞에 and를 자연스럽게 놓기 위한 꼼수다. DB 옵티마이저는 대부분 이 상수식을 제거하므로 성능상 의미는 없지만, 리뷰에서 "왜 1=1이냐"는 지적을 받으면 설명하기 귀찮은 코드다. 조건이 세 개 이상이면 이미 StringBuilder 자체가 실수의 근원이 된다. and를 빼먹어도 컴파일 에러는 없다.

2-2) 타입 안전 없음

jpql.append(" and o.stauts = :status") 같은 오타는 런타임에 DB가 보기 전까지 드러나지 않는다. JPQL은 문자열이고 IDE가 검사하지 않는다. JPA 엔티티 이름 변경도 문자열 쿼리에는 반영되지 않는다. 작은 리팩터가 조용히 쿼리를 깨뜨린다.

2-3) 언제 쓸 수 있는가

조건이 2~3개 이하이고 변할 가능성이 낮다면 JPQL 문자열 빌더가 가장 빠르고 읽기 쉽다. 네임드 쿼리나 @Query 애너테이션으로 고정할 수 있는 경우에는 동적 쿼리 도구를 꺼낼 이유가 없다. 이 섹션의 교훈은 "JPQL을 쓰지 말라"가 아니라, "동적이 된 순간 StringBuilder는 부채"라는 것이다.

3) JPA Criteria API: 타입 안전의 대가

Criteria API는 Jakarta Persistence 3.x 표준이다. 쿼리를 문자열이 아니라 객체 그래프로 조립한다. CriteriaBuilder가 Predicate를 만들고, CriteriaQuery가 from/where/select/orderBy를 조합한다. JPQL의 모든 기능을 코드로 표현할 수 있다.

public List<Order> search(OrderStatus status, BigDecimal minAmount, Long memberId) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Order> cq = cb.createQuery(Order.class);
    Root<Order> o = cq.from(Order.class);

    List<Predicate> ps = new ArrayList<>();
    if (status != null)    ps.add(cb.equal(o.get("status"), status));
    if (minAmount != null) ps.add(cb.ge(o.<BigDecimal>get("amount"), minAmount));
    if (memberId != null)  ps.add(cb.equal(o.get("member").get("id"), memberId));

    cq.select(o).where(ps.toArray(new Predicate[0]));
    return em.createQuery(cq).getResultList();
}

JPQL에서는 5줄이던 쿼리가 Criteria API에서는 20줄이 된다. 타입 안전의 대가가 장황함이다. 가독성이 떨어진다는 건 단순한 취향 문제가 아니라, 팀원 리뷰 비용이 올라간다는 뜻이다. 조건이 열 개 넘어가면 메서드 하나가 50줄을 훌쩍 넘긴다.

3-1) metamodel — 진짜 타입 안전의 조건

위 예제의 o.get("status") 는 실제로는 문자열 키다. "status"를 "stauts"로 오타 내면 Criteria도 런타임에서 터진다. Criteria API의 타입 안전성은 metamodel 클래스를 생성해야 비로소 완성된다.

// 빌드 시 APT가 생성: Order_.java
@StaticMetamodel(Order.class)
public abstract class Order_ {
    public static volatile SingularAttribute<Order, OrderStatus> status;
    public static volatile SingularAttribute<Order, BigDecimal> amount;
    public static volatile SingularAttribute<Order, Member> member;
}

// metamodel 기반 Criteria
ps.add(cb.equal(o.get(Order_.status), status));
ps.add(cb.ge(o.get(Order_.amount), minAmount));

Order_.status는 필드 참조이므로 오타면 컴파일이 안 된다. 타입도 OrderStatus로 잡혀 cb.equal이 올바른 타입만 받는다. metamodel은 Hibernate JPA Modelgen 같은 APT 플러그인이 빌드 시 생성한다.

dependencies {
    annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen:6.x"
}

metamodel 없이 Criteria를 쓰는 건 타입 안전성을 반만 챙기는 것이다. 하지만 metamodel을 붙여도 가독성은 여전히 JPQL의 몇 배다. 이게 Criteria API가 실무에서 밀려난 결정적 이유다.

3-2) 언제 Criteria를 쓰나

외부 의존성을 추가할 수 없는 환경(라이브러리 프로젝트, 엔터프라이즈 규정상 Querydsl 금지)이라면 Criteria가 유일한 타입 안전 선택지다. 또는 동적 조건이 드물고 구조 자체가 복잡한 단발성 쿼리(서브쿼리, CASE, 집계가 섞인 리포트 쿼리)에서 Criteria의 표현력이 필요할 때가 있다. 이 두 가지가 아니라면 Querydsl 또는 Specification으로 넘어가는 게 합리적이다.

4) Querydsl: 사실상 표준이 된 이유

Querydsl은 외부 라이브러리지만 JPA 동적 쿼리의 사실상 표준이다. 이유는 하나다 — Criteria의 타입 안전성을 유지하면서 JPQL에 가까운 가독성을 제공한다.

public List<Order> search(OrderStatus status, BigDecimal minAmount, Long memberId) {
    QOrder o = QOrder.order;

    BooleanBuilder where = new BooleanBuilder();
    if (status != null)    where.and(o.status.eq(status));
    if (minAmount != null) where.and(o.amount.goe(minAmount));
    if (memberId != null)  where.and(o.member.id.eq(memberId));

    return queryFactory
        .selectFrom(o)
        .where(where)
        .fetch();
}

JPQL의 구조가 그대로 보인다. selectFrom(o).where(...).fetch()는 select o from Order o where ...의 메서드 체인 번역이다. 컴파일 타임에 QOrder라는 클래스가 생성돼 o.status.eq(status)가 전부 타입 체크된다. 오타는 컴파일 에러, 타입 불일치도 컴파일 에러다.

4-1) QClass와 JPAQueryFactory

Querydsl은 엔티티마다 QClass(QOrder, QMember)를 생성한다. 이건 Annotation Processor가 빌드 시 만들어낸다. 쿼리 시작점은 JPAQueryFactory이고, Spring Bean으로 등록해 주입받아 쓴다.

@Configuration
public class QuerydslConfig {

    @PersistenceContext
    private EntityManager em;

    @Bean
    public JPAQueryFactory queryFactory() {
        return new JPAQueryFactory(em);
    }
}

Querydsl이 아니라 "Querydsl-JPA"라고 부르는 이유가 여기 있다. Querydsl은 SQL, JPA, MongoDB, Lucene 등 여러 저장소를 지원하는 상위 프레임워크이고, JPA용 모듈이 querydsl-jpa다. 우리가 쓰는 건 이 JPA 모듈이다.

4-2) BooleanBuilder vs where varargs

Querydsl에서 조건을 동적으로 조립하는 방법은 두 가지다. BooleanBuilder는 앞 예제에서 본 것처럼 and/or를 누적한다. 다른 방법은 where(...)에 varargs로 BooleanExpression을 나열하고, 각 조건은 조건부로 null을 반환하게 만드는 것이다.

return queryFactory
    .selectFrom(o)
    .where(
        statusEq(status),
        amountGoe(minAmount),
        memberIdEq(memberId)
    )
    .fetch();

private BooleanExpression statusEq(OrderStatus s) {
    return s == null ? null : QOrder.order.status.eq(s);
}

where는 인자 중 null을 자동으로 무시한다. BooleanBuilder를 직접 조립하는 방식보다 더 선언적이고, 각 조건을 메서드로 분리하면 재사용도 쉬워진다. 이 패턴은 §8 BooleanExpression 분리 패턴에서 자세히 다룬다.

5) QClass 생성과 Boot 3 + Hibernate 6 호환

Querydsl의 가장 흔한 도입 실패는 QClass가 생성되지 않는 것이다. 컴파일이 되는데 QOrder를 import할 수 없다, 또는 생성은 됐는데 빌드를 다시 하니 사라진다 같은 문제다. 원인은 대부분 Annotation Processor 설정과 Jakarta classifier 누락 두 가지에 있다.

5-1) Jakarta classifier는 필수

Spring Boot 3.x는 javax.persistence 대신 jakarta.persistence를 쓴다. Hibernate 6도 마찬가지다. Querydsl은 기본 배포가 여전히 javax 기반이므로, Boot 3 + Hibernate 6 환경에서는 반드시 jakarta classifier를 붙여야 한다.

dependencies {
    implementation "com.querydsl:querydsl-jpa:5.1.0:jakarta"
    annotationProcessor "com.querydsl:querydsl-apt:5.1.0:jakarta"
    annotationProcessor "jakarta.annotation:jakarta.annotation-api"
    annotationProcessor "jakarta.persistence:jakarta.persistence-api"
}

classifier 없이 com.querydsl:querydsl-jpa:5.1.0만 쓰면 APT가 javax.persistence 타입을 못 찾아 빌드 시 QClass 생성이 실패하거나, 빌드가 통과되더라도 런타임에 NoClassDefFoundError: javax/persistence/Entity가 터진다. 또는 @Entity가 달린 엔티티를 APT가 인식하지 못해 QClass가 아예 생성되지 않는다. 이 증상이 Querydsl 도입 실패 사례의 8할이다.

5-2) QClass 생성 위치

Gradle 기준 QClass는 build/generated/sources/annotationProcessor/java/main에 생성된다. IDE가 이 경로를 소스 루트로 인식해야 QOrder를 import할 수 있다. IntelliJ는 대부분 자동 인식하지만, 인식 못 하면 Mark Directory as → Generated Sources Root로 수동 설정한다.

clean 빌드를 하면 QClass가 사라지는 경우는 clean 태스크가 해당 디렉터리를 날리고 compileJava가 재생성하지 않는 설정 문제다. 빌드 로그에서 Note: Generating QOrder가 보이는지 확인하고, 안 보이면 APT가 돌지 않은 것이다.

5-3) @Entity 스캔 범위

QClass는 @Entity가 붙은 클래스에 대해서만 생성된다. MappedSuperclass, @Embeddable은 별도 설정이 필요하지 않다(APT가 같이 처리한다). 반면 멀티 모듈 프로젝트에서 엔티티가 다른 모듈에 있으면 해당 모듈에도 annotationProcessor 설정을 넣어줘야 한다. 빌드 모듈마다 독립적이다.

6) Spring Data Specification: Criteria의 Spring 래퍼

Specification은 Spring Data JPA가 제공하는 JpaSpecificationExecutor 인터페이스와 함께 쓰는 도구다. 본질은 Criteria API의 함수형 래퍼다. 조건 하나를 Specification<T>로 만들고, 여러 개를 and/or로 합성한다.

public interface OrderRepository
        extends JpaRepository<Order, Long>, JpaSpecificationExecutor<Order> {}

JpaSpecificationExecutor를 상속하면 findAll(Specification), findOne(Specification), count(Specification), findAll(Specification, Pageable) 같은 메서드가 공짜로 추가된다. 개별 Specification은 함수 인터페이스다.

public class OrderSpecs {

    public static Specification<Order> statusEq(OrderStatus s) {
        return (root, query, cb) ->
            s == null ? null : cb.equal(root.get("status"), s);
    }

    public static Specification<Order> amountGoe(BigDecimal min) {
        return (root, query, cb) ->
            min == null ? null : cb.ge(root.get("amount"), min);
    }
}

조건이 null이면 람다 자체가 null을 반환한다. Spring Data는 합성 과정에서 null Predicate를 자동으로 걸러낸다. 이게 Specification이 동적 쿼리에서 빛나는 이유다 — null 처리가 내장돼 있어 if문 분기가 사라진다.

6-1) 합성

Specification에는 and/or/not/where 정적 메서드가 있다.

Specification<Order> spec = Specification
    .where(OrderSpecs.statusEq(status))
    .and(OrderSpecs.amountGoe(minAmount))
    .and(OrderSpecs.memberIdEq(memberId));

List<Order> result = orderRepository.findAll(spec);

Specification.where(null)도 안전하다. Spring Data가 null을 "조건 없음"으로 처리한다. 결과적으로 JPQL 문자열 빌더의 if 체인이 선언적인 합성 표현으로 바뀐다.

6-2) 그래도 Criteria의 자손이다

편리하지만 Specification의 람다 내부는 여전히 Criteria API다. root.get("status")처럼 문자열 키를 쓰면 §3-1 metamodel에서 본 함정이 그대로 나타난다. metamodel을 같이 쓰면 타입 안전하지만, Specification 람다의 장황함은 Querydsl 대비 여전하다.

// metamodel 적용
public static Specification<Order> statusEq(OrderStatus s) {
    return (root, query, cb) ->
        s == null ? null : cb.equal(root.get(Order_.status), s);
}

Specification은 "Criteria의 가독성을 약간 개선한 합성 도구"다. 타입 안전성과 표현력은 Criteria 그대로고, 이점은 null 조건 자동 무시와 메서드 합성에 집중돼 있다. 조건 수가 그리 많지 않고 Querydsl을 추가하기 부담스러운 프로젝트에서 괜찮은 타협점이다.

7) Null 안전한 Specification 합성

Specification의 "null이면 자동 무시" 동작은 편리하지만 정확히 어디까지 자동인지를 알아야 실수가 없다. 규칙은 간단하다.

Specification 람다가 null Predicate를 반환하면 and/or 합성에서 제외된다
**Specification.where(null)**은 빈 조건으로 시작한다
lambda 안에서 예외를 던지면 그 조건만 무시되는 게 아니라 쿼리 전체가 터진다

실무에서 깔끔한 패턴은 조건마다 null 가드를 람다 첫 줄에 두는 것이다.

public static Specification<Order> createdBetween(LocalDate from, LocalDate to) {
    return (root, query, cb) -> {
        if (from == null && to == null) return null;
        if (from == null) return cb.lessThanOrEqualTo(root.get("createdAt"), to.atTime(LocalTime.MAX));
        if (to == null)   return cb.greaterThanOrEqualTo(root.get("createdAt"), from.atStartOfDay());
        return cb.between(root.get("createdAt"), from.atStartOfDay(), to.atTime(LocalTime.MAX));
    };
}

이런 복잡한 조건도 Specification 하나로 감싸면 호출부는 specs.and(createdBetween(from, to)) 한 줄이다. 조건의 복잡도가 호출부로 새지 않는다.

7-1) 여러 Specification 조합

여러 조건이 있는 검색은 서비스 레이어에서 합성한다.

public Page<Order> search(OrderSearchCondition cond, Pageable pageable) {
    Specification<Order> spec = Specification
        .where(OrderSpecs.statusEq(cond.status()))
        .and(OrderSpecs.amountGoe(cond.minAmount()))
        .and(OrderSpecs.createdBetween(cond.from(), cond.to()))
        .and(OrderSpecs.memberNameLike(cond.memberName()));

    return orderRepository.findAll(spec, pageable);
}

조건 객체(OrderSearchCondition)가 null이어도 각 Specification의 null 가드가 처리한다. 호출부에 if가 한 줄도 없다. 여기서 틀리기 쉬운 건 Specification.where(a).and(b)의 순서다. 합성된 WHERE 조건은 합성 순서대로 AND로 이어진다. 다만 실제 조건 평가 순서는 DB 옵티마이저가 재정렬하므로 쿼리 계획상 특정 순서를 가정하지 말 것.

8) Querydsl BooleanExpression 분리 패턴

Querydsl에서 동적 조건을 가장 깔끔하게 쓰는 관용구가 BooleanExpression 분리다. 각 조건을 private BooleanExpression을 반환하는 메서드로 분리하고, 조건이 null이면 그냥 null을 반환한다.

@Repository
@RequiredArgsConstructor
public class OrderQueryRepository {

    private final JPAQueryFactory queryFactory;

    public List<Order> search(OrderSearchCondition cond) {
        QOrder o = QOrder.order;

        return queryFactory
            .selectFrom(o)
            .where(
                statusEq(cond.status()),
                amountGoe(cond.minAmount()),
                createdBetween(cond.from(), cond.to()),
                memberIdEq(cond.memberId())
            )
            .fetch();
    }

    private BooleanExpression statusEq(OrderStatus s) {
        return s == null ? null : QOrder.order.status.eq(s);
    }

    private BooleanExpression amountGoe(BigDecimal min) {
        return min == null ? null : QOrder.order.amount.goe(min);
    }

    private BooleanExpression memberIdEq(Long id) {
        return id == null ? null : QOrder.order.member.id.eq(id);
    }

    private BooleanExpression createdBetween(LocalDate from, LocalDate to) {
        if (from == null && to == null) return null;
        if (from == null) return QOrder.order.createdAt.loe(to.atTime(LocalTime.MAX));
        if (to == null)   return QOrder.order.createdAt.goe(from.atStartOfDay());
        return QOrder.order.createdAt.between(from.atStartOfDay(), to.atTime(LocalTime.MAX));
    }
}

이 패턴의 장점은 세 가지다.

8-1) null 자동 무시

where(a, b, c)의 varargs에 null이 섞이면 Querydsl은 해당 조건을 조용히 버린다. BooleanBuilder로 if를 쓰는 방식과 결과는 같지만, 코드가 선언적이고 if가 한 줄도 없다.

8-2) 재사용

memberIdEq 같은 작은 조건 메서드는 다른 쿼리에서도 쓸 수 있다. 여러 검색 API에 공통으로 들어가는 조건은 별도 클래스(OrderPredicates)로 빼두면 쿼리 레포가 깔끔해진다.

8-3) 합성도 쉽다

BooleanExpression끼리는 .and(), .or()로 합칠 수 있다. 다만 null 체크를 넣어야 안전하다.

private BooleanExpression statusActiveOrHold(OrderStatus s) {
    return statusEq(OrderStatus.ACTIVE).or(statusEq(s));
    // s가 null이면 statusEq(s)가 null → NullPointerException 위험
}

BooleanExpression.or(null)은 예외로 터진다 (구현 경로에 따라 NullPointerException 또는 IllegalArgumentException). varargs 레벨의 "null 자동 무시"는 Querydsl이 where에서 직접 처리하는 것이지, BooleanExpression의 연산자에는 적용되지 않는다. 메서드 내부에서 합성할 때는 null 체크를 직접 해야 한다.

여기서 틀리기 쉽다. "Querydsl은 null 안전하다"는 말은 where의 varargs 한정이다.

9) 네 가지 비교와 선택 기준

네 도구의 성격을 한 화면에 정리한다.

도구	타입 안전	가독성	코드 생성기	학습 비용	외부 의존성
JPQL 빌더	X	높음 (단순한 경우)	불필요	낮음	없음
Criteria API	O (metamodel 필요)	매우 낮음	Hibernate JPA Modelgen	높음	없음 (표준)
Querydsl	O	높음	querydsl-apt (QClass)	중간	`querydsl-jpa`
Specification	O (metamodel 필요)	중간	선택	낮음	없음 (Spring Data 내장)

"타입 안전"이라고 해서 전부 같은 수준이 아니다. Criteria와 Specification은 metamodel을 붙여야 진짜 타입 안전이고, Querydsl은 기본적으로 타입 안전하다. 가독성 차이는 코드 줄 수로 체감된다 — 같은 쿼리를 Criteria로 쓰면 Querydsl 대비 2~3배 길어진다.

9-1) 의사결정 플로우

이 플로우가 말하는 건 하나다. **"외부 의존성 OK + 조건이 복잡 = Querydsl"**이 현대 JPA의 기본값이다. 그 외의 경우에만 나머지 세 개를 고른다. Criteria API가 표준임에도 불구하고 플로우에서 말단으로 밀리는 이유는 가독성 때문이다.

9-2) 실무에서 가장 흔한 조합

현장에서 가장 많이 보이는 패턴은 "Spring Data JPA 메서드 파생 + Querydsl 커스텀" 조합이다.

// 단순 조회는 메서드 파생
public interface OrderRepository extends JpaRepository<Order, Long>, OrderRepositoryCustom {
    List<Order> findByStatus(OrderStatus status);
}

// 복잡한 동적 쿼리는 Querydsl 커스텀
public interface OrderRepositoryCustom {
    List<Order> searchComplex(OrderSearchCondition cond);
}

@RequiredArgsConstructor
public class OrderRepositoryImpl implements OrderRepositoryCustom {
    private final JPAQueryFactory queryFactory;

    @Override
    public List<Order> searchComplex(OrderSearchCondition cond) {
        // Querydsl 로직
    }
}

Spring Data JPA는 xxxRepository + xxxRepositoryCustom + xxxRepositoryImpl 네이밍 관례를 인식해 두 인터페이스를 하나의 Repository로 합친다. 호출부에서는 orderRepository만 주입받으면 메서드 파생과 커스텀 Querydsl을 다 쓸 수 있다. 이 조합이 사실상 표준이다.

10) DTO Projection과 동적 정렬/페이징

동적 쿼리 도구를 골랐다고 끝이 아니다. 실무에서는 Projection, 정렬, 페이징이 같이 얽힌다.

10-1) DTO Projection

엔티티 그대로가 아니라 응답 DTO로 바로 받고 싶으면 Querydsl에서는 Projections를 쓴다.

public record OrderSummary(Long id, BigDecimal amount, String memberName) {}

List<OrderSummary> result = queryFactory
    .select(Projections.constructor(OrderSummary.class,
        o.id, o.amount, o.member.name))
    .from(o)
    .join(o.member, m)
    .where(...)
    .fetch();

Projections.constructor는 생성자 호출이다. Projections.fields는 리플렉션으로 필드에 직접 주입(세터 불필요), Projections.bean은 자바빈즈 세터(setXxx) 주입. 세 가지 중 constructor를 기본으로 쓴다. record와 조합이 제일 깔끔하고, 필드 순서만 맞으면 컴파일 시점에 검사된다.

JPQL에서도 같은 패턴이 된다 — select new com.x.OrderSummary(o.id, o.amount, o.member.name) from Order o .... Constructor Expression이라고 부른다.

10-2) 동적 정렬

Sort.by("createdAt").descending()을 Querydsl에 전달하는 방법은 두 가지다.

// 1) OrderSpecifier 직접 만들기
OrderSpecifier<?> order = cond.sortByAmountDesc()
    ? o.amount.desc()
    : o.createdAt.desc();

queryFactory.selectFrom(o).orderBy(order).fetch();

// 2) Spring Data Sort → Querydsl OrderSpecifier 변환
// com.querydsl.core.types.Order 기준 (엔티티 Order와 이름 충돌 주의)
Sort sort = Sort.by("createdAt").descending();
JPAQuery<Order> query = queryFactory.selectFrom(o);
for (Sort.Order s : sort) {
    PathBuilder<Order> path = new PathBuilder<>(Order.class, "order");
    query.orderBy(new OrderSpecifier(
        s.isAscending() ? com.querydsl.core.types.Order.ASC : com.querydsl.core.types.Order.DESC,
        path.get(s.getProperty())));
}

첫 번째가 타입 안전하고 깔끔하지만, 정렬 키 목록이 대량이면 두 번째 변환이 필요하다. PathBuilder는 문자열 경로를 Querydsl 표현식으로 바꿔주는 도구다. 컴파일 타임 안전성은 잃는 대신 유연성을 얻는다.

10-3) 페이징

Querydsl + Pageable 조합은 PageableExecutionUtils가 표준 관용구다.

public Page<Order> search(OrderSearchCondition cond, Pageable pageable) {
    List<Order> content = queryFactory
        .selectFrom(o)
        .where(...)
        .offset(pageable.getOffset())
        .limit(pageable.getPageSize())
        .fetch();

    JPAQuery<Long> countQuery = queryFactory
        .select(o.count())
        .from(o)
        .where(...);

    return PageableExecutionUtils.getPage(content, pageable, countQuery::fetchOne);
}

PageableExecutionUtils.getPage는 count 쿼리를 항상 실행하지 않는다. 페이지가 첫 페이지이면서 content 크기가 페이지 크기보다 작으면 count가 불필요하므로 자동으로 생략한다. 이 최적화 덕분에 count 쿼리는 메서드 참조(countQuery::fetchOne)로 넘겨 게으르게 평가한다.

10-4) count 쿼리는 분리가 유리

count 쿼리는 본 쿼리와 구조가 다를 때 성능이 가장 좋다. JOIN이 필요 없고, fetch join도 제거하고, DTO Projection도 없다. content 쿼리와 같은 where만 공유하고 JOIN/Projection은 벗긴 별도 쿼리로 작성하면 대형 테이블에서 체감 차이가 크다.

JPAQuery<Long> countQuery = queryFactory
    .select(o.count())
    .from(o)
    // content 쿼리에 있던 fetch join 제거
    .where(statusEq, amountGoe, ...);   // where만 동일

count와 content가 똑같은 JOIN을 쓰면 DB는 불필요한 조인을 두 번 돌린다. 분리하는 게 규율이다.

11) 함정 종합: metamodel / distinct / fetch join

도구별로 자주 터지는 함정 네 가지를 한 번에 정리한다.

11-1) Criteria/Specification의 문자열 키

root.get("status")는 타입 안전이 아니다. 오타가 런타임에서 터진다. metamodel을 생성해 root.get(Order_.status)로 쓰는 게 Criteria/Specification의 올바른 사용법이다. metamodel 없이 Criteria를 쓰면 "JPQL 문자열 쿼리를 객체 API로 옮겨 장황하게 만든 것" 이상의 이점이 없다.

11-2) Specification + JOIN + distinct

Specification에서 컬렉션 연관을 JOIN하면 결과가 부모 × 자식만큼 늘어난다. distinct를 안 걸면 같은 부모가 여러 번 나와 content.size()와 실제 고유 개수가 다르다.

// 피하기: distinct 누락
public static Specification<Order> hasItemCategory(String category) {
    return (root, query, cb) -> {
        Join<Order, OrderItem> items = root.join("items");
        return cb.equal(items.get("category"), category);
    };
}

// 선호: distinct 명시
public static Specification<Order> hasItemCategory(String category) {
    return (root, query, cb) -> {
        query.distinct(true);   // 중복 제거
        Join<Order, OrderItem> items = root.join("items");
        return cb.equal(items.get("category"), category);
    };
}

query.distinct(true)는 Specification 람다 내부의 CriteriaQuery를 받아 호출한다. 여러 Specification이 JOIN을 걸 수 있는 경우 어느 한 곳에서라도 distinct(true)를 걸어두는 게 안전하다. Querydsl에서는 selectDistinct(o) 또는 .distinct()로 같은 의도를 표현한다.

11-3) Specification + fetch join

Specification 안에서 fetch join을 쓰려면 root.fetch("items")로 명시한다. 단, count 쿼리에서는 fetch가 금지된다. Pageable과 같이 쓰는 경우 Specification이 count 쿼리에서도 fetch를 걸어 에러가 나는 경우가 있다.

public static Specification<Order> fetchItems() {
    return (root, query, cb) -> {
        // count 쿼리에서는 fetch 건너뛰기
        if (Long.class != query.getResultType() && long.class != query.getResultType()) {
            root.fetch("items", JoinType.LEFT);
        }
        return null;   // 조건은 없고 fetch만
    };
}

query.getResultType()이 Long.class이면 count 쿼리라는 뜻이다. Specification이 이 트릭을 쓰지 않으면 org.hibernate.QueryException: query specified join fetching, but the owner of the fetched association was not present in the select list가 터진다.

11-4) Querydsl QClass 미생성

가장 흔한 빌드 실패. 원인은 §5에서 본 Jakarta classifier 누락 또는 annotationProcessor 의존성 미설정. 증상은 "컴파일은 되는데 IDE에서 QOrder를 인식 못 함" 또는 "빌드 시 QClass 자체가 생성 안 됨". 해결은 build 파일의 의존성 재점검 후 clean 빌드.

멀티 모듈에서는 엔티티가 있는 모듈마다 APT 설정이 필요하다. entity 모듈 따로, service 모듈 따로라면 entity 모듈에 annotationProcessor를 넣고, service 모듈은 entity 모듈을 의존하면 생성된 QClass를 쓴다. APT 설정이 service 모듈에 있으면 엔티티가 없어 아무것도 생성되지 않는다.

12) 실무에서 이렇게 읽고 쓴다

동적 조건이 2~3개 이하로 고정이면 @Query에 JPQL로 끝내라. 도구를 꺼낼 이유가 없다. 동적 쿼리 도구는 문자열 빌더의 고통이 실제로 있을 때만 꺼낸다
외부 의존성 추가가 가능하면 Querydsl을 기본으로 간다. Criteria API는 표준이지만 가독성에서 밀리고, Specification은 Criteria의 래퍼라 같은 장황함을 공유한다. Querydsl의 유일한 장벽은 QClass 생성 설정이다
Boot 3 + Hibernate 6면 querydsl-jpa:5.x:jakarta classifier는 반드시 확인. 도입 실패의 8할이 여기다. APT 의존성도 같이 넣어야 QClass가 생성된다
Spring Data만 쓰는 프로젝트에서 외부 라이브러리를 피해야 한다면 Specification + metamodel이 최선. metamodel 없이 쓰는 Specification은 타입 안전을 반만 챙긴 상태다
실무 관용구는 Spring Data 메서드 파생 + Querydsl 커스텀. 단순 조회는 findByStatus로, 복잡한 검색은 OrderRepositoryCustom + Impl로 분리. 한 Repository로 합쳐져 호출부는 깔끔하다
페이징은 PageableExecutionUtils.getPage + count 쿼리 분리 관용구를 기본으로. content와 같은 JOIN을 count가 돌리는 건 낭비다
Specification에서 JOIN이 들어가면 query.distinct(true) 습관적으로 체크. 중복 결과가 부풀어 집계 오류가 나는 사고가 실제로 많다
Criteria/Specification을 쓴다면 metamodel 생성을 빌드 파이프라인에 넣어둔다. 문자열 키로 타협하면 리팩터 한 번에 쿼리가 조용히 깨진다

13) 한 줄 정리

JPA 동적 쿼리의 현실적 기본값은 Querydsl이고, Criteria/Specification은 외부 의존성이 막힌 환경의 차선책이며, JPQL 빌더는 조건이 2~3개 이하일 때만 정당화된다. Boot 3 + Hibernate 6에서 Querydsl을 쓰려면 jakarta classifier와 APT 설정이 필수이고, 이걸 놓치면 QClass 자체가 생성되지 않는다. 도구가 네 개여도 선택 기준은 하나 — 조건의 복잡도에 비해 어느 도구가 코드를 가장 덜 깨뜨리는가.

태그: JPA, Querydsl, Spring Data JPA, Criteria API, Specification, JPQL, 동적 쿼리, Hibernate, Spring Boot 3, metamodel

JPA 상속 매핑 — SINGLE_TABLE·JOINED·TABLE_PER_CLASS와 @MappedSuperclass

dding-shark — Tue, 21 Apr 2026 20:24:54 +0900

JPA 상속 매핑 — SINGLE_TABLE·JOINED·TABLE_PER_CLASS와 @MappedSuperclass

들어가며

객체 지향 코드에서 Payment를 추상 클래스로 두고 CardPayment, BankTransfer가 상속받는 구조는 자연스럽다. 문제는 이걸 관계형 DB로 옮기는 순간부터다. 테이블 하나에 다 욱여넣을지, 부모-자식으로 쪼갤지, 아예 자식마다 독립 테이블을 팔지. 선택마다 트레이드오프가 명확해서, 첫 설계에서 잘못 고르면 쿼리 튜닝이든 스키마 변경이든 몇 달 뒤에 비용이 크게 돌아온다.

JPA는 이 고민을 @Inheritance 전략 셋 — SINGLE_TABLE / JOINED / TABLE_PER_CLASS — 으로 풀고, 여기에 "상속은 아니지만 공통 필드만 공유하고 싶다"는 요구를 위해 @MappedSuperclass를 따로 얹었다. 이름이 비슷한 @Embeddable까지 끼면 세 축의 역할이 한 번에 헷갈린다.

SINGLE_TABLE에서 서브 컬럼을 NOT NULL로 못 건다 — 검증 책임이 애플리케이션으로 넘어온다
JOINED는 정규화지만 쿼리마다 JOIN이 붙어 프로파일링이 필요하다
@MappedSuperclass를 @Inheritance처럼 쓰려다 다형성 쿼리가 안 먹는다
TABLE_PER_CLASS + IDENTITY는 그냥 동작하지 않는다 — 시퀀스 전략 필수

이 글은 상속 → 세 전략 → 선택 기준 → @MappedSuperclass → @Embeddable 구분 → 최적화 → 실전 함정 순으로 Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x 기준으로 정리한다.

1) 상속을 DB로 옮길 때의 고민
2) SINGLE_TABLE: 기본 전략의 장단
3) @DiscriminatorColumn과 타입 판별
4) JOINED: 정규화의 대가
5) TABLE_PER_CLASS: 왜 피하는가
6) 전략 선택 의사결정 표
7) @MappedSuperclass: 엔티티 아닌 공통 필드
8) @MappedSuperclass vs @Inheritance vs @Embeddable
9) Dynamic Insert/Update로 SINGLE_TABLE 최적화
10) 실전 함정 종합
11) 실무에서 이렇게 읽고 쓴다
12) 한 줄 정리

1) 상속을 DB로 옮길 때의 고민

객체 세계에서 상속은 "공통을 묶고, 특수를 확장한다"는 한 마디로 끝난다. 하지만 관계형 DB에는 상속 개념이 없다. 테이블은 평평한 레코드 집합이고, "이 row는 CardPayment이고 저 row는 BankTransfer다"를 표현하려면 어딘가에 타입 정보를 넣든, 테이블을 분리하든, 결국 구조적 선택을 해야 한다.

JPA는 이 선택을 세 가지로 정형화한다. 모두 부모 쪽에 @Inheritance(strategy = ...)를 붙이고, 자식들이 이를 물려받는 형식이다.

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE) // 또는 JOINED, TABLE_PER_CLASS
public abstract class Payment {
    @Id @GeneratedValue
    private Long id;
    private Long amount;
    private LocalDateTime paidAt;
}

@Entity
public class CardPayment extends Payment {
    private String cardNumber;
    private String approvalCode;
}

@Entity
public class BankTransfer extends Payment {
    private String bankCode;
    private String accountNumber;
}

전략	테이블 개수	JOIN	다형성 쿼리
`SINGLE_TABLE`	1개 (공용)	없음	단일 테이블 스캔
`JOINED`	부모 + 자식 N개	필수	LEFT JOIN N회
`TABLE_PER_CLASS`	자식 N개 (부모 없음)	없음	UNION ALL

@Inheritance를 아예 안 붙이면 기본값은 SINGLE_TABLE이다. 부모를 abstract로 둘지 말지는 전략과 무관하지만, 도메인상 부모를 직접 인스턴스화할 일이 없다면 abstract로 두는 편이 안전하다. 구체 클래스로 두면 부모 자체 row가 만들어질 수 있어 타입 판별이 지저분해진다.

세 전략의 차이는 결국 **"다형성 쿼리의 비용을 어디에 몰아넣을 것인가"**로 귀결된다. SINGLE_TABLE은 스키마 유연성(NOT NULL 못 검)을 희생해서 조회 속도를 챙기고, JOINED는 조회 JOIN 비용을 감수하고 정규화를 얻고, TABLE_PER_CLASS는 단일 자식 조회는 빠르지만 다형성 쿼리에서 UNION ALL이라는 큰 비용을 치른다. 실무 선택의 90% 이상이 SINGLE_TABLE 아니면 JOINED 둘 중 하나로 수렴하는 이유다.

2) SINGLE_TABLE: 기본 전략의 장단

SINGLE_TABLE은 모든 서브클래스의 컬럼을 한 테이블에 전부 욱여넣는다. 부모의 공통 컬럼과 모든 자식의 특수 컬럼이 한 row 안에 병렬로 존재하고, 타입 구분자(@DiscriminatorColumn, 기본 DTYPE) 한 컬럼으로 "이 row는 어느 자식이냐"를 표현한다. @Inheritance를 생략하면 이게 기본이다.

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "payment_type", discriminatorType = DiscriminatorType.STRING, length = 20)
public abstract class Payment {
    @Id @GeneratedValue
    private Long id;
    private Long amount;
    private LocalDateTime paidAt;
}

@Entity
@DiscriminatorValue("CARD")
public class CardPayment extends Payment {
    private String cardNumber;
    private String approvalCode;
}

@Entity
@DiscriminatorValue("BANK")
public class BankTransfer extends Payment {
    private String bankCode;
    private String accountNumber;
}

DDL은 이렇게 나온다.

CREATE TABLE payment (
    id BIGINT PRIMARY KEY,
    amount BIGINT,
    paid_at TIMESTAMP,
    payment_type VARCHAR(20) NOT NULL,
    card_number VARCHAR(255),     -- CardPayment 전용, NULL 허용 강제
    approval_code VARCHAR(255),   -- CardPayment 전용, NULL 허용 강제
    bank_code VARCHAR(255),       -- BankTransfer 전용, NULL 허용 강제
    account_number VARCHAR(255)   -- BankTransfer 전용, NULL 허용 강제
);

2-1) 장점: JOIN 제로, 쿼리 단순

장점은 한 줄로 요약된다. JOIN이 없다. SELECT p FROM Payment p WHERE p.amount > 10000은 단일 테이블 인덱스 스캔으로 끝난다. 다형성 쿼리가 많은 읽기 위주 서비스라면 성능상 가장 유리하다. 자식별 조회(SELECT c FROM CardPayment c)도 WHERE payment_type = 'CARD'가 자동으로 붙어 역시 한 테이블 스캔이다.

INSERT도 한 번에 끝난다. JOINED처럼 부모/자식 테이블에 각각 INSERT를 날릴 필요가 없다.

2-2) 단점: NOT NULL 불가와 스키마 팽창

단점도 구조적이다. 서브클래스 전용 컬럼은 NOT NULL을 걸 수 없다. CardPayment가 저장될 때 bank_code 컬럼은 NULL일 수밖에 없고, 반대도 마찬가지다. DDL 레벨에서 NOT NULL을 선언하는 순간 다른 자식 저장이 전부 실패한다.

여기서 틀리기 쉽다. Bean Validation의 @NotNull은 필드 단위로 엔티티별로 걸 수 있다 — 즉 CardPayment.cardNumber에 @NotNull을 붙이는 건 가능하다. 다만 이건 애플리케이션 레벨 검증이지 DB 제약이 아니다. 누군가 SQL로 직접 INSERT하거나 배치가 잘못되면 검증을 우회한다.

또 하나, 서브클래스가 늘어날수록 테이블 스키마가 팽창한다. 자식이 10개고 각각 10개씩 특수 컬럼이 있으면 테이블은 100개 컬럼을 껴안게 되고, 대부분이 NULL인 row가 수두룩 쌓인다. 디스크 효율도 떨어지고, DDL 변경 비용도 커진다.

항목	장점	단점
쿼리 성능	JOIN 없음, 단일 테이블 스캔	서브 컬럼이 많으면 row 넓어짐
다형성 쿼리	가장 간단, `WHERE type IN (...)` 한 번	—
무결성	—	서브 전용 컬럼 NOT NULL 불가
디스크	—	NULL 컬럼 다수, 스키마 팽창
INSERT	1회	—

서브클래스 특화 컬럼이 적거나 자식 개수가 2~3개 수준이면 SINGLE_TABLE이 가장 무난하다. 반대로 자식별로 특수 컬럼이 5개 이상 쌓이면 JOINED를 검토하는 편이 낫다.

3) @DiscriminatorColumn과 타입 판별

SINGLE_TABLE에서 같은 테이블의 각 row가 어느 자식인지 구분하는 장치가 @DiscriminatorColumn이다. 부모 쪽에 컬럼을 선언하고, 자식 쪽에 @DiscriminatorValue로 값을 지정한다. 둘 다 생략하면 기본값은 DTYPE VARCHAR(31)에 자식 클래스의 단순 이름이 값으로 들어간다.

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(
    name = "payment_type",
    discriminatorType = DiscriminatorType.STRING,
    length = 20
)
public abstract class Payment { ... }

@Entity
@DiscriminatorValue("CARD")   // 생략하면 "CardPayment"
public class CardPayment extends Payment { ... }

discriminatorType은 STRING / CHAR / INTEGER 셋 중 하나. 실무에서는 STRING이 가독성·확장성 면에서 제일 무난하다. INTEGER는 디스크를 아낀다는 이유로 제안되기도 하지만, DB를 직접 들여다볼 때 "1이면 카드, 2면 이체"를 매번 기억해야 해서 운영 비용이 더 크다.

3-1) 수동 조작 불가

여기서 한 번 더 짚고 갈 것. @DiscriminatorColumn은 Hibernate가 관리하는 컬럼이라 엔티티 필드로 매핑해 직접 setXxx()로 바꾸는 건 허용되지 않는다. 정 필드로 노출하고 싶으면 다음처럼 읽기 전용으로만 쓴다.

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "payment_type")
public abstract class Payment {
    @Column(name = "payment_type", insertable = false, updatable = false)
    private String paymentType;  // 읽기 전용. 직접 쓰려고 하면 무시됨
}

insertable=false updatable=false로 선언해도 Hibernate가 내부적으로 값을 채운다. 개발자가 setPaymentType(...)를 직접 호출해도 flush 시점에 Hibernate가 자식 타입에 맞게 덮어써서 무의미해진다. 타입 바꾸기는 애초에 DB 레벨에서 지원되지 않는 연산이라고 생각하는 편이 맞다.

3-2) JOINED에서도 쓸 수 있다

@DiscriminatorColumn은 이름과 달리 SINGLE_TABLE 전용이 아니다. JOINED에도 붙일 수 있고, Hibernate 6부터는 JOINED에 디스크리미네이터를 두면 부모 테이블 하나만 조회해도 타입을 즉시 알 수 있다. 없으면 어떤 자식인지 판단하려고 LEFT JOIN으로 자식 테이블들을 다 훑어야 한다. JOINED에서 부모만 조회하는 경우가 잦다면 디스크리미네이터를 같이 얹는 쪽이 성능상 유리하다.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "payment_type")  // JOINED에도 OK
public abstract class Payment { ... }

TABLE_PER_CLASS에는 의미가 없다. 각 자식이 독립 테이블을 쓰므로 "어느 테이블에서 온 row냐"가 곧 타입 정보다. 스펙상 지정해도 무시된다.

4) JOINED: 정규화의 대가

JOINED는 SINGLE_TABLE의 반대편이다. 부모 테이블에는 공통 컬럼만, 자식 테이블에는 자식 특수 컬럼만 두고, 자식 테이블의 PK가 동시에 부모 테이블의 FK 역할을 한다. 전형적인 3정규화 스키마와 모양이 같다.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "payment_type")
public abstract class Payment {
    @Id @GeneratedValue
    private Long id;
    private Long amount;
    private LocalDateTime paidAt;
}

@Entity
@PrimaryKeyJoinColumn(name = "payment_id")  // 자식 PK(=부모 FK) 컬럼 이름 지정
public class CardPayment extends Payment {
    @Column(nullable = false)  // NOT NULL 가능
    private String cardNumber;
    @Column(nullable = false)
    private String approvalCode;
}

DDL은 이렇게 풀린다.

CREATE TABLE payment (
    id BIGINT PRIMARY KEY,
    amount BIGINT,
    paid_at TIMESTAMP,
    payment_type VARCHAR(31) NOT NULL
);

CREATE TABLE card_payment (
    payment_id BIGINT PRIMARY KEY,
    card_number VARCHAR(255) NOT NULL,   -- NOT NULL 가능
    approval_code VARCHAR(255) NOT NULL,
    FOREIGN KEY (payment_id) REFERENCES payment(id)
);

CREATE TABLE bank_transfer (
    payment_id BIGINT PRIMARY KEY,
    bank_code VARCHAR(255) NOT NULL,
    account_number VARCHAR(255) NOT NULL,
    FOREIGN KEY (payment_id) REFERENCES payment(id)
);

4-1) 장점: 정규화와 무결성

JOINED의 이점은 DB 스키마가 객체 모델과 일대일로 대응한다는 점이다. 자식 전용 컬럼에 NOT NULL 걸기, 디스크 공간 효율, 자식별 인덱스 독립 관리 — 전부 자연스럽게 된다. DBA 관점에서 가장 편한 구조다.

4-2) 단점: JOIN 오버헤드

단점은 하나지만 묵직하다. 조회마다 JOIN이 붙는다. 자식 엔티티 한 건을 조회하려면 SELECT ... FROM card_payment c INNER JOIN payment p ON c.payment_id = p.id. 부모 엔티티를 조회해도 타입 판별을 위해 자식 테이블로 LEFT JOIN이 필요할 수 있다.

-- SELECT p FROM Payment p (다형성 쿼리, Hibernate 6 기준)
SELECT p.id, p.amount, p.paid_at, p.payment_type,
       c.card_number, c.approval_code,
       b.bank_code, b.account_number
FROM payment p
LEFT JOIN card_payment c ON p.id = c.payment_id
LEFT JOIN bank_transfer b ON p.id = b.payment_id
WHERE p.payment_type IN ('CARD', 'BANK');

자식 테이블이 늘어날수록 LEFT JOIN 개수가 선형으로 증가하고, 옵티마이저가 넓적한 플랜을 못 짜면 전체 테이블 스캔과 JOIN 조합이 나와 성능이 들쑥날쑥해진다. 이 쿼리가 핫패스라면 프로파일링이 반드시 필요하다.

또 하나, INSERT가 두 번 나간다. 부모 테이블에 먼저 INSERT, 그다음 자식 테이블에 INSERT. 트랜잭션 하나 안에서 자동으로 묶이긴 해도 SQL 왕복이 두 번이다. 배치 INSERT를 써도 테이블별로 따로 묶이므로 SINGLE_TABLE만큼 효율이 안 나온다.

4-3) @PrimaryKeyJoinColumn과 이름 튜닝

자식 테이블의 FK(=PK) 컬럼 이름을 바꾸고 싶으면 @PrimaryKeyJoinColumn을 쓴다. 기본은 부모 PK와 같은 이름(id)이 자식 테이블에도 그대로 들어간다. 관례상 {parent_table}_id 형식이 가독성이 좋다.

@Entity
@PrimaryKeyJoinColumn(name = "payment_id")
public class CardPayment extends Payment { ... }
// → card_payment.payment_id (PK, FK → payment.id)

4-4) 성능 튜닝: @EntityGraph와 디스크리미네이터

JOINED에서 N+1을 줄이려면 @EntityGraph를 쓰는 게 기본이다. 부모만 필요하면 부모만 로딩하고, 특정 자식 경로만 필요하면 그것만 fetch. 디스크리미네이터 컬럼이 부모 테이블에 있으면 자식 테이블 LEFT JOIN을 건너뛸 수 있다 — Hibernate 6이 이 최적화를 많이 개선했다.

반대로 "어떤 자식인지까지 알고 필드도 다 써야 하는" 경우면 결국 JOIN을 피할 수 없다. 이 때문에 JOINED는 쓰기 위주 + 무결성이 중요한 도메인에 맞고, 다형성 읽기가 핫패스인 도메인에는 SINGLE_TABLE이 더 맞는 경향이 있다.

5) TABLE_PER_CLASS: 왜 피하는가

TABLE_PER_CLASS는 각 구체 서브클래스마다 독립 테이블을 파고, 공통 컬럼도 각 테이블에 전부 중복해 넣는 전략이다. 부모가 abstract면 부모 테이블 자체는 생성되지 않는다.

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public abstract class Payment {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)  // IDENTITY 불가
    private Long id;
    private Long amount;
    private LocalDateTime paidAt;
}

@Entity
public class CardPayment extends Payment {
    private String cardNumber;
    private String approvalCode;
}

DDL.

-- payment 테이블 없음 (abstract이므로)

CREATE TABLE card_payment (
    id BIGINT PRIMARY KEY,
    amount BIGINT,                -- 중복
    paid_at TIMESTAMP,            -- 중복
    card_number VARCHAR(255),
    approval_code VARCHAR(255)
);

CREATE TABLE bank_transfer (
    id BIGINT PRIMARY KEY,
    amount BIGINT,                -- 중복
    paid_at TIMESTAMP,            -- 중복
    bank_code VARCHAR(255),
    account_number VARCHAR(255)
);

5-1) 장점: 단일 자식 조회는 빠르다

특정 자식 하나만 조회하면 해당 테이블 스캔으로 끝난다. SELECT c FROM CardPayment c는 card_payment 테이블만 읽는다. JOIN도 없고 디스크리미네이터 필터도 없다.

5-2) 단점: 다형성 쿼리의 UNION ALL

여기서 틀리기 쉽다. SELECT p FROM Payment p를 날리면 Hibernate는 모든 자식 테이블을 UNION ALL로 합친다.

SELECT id, amount, paid_at, card_number, approval_code, NULL AS bank_code, NULL AS account_number, 'CARD' AS clazz_
FROM card_payment
UNION ALL
SELECT id, amount, paid_at, NULL, NULL, bank_code, account_number, 'BANK'
FROM bank_transfer

자식이 3개면 UNION ALL 3번, 10개면 10번. 각 테이블 풀스캔에 결과를 합치는 비용까지 얹힌다. 페이징·정렬이 들어가면 옵티마이저가 짜는 플랜이 더 복잡해진다. 다형성 쿼리를 조금이라도 쓸 거면 이 전략은 거의 못 쓴다.

5-3) PK 전략 제약

공통 PK 시퀀스를 모든 자식 테이블이 공유해야 한다. 그래야 CardPayment의 id=1과 BankTransfer의 id=1이 충돌하지 않는다. 이 때문에 GenerationType.IDENTITY는 쓸 수 없다. IDENTITY는 테이블별 auto-increment라 자식 간 충돌이 불가피하다. SEQUENCE나 TABLE 전략을 강제로 써야 하고, MySQL처럼 시퀀스가 없는 DB에서는 TABLE 전략으로 우회해야 한다.

// 피하기: IDENTITY는 TABLE_PER_CLASS에서 동작하지 않음
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// 선호: SEQUENCE 또는 TABLE
@Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "payment_seq")
@SequenceGenerator(name = "payment_seq", sequenceName = "payment_seq", allocationSize = 50)
private Long id;

실무에서 TABLE_PER_CLASS를 채택하는 사례는 드물다. "상속이긴 한데 자식들을 완전히 별개의 엔티티처럼만 쓰고 다형성 쿼리가 정말 없다"는 조건이 맞으면 고려 대상이지만, 그 정도 분리가 되어 있다면 애초에 상속 구조 자체를 걷어내고 독립 엔티티 N개로 두는 편이 더 깔끔하다.

6) 전략 선택 의사결정 표

세 전략 중 실전에서 고민은 주로 SINGLE_TABLE과 JOINED 사이에서 일어난다. 판단 기준은 크게 네 가지.

조건	SINGLE_TABLE	JOINED	TABLE_PER_CLASS
자식 개수 2~3개, 특화 컬럼 적음	최적	과함	비추천
자식별 특화 컬럼 많음	스키마 팽창	적합	비추천
다형성 쿼리 자주	최적	무난	비추천 (UNION ALL)
다형성 쿼리 거의 없음	무난	JOIN 비용	고려 대상
자식 전용 컬럼 NOT NULL 필요	불가	가능	가능
쓰기 성능 중요	최적 (INSERT 1회)	부담 (INSERT 2회)	무난
DBA 관점 스키마 선호	비표준 스키마	정규화 스키마	중복 컬럼

대부분의 경우 **"SINGLE_TABLE을 기본으로 두고, 자식별 특화 컬럼이 많아지거나 DB 무결성이 특별히 중요하면 JOINED로 이동"**이 합리적인 디폴트다. 성능만 보면 SINGLE_TABLE이 유리하고, 데이터 품질을 DB 레벨에서 보증하려면 JOINED가 유리하다. TABLE_PER_CLASS는 선택지에서 제외하고 고민을 시작하는 편이 시간을 아낀다.

한 가지 더. 중간에 전략을 바꾸는 비용은 생각보다 크다. 운영 중인 테이블을 SINGLE_TABLE에서 JOINED로 옮기려면 데이터 마이그레이션 스크립트를 별도로 짜야 하고, 그 사이 애플리케이션 다운타임이나 듀얼 라이트가 필요하다. 초기 설계에서 충분히 고민하는 편이 장기적으로 싸다.

7) @MappedSuperclass: 엔티티 아닌 공통 필드

지금까지의 @Inheritance는 도메인 상속이었다. 그런데 실무에서 더 자주 마주치는 건 "모든 엔티티에 createdAt·updatedAt·id가 공통으로 들어간다"는 단순한 코드 중복 제거 요구다. 이건 상속이라기보다 공통 필드 재사용이고, 다형성 쿼리도 필요 없다. 여기 맞는 도구가 @MappedSuperclass다.

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {
    @Id @GeneratedValue
    private Long id;

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;
}

@Entity
public class Order extends BaseEntity {
    private Long userId;
    private Long amount;
}

@Entity
public class Product extends BaseEntity {
    private String name;
    private Long price;
}

DDL은 이렇게 나온다. BaseEntity 테이블은 생성되지 않고, Order·Product 각각의 테이블에 id·created_at·updated_at이 복사되어 들어간다.

-- base_entity 테이블 없음

CREATE TABLE orders (
    id BIGINT PRIMARY KEY,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    user_id BIGINT,
    amount BIGINT
);

CREATE TABLE product (
    id BIGINT PRIMARY KEY,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    name VARCHAR(255),
    price BIGINT
);

7-1) 핵심 특징

엔티티가 아니다. @Entity가 없고, 테이블이 생성되지 않는다.
쿼리 대상이 아니다. SELECT b FROM BaseEntity b는 컴파일은 되어도 실행 시 BaseEntity is not mapped로 실패한다.
필드가 자식 테이블에 복사된다. BaseEntity.id는 Order.id, Product.id로 각각 매핑된다.
@Id를 가질 수 있다. 이게 @MappedSuperclass를 쓰는 가장 흔한 패턴이다.

7-2) 전형적 용도: 감사(auditing) 필드

스프링 데이터의 @CreatedDate / @LastModifiedDate / @CreatedBy / @LastModifiedBy를 한 데 묶는 베이스 클래스로 거의 필수적으로 쓴다.

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class AuditableEntity {
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;

    @CreatedBy
    @Column(updatable = false)
    private String createdBy;

    @LastModifiedBy
    private String updatedBy;
}

이 패턴을 @Inheritance(SINGLE_TABLE)로 흉내 내면 오히려 이상해진다. 공통 감사 필드를 위해 모든 엔티티가 auditable_entity라는 한 테이블을 공유하는 꼴이 된다. 엔티티 간 PK가 충돌하고, 엔티티 수가 늘 때마다 테이블이 더 넓어진다. "공통 필드를 공유하고 싶을 뿐"이면 @MappedSuperclass, **"도메인상 자식들이 부모의 일종"이면 @Inheritance**가 맞는 판단 기준이다.

7-3) 연관관계 매핑도 가능

@MappedSuperclass에 @OneToMany·@ManyToOne을 두는 것도 가능하다. 자식 엔티티가 이 연관관계를 물려받는다. 다만 자식별로 FK 컬럼이 다른 테이블에 생기므로, 베이스 클래스 쪽에 하나의 연관 엔티티를 두고 "모든 자식이 같은 컬렉션을 가진다"는 의미는 아니다.

8) @MappedSuperclass vs @Inheritance vs @Embeddable

셋 다 "재사용"이라는 키워드에 걸려 한 번씩 헷갈린다. 차원이 다르다는 걸 표로 정리하면 선명해진다.

구분	@MappedSuperclass	@Inheritance	@Embeddable
엔티티인가?	아님 (abstract 권장)	엔티티 (부모)	아님 (값 타입)
테이블 생성	안 됨	전략에 따라 (SINGLE/JOINED/PER_CLASS)	안 됨
쿼리 대상	아님	다형성 쿼리 가능	아님
`@Id` 소유	가능	부모가 가진다	불가 (식별자 없음)
사용 방식	`extends` (상속)	`extends` (상속)	`@Embedded`로 필드처럼 내장
주 용도	공통 필드 코드 재사용	도메인 상속 (Payment → CardPayment)	값 타입 구조 재사용 (Address, Money)

8-1) @Embeddable: 값 타입 구조 공유

@Embeddable은 여러 엔티티가 같은 구조의 컬럼 뭉치를 가지고 싶을 때 쓴다. 상속이 아니고, @Embedded로 필드처럼 내장한다.

@Embeddable
public class Address {
    private String zipcode;
    private String city;
    private String street;
}

@Entity
public class User {
    @Id @GeneratedValue
    private Long id;
    private String name;

    @Embedded
    private Address address;   // user 테이블에 zipcode, city, street 컬럼이 생김
}

@Entity
public class Company {
    @Id @GeneratedValue
    private Long id;

    @Embedded
    private Address address;   // company 테이블에도 같은 zipcode, city, street 컬럼
}

User도 Company도 Address의 세 컬럼을 각자 자기 테이블에 품는다. 상속 관계는 아니고, "같은 컬럼 구조를 필드처럼 끼워 넣었다"에 가깝다. 값 타입이므로 식별자(@Id)가 없고, equals/hashCode로 동치성을 판단한다.

8-2) 선택 기준

"같은 필드 몇 개를 여러 엔티티에 반복해서 쓰는데, 값 자체로 의미가 있다" → @Embeddable (예: Address, Money, DateRange)
"모든 엔티티가 공통으로 가져야 할 기술적 공통 필드 (id, audit)" → @MappedSuperclass
"자식들이 부모의 일종이며 다형성 쿼리·공유 FK가 필요하다" → @Inheritance

혼동 사례 하나. "Address를 여러 엔티티에서 공유한다"는 요구에 @MappedSuperclass AbstractAddressOwner를 만들고 User·Company가 상속하게 만드는 설계를 가끔 본다. 상속 관계가 전혀 없는 도메인(회사와 사용자는 부모-자식이 아니다)을 기술적 이유로 상속으로 묶는 셈이다. 이런 경우엔 @Embeddable이 맞다. 도메인 모델링이 기술 장치에 끌려가면 안 된다.

9) Dynamic Insert/Update로 SINGLE_TABLE 최적화

SINGLE_TABLE의 단점 중 하나인 "자식별 컬럼이 많아 NULL이 수두룩"을 달래는 도구가 @DynamicInsert·@DynamicUpdate다. 둘 다 Hibernate 고유 어노테이션으로, jakarta.persistence 표준은 아니다.

import org.hibernate.annotations.DynamicInsert;
import org.hibernate.annotations.DynamicUpdate;

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DynamicInsert   // NULL인 컬럼은 INSERT SQL에서 제외
@DynamicUpdate   // 변경되지 않은 컬럼은 UPDATE SQL에서 제외
public abstract class Payment { ... }

9-1) 동작 방식

기본값(정적 SQL)이면 Hibernate는 애플리케이션 시작 시점에 "이 엔티티의 INSERT SQL"을 모든 컬럼을 포함한 형태로 미리 만들어둔다. 한 번 만든 SQL을 모든 row에 재활용한다. 이 방식이 PreparedStatement 캐시 재사용에 유리해서 DB 쪽 파싱 캐시를 잘 쓴다.

@DynamicInsert를 붙이면 매 INSERT마다 실제 NULL이 아닌 컬럼만 포함하는 SQL을 동적으로 조립한다. CardPayment 저장 시에는 bank_code·account_number 컬럼이 SQL에서 아예 빠진다. SQL 전송량이 줄고, DB 쪽에서도 불필요한 NULL 처리가 없어진다.

-- 정적 INSERT (기본)
INSERT INTO payment (id, amount, paid_at, payment_type,
                     card_number, approval_code, bank_code, account_number)
VALUES (?, ?, ?, ?, ?, ?, ?, ?);

-- @DynamicInsert 적용 (CardPayment 저장 시)
INSERT INTO payment (id, amount, paid_at, payment_type,
                     card_number, approval_code)
VALUES (?, ?, ?, ?, ?, ?);

9-2) 트레이드오프

여기서 틀리기 쉽다. 동적 SQL은 매번 SQL 모양이 달라진다는 뜻이고, 그러면 PreparedStatement 캐시 재사용률이 떨어진다. 대량 INSERT에서는 이 손실이 NULL 컬럼 제외의 이득보다 클 수 있다. 반대로 INSERT 빈도가 낮고 컬럼 수가 아주 많은 경우엔 이득이 크다.

@DynamicUpdate도 같은 이야기다. 변경된 필드만 UPDATE에 포함하므로 "많은 컬럼 중 한두 개만 바꾸는" 시나리오에서 유리하고, 모든 컬럼을 일괄 갱신하는 배치라면 정적 UPDATE가 더 효율적이다.

상황	권장
SINGLE_TABLE + 자식별 특화 컬럼 10개 이상	`@DynamicInsert` 검토
대량 배치 INSERT (초당 수천 건)	정적 (기본) — PreparedStatement 캐시 이점
와이드 테이블이고 실제 변경 필드 소수	`@DynamicUpdate`
컬럼 수 적음 (10개 미만)	기본 유지 — 효과 미미

실무에서는 기본값으로 두다가 프로파일링으로 병목이 확인되면 적용하는 순서가 맞다. "혹시 모르니 붙여두자"는 조기 최적화고, 오히려 배치 성능을 깎을 수 있다.

10) 실전 함정 종합

설계 중·운영 중에 반복적으로 마주치는 함정을 모아둔다. 앞 섹션에서 흩어져 언급된 것도 한 번에 본다.

10-1) SINGLE_TABLE에서 자식별 NOT NULL

이미 여러 번 나왔지만 다시. DB 레벨 NOT NULL은 불가, Bean Validation의 @NotNull은 가능(애플리케이션 레벨). 규모가 커지면 Bean Validation만으로는 부족하다 싶을 때 JOINED 전환이 진지한 선택지가 된다. SQL로 직접 INSERT하는 배치 잡이 있다면 Bean Validation이 우회되므로, 이 경로에서 데이터 정합성을 잃을 여지가 있다.

10-2) JOINED에서 부모만 조회할 때 LEFT JOIN 폭증

SELECT p FROM Payment p 같은 부모 다형성 쿼리가 LEFT JOIN card_payment LEFT JOIN bank_transfer LEFT JOIN ...으로 늘어난다. 자식이 많으면 플랜이 복잡해진다. 해결책은 두 가지.

@DiscriminatorColumn을 부모에 둔다 — 타입 판별만 필요하면 자식 JOIN을 건너뛸 수 있다 (Hibernate 6).
@EntityGraph로 필요한 자식만 fetch한다 — 전체 자식을 뒤지지 않는다.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
@DiscriminatorColumn(name = "payment_type")
public abstract class Payment { ... }

// 부모만 필요하면 부모 테이블 스캔으로 끝날 수 있다
List<Payment> all = em.createQuery(
    "select p from Payment p where p.amount > :amt", Payment.class)
    .setParameter("amt", 10000L)
    .getResultList();

10-3) @DiscriminatorColumn을 필드로 수동 조작

insertable=false updatable=false로 읽기 전용 필드를 두는 건 가능하지만, 값을 바꾸려는 시도는 Hibernate가 덮어쓰므로 무의미하다. 타입 변경은 DB 레벨에서 지원되지 않는다. 타입을 바꾸고 싶으면 새 자식 엔티티로 INSERT 후 기존 row 삭제가 유일한 경로다.

10-4) TABLE_PER_CLASS + IDENTITY 조합 불가

// 피하기: 애플리케이션 시작 시 실패하거나 런타임에 충돌
@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public abstract class Payment {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)  // X
    private Long id;
}

// 선호: SEQUENCE
@Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "payment_seq")
@SequenceGenerator(name = "payment_seq", sequenceName = "payment_seq", allocationSize = 50)
private Long id;

TABLE_PER_CLASS는 자식 테이블 간 PK 유일성을 애플리케이션이 보장해야 하는데, IDENTITY는 테이블별로 따로 증가하므로 보장할 방법이 없다. SEQUENCE(또는 TABLE)가 강제된다.

10-5) @MappedSuperclass로 다형성 쿼리 시도

@MappedSuperclass
public abstract class BaseEntity { ... }

// 실패: BaseEntity는 엔티티가 아님
em.createQuery("select b from BaseEntity b", BaseEntity.class);
// → IllegalArgumentException: BaseEntity is not mapped

@MappedSuperclass는 쿼리 대상이 아니다. 다형성 쿼리가 필요하면 @Inheritance로 바꿔야 한다. 거꾸로 다형성 쿼리가 필요 없는데 @Inheritance를 쓰면 불필요한 다형성 오버헤드(DTYPE 컬럼, LEFT JOIN 등)가 붙는다.

10-6) @Embeddable로 식별자 공유 시도

@Embeddable은 값 타입이라 @Id를 가질 수 없다. "ID를 공유하고 싶다"가 목적이라면 @MappedSuperclass의 영역이다. 복합 키는 @EmbeddedId로 별개 패턴이 있지만 이건 상속과는 다른 이야기다.

10-7) 자식 추가 시 SINGLE_TABLE의 마이그레이션

새 자식을 하나 추가하면 해당 자식 특화 컬럼들이 기존 테이블에 ALTER TABLE ADD COLUMN으로 붙는다. 운영 테이블이 크면 이 DDL이 오래 걸리거나 락을 잡는다. 온라인 DDL이 지원되는 DB(MySQL 8 등)라도 주의가 필요하다. 자식이 꾸준히 늘어날 도메인이라면 JOINED가 더 편하다 — 새 자식은 새 테이블로 생기므로 기존 테이블에 영향이 없다.

11) 실무에서 이렇게 읽고 쓴다

기본은 SINGLE_TABLE로 시작하고, 자식별 특화 컬럼이 5개를 넘기거나 DB NOT NULL이 필요해지면 JOINED로 옮기는 지점을 고민하자. 초기 자식 수가 2~3개 정도라면 SINGLE_TABLE이 가장 손이 덜 간다.
TABLE_PER_CLASS는 선택지에서 제외하고 시작하자. 다형성 쿼리가 단 한 줄이라도 섞이면 UNION ALL 비용이 즉시 튀어나온다. 완전히 독립된 엔티티들이라면 상속을 걷어내는 게 맞다.
@DiscriminatorColumn은 JOINED에도 붙이자. Hibernate 6에서 부모만 조회할 때 자식 LEFT JOIN을 건너뛰게 해준다. 운영 쿼리의 상당수가 부모 조회라면 체감 차이가 크다.
@MappedSuperclass는 BaseEntity·AuditableEntity 용도로만 쓰자. 도메인 상속으로 확장하려는 순간 혼선이 시작된다. 도메인 상속은 @Inheritance, 공통 기술 필드는 @MappedSuperclass로 구분선을 명확히.
@DynamicInsert/@DynamicUpdate는 프로파일링 이후에. 조기 최적화는 PreparedStatement 캐시 효율을 떨어뜨려 오히려 배치 성능을 깎는다. 자식별 NULL 컬럼이 10개 이상 쌓이는 SINGLE_TABLE에서나 의미가 있다.
전략 변경은 비싸다. 운영 중 SINGLE_TABLE → JOINED 이동은 데이터 마이그레이션 + 듀얼 라이트 + 다운타임 조합이 필요하다. 첫 설계에서 "앞으로 자식이 몇 개로 늘어날지, 특화 컬럼은 몇 개가 될지"를 한 번 더 추정해두는 편이 싸다.

12) 한 줄 정리

JPA 상속 매핑의 핵심은 "다형성 쿼리의 비용을 테이블 구조·JOIN·UNION ALL 셋 중 어디에 몰아넣을지"의 선택이다. SINGLE_TABLE은 조회 속도를 얻는 대신 NOT NULL을 포기하고, JOINED는 정규화를 얻는 대신 JOIN 비용을 받아들이며, TABLE_PER_CLASS는 다형성 쿼리에서 UNION ALL이 터지므로 실무에서 피하는 편이다. 여기에 @MappedSuperclass는 엔티티가 아닌 공통 필드 재사용 용도, @Embeddable은 값 타입 구조 재사용 용도로 차원이 다른 도구라는 걸 구분해두면 설계가 흔들리지 않는다.

태그: JPA, Hibernate, 상속 매핑, SINGLE_TABLE, JOINED, TABLE_PER_CLASS, @Inheritance, @DiscriminatorColumn, @MappedSuperclass, @Embeddable, DynamicInsert, Spring Boot

JPA ID 생성 전략과 복합 키 — IDENTITY·SEQUENCE·UUID·@EmbeddedId

dding-shark — Tue, 21 Apr 2026 20:24:17 +0900

JPA ID 생성 전략과 복합 키 — IDENTITY·SEQUENCE·UUID·@EmbeddedId

들어가며

새 엔티티 하나 만들 때 @Id @GeneratedValue 한 줄을 별생각 없이 붙여본 경험은 누구나 있다. 그런데 그 한 줄이 무슨 전략인지, 왜 MySQL은 IDENTITY가 기본이고 PostgreSQL은 SEQUENCE가 기본인지, saveAll(10000건)이 왜 batch insert로 안 묶이는지를 묻기 시작하면 답이 막힌다. ID 전략은 "PK 어떻게 만들지"에 그치지 않고 batch insert 가능 여부, 인덱스 페이지 분할, 분산 환경의 충돌, ORM의 영속화 시점까지 한꺼번에 결정한다.

이 글은 JPA의 4가지 기본 전략(IDENTITY, SEQUENCE, TABLE, AUTO)에 더해 Hibernate 6에서 정식화된 UUID 전략, 그리고 복합 키를 다루는 @IdClass와 @EmbeddedId까지 한 화면에 정리한다. 도구 나열이 아니라 언제 무엇을 고르는가가 핵심이다. 특히 다음 네 가지는 실무에서 가장 많이 밟는다.

IDENTITY를 쓰면 JDBC batch insert가 구조적으로 비활성화된다 — saveAll(10000건)이 INSERT를 10000번 찍는 이유
MySQL PK에 UUID.randomUUID()를 그대로 붙이면 인덱스가 망가진다 — v4의 무작위성이 B+Tree와 충돌한다
SEQUENCE allocationSize=50인데 ID가 중간중간 비어 있다 — 이게 정상 동작이고 버그가 아니라는 걸 설명할 수 있어야 한다
@EmbeddedId에 equals / hashCode를 안 만들면 영속성 컨텍스트가 같은 키를 다른 객체로 본다 — 1차 캐시가 깨진 것처럼 보이는 증상이 여기서 나온다

이 글은 왜 ID 전략이 설계 결정인가 → 4전략 개요 → IDENTITY의 batch 제약 → SEQUENCE 튜닝 → TABLE은 왜 피하나 → UUID(v4 vs v7/TSID) → MySQL UUID 저장 → 복합 키(@IdClass vs @EmbeddedId) → @MapsId → 자연 키 vs 대리 키 → 실무 체크리스트 순으로 정리한다. 환경은 Spring Boot 3.x / Hibernate 6.x / Jakarta Persistence 3.x / Java 17+ 기준이다.

1) 왜 ID 전략이 설계 결정인가
2) @GeneratedValue 네 전략 개요
3) IDENTITY의 Batch Insert 불가: 구조적 제약
- 3-3) TABLE_PER_CLASS + IDENTITY는 금지
4) SEQUENCE + allocationSize + pooled optimizer
5) TABLE 전략은 왜 피하나
6) UUID 전략: v4 vs v7/TSID
7) MySQL UUID 저장 전략: VARCHAR(36)이 왜 위험한가
8) @IdClass vs @EmbeddedId: 복합 키 두 방식
9) @MapsId로 파생 식별자 구성
10) 자연 키 vs 대리 키, 그리고 시퀀스 이름 공유
11) 실무에서 이렇게 읽고 쓴다
12) 한 줄 정리

1) 왜 ID 전략이 설계 결정인가

ID 전략은 단순히 "PK 값을 어디서 받아오는가"의 문제가 아니다. 그 결정 하나로 다음 네 가지가 동시에 결정된다.

batch insert 가능 여부 — IDENTITY는 INSERT 실행 후에야 PK를 알 수 있어 batch로 묶을 수 없다
분산 환경에서의 충돌 가능성 — DB 시퀀스는 단일 서버 의존, UUID/TSID는 분산 친화
인덱스 효율 — PK가 단조 증가하면 B+Tree 인덱스의 끝부분에만 삽입돼 페이지 분할이 적다. 무작위면 페이지 전반에 흩어져 분할·재배치가 잦다
JPA 영속화 시점 — persist가 호출되는 순간 PK가 정해지는지, 아니면 flush 시점에 정해지는지가 전략마다 다르다

이 네 축은 서로 얽혀 있다. 예를 들어 "분산이 필요해 UUID를 쓰자"가 그대로 "MySQL InnoDB 인덱스가 망가진다"로 이어지고, 그 해법이 "UUIDv7로 단조 증가성을 회복한다"인 식이다. 그래서 ID 전략은 새 엔티티 만들 때 별생각 없이 IDENTITY 붙이는 게 아니라, 도메인 특성을 보고 골라야 한다. 이 글의 나머지는 그 선택지를 하나씩 푼다.

2) @GeneratedValue 네 전략 개요

JPA가 정의한 GenerationType은 4가지다. Jakarta Persistence 3.1이 GenerationType.UUID를 표준에 추가했고, Hibernate 6.2+가 이를 구현한다. Hibernate 6.0~6.1에서는 @UuidGenerator(Hibernate 고유 어노테이션)만 썼다.

전략	DB 의존	PK 확정 시점	batch insert	대표 DB
`IDENTITY`	AUTO_INCREMENT / SERIAL	INSERT 실행 후	불가	MySQL, MariaDB, SQL Server
`SEQUENCE`	DB 시퀀스 객체	INSERT 전 (`nextval`)	가능	PostgreSQL, Oracle, H2
`TABLE`	별도 PK 카운트 테이블	락 획득 후	가능하나 락 경합	모든 DB
`AUTO` (기본)	벤더에 위임	벤더에 따라	벤더에 따라	모든 DB
`UUID`	없음 (앱에서 생성)	persist 시점	가능	모든 DB

AUTO는 Hibernate 6 기준으로 대부분의 경우 SequenceStyleGenerator로 풀린다. MySQL처럼 시퀀스가 없는 DB에서는 IDENTITY로 떨어진다. 명시적으로 골라 쓰는 편이 안전하다. AUTO에 의존하면 DB를 바꿀 때 예고 없이 동작이 바뀐다.

// 명시적 — 권장
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "member_seq")
@SequenceGenerator(name = "member_seq", sequenceName = "member_seq", allocationSize = 50)
private Long id;

// 묵시적 — 비권장 (DB 따라 동작 달라짐)
@Id
@GeneratedValue
private Long id;

각 전략의 세부는 다음 섹션에서 풀지만, 결론부터 말하면 선택의 축은 두 개다. "batch insert가 중요한가"와 "분산 환경인가". 이 두 질문에 따라 IDENTITY / SEQUENCE / UUID 중 하나로 좁혀진다.

3) IDENTITY의 Batch Insert 불가: 구조적 제약

IDENTITY는 가장 익숙한 전략이다. MySQL을 쓰면 디폴트가 이쪽이고, 별 설정 없이 AUTO_INCREMENT 컬럼이 알아서 PK를 증가시키니 편하다. 단, 대량 insert가 섞이는 도메인에서는 첫 번째로 의심해야 할 선택이다.

// 피하기 (대량 insert가 잦은 도메인에서)
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

문제는 §3-1에서 보듯 batch insert가 구조적으로 안 된다는 점이다. 이 제약은 13편 N+1 글의 §12에서 한 번 다뤘는데, ID 전략 관점에서 다시 한번 정리한다.

3-1) 왜 batch가 안 묶이는가

JPA의 EntityManager.persist()는 호출된 순간 엔티티를 영속 상태로 전이시켜야 한다. 영속 상태가 되려면 1차 캐시(영속성 컨텍스트)에 PK를 키로 등록해야 하는데, IDENTITY는 PK를 알아내려면 INSERT를 실제로 실행해야 한다. 결과적으로 persist 한 번 = INSERT 한 번 = 네트워크 왕복 한 번이 1:1로 묶인다. batch로 묶을 틈이 없다.

// 1만 건 saveAll
memberRepository.saveAll(members);

// 실제 발생하는 SQL (IDENTITY 기준)
// INSERT INTO member (...) VALUES (...);  -- 1번
// INSERT INTO member (...) VALUES (...);  -- 2번
// ...
// INSERT INTO member (...) VALUES (...);  -- 10000번

hibernate.jdbc.batch_size=50을 켜둬도 IDENTITY 전략에서는 로그가 변하지 않는다. 이걸 모르고 batch_size를 100, 200으로 올려보다가 "batch가 안 먹힌다"는 이슈로 넘어오는 경우가 많다. 원인은 batch_size가 아니라 PK 전략이다.

3-2) 해결 방향

IDENTITY를 유지해야 한다면 batch insert는 포기하고 13편의 §13 마지막에서 말한 대로 JdbcTemplate.batchUpdate로 내려가는 편이 빠르다. PK 전략을 바꿀 수 있다면 SEQUENCE로 옮기는 게 정공법이다. PostgreSQL/Oracle은 즉시 가능하고, MySQL 8.0 이후라면 시퀀스 시뮬레이션 테이블을 만들거나 UUIDv7 / TSID를 PK로 쓰는 우회로가 있다.

여기서 틀리기 쉬운 건 "IDENTITY가 항상 나쁘다"는 결론으로 비약하는 것이다. 읽기 위주 + 단건 insert가 대부분인 시스템(관리 페이지, 게시판류)에서는 IDENTITY가 가장 단순하고 충분하다. batch insert가 필요한 경로가 있는가가 판단 기준이다.

3-3) TABLE_PER_CLASS + IDENTITY는 금지

상속 매핑에서 InheritanceType.TABLE_PER_CLASS를 쓰면 자식 테이블마다 PK 컬럼이 별도로 생기지만, PK 공간 자체는 모든 자식 테이블이 공유한다. 이때 IDENTITY를 붙이면 자식 테이블의 AUTO_INCREMENT가 각자 독립적으로 증가하므로 서브클래스 간 PK가 충돌하고, Hibernate는 시작 시점에 런타임 예외로 거부한다. TABLE_PER_CLASS에서는 SEQUENCE 또는 TABLE 전략만 가능하다.

4) SEQUENCE + allocationSize + pooled optimizer

SEQUENCE는 DB의 시퀀스 객체(PostgreSQL/Oracle 등)에서 PK를 미리 받아온다. INSERT 실행 전에 SELECT nextval('member_seq')로 PK를 확보하므로 영속화 시점에 이미 PK를 알고 있고, 따라서 batch insert가 자유롭다.

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "member_seq")
@SequenceGenerator(name = "member_seq", sequenceName = "member_seq", allocationSize = 50)
private Long id;

핵심은 allocationSize다. 이름 그대로 "한 번의 nextval 호출로 미리 예약할 PK 개수"다.

4-1) allocationSize의 동작 원리

allocationSize=50이면 Hibernate는 nextval을 호출해 50개의 ID 범위를 통째로 받아온다. 그 뒤에는 메모리에서 1, 2, 3, ... 50을 차례로 꺼내 쓰고, 51번째 INSERT가 필요할 때 다시 nextval을 호출해 다음 50개를 받는다.

allocationSize=1이면 매 INSERT마다 nextval 이 발생해 네트워크 왕복이 N번 늘어난다. 1만 건 insert면 nextval이 1만 번 나간다. 50으로만 잡아도 200번으로 줄고, 100이면 100번이다. 권장은 50~100이다.

4-2) Hibernate 6의 pooled optimizer

Hibernate는 optimizer 옵션으로 시퀀스 사용 방식을 고른다.

optimizer	동작	DB 시퀀스 INCREMENT
`none`	매 INSERT마다 `nextval` (= allocationSize=1과 동일)	1
`hilo`	hi/lo 알고리즘. 옛 Hibernate 5 호환용	1
`pooled`	`nextval` 결과를 상한(hi)으로 해석, 사용 범위 = `[val-inc+1, val]`	allocationSize
`pooled-lo`	`nextval` 결과를 하한(lo)으로 해석, 사용 범위 = `[val, val+inc-1]`	allocationSize

Hibernate 6은 allocationSize > 1일 때 pooled 계열 optimizer를 자동 선택한다. 어느 쪽이든 DB 시퀀스 자체의 INCREMENT를 allocationSize와 같게 설정해야 한다. PostgreSQL이라면 다음과 같이 시퀀스를 만든다.

CREATE SEQUENCE member_seq START WITH 1 INCREMENT BY 50;

@SequenceGenerator(allocationSize=50)만 쓰고 DB 시퀀스를 INCREMENT 1로 만들어두면 Hibernate가 받아온 값을 잘못 해석해 PK 충돌이 날 수 있다. 앱 설정과 DB 시퀀스 설정이 일치해야 한다는 점은 마이그레이션 스크립트 작성 시 반드시 확인할 항목이다.

4-3) "ID가 비어 있다"는 오해

allocationSize=50을 쓰면 PK가 중간중간 빈다. 이건 정상 동작이다. 이유는 두 가지다.

앱 재시작 — 1번 인스턴스가 [1..50]을 받아 23번까지 쓰고 종료되면, 24~50은 그대로 버려진다. 다음 인스턴스는 nextval로 100을 받아 [51..100]을 쓴다. 24~50이 영원히 빈 ID로 남는다
트랜잭션 롤백 — persist 후 PK가 할당됐어도 트랜잭션이 롤백되면 그 PK는 DB에 INSERT되지 않는다. 메모리에서만 소비된 채 사라진다

이게 감사/운영 담당자에게 "ID가 왜 11, 12, 13 다음에 65로 뛰냐"는 질문으로 돌아온다. 답은 단순하다. PK는 오직 식별자일 뿐, 연속성을 의미하지 않는다. "1번 회원, 2번 회원, ... N번 회원" 같은 비즈니스 의미가 필요하다면 그건 PK가 아니라 별도의 순번 컬럼으로 분리해야 한다. PK에 비즈니스 의미를 얹는 순간 이런 문제가 시작된다.

5) TABLE 전략은 왜 피하나

TABLE 전략은 PK를 받아오기 위한 별도 테이블을 둔다. 이름과 마지막 값만 저장하는 단순한 테이블이고, JPA가 표준으로 정의한 가장 이식성 좋은 방법이다.

@Id
@GeneratedValue(strategy = GenerationType.TABLE, generator = "member_table_gen")
@TableGenerator(
    name = "member_table_gen",
    table = "id_generator",
    pkColumnName = "gen_name",
    valueColumnName = "gen_val",
    pkColumnValue = "member_id",
    allocationSize = 50
)
private Long id;

이 방식은 모든 DB에서 동일하게 작동한다는 장점이 있다. MySQL도, PostgreSQL도, H2도, 시퀀스가 없는 DB도 다 된다. 이식성만 보면 최강이다. 단, 성능은 최악이다.

이유는 단순하다. PK 한 번 받으려면 id_generator 테이블에 SELECT FOR UPDATE → UPDATE를 쳐야 한다. 이게 모든 INSERT의 직렬화 지점이 된다. 한 번에 여러 트랜잭션이 같은 PK를 받으려고 줄 서서 락을 기다린다.

전략	PK 1개 비용	동시성
IDENTITY	INSERT의 일부 (오버헤드 없음)	DB AUTO_INCREMENT가 처리
SEQUENCE	`nextval` 1회 (allocationSize로 분산)	시퀀스 객체가 비차단
TABLE	`SELECT FOR UPDATE` + `UPDATE` (락 획득)	테이블 행 락 직렬화

allocationSize로 어느 정도 완화는 되지만, 그래도 시퀀스보다 무겁다. 실무에서는 거의 쓰지 않는다. 진짜로 모든 DB를 지원하는 라이브러리를 만드는 게 아니라면 후보에서 빼는 게 맞다.

6) UUID 전략: v4 vs v7/TSID

UUID는 DB 의존 없이 앱에서 PK를 생성하는 전략이다. 분산 환경, 멀티 리전, 외부 시스템과의 키 교환 등에서 자연스러운 선택이다. Hibernate 6 (Jakarta Persistence 3.1)부터 @UuidGenerator 어노테이션이 정식화됐다.

// Hibernate 6+
@Id
@UuidGenerator(style = UuidGenerator.Style.RANDOM)   // v4
private UUID id;

// Hibernate 6+
@Id
@UuidGenerator(style = UuidGenerator.Style.TIME)     // 시간 정렬 (Hibernate 고유 포맷)
private UUID id;

Style.TIME은 RFC 표준 v6/v7이 아니라 Hibernate 자체의 시간 정렬 UUID 포맷이다(v1 Gregorian timestamp를 상위 비트로 재배치). IETF 표준 v7이 필요하면 uuid-creator 같은 외부 라이브러리로 생성해 @PrePersist에서 주입한다.

UUID는 분산 친화적이라는 명백한 장점이 있다. 단, 어떤 버전을 쓰느냐로 인덱스 효율이 완전히 달라진다. 이게 UUID 도입의 첫 함정이다.

6-1) UUIDv4의 인덱스 함정

UUIDv4는 완전 무작위다. 버전·variant 고정 비트 6개를 빼면 122비트가 난수다. PK로 쓰면 새 row가 들어올 때마다 B+Tree 인덱스의 임의 위치에 삽입된다. MySQL InnoDB는 클러스터드 인덱스라서 PK 순서로 row를 물리적으로 정렬하는데, 무작위 PK는 다음 두 가지를 동시에 일으킨다.

페이지 분할(page split) — 빈 자리가 부족한 페이지에 끼워 넣으려면 페이지를 둘로 쪼개야 한다. I/O 비용이 직접적으로 든다
버퍼 풀 적중률 저하 — 새 row가 모든 페이지에 흩어져 들어가므로, 자주 쓰는 페이지가 캐시에서 자꾸 밀려난다

PostgreSQL은 클러스터드 인덱스가 아니라 영향이 덜하지만(heap에 append하고 인덱스는 별도), 인덱스 자체의 페이지 분할 비용은 마찬가지로 발생한다.

6-2) UUIDv7 / v6의 시간 정렬

해법은 시간 정렬 UUID다. 상위 비트에 timestamp를 두면 새 PK가 항상 기존 PK보다 크게 생성되고, B+Tree의 끝부분에만 삽입돼 페이지 분할이 거의 없다. IETF가 표준화한 게 UUIDv6, UUIDv7이다. Hibernate의 @UuidGenerator(style = TIME)은 IETF 표준 v6/v7이 아닌 Hibernate 자체의 시간 정렬 포맷을 생성하므로, 표준 v7이 필요하면 외부 라이브러리(uuid-creator 등)를 쓴다.

버전	생성 방식	정렬 가능?	MySQL InnoDB 적합도
v1	timestamp + MAC	부분적 (timestamp 비트 위치 때문)	낮음
v4	완전 무작위	아니오	매우 낮음
v6	v1 비트 재배치 (timestamp 상위)	예	높음
v7	Unix timestamp ms + 난수	예	높음

새 시스템에서 UUID를 PK로 쓴다면 v7이 사실상의 권장이다. v6는 v1 호환을 위한 과도기 표준이고, v7이 가장 단순하면서 정렬 가능성을 보장한다.

6-3) TSID — UUID의 가벼운 대안

TSID(Time-Sorted ID)는 64비트 long 한 개로 시간 정렬 ID를 만든다. UUID(128비트)의 절반 크기로 같은 효과를 낸다.

크기: 64비트 = MySQL BIGINT 한 컬럼
정렬: timestamp 상위 → 자연 정렬
분산: node ID + sequence 비트로 충돌 회피
가독성: Crockford Base32로 13자 문자열 변환 가능

라이브러리는 com.github.f4b6a3:tsid-creator가 표준이다. Hibernate 표준 @UuidGenerator로는 TSID를 만들 수 없으므로, 앱 레벨에서 직접 생성해 persist 전에 set한다.

@Id
private Long id;

@PrePersist
public void assignId() {
    if (this.id == null) {
        this.id = TsidCreator.getTsid().toLong();
    }
}

@GeneratedValue 없이 앱에서 직접 PK를 박는 패턴이다. JPA 입장에서는 "이미 PK가 있는 엔티티"로 보이므로 batch insert도 자유롭다. 분산 + batch + 인덱스 효율을 동시에 만족하는 가장 가벼운 조합이 TSID다.

여기서 틀리기 쉬운 건 "UUID와 TSID 둘 중 무조건 하나가 좋다"는 단순화다. 외부 시스템과의 키 교환이 잦거나 표준 호환이 중요하면 UUIDv7이 낫다. PK 크기를 줄이고 BIGINT 그대로 다루고 싶으면 TSID가 낫다. 요구사항이 가른다.

7) MySQL UUID 저장 전략: VARCHAR(36)이 왜 위험한가

UUID를 PK로 골랐다면 다음 결정은 DB에 어떻게 저장할 것인가다. PostgreSQL은 네이티브 uuid 타입이 있어 16바이트 그대로 저장된다. MySQL은 네이티브 타입이 없어서 보통 두 가지 중 하나를 고른다.

저장 방식	컬럼 타입	크기	인덱스 페이지당 행 수
`VARCHAR(36)`	문자열 (`'550e8400-e29b-...'`)	36바이트 + 길이 prefix	적음
`BINARY(16)`	16바이트 raw	16바이트	대략 2배 수준

VARCHAR(36)로 저장하면 인덱스 한 노드에 들어갈 수 있는 PK 개수가 대략 절반 수준으로 줄어든다. 인덱스 깊이가 깊어지고, 같은 메모리에 캐시할 수 있는 인덱스 페이지도 줄어든다. BINARY(16)이 항상 우선이다.

7-1) Hibernate 6의 매핑 제어

Hibernate 6은 @JdbcTypeCode로 UUID의 JDBC 타입을 명시할 수 있다.

import org.hibernate.annotations.JdbcTypeCode;
import org.hibernate.type.SqlTypes;

@Id
@UuidGenerator(style = UuidGenerator.Style.TIME)
@JdbcTypeCode(SqlTypes.BINARY)   // BINARY(16)으로 저장
@Column(length = 16)
private UUID id;

SqlTypes.CHAR로 두면 문자열 매핑이 되고, SqlTypes.BINARY로 두면 바이너리 매핑이 된다. MySQL이라면 BINARY가 기본값이어야 한다. PostgreSQL은 별도 지정 없이 네이티브 uuid로 매핑되므로 신경 쓸 일이 없다.

7-2) 가독성 문제

BINARY(16)은 인덱스에 좋지만 콘솔에서 바로 읽기 어렵다. mysql> 프롬프트에서 SELECT하면 16바이트 raw가 깨진 문자로 나온다. 운영 편의를 위해서는 view나 generated column으로 문자열 변환을 노출해두는 편이 좋다.

ALTER TABLE member ADD COLUMN id_str VARCHAR(36) AS (
    LOWER(CONCAT_WS('-',
        HEX(SUBSTRING(id, 1, 4)),
        HEX(SUBSTRING(id, 5, 2)),
        HEX(SUBSTRING(id, 7, 2)),
        HEX(SUBSTRING(id, 9, 2)),
        HEX(SUBSTRING(id, 11, 6))
    ))
) VIRTUAL;

이렇게 하면 SELECT * FROM member WHERE id_str = '550e8400-...'로 가독성을 챙기면서 실제 PK는 BINARY(16)을 유지할 수 있다. 인덱스 효율과 사람의 눈을 둘 다 챙기는 절충안이다.

8) @IdClass vs @EmbeddedId: 복합 키 두 방식

여기까지가 단일 PK 이야기였다면, 이제 여러 컬럼이 모여 PK를 이루는 복합 키로 넘어간다. JPA가 정의한 표준은 두 가지다.

8-1) @IdClass — 엔티티에 @Id 여러 개

엔티티 안에 @Id를 여러 번 붙이고, 그 조합을 표현하는 별도 클래스를 @IdClass로 지정한다.

@Entity
@IdClass(OrderItemId.class)
public class OrderItem {
    @Id
    private Long orderId;

    @Id
    private Long productId;

    private int quantity;

    // getter·setter 생략
}

public class OrderItemId implements Serializable {
    private Long orderId;
    private Long productId;

    public OrderItemId() {}

    public OrderItemId(Long orderId, Long productId) {
        this.orderId = orderId;
        this.productId = productId;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderItemId that)) return false;
        return Objects.equals(orderId, that.orderId)
            && Objects.equals(productId, that.productId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderId, productId);
    }
}

@IdClass는 엔티티의 필드 구조를 그대로 펼쳐 PK로 쓴다. 엔티티 입장에서는 orderId와 productId가 평범한 필드로 보이고, 별도의 PK 클래스는 키 값 비교 용도로만 쓰인다.

8-2) @EmbeddedId — 별도 PK 클래스 통째로

PK를 하나의 @Embeddable 클래스로 묶어 엔티티에 박는다.

@Entity
public class OrderItem {
    @EmbeddedId
    private OrderItemId id;

    private int quantity;

    public OrderItem() {}

    public OrderItem(Long orderId, Long productId, int quantity) {
        this.id = new OrderItemId(orderId, productId);
        this.quantity = quantity;
    }
}

@Embeddable
public class OrderItemId implements Serializable {
    private Long orderId;
    private Long productId;

    public OrderItemId() {}

    public OrderItemId(Long orderId, Long productId) {
        this.orderId = orderId;
        this.productId = productId;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderItemId that)) return false;
        return Objects.equals(orderId, that.orderId)
            && Objects.equals(productId, that.productId);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderId, productId);
    }
}

엔티티의 PK는 id 한 필드이고, 그 안에 orderId와 productId가 들어 있다. 객체지향적으로 더 자연스럽고, PK 클래스를 다른 곳에서도 재사용하기 쉽다.

8-3) 비교

항목	@IdClass	@EmbeddedId
PK 위치	엔티티 필드에 분산	`@Embeddable` 한 객체에 캡슐화
JPQL 접근	`select o.orderId from OrderItem o` (직관적)	`select o.id.orderId from OrderItem o` (중첩)
객체지향성	낮음 (필드 평탄화)	높음
재사용	PK 클래스가 엔티티와 분리된 별개의 표현	`@Embeddable` 자체를 다른 엔티티에서도 사용 가능
표준 권장	JPA 1.0 호환용	현대 JPA의 권장 방식
`equals`/`hashCode`	필수	필수
`Serializable`	필수	필수

새 코드는 @EmbeddedId로 가는 게 맞다. @IdClass는 레거시 DB 매핑이나 JPA 1.0 호환이 필요한 경우만이다.

8-4) equals / hashCode가 필수인 이유

복합 키 클래스에서 equals와 hashCode를 안 만들면 영속성 컨텍스트가 깨진 것처럼 보인다. 1차 캐시는 (엔티티 클래스 + PK) 조합을 key로 HashMap에 저장한다. 같은 PK인데 equals가 default(Object의 reference equality)면 두 번째 조회에서 null이 나오고, JPA는 DB로 다시 쿼리를 날린다. 또는 같은 식별자인 두 인스턴스가 영속성 컨텍스트에 동시에 존재하는 모순이 생긴다.

// 같은 PK이지만 equals/hashCode가 없으면 false
OrderItemId k1 = new OrderItemId(1L, 100L);
OrderItemId k2 = new OrderItemId(1L, 100L);

System.out.println(k1.equals(k2));        // false (Object.equals)
System.out.println(k1.hashCode() == k2.hashCode());  // false

// 결과: em.find(OrderItem.class, k1)와 em.find(OrderItem.class, k2)가
//       1차 캐시에서 다른 객체로 인식되거나, 캐시 미스로 DB 쿼리가 추가 발생

해결은 단순하다. PK 클래스에는 무조건 equals / hashCode / Serializable을 박는다. 자동 생성에 의존해도 되고, Java 17+의 record로 만들어도 된다(record는 자동으로 갖춰진다). 다만 @EmbeddedId에 record를 쓰려면 Hibernate가 정확히 해석할 수 있는지 버전을 확인해야 한다 — Hibernate 6.x는 record @Embeddable을 공식 지원한다.

9) @MapsId로 파생 식별자 구성

복합 키의 일부가 다른 엔티티의 PK를 그대로 가져오는 경우가 흔하다. 예를 들어 OrderItem의 PK가 (orderId, productId)인데, orderId는 Order 엔티티의 PK다. 이 관계를 표현하는 게 @MapsId다.

@Entity
public class OrderItem {

    @EmbeddedId
    private OrderItemId id;

    @MapsId("orderId")            // id.orderId 필드를 이 연관에서 파생
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id")
    private Order order;

    @MapsId("productId")
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "product_id")
    private Product product;

    private int quantity;
}

@MapsId("orderId")는 "이 @ManyToOne 연관의 PK를 id.orderId로 매핑하라"는 의미다. 결과적으로 OrderItem의 PK인 (orderId, productId)는 두 연관 엔티티의 PK에서 자동으로 파생된다. 별도로 id.setOrderId(...)를 호출할 필요가 없다.

// @MapsId 사용 (선호)
Order order = orderRepository.findById(orderId).orElseThrow();
Product product = productRepository.findById(productId).orElseThrow();

OrderItem item = new OrderItem();
item.setId(new OrderItemId());   // 빈 PK
item.setOrder(order);            // @MapsId가 id.orderId = order.id 자동 채움
item.setProduct(product);        // @MapsId가 id.productId = product.id 자동 채움
item.setQuantity(3);

em.persist(item);

9-1) @MapsId 없이 처리하면

@MapsId 없이 같은 구조를 만들려면 PK 필드와 연관 필드를 둘 다 세팅해야 한다. 안 그러면 PK는 비어 있고 연관만 박혀 있는 상태가 된다.

// 피하기
OrderItem item = new OrderItem();
item.getId().setOrderId(order.getId());     // PK 수동 세팅
item.getId().setProductId(product.getId());
item.setOrder(order);                        // 연관 세팅 (중복 작업)
item.setProduct(product);

같은 값을 두 번 세팅하면 불일치 가능성이 생긴다. PK는 1번 주문, 연관은 2번 주문을 가리키는 모순이 가능해진다. @MapsId는 이 불일치를 컴파일 단계는 아니지만 런타임에서 자동 보정해 준다.

9-2) PK 컬럼과 FK 컬럼 공유

@MapsId를 쓰면 PK 컬럼과 FK 컬럼이 물리적으로 같은 컬럼이 된다. 즉 OrderItem 테이블에는 order_id, product_id 두 컬럼만 있고, 이 두 컬럼이 동시에 PK이자 FK다.

CREATE TABLE order_item (
    order_id    BIGINT NOT NULL,
    product_id  BIGINT NOT NULL,
    quantity    INT NOT NULL,
    PRIMARY KEY (order_id, product_id),
    FOREIGN KEY (order_id)   REFERENCES orders(id),
    FOREIGN KEY (product_id) REFERENCES product(id)
);

스키마 입장에서도 자연스럽고, 인덱스 중복도 없다. 연관 테이블/조인 테이블에서는 @MapsId가 거의 항상 정답이다.

10) 자연 키 vs 대리 키, 그리고 시퀀스 이름 공유

10-1) 자연 키는 PK로 쓰지 마라

자연 키(natural key)는 비즈니스 의미가 있는 식별자다 — 이메일, 주민등록번호, 상품 코드, ISBN 등. PK로 쓰면 안 된다는 게 현대 DB 설계의 기본 합의다. 이유는 단순하다.

변경 비용 — 이메일은 바뀐다. 상품 코드는 정책에 따라 재발급된다. PK가 바뀌면 모든 FK를 갱신해야 한다
외부 노출 — PK는 JOIN 키로 모든 테이블에 박힌다. 비즈니스 의미가 노출되면 보안/프라이버시 문제로 번진다
타입의 자유도 — 자연 키는 가변 길이 문자열이 많다. 인덱스 효율이 떨어진다

해법은 **대리 키(surrogate key)**다. Long 또는 UUID/TSID로 의미 없는 식별자를 만들고, 자연 키는 별도 컬럼에 unique 제약을 거는 식이다.

@Entity
public class Member {
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "member_seq")
    @SequenceGenerator(name = "member_seq", sequenceName = "member_seq", allocationSize = 50)
    private Long id;                        // 대리 키

    @Column(unique = true, nullable = false)
    private String email;                   // 자연 키, unique 제약
}

이렇게 두면 이메일이 바뀌어도 PK는 그대로다. FK 갱신이 필요 없고, 외부에는 PK만 노출하면 된다.

10-2) 시퀀스 이름은 엔티티별로

Hibernate 5는 @SequenceGenerator를 명시하지 않으면 모든 엔티티가 hibernate_sequence 라는 단일 시퀀스를 공유했다. 결과적으로 Member와 Order가 같은 시퀀스에서 PK를 받아 ID 값이 뒤섞였다. 운영하면서 "회원 1, 2, 3 다음에 7, 8이 나오는 이유는 4, 5, 6이 주문에 할당돼서"라는 사실을 모르고 의아해하는 경우가 많았다.

Hibernate 6은 이 동작을 바꿨다. @GeneratedValue(strategy = SEQUENCE)만 있고 @SequenceGenerator가 없으면 엔티티별 개별 시퀀스(<entity>_SEQ)를 사용한다. 다만 명시적으로 이름을 주는 편이 의도가 분명하고 마이그레이션 스크립트와 매칭하기도 쉽다.

// 권장
@SequenceGenerator(
    name = "member_seq",
    sequenceName = "member_seq",
    allocationSize = 50
)

CREATE SEQUENCE member_seq START WITH 1 INCREMENT BY 50;
CREATE SEQUENCE order_seq  START WITH 1 INCREMENT BY 50;
CREATE SEQUENCE product_seq START WITH 1 INCREMENT BY 50;

엔티티별 시퀀스는 다음 두 가지 이점이 있다.

의미 분리 — Member.id와 Order.id가 독립된 카운터를 갖는다
장애 격리 — 한 시퀀스가 비정상 상태가 돼도 다른 엔티티에 영향이 없다

전사 단일 시퀀스는 분산 ID 생성 같은 특수 목적이 아니면 쓸 일이 없다. 새 엔티티 만들 때마다 시퀀스 한 개 만드는 걸 규약으로 삼는 편이 안전하다.

11) 실무에서 이렇게 읽고 쓴다

새 엔티티 만들 때 @GeneratedValue 한 줄을 그냥 붙이지 말고 batch insert가 필요한가 / 분산 환경인가 두 질문을 먼저 한다. 이 질문에 따라 IDENTITY / SEQUENCE / UUID·TSID 중 하나로 좁혀진다
MySQL + IDENTITY는 batch insert가 안 된다는 구조적 제약을 안고 있다. saveAll(10000건)이 느리면 PK 전략부터 의심한다. PostgreSQL이면 SEQUENCE + allocationSize=50이 무난한 디폴트
UUID를 쓴다면 반드시 v7 또는 TSID다. v4는 인덱스 페이지 분할로 성능을 갉아먹는다. MySQL에 UUID를 저장하면 BINARY(16), 절대 VARCHAR(36)으로 두지 말 것. @JdbcTypeCode(SqlTypes.BINARY)로 명시
SEQUENCE allocationSize로 ID 갭이 생기는 건 정상이다. 운영 담당자에게 "PK는 식별자일 뿐 연속성을 의미하지 않는다"는 점을 설명할 수 있어야 한다. 비즈니스 순번이 필요하면 별도 컬럼으로 분리한다
복합 키는 연관 테이블 / 조인 테이블에만 쓰고, 일반 엔티티는 대리 키 + 자연 키 unique 제약이 정공법이다. 복합 키를 일반 엔티티에 박으면 페이징, 정렬, 외부 참조 모든 곳에서 비용이 따라붙는다
@EmbeddedId를 쓰면 equals / hashCode / Serializable 3종은 무조건이다. 빠지면 1차 캐시가 동작하지 않는 것처럼 보이는 기괴한 증상이 나온다. Java 17+ record @Embeddable이 가장 안전한 패턴
@IdClass는 레거시 호환용. 새 코드는 @EmbeddedId + @MapsId로 가는 게 표준이다. @MapsId는 "PK와 FK가 같은 컬럼"이라는 자연스러운 매핑을 어노테이션 한 줄로 표현해 준다
시퀀스 이름은 엔티티별로 명시한다. 디폴트 공유 시퀀스에 의존하지 말 것. 마이그레이션 스크립트(Flyway/Liquibase)에 CREATE SEQUENCE ... INCREMENT BY 50을 함께 적어두는 걸 규약으로 삼는다

12) 한 줄 정리

JPA의 ID 전략은 batch insert 가능 여부와 분산 친화성으로 갈린다. MySQL+IDENTITY의 batch 제약과 UUIDv4의 인덱스 함정은 도입 전에 반드시 알아야 할 두 함정이다. 복합 키는 가능하면 피하되 필요하면 @EmbeddedId + @MapsId 조합으로 가고, PK 클래스의 equals·hashCode·Serializable은 협상 불가다. ID는 그저 식별자일 뿐 연속성도 비즈니스 의미도 담지 않는다는 원칙을 유지하면 운영 중 ID 갭이나 자연 키 변경 같은 사고를 사전에 잘라낼 수 있다.

태그: JPA, Hibernate, IDENTITY, SEQUENCE, UUID, TSID, EmbeddedId, MapsId, 복합키

상어코딩

Spring Data JPA @Modifying — 벌크 쿼리와 영속성 컨텍스트 동기화

Spring Data JPA @Modifying — 벌크 쿼리와 영속성 컨텍스트 동기화

들어가며

목차

1) @Modifying은 왜 필요한가

2) clearAutomatically / flushAutomatically: 기본값 false가 함정의 원인

2-1) flushAutomatically가 필요한 상황

2-2) clearAutomatically가 필요한 상황

3) 벌크 쿼리가 영속성 컨텍스트를 우회하는 메커니즘

4) 흔한 버그 시나리오: stale 엔티티

4-1) 시나리오 1: 조회 후 벌크 UPDATE, 다시 조회

4-2) 시나리오 2: 벌크 이후 변경 감지가 동작하지 않는 것처럼 보임

4-3) 시나리오 3: 네이티브 쿼리로 update 후 조회

5) JPQL 벌크 vs Native 벌크: @SQLRestriction이 적용되지 않는다

5-1) JPQL 벌크 UPDATE가 건드리지 못하는 것

5-2) FlushMode와의 상호작용

6) @Version 자동 증가가 일어나지 않는다

7) 영향 받은 row 수 반환과 해석

8) 파생 delete vs @Modifying DELETE: cascade와 이벤트의 갈림길

9) saveAllAndFlush / deleteAllInBatch — 편리함의 뒷면

9-1) saveAllAndFlush

9-2) deleteAllInBatch

10) 트랜잭션 경계와 Service @Transactional

10-1) 읽기 전용과 쓰기의 경계 분리

10-2) 내부 호출과 프록시 우회

11) 실무에서 이렇게 읽고 쓴다

11-1) 테스트에서 stale 엔티티 잡기

11-2) 대량 처리의 청크 분할

12) 한 줄 정리

Hibernate StatelessSession과 ScrollableResults — 대량 처리에서 영속성 컨텍스트를 버리는 선택

Hibernate StatelessSession과 ScrollableResults — 대량 처리에서 영속성 컨텍스트를 버리는 선택

들어가며

목차

1) 100만 건 처리가 왜 힘든가

2) 일반 Session의 메모리 구조 복습

3) StatelessSession 개요: 잃는 것과 얻는 것

4) StatelessSession의 네 가지 메서드

5) 대량 Insert 패턴 비교: 일반 Session vs StatelessSession

5-1) 일반 EntityManager + flush/clear

5-2) StatelessSession

5-3) 비교

6) ScrollableResults: 커서 기반 스트리밍 조회

7) Stream Entity: Spring Data JPA 스타일

8) 드라이버별 ScrollableResults 제약: MySQL과 PostgreSQL

8-1) MySQL (mysql-connector-j)

8-2) PostgreSQL (pgjdbc)

8-3) 드라이버 제약 요약

9) Entity Listener와 2차 캐시와의 상호작용

9-1) @PrePersist·AuditingEntityListener

9-2) 2차 캐시

10) Spring Batch의 ItemWriter와 어떻게 맞물리나

11) 실무에서 이렇게 읽고 쓴다

12) 한 줄 정리

Hibernate Batch Insert/Update — JDBC batch와 영속성 컨텍스트가 만나는 지점

Hibernate Batch Insert/Update — JDBC batch와 영속성 컨텍스트가 만나는 지점

들어가며

목차

1) 왜 row-by-row는 느린가: 네트워크 왕복의 누적

2) JDBC Batch의 기본: PreparedStatement.addBatch

3) Hibernate batch가 JDBC batch를 감싸는 방식

3-1) 왜 "연속되는 구간"이 중요한가

3-2) flush 시점과 batch_size의 관계

4) 필수 설정 3종: batch_size / order_inserts / order_updates

4-1) batch_size는 얼마가 적당한가

4-2) 전역 vs 엔티티별

5) IDENTITY가 batch를 죽이는 이유

5-1) IDENTITY의 타이밍

5-2) 해결 — SEQUENCE 또는 애플리케이션 생성 PK

6) batch_versioned_data와 @DynamicUpdate 트레이드오프

6-1) @Version과 batch_versioned_data

6-2) @DynamicUpdate와 batch는 사실상 공존 불가

7) 대량 persist: saveAll은 해답이 아니다, flush/clear 패턴

7-1) 메모리 폭발을 막는 flush/clear

7-2) clearAutomatically는 벌크 쿼리 전용

8) JPQL bulk UPDATE가 우선인 이유

8-1) bulk UPDATE의 주의점

8-2) bulk DELETE도 같은 논리

9) JDBC 드라이버별 rewriteBatchedStatements

9-1) MySQL / MariaDB

9-1) `@PrePersist`·`AuditingEntityListener`