🧪 Spring Batch JpaCursorItemReader에 대하여

Spring Batch에서 대량 데이터 처리를 다뤄본 개발자라면 한 번쯤 고민했을 것입니다.
“JPA 기반으로 커서(Cursor)처럼 데이터를 읽을 수 있을까?”
오늘은 그 핵심 컴포넌트인 JpaCursorItemReader 의 역사와, 왜 HibernateCursorItemReader가 사라졌는지, 그리고 MySQL과 PostgreSQL의 커서 동작 차이까지 실제 실험 데이터와 함께 정리해보겠습니다.

---

1. JpaCursorItemReader의 역사

1.1 등장 배경

JpaCursorItemReader는 Spring Batch 4.3 (2020년경) 에 도입된 컴포넌트입니다.
그 이전까지는 JPA 환경에서 커서 기반 배치를 구현하려면 Hibernate의 ScrollableResults를 직접 사용하거나, PagingItemReader를 우회적으로 이용해야 했습니다.

하지만 Paging 방식은 offset 기반 페이징 쿼리 특성상 큰 데이터셋에서는 성능이 급격히 저하되는 문제가 있었습니다.
그래서 Spring 팀은 “JPA 환경에서도 커서처럼 순차적으로 데이터를 읽자”는 목표로 JpaCursorItemReader를 도입했습니다.

---

1.2 내부 동작 (초기 버전)

초기 JpaCursorItemReader는 이름만 Cursor였을 뿐, 실제 DB 커서(fetchSize 기반 streaming) 가 아닌 JPA EntityManager의 ResultList 전체 로딩 구조였습니다.
즉, 내부적으로는 아래 로직이 반복되었습니다.

Query query = entityManager.createQuery("SELECT e FROM Entity e");
List<Entity> results = query.getResultList(); // 전체 fetch

결국 “커서처럼 생겼지만 전혀 커서가 아니었던” 것입니다.
이 때문에 수십만 건 이상 처리 시 힙 메모리 급등 → OutOfMemoryError 가 자주 발생했습니다.

---

1.3 전환점: Spring Batch 5.x (2024년)

Spring Batch 5.2.0-M1부터 JpaCursorItemReader는 JPA 2.2의 getResultStream() API를 활용하도록 개선되었습니다.
이제 Hibernate 5.5+ 환경에서는 실제로 Streaming + FetchSize 조합이 작동합니다.

🔍 즉, Query.getResultStream() → JDBC 드라이버의 fetchSize까지 내려가며,
드라이버 수준에서 커서가 유지됩니다.

하지만 이 역시 JPA 구현체와 DB 드라이버의 지원 여부에 따라 달라집니다.
MySQL은 이 기능을 완전히 지원하지 않지만, PostgreSQL은 상당히 완성도 높게 지원합니다.

이것이 이 글을 쓰게 된 이유이기도 한데요, PostgreSQL이 커서 기능을 훌륭하게 지원하는 것과는 달리, MySQL에서는 별도의 설정이 필요하다는 것을 깨달았기 때문입니다.

---

2. HibernateCursorItemReader 폐기 이유

Spring Batch 3.x ~ 4.0 시절에는 HibernateCursorItemReader가 존재했습니다.
그러나 이 컴포넌트는 다음과 같은 이유로 폐기되었습니다.

2.1 폐기 시점

• Spring Batch 5.0 에서 Deprecated
• Spring Batch 5.2 에서 완전 제거되었습니다.

2.2 폐기 사유

1. Hibernate 전용이라는 구조적 한계
   → JPA 표준이 아니며, Hibernate API 버전에 따라 깨지거나 동작이 불안정했습니다.
2. Session 관리 이슈
   → ScrollableResults 사용 시 Session 유지 시간이 길어져 DB Connection Pool이 쉽게 고갈되었습니다.
3. JPA 표준화 흐름
   → JPA 2.2에서 getResultStream()이 도입되며, HibernateCursorItemReader는 중복 기능이 되었습니다.
4. Spring Batch 모듈 정리 정책
   → Hibernate 전용 Reader는 표준화 정책에 맞지 않아 제거되었습니다.

즉, Hibernate 전용에서 JPA 표준 기반(JpaCursorItemReader)으로 방향이 옮겨간 것입니다.

---

3. MySQL vs PostgreSQL: 커서 트리거 방식의 차이

커서 기반 페칭은 단순히 “fetchSize를 설정하면 된다” 수준이 아닙니다.
JDBC 드라이버가 어떤 시점에 커서를 트리거할지에 따라 완전히 다르게 작동합니다.

구분	MySQL	PostgreSQL
JDBC 옵션	useServerPrepStmts, useCursorFetch=true, defaultFetchSize 필요	defaultFetchSize만으로 충분
실행 방식	서버 사이드 커서를 명시적으로 활성화해야 함	기본적으로 서버 커서를 지원
쿼리 전송 구조	전체 결과를 클라이언트로 버퍼링 후 전달 (옵션 비활성 시)	서버 내부 커서 유지 후 필요할 때만 fetch
철학	단일 쿼리 결과를 빠르게 반환	대규모 스트리밍과 트랜잭션 안정성 중심
실질적 커서 모드	옵션 없으면 “가짜 커서”	항상 “진짜 커서”

결국 MySQL에서는
useServerPrepStmts + useCursorFetch=true + defaultFetchSize=N
세 옵션이 모두 필요해야 실제 커서 기반 스트리밍이 작동합니다.

---

4. 실험: MySQL의 Heap Memory 차이

4.1 간단한 배치 데이터 준비

MySQL JDBC드라이버를 사용할때, 옵션 지정 없이는 Cursor기반 배치처리가 의도대로 동작하지 않음을 증명하기 위해, 간단한 실험을 하나 준비했습니다.

해싱되기 전의 문자열을 가지는 BeforeHash 엔티티와, 해당 문자열을 해싱한 결과를 저장하는 AfterHash엔티티를 정의하겠습니다:

@Entity
public class BeforeHash {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, columnDefinition = "TEXT")
    private String content;
    
}


@Entity
public class AfterHash {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, columnDefinition = "TEXT")
    private String content;
    
    @OneToOne
    @JoinColumn(name = "source_id", nullable = false)
    private BeforeHash beforeHash;
    
}

여기서 중요한것은 Reader 뿐이므로, Processor나 Writer는 생략하고, Reader 구성만 살펴보겠습니다:

@Configuration
public class BeforeHashItemReaderConfig {
    
    @Bean
    @StepScope
    @Qualifier("beforeHashItemReader")
    public JpaCursorItemReader<BeforeHash> beforeHashItemReader(EntityManagerFactory emf) {
        return new JpaCursorItemReaderBuilder<BeforeHash>()
            .name("beforeHashItemReader")
            .entityManagerFactory(emf)
            .queryString(
            """
            SELECT b FROM BeforeHash b
            WHERE NOT EXISTS
                (SELECT a FROM AfterHash a WHERE a.beforeHash.id = b.id)
            ORDER BY b.id ASC
            """
            )
            .build();
    }
}

아직 AfterHash가 생성되지 않은 BeforeHash들을 모아서 Cursor 방식으로 가져오도록 합니다.

Step 및 Job은 다음과 같습니다:

@Configuration
public class HashJobStep {
    
    @Bean
    @Qualifier("hashStep")
    public Step hashStep(
        JobRepository jobRepository,
        PlatformTransactionManager txManager,
        @Qualifier("beforeHashItemReader")ItemReader<BeforeHash> reader,
        HashItemProcessor processor,
        @Qualifier("afterHashCreateWriter") ItemWriter<AfterHash> writer
        ) {
        return new StepBuilder("hashStep", jobRepository)
            .<BeforeHash, AfterHash>chunk(500, txManager)
            .reader(reader)
            .processor(processor)
            .writer(writer)
            .build();
    }
    
    @Bean
    @Qualifier("hashJob")
    public Job hashJob(
        JobRepository jobRepository,
        @Qualifier("hashStep") Step hashStep
    ) {
        return new JobBuilder("hashJob", jobRepository)
                .start(hashStep)
                .build();
    }
}

500개씩 청크로 묶어 처리하도록 해보겠습니다.

테스트 데이터로는, BeforeHash 테이블에 약 150만개의 Row를 준비해 두었는데요, 기본적으로 힙에 올라가 있는 데이터들(클래스 로더, String 상수 풀 등)이 있어서 상대적으로 크게 비교를 하기 위해 많은 데이터를 준비해 놓았습니다.

select count(*) from before_hash;

이제 실제 Job을 트리거 해보겠습니다.

4.2 Cursor 비활성화 (useCursorFetch=false)

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/batch
           ?useSSL=true
           &useUnicode=true
           &maxQuerySizeToLog=999999
           &zeroDateTimeBehavior=convertToNull
           &rewriteBatchedStatements=true

바로 위 설정이, 제가 처음 MySQL로 Cursor 배치 처리를 했을 때의 설정입니다. 따로 useServerPrepStmts, defaultFetchSize나 useCursorFetch옵션을 지정하지 않았습니다. 이 경우, 150만건의 데이터를 JpaCursorItemReader로 배치처리하는 경우, 힙 메모리 사용량은 아래처럼 선형적으로 증가합니다.

모든 데이터를 JVM에 직접 올리고 처리하기 때문입니다.

• 메모리 급등 → GC 반복 → 처리 지연
• fetchSize 설정 무시, 전체 결과를 메모리에 적재합니다.

---

4.3 Cursor 활성화

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/batch
           ?useSSL=true
           &useUnicode=true
           &useServerPrepStmts=true
           &maxQuerySizeToLog=999999
           &zeroDateTimeBehavior=convertToNull
           &rewriteBatchedStatements=true
           &useServerPrepStmts=true # 💡 추가!
           &defaultFetchSize=500    # 💡 추가!
           &useCursorFetch=true     # 💡 추가!

이번엔 커서를 활성화하기 위해 useServerPrepStmts, defaultFetchSize, useCursorFetch 옵션을 활성화했습니다. 결과는 다음과 같습니다.

힙메모리 점유율리 놀랍도록 줄어든 것이 보이나요?

• 일정한 힙 사용량 유지
• 일정 chunk 단위로 fetch 수행
• 안정적인 Throughput 확보가 가능합니다.

---

정리

완전한 커서 동작을 기대하려면, 여전히 JPA 구현체와 DB 드라이버의 협조가 필수입니다.

• Hibernate 5.5+ 이상
• MySQL Connector/J 8.0+
• useServerPrepStmts + useCursorFetch=true + defaultFetchSize(기본값 500) 명시

Cursor의 동작 방식을 이해하려면, PreparedStatement라는 것을 먼저 이해해야 하는데요, 순서가 바뀐 느낌이 있지만 다음 아티클에서는 이에 관해 살펴보겠습니다.