무럭무럭 자라나는 개발 기록

[Java/Spring] Heap 캐시 vs Offheap 캐시 - 캐시 히트인데 왜 느릴까?

giraffe_ — Tue, 30 Jun 2026 12:11:03 +0900

배경

얼마 전 업무에서 캐시를 적용했는데도 성능이 나아지지 않는 이상한 상황을 겪었다.

캐시 히트는 정상이었다. 근데 느렸다.

문제는 8500개짜리 Map을 캐시에서 꺼내는 로직에 있었다. getDataMap()은 분명 캐시에서 응답하고 있었는데, 요청이 몰릴 때마다 성능 저하가 반복됐다.

@Cacheable(value = "dataCache", key = "'dataMap'")
public Map<String, String> getDataMap() {
    return dataRepository.findAll();
}

원인을 파고들다 보니 내가 캐시 설정 파일에서 무심코 <offheap>을 쓰고 있었다는 걸 알게 됐다.

<cache alias="dataCache">
    <resources>
        <offheap unit="MB">50</offheap>
    </resources>
</cache>

그리고 그때 처음으로 제대로 이해했다. Heap 캐시와 Offheap 캐시는 동작 방식 자체가 다르다는 걸.

이 글은 그 과정에서 정리한 내용이다.

Heap과 Offheap의 차이

JVM 메모리 구조

두 캐시를 이해하려면 JVM의 메모리 구조를 먼저 봐야 한다.

Heap: new HashMap() 같이 Java가 생성하는 모든 객체가 올라가는 공간. GC가 관리한다.
Offheap: JVM 외부의 네이티브 메모리. GC의 관리 범위 밖이다.

Heap 캐시의 동작 방식

Heap 캐시는 객체를 Heap에 그대로 올려두고, 캐시 히트 시 메모리 주소만 전달한다. 복사도, 변환도 없다.

그냥 "거기 있어" 하고 주소를 가리키는 것과 같다.

Offheap 캐시의 동작 방식

Offheap은 다르다.

캐시 히트가 일어날 때마다 역직렬화가 발생한다. 이 부분이 핵심이다.

왜 Offheap은 직렬화가 필요할까?

JVM Heap의 Java 객체는 단순한 바이트 덩어리가 아니다.

객체들이 메모리 주소(참조) 로 서로 연결된 그래프 구조다.

이 구조를 Offheap으로 그대로 가져갈 수 없는 이유가 세 가지 있다.

이유 1 - 참조(포인터)는 JVM Heap 안에서만 유효하다

Heap 포인터는 JVM이 관리하는 주소 공간 안에서만 의미를 가진다.

이유 2 - GC가 객체를 이동시킨다

Offheap에 주소를 저장해뒀다가 GC 후에 꺼내면 엉뚱한 곳을 가리키게 된다.

이유 3 - Object Header는 JVM 전용 구조다

Object Header에는 클래스 정보 포인터, GC 마킹 비트, 동기화 락 정보가 담겨 있는데, JVM 외부에서는 해석이 불가능하다.

그래서 직렬화로 "주소 없는 순수 데이터"로 변환해서 저장하는 것이다.

역직렬화 시에는 이 바이트 배열을 읽어 JVM Heap에 새 객체를 새로 생성한다.

정리 - 캐시 히트라도 Offheap은 항상 역직렬화한다

내 케이스에서 문제가 됐던 이유가 바로 이거다.

[Offheap 캐시 조회 시]
Offheap 메모리 → [바이트 배열] → 역직렬화 → 새 HashMap 객체 생성
                                    ↑ 히트마다 이 비용 반복 발생

processRequest()는 요청마다 호출된다. 8500개짜리 Map을 요청마다 역직렬화하면 당연히 느리다.

Heap vs Offheap 선택 기준

	Heap 유리	Offheap 유리
객체 크기	작을 때 (~수 MB 이하)	매우 클 때 (수백 MB~GB)
조회 빈도	높을 때	낮을 때
GC 상황	Stop-the-world 문제 없을 때	GC 부담이 심할 때
Heap 메모리	여유 있을 때	부족할 때

내 케이스는 약 300KB짜리 Map, 고빈도 조회 → Heap이 적합한 상황이었다.

자바 스프링에서의 구현

Ehcache 설정에서 <offheap>을 <heap>으로 바꾸는 것만으로 해결됐다.

<cache alias="dataCache">
    <key-type>java.lang.String</key-type>
    <value-type>java.util.HashMap</value-type>
    <expiry>
        <ttl unit="hours">1</ttl>
    </expiry>
    <resources>
        <heap unit="entries">1</heap>
    </resources>
</cache>

unit="entries"는 바이트 크기가 아닌 키-값 쌍의 개수로 용량을 제한하는 단위다. 캐시 키가 고정 문자열 하나뿐이라 엔트리가 항상 1개 → entries = 1로 설정했다.

@Cacheable(value = "dataCache", key = "'dataMap'")
//                                     ↑ 항상 고정 → 엔트리 1개
public Map<String, String> getDataMap() {
    return dataRepository.findAll();
}

이걸로 캐시 히트 시 역직렬화 없이 바로 객체 참조를 반환하게 됐고, 성능 이슈가 해결됐다.

마무리

"캐시 히트 = 빠름"이라고만 생각하고 있었는데, Offheap의 경우 히트 시에도 역직렬화 비용이 매번 발생한다는 걸 처음으로 제대로 이해한 계기였다.

설정 파일 한 줄(<offheap> → <heap>)만 바꿨는데 성능이 개선됐다. 그 한 줄의 의미를 몰랐던 게 문제였다.

캐시를 선택할 때는 객체 크기와 조회 빈도를 기준으로 생각해야겠다는 교훈을 얻었다.

[ClickHouse] ClickHouse JOIN이 느린 이유와 최적화 전략

giraffe_ — Mon, 15 Jun 2026 19:00:01 +0900

ClickHouse를 처음 쓰다 보면 한 번쯤 이런 경험을 한다. MySQL에서는 아무 문제 없이 돌아가던 JOIN 쿼리가 ClickHouse에서는 유독 느리거나, WHERE 조건을 다 걸었는데도 풀스캔 수준의 시간이 걸리는 것이다. 이 글에서는 그 이유를 ClickHouse의 내부 동작 방식에서 찾고, 실제로 쓸 수 있는 최적화 전략을 정리한다.

어떤 상황인가

수억 건의 유저 행동 로그(page_view_log)와 주문 데이터(order_log)를 JOIN해서 페이지를 본 특정 기간, 특정 유저의 구매 건수를 집계한다고 해보자. 아래처럼 쓰는 것이 자연스럽다.

SELECT count(*)
FROM default.page_view_log p
  JOIN default.order_log o
      ON p.user_id = o.user_id
    AND p.session_id = o.session_id
WHERE o.order_date BETWEEN '20260604' AND '20260610'
  AND o.user_id = 'user_001'

그런데 이 쿼리는 유독 느리다.

실제로 왼쪽 테이블 약 3억 건, 오른쪽 테이블 약 7천만 건의 데이터를 위의 쿼리로 조회했을 때 약 1분 40초가 걸렸다.

반면 아래처럼 서브쿼리로 먼저 필터링하면 체감이 다를 정도로 빠르게 실행된다.

SELECT count(*)
FROM
    (SELECT * FROM default.order_log
     WHERE order_date BETWEEN '20260604' AND '20260610'
       AND user_id = 'user_001'
    ) O
    INNER JOIN (
        SELECT * FROM default.page_view_log
        WHERE user_id = 'user_001'
          AND created_at > '20260504'
    ) P ON P.user_id = O.user_id AND P.session_id = O.session_id

실제로 위의 개선된 쿼리로 다시 조회했을 때 약 0.6초가 걸렸다.

두 쿼리의 논리적 결과는 같다. 그런데 왜 실행 시간이 다를까?

이유 1 - ClickHouse는 Predicate Pushdown을 자동으로 하지 않는다

MySQL, PostgreSQL 같은 RDBMS는 Cost-Based Optimizer(CBO) 를 탑재하고 있다. 테이블 통계를 바탕으로 "어떤 순서로 실행하면 비용이 가장 낮을지"를 계산하고, WHERE 조건을 JOIN 이전 단계로 밀어 넣는 Predicate Pushdown을 자동으로 수행한다.

Cost-Based Optimizer

https://docs.oracle.com/en/database/oracle/oracle-database/21/tgsql/query-optimizer-concepts.html#GUID-298EDC61-405A-4E25-AEF6-C795E32AAC93

CBO는 테이블 통계를 바탕으로 실행 비용을 계량화해서, 가장 낮은 비용의 실행 계획을 자동으로 선택하는 옵티마이저다. 테이블 행 수, 컬럼 카디널리티, 값의 분포(히스토그램), 인덱스 유무 같은 통계 정보를 활용해 "A 방법은 예상 비용 1200, B 방법은 예상 비용 340" 식으로 계산한 뒤 최적 순서를 결정한다.

이게 필요한 이유는 쿼리를 실행하는 방법이 하나가 아니기 때문이다. 아래 쿼리 하나만 해도 실행 순서가 여러 가지다.

SELECT * FROM orders o JOIN users u ON o.user_id = u.id
WHERE o.created_at > '2026-01-01' AND u.country = 'KR'

orders를 먼저 필터링한 뒤 users와 JOIN하거나
users를 먼저 필터링한 뒤 orders와 JOIN하거나
두 테이블을 통째로 JOIN한 다음 WHERE를 적용하거나

어떤 순서가 빠른지는 데이터 분포에 따라 다르다. country = 'KR'이 전체 유저의 90%라면 users 필터는 별 도움이 안 되고, created_at 조건이 orders를 1%로 줄인다면 거기서 먼저 필터링하는 게 훨씬 유리하다. CBO는 이 판단을 사람 대신 자동으로 해준다.

Predicate Pushdown

"Predicate(조건)를 Pushdown(밀어 넣는다)"이라는 이름 그대로, WHERE 조건을 가능한 한 데이터 소스에 가깝게 밀어 넣어 일찍 필터링하는 최적화다. 데이터는 늦게 걸러낼수록 손해다. 100만 건을 JOIN한 뒤 1만 건만 남기는 것보다, 먼저 1만 건으로 줄인 뒤 JOIN하는 게 당연히 빠르다.

-- 개발자가 작성한 쿼리
SELECT * FROM orders o JOIN users u ON o.user_id = u.id
WHERE o.created_at > '2026-01-01' AND u.country = 'KR'

-- 옵티마이저가 Predicate Pushdown 적용 후 실행하는 형태
SELECT * FROM
    (SELECT * FROM orders WHERE created_at > '2026-01-01') o
JOIN
    (SELECT * FROM users WHERE country = 'KR') u
ON o.user_id = u.id

JOIN 전에 양쪽을 각자 줄여놓으니, 붙여야 할 데이터 자체가 작아진다. 개발자가 WHERE를 어디에 두든 옵티마이저가 알아서 이 순서로 재구성한다.

단, Predicate Pushdown이 항상 가능한 건 아니다. HAVING처럼 집계 이후에 적용되는 조건이나, 비결정적 함수(NOW() 등)가 포함된 조건은 밀어 넣을 수 없다.

-- HAVING: 집계가 끝나야 cnt 값이 생기므로 GROUP BY 이전으로 밀어 넣을 수 없다
SELECT user_id, count(*) AS cnt
FROM orders
GROUP BY user_id
HAVING cnt > 10

-- 비결정적 함수: 실행 시점마다 값이 달라지므로 pushdown이 제한된다
WHERE created_at > NOW() - INTERVAL 7 DAY

ClickHouse에서는?

ClickHouse도 일부 Cost-Based 최적화를 지원하지만, MySQL·PostgreSQL의 CBO처럼 JOIN 실행 순서나 Predicate Pushdown이 RDBMS 수준으로 보장되지는 않는다. 단일 테이블에 대한 단순한 조건은 pushdown되기도 하지만, JOIN이 포함된 복잡한 쿼리에서는 WHERE 조건이 JOIN 이후에 적용되는 경우가 많다. 옵티마이저가 알아서 해줄 거라고 믿고 쓰기 어렵다.

page_view_log (전체) × order_log (전체) → JOIN → WHERE 필터

필터가 붙기 전에 이미 수억 건짜리 테이블 두 개가 전부 조인된다. 쿼리가 느린 건 당연한 결과다.

pushdown이 되더라도 부분적으로만 적용되거나 아예 되지 않는 경우가 많아, 결과를 예측하기 어렵다. 결국 뒤에서 다룰 "서브쿼리로 먼저 줄이기" 패턴은 CBO + Predicate Pushdown을 개발자가 직접 명시적으로 구현하는 것과 같다.

이유 2 - Hash Join은 오른쪽 테이블을 메모리에 통째로 올린다

ClickHouse의 기본 JOIN 알고리즘은 Hash Join이다.

오른쪽 테이블 전체를 해시 테이블로 메모리에 적재
왼쪽 테이블을 스트리밍하면서 해시 테이블과 매칭

https://clickhouse.com/blog/clickhouse-fully-supports-joins-hash-joins-part2

해시 테이블은 키로 즉시 조회가 가능한 자료구조다. 오른쪽을 메모리에 올려두고, 왼쪽 행이 들어올 때마다 해당 키로 바로 찾아 매칭하는 방식이다. 조회 자체는 빠르지만, 오른쪽 테이블 전체가 메모리에 들어가야 한다는 전제가 있다.

오른쪽 테이블이 필터링되지 않은 대용량 로그라면 수억 건이 메모리에 올라가야 하고, 메모리가 부족하면 디스크로 넘쳐 더 느려진다. 서브쿼리로 미리 걸러서 오른쪽을 소량으로 줄이면, 메모리 적재 비용 자체가 작아져 전체 처리 시간이 크게 단축된다.

ClickHouse와 RDBMS, 설계 목적이 다르다

위의 두 가지 이유(Predicate Pushdown 미보장, Hash Join의 메모리 적재 방식)는 모두 ClickHouse가 RDBMS와 근본적으로 다른 설계 철학을 갖고 있기 때문에 생긴다.

항목	RDBMS	ClickHouse
설계 목적	OLTP - 다양한 쿼리 패턴을 균형 있게 처리	OLAP - 단일 테이블 대규모 스캔 특화
옵티마이저	Cost-Based, 통계 기반 실행 계획 수립	상대적으로 단순한 Rule-Based
Predicate Pushdown	자동 수행	제한적, 명시적으로 작성해야 함
JOIN 알고리즘 선택	Nested Loop / Hash / Merge 중 자동 선택	기본 Hash Join 고정

ClickHouse는 처음부터 "단일 테이블 집계를 극한으로 빠르게" 하는 데 집중해서 설계됐다. 복잡한 옵티마이저 대신 컬럼 스토리지와 벡터화 연산에 투자했고, 그 결과 단일 테이블 집계는 빠르지만 JOIN은 개발자가 직접 챙겨야 한다.

최적화 전략

Dictionary, View처럼 DDL 권한이 필요한 방법도 있지만, 여기서는 쿼리 작성 수준에서 바로 적용할 수 있는 방법만 다룬다.

1. 서브쿼리로 데이터를 먼저 줄이기

가장 기본이자 가장 효과적인 방법이다. JOIN 전에 각 테이블을 서브쿼리로 필터링해서 실제 JOIN 대상 데이터를 최소화한다. 앞에서 본 두 번째 쿼리가 이 원칙을 적용한 형태다.

SELECT count(*)
FROM
    (SELECT * FROM default.order_log
     WHERE order_date BETWEEN '20260604' AND '20260610'
       AND user_id = 'user_001'
    ) O
    INNER JOIN (
        SELECT * FROM default.page_view_log
        WHERE user_id = 'user_001'
          AND created_at > '20260504'
    ) P ON P.user_id = O.user_id AND P.session_id = O.session_id

2. 작은 테이블을 오른쪽에 배치

Hash Join 특성상 오른쪽 테이블이 메모리에 올라가므로, 항상 더 작은 쪽을 오른쪽에 두어야 한다.

-- 나쁨: 필터링되지 않은 대용량 테이블이 오른쪽
FROM order_log O
JOIN page_view_log P ON ...

-- 좋음: 필터링된 작은 쪽이 오른쪽
FROM (SELECT * FROM page_view_log WHERE ...) P
JOIN (SELECT * FROM order_log WHERE ...) O ON ...

3. JOIN 알고리즘 명시적 지정

SETTINGS로 알고리즘을 직접 지정할 수 있다.

SELECT ...
FROM A JOIN B ON ...
SETTINGS join_algorithm = 'grace_hash'

알고리즘	특징
hash	기본값. 오른쪽 전체를 메모리에 적재
partial_merge	메모리를 아낄 때. 속도는 느림
grace_hash	대용량 JOIN. 디스크를 보조로 활용
auto	메모리 상황에 따라 자동 선택

마치며

ClickHouse에서 JOIN 성능은 옵티마이저를 믿는 것이 아니라 개발자가 실행 순서를 직접 설계하는 데서 나온다. 서브쿼리로 데이터를 충분히 줄이고, 작은 쪽을 오른쪽에 두는 것만으로도 대부분의 성능 문제는 해결된다.

[후기] AWS Summit Seoul 2026

giraffe_ — Thu, 11 Jun 2026 00:14:49 +0900

AWS Summit Seoul 2026에 다녀왔다. 5월 20일, 1일차다. 뒤늦은 후기이다.

백엔드 개발자로서 SSAFY와 사이드 프로젝트를 거치며 AWS를 써왔는데, 취업은 온프레미스 환경의 회사로 했다. 현재 회사에서 인프라를 거의 다루지 않다 보니 클라우드와 점점 멀어지고 있던 차에 AWS Summit 소식을 듣고, 소중한 연차 하루를 써서 다녀왔다.

다녀오길 잘했다. 지금 하는 개발이 클라우드나 AI와 직접적인 연관은 없지만, 개발자로서 영감을 얻을 수 있는 내용이 많았다.

역시 AI 시대답게 거의 모든 세션이 AI 활용에 관한 내용이었다. 얼마 전까지만 해도 대용량 아키텍처나 인프라 설계가 주를 이뤘던 것 같은데, AI 시대가 도래하면서 주제도 달라졌다.

AWS Events 앱을 설치해서, 대학생 때 시간표를 짜듯 세션 라인업과 시간을 꼼꼼히 살펴봤다. 제목과 설명을 보고 끌리는 세션을 골랐고, 마땅히 보고 싶은 세션이 없는 시간대에는 일행을 따라가거나 부스를 구경했다.

내게 도움이 될 만한 세션은 대용량 트래픽 및 데이터 처리 관련 내용이었는데, 대부분이 AI 세션이라 고르기 쉽지 않았다. 제목과 개요만으로는 내용이 잘 와닿지 않는다는 것도 어려움이었다.

https://aws.amazon.com/ko/events/summits/seoul/agenda/

강연 목록 | AWS Summit Seoul 2026

2026년 5월 20-21일 오전 8시 30분: 등록 시작 오전 9시 30분 - 오전 10시 40분: 기조연설 오전 11시 10분 - 오후 4시 50분: 브레이크아웃 세션 오전 10시 - 오후 5시 30분: 엑스포

aws.amazon.com

세션 장소는 산업별로 트랙이 구분되어 있었다.

Track1 : AI 시대의 리더십
Track2, Track3, Track4 : 리테일 및 커머스, 금융 및 핀테크, SaaS 및 디지털 플랫폼
Track5, Track6, Track7 : 제조 및 하이테크, 피지컬AI, 통신, 미디어 및 게임
Track8, Track9 : 트래블 및 호스피탈리티, 공공 및 헬스케어

9시 30분 기조연설은 패스하고 11시 세션부터 들었다. 보고 싶은 세션이 대부분 Track2, Track3, Track4에 몰려 있어서 주로 3층 행사장에 있었다.

확실히 Track2, Track3, Track4 행사장은 규모도 크고 사람도 많았다. 특히 금융 및 핀테크의 Track3은 줄이 길었다. 트랙별로 구역이 나뉘어져 있고 스크린도 별도지만, 한 공간 안에 있어서 다른 트랙 강연을 동시에 볼 수 있었다. 자리마다 헤드셋이 비치되어 있어, 채널을 바꾸면 다른 트랙 세션을 들을 수 있었다.

왼쪽에 스위치 딸깍으로 다른 트랙 강연을 들을 수 있었다

KBaaS, 금융이 플랫폼 속으로 KB국민은행의 임베디드 금융 전략과 API 인프라 현대화

(11:10~11:50)

비금융 플랫폼 속에 금융을 녹여내는 임베디드 금융 시대, KB국민은행은 자체 개발한 BaaS 플랫폼 'KBaaS'를 통해 결제, 예금, 인증 등 다양한 금융 서비스의 영역을 비금융 플랫폼으로 확장하고 있습니다. 1,800여 개 API와 일 2억 건의 호출을 처리하는 KBaaS의 API 인프라를 3rd Party 솔루션에서 자체 개발 게이트웨이로 전환하고, AWS EKS 기반 클라우드 네이티브 아키텍처로 고도화한 실사례를 통해, 비용 절감·성능 향상·네트워크 혁신의 실질적 성과와 임베디드 금융 확산을 위한 인사이트를 제공합니다.

이 세션을 고른 이유는 두 가지였다. 대용량 트래픽을 처리하는 구조가 궁금했고, 보수적인 금융권에서 자체 시스템을 클라우드 기반으로 어떻게 전환했는지 알고 싶었다.

현재 회사에서도 게이트웨이에서 일 수억 건의 API 호출을 처리하고 있지만, 온프레미스로 자체 구축한 시스템이다. 비슷한 규모를 클라우드로 어떻게 구현했는지 비교해보고 싶었다.

AB180이 SaaS 에이전틱 AI를 설계하는 방법

(12:50~13:30)

AB180은 2024년 11월 RAG 기반 챗봇 ASK Airbridge를 출시했으나 30% 미만의 낮은 유효 답변율로 사람의 개입이 필요했습니다. 본 세션에서는 Amazon Bedrock AgentCore 기반 에이전틱 AI 챗봇 Airbridge Pilot이 B2B SaaS 보안 요건을 만족하고 90% 이상의 유효 답변율을 달성한 여정을 공개합니다.

원래 일정은 Track3(금융 및 핀테크)의 '미래에셋증권의 GraphRAG 기반 상품지식DB 구축기'였다.

GraphDB를 활용한 RAG 구성이 궁금했다. 현재 회사 기술과는 거리가 있지만, 요즘 개인적으로 사이드 프로젝트를 하면서 관심을 갖게 된 주제였다.

세션을 들으며 내용이 어려워 이해하느라 애를 쓰던 차에, Track4(SaaS 및 디지털 플랫폼) 화면에 회사에서 사용 중인 익숙한 솔루션이 눈에 들어왔다. 바로 채널을 바꿨다.

반갑다 에어브릿지

(내용 추가하기!)

중앙대의료원 - 의료진이 직접 만드는 의료 AI

(13:50~14:10)

중앙대의료원은 의료진이 AI를 단순히 활용하는 수준을 넘어 현장에서 필요한 기능을 직접 기획하고 구현할 수 있는 환경을 만들어가고 있습니다. 의료 현장의 구조적 과제를 해결하기 위한 전략으로 AI 전환을 추진해왔으며 AWS T&C 프로그램과 KIRO 기반의 바이브 코딩을 통해 개발 경험이 없는 의료진도 실제 업무에 필요한 도구를 빠르게 만들 수 있다는 가능성을 확인했습니다. 본 세션에서는 이러한 실행 경험을 바탕으로 의료 AI 혁신의 장벽을 낮추기 위한 사람 중심의 전환 전략과 의료진 주도 개발이 현장에 주는 인사이트를 공유합니다.

요즘 바이브 코딩이 주목받고 있다. 나도 Claude Code를 활용해 만들고 싶은 서비스를 바이브코딩으로 구현하고 있고, 최근에는 문과 친구에게 바이브 코딩을 가르치기도 했다. 비개발자가 AI를 활용해 현장에서 필요한 도구를 어떻게 만드는지 궁금해서 고른 세션이었다.

AWS Kiro가 바이브코딩에 필요한 과정을 자동화하고 있다는 점이 인상적이었다. 비개발자 입장에서 바이브 코딩의 진입장벽은 분명히 존재하는데, Kiro 같은 도구가 있다면 훨씬 쉬워질 것 같다. 비개발자도 코딩할 수 있는 시대가 가까워지고 있다는 걸 체감했다.

개발자인 나는 코딩과 인프라 구축·배포는 할 수 있지만, 막상 사람들에게 진짜 필요한 서비스가 무엇인지는 잘 모른다는 게 항상 아쉬웠다. 직업 현장에서 일하는 사람들이 필요를 느껴 직접 만드는 서비스가 결국 더 많은 사람에게 쓰이고 살아남을 거라는 생각이 든다.

바비톡의 AX 여정 에이전틱 AI로 K-beauty를 바꾸다

(14:30~15:10)

1,000만 유저의 바비톡은 AI 특공대와 Monthly PoC로 AX를 추진하고 있습니다. 본 세션에서는 Amazon Bedrock 기반 K-Beauty 어시스턴트 등 Agentic AI 도입 사례와, AI-DLC(AI Development Life Cycle)를 사용해 마케팅팀과 개발팀 협업 모델 변화를 통한 개발 문화 및 생산성 혁신 경험을 공유합니다.

(내용 추가하기!)

원래는 16:10~16:50에 열리는 '새벽 3시, 18만 개의 모델이 대신 판단한다 : 넥슨의 에이전틱 Ops'를 듣고 싶었다.

AI를 활용해 실시간 서비스의 장애를 어떻게 대응하는지 궁금했기 때문이다. 회사에서도 이슈가 발생할 때마다 실시간 알림을 받고 있는 입장이라 더 관심이 갔다. 하지만 시간 상 못 봤다. 나중에 영상으로 봐야겠다.

(내용 추가하기!)

부스

역시 AI를 접목한 서비스들이 대부분이었다. AI, LLM, RAG... 아는 게 많지 않아 일행이 대신 질문을 해줬지만, 각 산업에서 어떤 니즈가 있고 AI로 어떤 기능을 구현할 수 있는지 영감 정도는 얻었다. 나도 AI 공부를 좀 더 해야겠다는 생각이 들었다.

부스를 돌아다니며 설문조사에 참여하고 스티커를 받았다. 그리고 담당자분들과 대화하고 스탬프와 기념품도 챙겼다.

반갑다 클릭하우스

돌아다니다 Clickhouse 부스가 눈에 들어왔다. 회사에서 로그와 통계 쌓는 용으로 쓰고 있는 DB인데, 국내 사용자도 적고 정보도 많지 않아 애를 먹던 터라 반가움이 이루 말할 수 없었다. 나는 블로그에 Clickhouse 관련해서 글을 쓰고 있다. 많관부.

담당자분께 회사에서 Clickhouse를 사용하고 있다고 먼저 인사를 드렸다. 설문조사에 참여하고 Clickhouse Cloud 300달러 크레딧과 볼펜을 받았다. 노란 볼펜이 꽤 귀엽다. 회사에서 일하면서 볼펜 아주 잘 쓰고 있다.

정신없이 돌아다니다 보니 5시가 넘었다. 티셔츠 수령처에 갔더니 마감이라고 했다. AWS 티셔츠를 못 챙겨서 아쉬웠지만, Elastic 부스에서 사슴 캐릭터가 그려진 ELK 티셔츠를 받아왔다.

귀엽다 스티커들

[Java/Spring] 파일 기반 재처리 아키텍처 - BlockingQueue로 데이터 유실 막기

giraffe_ — Tue, 2 Jun 2026 01:01:48 +0900

배경

멀티스레드 배치 시스템에서 벌크 INSERT가 간헐적으로 타임아웃으로 실패했다. 기존 코드는 예외를 로그로만 남겼기 때문에 실패한 수천 건이 그대로 유실됐다. 게다가 타임아웃이 발생하는 시점은 DB 부하가 높은 구간이다. 실패가 연달아 수 천건씩 N번 발생했다.

시도했던 방식

단순히 예외를 잡아 재시도하는 방식은 배치 스레드를 지연시키고, 실패가 연달아 발생하면 재시도 로직도 함께 실패한다.

타임아웃이 발생하는 시점은 DB 부하가 높은 구간이다. 재시도를 즉시 실행하면 같은 부하 구간에서 다시 실패할 가능성이 높고, 그 사이 다른 배치도 같은 스레드풀을 기다린다. 실패가 연달아 수 천건씩 N번 발생하는 패턴에서 인라인 재시도는 수십 번 연속으로 쌓여 배치 전체를 마비시킬 수 있다.

대신 실패 데이터를 파일로 보존한 뒤 별도 스케줄러로 재처리하는 구조를 선택했다. 배치 스레드는 실패를 큐에 넣는 것만 하고 즉시 다음 chunk로 넘어간다. DB 부하가 해소된 뒤, 별도 스케줄러가 단건 INSERT로 재처리하면 타임아웃이 발생하지 않는다.

아키텍처 설계

전체 흐름은 실패 감지 → 큐에 삽입 → 파일에 쓰기 → 재처리 네 단계로 나뉜다. 각 단계는 서로 다른 스레드에서 독립적으로 동작한다.

배치 스레드는 실패를 큐에 넣는 순간 할 일이 끝난다. 큐 뒤에서 무슨 일이 일어나는지 알 필요가 없다. FailFileWriter는 큐에서 데이터를 꺼내 파일에 쓰는 일만 한다. FailScheduler는 파일이 언제 만들어졌는지 신경 쓰지 않고 정해진 시각에 파일을 읽어 재처리한다.

각 단계가 다음 단계를 직접 호출하지 않고, 큐와 파일이라는 중간 저장소를 통해서만 데이터를 넘긴다. 각 컴포넌트가 독립적으로 동작하기 때문에 재처리 로직이 배치 성능에 영향을 주지 않는다.

구현 상세

DAO 레이어 - INSERT 실패 감지

public int collectProductData(User user, List<Product> products, ...) {
    try (SqlSession sqlSession = ...) {
        sqlSession.insert("productMapper.insertBulk", products);
        return products.size();
    } catch (Exception e) {
        failQueue.offerAll(user, products, ...);  // 실패 → 큐 삽입
        return 0;
    }
}

DAO 레이어에서 실패를 감지하면 예외를 상위로 던지지 않고 `FailQueue.offerAll()`을 호출해 실패 데이터를 큐에 넣는다. 배치 스레드 입장에서 실패 처리는 여기서 끝나고, 이후 파일 기록과 재처리는 별도 컴포넌트가 담당한다.

큐 삽입이 블로킹되지 않기 때문에 배치 스레드는 즉시 다음 chunk로 넘어간다.

FailQueue - 공유 큐

private final BlockingQueue<Object> queue = new LinkedBlockingQueue<>(200_000);

public void offerAll(UserInfo user, List<Product> products) {
    for (Product product : products) {
        queue.offer(new FailedProduct(user, product));
    }
}

public boolean offer(CloseRequest closeRequest) {
    return queue.offer(closeRequest);
}

FailQueue는 LinkedBlockingQueue로 구현된 공유 버퍼다. DAO 레이어(producer)와 FailFileWriter(consumer) 사이를 연결한다. 배치 스레드가 여러 개여도 큐는 하나이기 때문에 동시성 처리는 BlockingQueue가 내부적으로 보장한다.

FailedProduct(실패 데이터)와 CloseRequest(배치 완료 신호) 두 타입을 같은 큐로 관리해 consumer가 순서를 보장받는다.

offer vs put: put은 큐가 꽉 차면 공간이 생길 때까지 블로킹한다. 배치 스레드가 큐 삽입 때문에 멈추면 안 되므로 블로킹하지 않는 offer를 사용했다. 큐가 꽉 차서 offer가 false를 반환하는 상황은 200,000건이 모두 쌓인 극단적인 경우로, 실운영에서는 발생하지 않을 것으로 판단했다.

FailFileWriter - 전용 consumer 스레드

필드 구성

private final FailQueue failQueue;
private final Map<String, BufferedWriter> writerMap = new ConcurrentHashMap<>();
private final ObjectMapper objectMapper = new ObjectMapper();
private volatile boolean running = true;

필드 설명

필드	설명
writerMap	키로 Writer 관리
running	volatile 선언으로 @PreDestroy와 consumer 스레드 간 가시성 보장
objectMapper	consumer 스레드가 1개이므로 인스턴스 공유 안전

writerMap : userId#...#...#date 형태의 키로 Writer 인스턴스를 관리한다. 배치 유형, 날짜 등 조합마다 파일이 하나씩 열리기 때문에, 키만 보면 어떤 배치의 실패 데이터가 어느 파일에 기록되고 있는지 알 수 있다. ConcurrentHashMap을 쓴 이유는 consumeLoop(consumer 스레드)와 shutdown()(@PreDestroy, 메인 스레드)이 동시에 맵에 접근할 수 있어서다. consumer 스레드가 하나뿐이더라도 종료 시점에 두 스레드가 맵을 동시에 읽고 쓸 수 있으므로 일반 HashMap은 안전하지 않다.

running 플래그는 volatile로 선언한다. @PreDestroy가 실행되는 메인 스레드에서 false로 변경한 값이 consumer 스레드에 즉시 보여야 하기 때문이다. volatile이 없으면 JVM이 레지스터나 CPU 캐시에 값을 들고 있을 수 있어 consumer 스레드가 변경을 인식하지 못할 수 있다.

voliatile에 대한 자세한 내용은 이전에 다룬 적이 있다.

[Java] volatile - 멀티스레드 가시성 문제 트러블슈팅

들어가며 독립 큐 + 전용 워커 스레드를 사용하는 서비스에서 종료 신호가 워커 스레드에 전달되지 않는 문제가 발생했다. @PreDestroy에서 running = false를 분명히 썼는데도 워커 스레드는 루프를 계

programmingiraffe.tistory.com

스레드 생명주기

@PostConstruct
public void start() {
    Thread t = new Thread(this::consumeLoop, "fail-file-writer");
    t.start();
}

@PreDestroy
public void shutdown() {
    running = false;
    for (BufferedWriter writer : writerMap.values()) {
        try { writer.close(); }
        catch (IOException e) { log.error("shutdown: 파일 닫기 실패"); }
    }
}

애플리케이션 기동 시 @PostConstruct가 consumer 스레드를 하나 띄운다. 스레드 이름을 fail-file-writer로 명시한 것은 스레드 모니터링에서 역할을 식별하기 위해서다.

@PreDestroy에서는 running = false로 루프를 빠져나오게 한 뒤 열려있는 Writer를 모두 닫는다.

consumeLoop

private void consumeLoop() {
    try {
        while (running) {
            Object object = failQueue.take(); // 큐가 빌 때까지 블로킹

            if (object instanceof FailedProduct(UserInfo user, Product product)) {
                String key = user.getId() + "#" + .. + "#" + LocalDate.now();

                BufferedWriter writer = writerMap.computeIfAbsent(key, k -> createWriter(k));
                writer.write(objectMapper.writeValueAsString(product));
                writer.newLine();
                writer.flush(); // 매 건마다 flush — 프로세스 종료 시 유실 방지
            }

            if (object instanceof CloseRequest(String userId, ..)) {
                closeWriterInternal(userId + "#" + ..);
            }
        }
    } catch (Exception e) {
        log.error("consumeLoop 비정상 종료", e);
    }
}

take()는 큐가 빌 때까지 블로킹한다. poll()처럼 타임아웃을 걸어 주기적으로 루프를 돌게 할 수도 있지만, 데이터가 없을 때 CPU를 낭비하지 않으려면 take()로 블로킹하는 것이 낫다. 배치가 오랫동안 실행되지 않는 시간대에도 스레드가 CPU를 점유하지 않는다.

FailedProduct를 꺼내면, 키로 Writer를 찾거나 새로 생성해 JSON 직렬화 결과를 한 줄로 기록하고 즉시 flush()한다. BufferedWriter는 내부 버퍼가 차야 디스크에 쓰기 때문에, flush() 없이 프로세스가 비정상 종료되면 버퍼에 남은 데이터가 사라진다. 재처리 대상을 보존하는 역할이므로 I/O 횟수보다 데이터 안전을 우선했다.

CloseRequest를 꺼내면 해당 배치의 Writer를 flush/close한다. close 이후 같은 키로 데이터가 다시 들어오면 computeIfAbsent가 Writer를 새로 생성하기 때문에 APPEND 옵션이 이 경우에도 중요하다.

파일 생성 - APPEND 옵션

private BufferedWriter createWriter(String key) {
    try {
        Path dir = Paths.get(FAIL_PATH);
        Files.createDirectories(dir);
        Path file = dir.resolve(key + ".txt");
        return Files.newBufferedWriter(file,
            StandardOpenOption.CREATE,
            StandardOpenOption.APPEND // 재시작 후에도 기존 파일에 이어쓰기
        );
    } catch (IOException e) {
        log.error("[{}] 파일 생성 실패", key);
        return null;
    }
}

APPEND 옵션이 없으면 Files.newBufferedWriter의 기본값인 TRUNCATE_EXISTING이 적용돼 기존 파일 내용이 지워진다. 배치 실행 중에 앱이 재시작되면 이전 실패 데이터가 파일에 남아있는 상태에서 새 실패 데이터가 추가될 수 있는데, APPEND 덕분에 이전 데이터를 덮어쓰지 않고 뒤에 이어쓴다. 스케줄러는 파일 전체를 순서대로 처리하므로 재시작 전후 데이터가 같은 파일에 섞여 있어도 문제없다.

Writer 종료 - prefix 매칭

private void closeWriterInternal(String requestKey) {
    writerMap.entrySet().removeIf(entry -> {
        if (entry.getKey().startsWith(requestKey + "#")) {
            try {
                entry.getValue().flush();
                entry.getValue().close();
            } catch (IOException e) {
                log.error("{} writer 닫기 실패", entry.getKey(), e);
            }
            return true;
        }
        return false;
    });
}

CloseRequest를 큐에 넣은 이유

처음에는 closeWriter()를 직접 호출했다. 그런데 큐에 아직 남아있는 FailedProduct가 처리되기 전에 close가 실행되는 문제가 있었다.

이를 해결하려고 closeRequestIds Set을 두고 consumeLoop에서 FailedProduct 처리 직전에 체크하는 방식을 시도했다. 하지만 이 방식은 마지막 FailedProduct 이후 큐가 비면 take()에서 블로킹 → close 신호가 Set에 있어도 영원히 실행되지 않는 문제가 있었다.

최종 해결책은 CloseRequest를 FailedProduct와 같은 큐에 넣는 것이다. 단일 consumer 스레드가 큐를 순서대로 소비하므로, CloseRequest 이전의 모든 FailedProduct가 반드시 먼저 처리된다.

FailServiceImpl - 재처리 로직

public void retryInsert() {
    List<Path> failFiles = Files.list(failDir)
        .filter(p -> p.getFileName().toString().endsWith(".txt"))
        .toList();

    for (Path failFile : failFiles) {
        String fileName = failFile.getFileName().toString();
        String userId   = extractUserId(fileName);
        ...

        UserInfo user = userDao.findUser(userId, ..);

        try (BufferedReader reader = Files.newBufferedReader(failFile)) {
            String line;
            while ((line = reader.readLine()) != null) {
                Product product = objectMapper.readValue(line, Product.class);
                insertProduct(user, product); // 단건 INSERT
            }
        }

        Files.delete(failFile);
    }
}

왜 단건 INSERT인가

벌크 INSERT가 타임아웃으로 실패했다는 것은 DB에 수천 건을 한 번에 밀어넣는 과정에서 max_statement_time을 초과했다는 의미다. 재처리를 다시 벌크로 하면 같은 이유로 또 실패할 가능성이 있다. 단건 INSERT는 한 건씩 순차 처리하기 때문에 쿼리 하나의 실행 시간이 짧아 타임아웃이 발생하지 않는다. 스케줄러가 배치 부하가 낮은 시간대에 실행되므로 단건이어도 전체 처리 시간은 문제가 되지 않는다.

FailScheduler

@Scheduled(cron = "0 0 16 * * *")
public void retry() {
    failService.retryInsert();
}

정리

핵심은 실패 감지 → 큐 → 파일 → 재처리 흐름을 배치 로직과 완전히 분리한 것이다. DAO 레이어는 실패를 큐에 넣기만 하고, 파일 쓰기와 재처리는 각자 독립된 컴포넌트가 담당한다. 덕분에 재처리 로직이 배치 성능에 영향을 주지 않고, 컴포넌트별로 독립적인 테스트와 교체가 가능하다.

[Java] volatile - 멀티스레드 가시성 문제 트러블슈팅

giraffe_ — Tue, 12 May 2026 00:50:03 +0900

들어가며

독립 큐 + 전용 워커 스레드를 사용하는 서비스에서 종료 신호가 워커 스레드에 전달되지 않는 문제가 발생했다. @PreDestroy에서 running = false를 분명히 썼는데도 워커 스레드는 루프를 계속 돌고 있었다.

private volatile boolean running = true;

해결책은 volatile 한 키워드였지만, 왜 없으면 안 되는지는 설명하기 어려웠다. 이 글은 문제의 원인을 파악하고 올바른 구현에 이르기까지의 과정을 담았다.

1. 문제 발생 - volatile 없이 어떤 일이 벌어지는가

volatile 없이 종료 플래그를 구현하면 어떤 일이 생기는지 코드로 먼저 보자.

// volatile 없음
private boolean running = true;

// 워커 스레드 (Core 1에서 실행)
private void runWorker(String id, BlockingQueue<Runnable> queue) {
    while (running) {  // ← Core 1의 캐시에서 running 읽기
        Runnable task = queue.poll(500, TimeUnit.MILLISECONDS);
        if (task == null) continue;
        task.run();
        Thread.sleep(1000);
    }
    drainQueue(id, queue);
}

// 메인 스레드 (Core 0에서 실행)
@PreDestroy
public void shutdown() {
    running = false;  // ← Core 0의 캐시를 false로 변경
    // 메인 메모리에 언제 반영될지 보장 없음
}

shutdown()이 running = false를 썼음에도 워커 스레드가 루프를 빠져나오지 않는다.

2. 원인 분석 - CPU 캐시와 메모리 가시성

현대 CPU는 메인 메모리(RAM)에 직접 접근하는 대신 L1/L2/L3 캐시를 계층적으로 사용한다. 메인 메모리 접근은 수백 클럭이 걸리지만 L1 캐시는 수 클럭이면 충분하기 때문이다.

Java Memory Model(JMM) 은 성능을 위해 각 스레드가 변수의 로컬 복사본(CPU 캐시 또는 레지스터)을 사용하도록 허용한다. 따라서 한 스레드가 변수를 변경해도 다른 스레드가 그 변경을 언제 볼지 보장하지 않는다.

이것이 가시성(Visibility) 문제다. shutdown()이 running = false를 써도 변경이 메인 메모리에 즉시 flush되지 않을 수 있고, 설령 flush되더라도 Core 1의 캐시가 갱신되지 않으면 워커 스레드는 영원히 running == true를 보게 된다.

3. 해결책 - volatile 선언

private volatile boolean running = true;

volatile을 선언하면 JMM은 두 가지를 보장한다.

3-1. 가시성 보장 (Visibility)

volatile 변수에 대한 쓰기는 즉시 메인 메모리에 flush되고, 읽기는 항상 메인 메모리에서 직접 읽는다. CPU 캐시를 우회하므로 모든 스레드가 최신 값을 본다.

3-2. 명령어 재정렬 방지 (Happens-Before)

JMM은 volatile 쓰기와 읽기 사이에 happens-before 관계를 보장한다.

volatile 변수에 대한 쓰기는 이후 같은 변수를 읽는 모든 작업보다 happens-before 한다.

이 말은 running = false 이전에 수행된 모든 쓰기 작업이 running을 읽는 스레드에도 보장된다는 의미다.

4. 올바른 구현 - 백그라운드 워커 스레드 종료

독립적인 작업 큐와 전용 워커 스레드를 운영하는 구조다.

// volatile 있음
private volatile boolean running = true;  // ← 핵심

// 워커 스레드 (Core 1에서 실행)
private void runWorker(String id, BlockingQueue<Runnable> queue) {
    while (running) {  // ← 메인 메모리에서 매번 읽기
        Runnable task = queue.poll(500, TimeUnit.MILLISECONDS);
        if (task == null) continue;
        task.run();
        Thread.sleep(1000);
    }
    drainQueue(id, queue);  // 잔여 작업 처리
}

// 메인 스레드 (Core 0에서 실행)
@PreDestroy
public void shutdown() {
    running = false;  // ← 메인 메모리에 즉시 반영
    executors.values().forEach(ExecutorService::shutdown);
    // ... awaitTermination
}

쓰는 스레드: @PreDestroy를 호출하는 메인(Spring 컨텍스트) 스레드
읽는 스레드: runWorker()를 실행 중인 워커 스레드들 (id당 1개)

서로 다른 스레드이므로, volatile 없이는 워커 스레드가 running = false를 영원히 못 볼 수도 있다.

5. 주의사항 - volatile이 해결하지 못하는 것

volatile은 가시성과 happens-before를 보장하지만, 복합 연산의 원자성은 보장하지 않는다.

private volatile int count = 0;

// 스레드 A와 B가 동시에
count++;

count++는 실제로 세 단계다: 읽기 → 증가 → 쓰기.

두 스레드가 동시에 읽기 단계를 통과하면 둘 다 같은 값을 읽고, 둘 다 +1을 한 뒤 같은 값을 두 번 쓴다. 결과적으로 증가가 한 번밖에 반영되지 않는다.

이런 경우엔 AtomicInteger를 써야 한다.

private final AtomicInteger count = new AtomicInteger(0);
count.incrementAndGet();  // CAS 연산으로 원자성 보장

참고

Java Language Specification — §17.4 Memory Model
- CPU 캐시와 가시성 문제 - JMM이 스레드별 로컬 복사본을 허용
- volatile 의 두 가지 보장 - 가시성(flush/read 보장)과 happens-before 관계

[DB] READ_UNCOMMITTED에서 DELETE가 타임아웃 나는 이유

giraffe_ — Wed, 6 May 2026 17:04:47 +0900

문제 상황

특정 사용자의 데이터를 일괄 삭제하는 배치에서 두 종류의 타임아웃이 발생했다.

Lock wait timeout exceeded; try restarting transaction   ← 서브쿼리 DELETE 단계
Query execution was interrupted (max_statement_time exceeded)  ← PK 기반 SELECT+DELETE 단계

두 에러는 동시에 발생한 것이 아니다. 서브쿼리 DELETE를 사용할 때 Lock wait timeout이 발생했고, PK 기반 SELECT+DELETE로 전환한 뒤 max_statement_time exceeded가 발생했다. 타임아웃 종류가 바뀐 것 자체가 분석 포인트다.

초기 코드는 서브쿼리 DELETE 구조였다.

DELETE FROM products
WHERE id IN (
    SELECT id FROM (
        SELECT id FROM products
        WHERE user_id = #{userId}
        ORDER BY id
        LIMIT 5000
    ) t
)

처음에는 서브쿼리가 타임아웃의 원인이라고 생각했다. 하지만 쿼리 형태가 아니라 시스템의 구조적 문제에 의해 발생한 충돌이었다.

같은 테이블에 실시간 서비스가 ON DUPLICATE KEY UPDATE 벌크 UPSERT를 지속적으로 실행 중이었다.

실시간 서비스의 락 획득

충돌 원인을 이해하려면 실시간 서비스의 락 획득 방식을 먼저 파악해야 한다.

@Transactional
public void saveProductData(List<Product> productList) {
    sqlSession.insert("productMapper.saveProductData", productList);
}

sqlSession은 MyBatis SqlSessionTemplate으로 Spring 트랜잭션에 자동 참여한다. @Transactional 범위 전체 동안 커넥션과 락이 유지된다.

실제 실행 쿼리는 <foreach> 벌크 INSERT + ON DUPLICATE KEY UPDATE다.

<insert id="saveProductData" parameterType="list">
    INSERT INTO products (user_id, name, code, price, ...)
    VALUES
    <foreach item="p" collection="list" separator=",">
        (#{p.userId}, #{p.name}, #{p.code}, #{p.price}, ...)
    </foreach>
    ON DUPLICATE KEY UPDATE
        name   = IF(status='N', name,   VALUES(name))
      , price  = IF(status='N', price,  VALUES(price))
      , ...
</insert>

ON DUPLICATE KEY UPDATE는 내부적으로 두 경로로 분기한다.

X lock은 INSERT/UPDATE 완료 시점이 아니라 트랜잭션 COMMIT 시점까지 유지된다. N건 벌크라면 X lock이 최대 N개 동시에 쌓인 채로 COMMIT까지 유지된다.

충돌 원인 분석

1. Dirty Read - 미커밋 신규 row

DB 격리 수준이 READ_UNCOMMITTED이므로 배치 SELECT는 아직 커밋되지 않은 row도 읽는다.

실시간 서비스가 신규 row를 INSERT 중인 트랜잭션(미커밋)이 X lock을 보유한 상태일 때, 배치 SELECT는 그 row를 Dirty Read로 읽고 DELETE 대상에 포함시킨다.

격리 수준이 READ_COMMITTED였다면 커밋된 row만 읽히므로 미커밋 row는 애초에 SELECT에 잡히지 않았을 것이다.

READ_UNCOMMITTED이기 때문에 아직 존재하지 않아야 할 row를 읽어서 DELETE까지 시도하게 된 것이다.

2. UPDATE 경로 X lock - 기존 row

실시간 서비스의 UPSERT는 기존 데이터가 있는 경우 UPDATE 경로를 탄다. 이 경우 충돌하는 row는 커밋된 상태다.

기존 데이터가 많을수록 UPDATE 경로 비율이 높아지고, 그만큼 X lock이 많이 걸려 DELETE와의 충돌 가능성이 올라간다.

3. 갭 락(Gap Lock) — 범위 스캔

기존 서브쿼리 DELETE는 쿼리 플래너가 user_id 인덱스 범위 스캔을 선택할 가능성이 높다. 이 과정에서 InnoDB가 Next-Key Lock(record + gap)을 설정한다.

락 종류	대상	설명
Record Lock	레코드 자체	특정 row에 대한 X/S 락
Gap Lock	레코드 사이 간격	해당 간격의 INSERT 차단
Next-Key Lock	레코드 + 앞 간격	Record Lock + Gap Lock 조합 (InnoDB 기본)

INSERT 실행 시 InnoDB는 실제 레코드 락 전에 INSERT INTENTION LOCK을 해당 간격에 건다. INSERT INTENTION LOCK끼리는 호환되지만, 해당 간격에 GAP LOCK이 걸려 있으면 블로킹된다.

해결 과정

1. SELECT+DELETE 분리 + id(PK) 기반 삭제

서브쿼리 DELETE를 SELECT와 DELETE로 분리하고, id(PK)로 삭제 대상을 지정한다.

<select id="selectProductIds" parameterType="map" resultType="long">
    SELECT id FROM products
    WHERE user_id = #{userId}
    LIMIT 5000
</select>

<delete id="deleteProductsBatch" parameterType="list">
    DELETE FROM products
    WHERE id IN
    <foreach collection="list" item="id" open="(" separator="," close=")">#{id}</foreach>
</delete>

이 방식에서 갭 락은 발생하지 않는다. InnoDB는 유니크 인덱스(PK 포함) 단건 조회에서 레코드 락만 걸고 갭 락은 설정하지 않는다. 갭 락은 범위 스캔이나 비고유 인덱스 스캔에서 사이에 새 row가 끼어들 수 없도록 막기 위해 설정하는 것인데, PK 포인트 룩업은 구간을 스캔하지 않기 때문이다.

에러 종류가 바뀌었다. 갭 락은 제거됐지만, Dirty Read와 UPDATE 경로 X lock 충돌은 여전히 남는다. 그런데 이 단계에서 에러 종류가 Lock wait timeout에서 max_statement_time exceeded로 바뀐다.

왜 타임아웃 종류가 바뀌었나

서브쿼리 DELETE는 user_id 범위 스캔 중 GAP LOCK이 첫 번째 충돌 지점에서 즉시 블로킹을 걸었다. 단 한 번의 락 대기가 innodb_lock_wait_timeout을 넘으면서 Lock wait timeout이 발생했다.

서브쿼리 DELETE:
    범위 스캔 → GAP LOCK → 실시간 INSERT와 충돌
    → 단일 대기 → 50초 초과 → Lock wait timeout exceeded

PK 기반 DELETE WHERE id IN (id_1, ..., id_5000)로 바꾸면 갭 락이 사라진다. 하지만 Dirty Read로 읽힌 미커밋 row들이 id 리스트에 포함된 상태이므로, DELETE는 5000개 row에 X lock을 하나씩 획득 시도한다.

실시간 서비스가 각 row를 짧게 잡고 빨리 커밋한다면 개별 락 대기는 40초에 못 미친다. 그러나 5000개 row를 처리하는 동안 짧은 대기가 수십~수백 번 누적되면 statement 전체 실행 시간이 max_statement_time을 초과한다.

PK 기반 DELETE:
    row 1:   락 획득 (즉시)
    row 2:   2초 대기 → 획득
    row 3:   락 획득 (즉시)
    ...
    row 847: 5초 대기 → 획득
    ...
    → 개별 대기는 40초 미만
    → 누적 실행 시간이 max_statement_time 초과
    → Query execution was interrupted (max_statement_time exceeded)

갭 락 제거로 빠른 단일 블로킹은 사라졌지만, Dirty Read row들에 대한 반복 락 시도가 statement 실행 시간 자체를 길게 늘린 것이다.

2. updated_at < baseTime 조건 추가

배치 시작 시점을 baseTime으로 고정하고, SELECT 시 해당 시각 이전 데이터만 조회한다.

<select id="selectProductIds" parameterType="map" resultType="long">
    SELECT id FROM products
    WHERE user_id = #{userId}
    AND updated_at &lt; #{baseTime}
    LIMIT 5000
</select>

String baseTime = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
Map<String, Object> param = new HashMap<>();
param.put("userId", userId);
param.put("baseTime", baseTime);

List<Long> ids;
do {
    ids = sqlSession.selectList("productMapper.selectProductIds", param);
    if (!ids.isEmpty()) {
        sqlSession.delete("productMapper.deleteProductsBatch", ids);
    }
} while (!ids.isEmpty());

Dirty Read (미커밋 신규 row) → 해소

신규 INSERT row의 updated_at은 baseTime 이후다. Dirty Read로 읽혀도 updated_at < baseTime 조건에서 걸러지므로 DELETE 대상에 포함되지 않는다.

UPDATE 경로 X lock (기존 row) → 완전 해소 불가

기존 row는 updated_at < baseTime이므로 SELECT에 포함된다. SELECT와 DELETE 사이 타이밍에 실시간 서비스가 같은 row의 X lock을 획득하면 충돌이 발생한다.

baseTime 필터는 이러한 타이밍 경합을 차단하지 못한다. Dirty Read 케이스는 '읽히면 안 될 row를 읽는' 문제였지만, 이 케이스는 '읽혀야 할 row인데 DELETE 직전에 락이 걸린' 타이밍 문제이기 때문이다.

아직 이 케이스에서 문제가 발생하지 않은 것은 SELECT → DELETE 사이 틈이 수 밀리초로 매우 짧고, INSERT보다 UPDATE 경로가 적게 발생하기 때문으로 보인다. 하지만 트래픽이 늘거나 배치 대상과 실시간 서비스가 겹치는 user_id가 많아지면 언제든 문제가 생길 수 있다.

마치며

이번 트러블슈팅의 핵심은 하나의 타임아웃이 아니라 세 가지 락 충돌 경로가 동시에 작동했다는 점이다.

갭 락은 PK 기반 WHERE id IN (...) 으로 전환해 완전히 제거했고, Dirty Read는 updated_at < baseTime 필터로 DELETE 시도 자체를 막았다. UPDATE 경로 X lock 충돌만이 남는다. 격리 수준 변경, 실행 시간 분리 등 여러 방법이 있지만 현재 시스템 환경에서는 적용할 수 없어 이 기능은 여기서 마무리한다.

[Spring/batch] BlockingQueue와 스레드를 활용한 Telegram 429 Rate Limit 해결

giraffe_ — Mon, 4 May 2026 16:05:45 +0900

문제 상황

스프링 배치 서비스에서 여러 작업 대상을 스레드 풀로 병렬 처리하고, 각 스레드가 완료 후 Telegram으로 배치 결과를 알림하는 기능이 있다.

평소에는 문제가 없었는데, 단기간(1~2초)에 끝나는 배치 대상이 많은 특정 시간대의 배치에서만 아래와 같은 에러가 반복 발생했다.

14:30:00에 46건을 대상으로 배치 시작 후, 순차적으로 Telegram 알림을 발송했다.(비즈니스 로직 수행부터 알림 발송까지 배치 대상 당 1~2초 안에 끝난다.)

그러다가 14:30:33부터 Telegram 알림 발송 에러가 발생했다.

14:30:33  429 Too Many Requests  retry_after: 27
14:30:34  429 Too Many Requests  retry_after: 26
14:30:35  429 Too Many Requests  retry_after: 25

429 Too Many Requests가 반환되며, 응답 본문에 retry_after 값(초)이 포함된다.

상세 로직

여러 작업을 동시에 처리하기 위해 스레드 풀을 사용한다. 스레드 풀 안에는 worker-1, worker-2.. 다수의 워커 스레드가 존재하고, 각 스레드는 독립적으로 배치 작업을 처리한다.

작업이 끝나면 결과에 따라 알림 경로가 나뉜다. 성공했을 때는 sendSuccess()를 통해 채팅방 A로, 실패했을 때는 sendFailure()를 통해 채팅방 B로 Telegram 알림이 전송된다. 두 워커가 병렬로 실행되기 때문에 이 알림들은 거의 동시에 발송된다.

배치 작업 대상이 많아질수록 두 워커는 빠르게 작업을 완료하고 연속적으로 알림을 쏟아낸다. 각 채팅방이 받는 메시지 건수가 쌓이다 보면 어느 순간 Telegram의 전송량 제한을 초과하게 되고, 그때부터 429 Too Many Requests 에러가 반복해서 발생한다.

원인 분석

Telegram Bot Rate Limit 정책

Telegram Bot API는 과도한 메시지 전송을 막기 위해 Rate Limit 정책을 두고 있다.

텔레그램 봇 공식 문서 - https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this

상황	제한
같은 채팅방	초당 1건 권장
그룹 채팅	분당 최대 20건
전체 (모든 채팅방 합산)	초당 약 30건

이 로직에서 핵심이 되는 규칙은 같은 채팅방에 분당 최대 20건이다. 채팅방 전체 합산이 아니라 채팅방 하나를 기준으로 카운팅한다.

채팅방이 A, B로 분리되어 있으니 괜찮지 않을까 싶지만, 실제로는 그렇지 않았다. 이 배치 서비스에서 같은 채팅방에 메시지가 쌓이는 경로가 두 가지 있다.

1.같은 채팅방으로 향하는 다른 배치 작업이 동시에 실행되는 경우

채팅방 A가 성공 알림방이라면, 이 서비스뿐 아니라 다른 배치 타입의 성공 알림도 같은 채팅방 A로 전송될 수 있다. 배치가 여러 개 겹쳐 실행되는 시간대에는 채팅방 A로 향하는 메시지가 여러 배치에서 동시에 몰려들고, 합산 건수가 20건을 넘기게 된다.

2. 배치 작업 대상 자체가 많은 경우

작업 대상이 수십 개라면 두 워커는 작업을 마칠 때마다 계속 알림을 전송한다. 워커가 빠르게 작업을 완료할수록 알림도 빠르게 쌓이고, 60초 안에 같은 채팅방으로 20건 이상이 누적되면 그 순간 429가 발생한다.

슬라이딩 윈도우

Telegram은 슬라이딩 윈도우 방식으로 제한을 적용한다.

배치가 시작되면 병렬 워커들이 작업을 마칠 때마다 Telegram 알림을 연속으로 전송한다. Telegram은 이 전송량을 슬라이딩 윈도우 방식으로 측정하는데, '지금 이 순간부터 과거 60초' 안에 들어온 메시지를 실시간으로 카운팅한다.

14:30:00에 배치가 시작된 후 33초 만에 메시지가 20건을 넘긴다. 그 순간 429가 반환되고, 응답에 담긴 retry_after 값이 매초 1씩 줄어드는 이유도 여기에 있다. 고정 윈도우였다면 14:31:00이 되는 순간 카운터가 리셋되겠지만, 슬라이딩 윈도우는 오래된 메시지가 60초 밖으로 밀려나야 비로소 한 건씩 여유가 생기기 때문이다. 14:31:00이 되어서야 retry_after가 0이 되고 전송이 재개된다.

해결책 후보

세 가지 방법을 검토했다.

방식	동시 발송 방지	워커 스레드 블록
sleep만 추가	X	X
synchronized + sleep	O	O
단일 BlockingQueue + 전용 스레드	O	X (비동기)

1. Thread.sleep() 추가

처음 떠오른 해결책은 메서드에 Thread.sleep()을 추가하는 것이었다.

public void sendSuccess(...) {
    Thread.sleep(1000); // 각 스레드가 1초 잠든 뒤
    telegramProcess.send(message); // 동시에 여기 도달 → 여전히 동시 발송
}

만약 10개 스레드가 동시에 sleep(1000)을 호출하면, 1초 후에 동시에 깨어나 동시에 전송한다. sleep은 각 스레드의 실행을 지연시킬 뿐, 전송 순서를 직렬화하지 않는다.

2. synchronized + sleep

@Service
public class TelegramNotificationService {
    private final Object lock = new Object();
    private long lastSentMs = 0;

    public void send(String chatId, String token, String message) {
        synchronized (lock) {
            long elapsed = System.currentTimeMillis() - lastSentMs;
            if (elapsed < 3000) {
                Thread.sleep(3000 - elapsed);
            }
            TelegramApi.send(chatId, token, message);
            lastSentMs = System.currentTimeMillis();
        }
    }
}

synchronized로 진입을 직렬화하고, 마지막 전송 이후 3초가 지나지 않았으면 나머지 시간만큼 sleep한다.

동시 발송은 막지만 워커 스레드가 synchronized 블록 안에서 발송 완료까지 블록된다. 처리 대상이 많을수록 마지막 스레드의 대기 시간이 길어진다.

3. BlockingQueue + 전용 스레드

@Service
public class TelegramNotificationService {
    private final BlockingQueue<Runnable> queue = new LinkedBlockingQueue<>(500);

    @PostConstruct
    public void startSender() {
        Thread.ofVirtual().name("telegram-sender").start(() -> {
            while (true) {
                try {
                    Runnable task = queue.take();
                    task.run();
                    Thread.sleep(3000);
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                    break;
                }
            }
        });
    }

    public void send(String chatId, String token, String message) {
        queue.offer(() -> TelegramApi.send(chatId, token, message));
    }
}

워커 스레드는 queue.offer()만 호출하고 즉시 리턴한다. 실제 전송은 전용 스레드 하나가 3초 간격으로 처리한다. 전체 전송량이 최대 20건/분(60초 ÷ 3초)이 되므로, 어느 채팅방으로 보내든 Rate Limit에 걸리지 않는다.

단일 큐의 한계 - 채팅방별 독립 큐로

단일 큐 방식은 Rate Limit 문제를 해결하지만, 채팅방이 여러 개일 때 한 가지 고민이 생긴다. (실제로 채팅방이 2개뿐 아니라 더 있다.)

단일 큐에서는 채팅방 A와 채팅방 B의 메시지가 같은 줄을 서게 된다. 채팅방 A에 메시지가 몰리면, 채팅방 B의 메시지는 채팅방 A의 메시지가 빠져나갈 때까지 대기해야 한다. 전체 처리량도 전 채팅방 합산 20건/분에 묶인다.

비교 항목	단일 큐	독립 큐
채팅방 간 간섭	있음	없음
채팅방별 최대 처리량	전체 합산 20건/분	채팅방당 20건/분

채팅방 수가 적고 알림 빈도가 낮다면 단일 큐로도 충분하다. 하지만 채팅방 간 간섭 없이 각 채팅방이 독립적으로 최대 처리량을 활용하고 싶다면, 채팅방별 독립 큐 + 채팅방당 전용 스레드로 가는 것이 적합하다는 생각이 들었다.

최종 구현

채팅방(chatId) 단위로 큐와 전용 발송 스레드를 관리한다. 같은 채팅방으로 향하는 메시지끼리만 직렬화되고, 서로 다른 채팅방은 독립적으로 동작한다.

// 채팅방별 큐
ConcurrentHashMap<String, BlockingQueue<Runnable>> roomQueues = new ConcurrentHashMap<>();
// 채팅방별 스레드
ConcurrentHashMap<String, ExecutorService> roomExecutors = new ConcurrentHashMap<>();

메시지 전송 로직

send() 호출
  → computeIfAbsent: 첫 호출이면 큐 + 가상 스레드 생성
  → queue.offer(task): 큐에 적재 후 즉시 리턴 (워커 스레드 블록 없음)
  → 가상 스레드: poll(500ms) → task.run() → sleep(3000) → ...

Graceful Shutdown 추가

애플리케이션이 갑작스럽게 종료되는 상황에서도 큐에 쌓인 메시지가 유실되지 않도록 Graceful Shutdown을 추가했다.

boolean running 플래그로 루프를 자연 종료시킨다.

@PreDestroy shutdown()
  → running = false
  → poll(500ms) 타임아웃 → while 루프 탈출
  → drainQueue(): 남은 메시지 순차 전송
  → awaitTermination(): 드레인 완료 대기

최종 구현 코드

@Slf4j
@Service
public class TelegramNotificationService {

    private volatile boolean running = true;
    private final ConcurrentHashMap<String, BlockingQueue<Runnable>> roomQueues = new ConcurrentHashMap<>();
    private final ConcurrentHashMap<String, ExecutorService> roomExecutors = new ConcurrentHashMap<>();

    public void send(String chatId, String token, String message) {
        BlockingQueue<Runnable> queue = roomQueues.computeIfAbsent(chatId, id -> {
            LinkedBlockingQueue<Runnable> q = new LinkedBlockingQueue<>(500);
            ExecutorService executor = Executors.newSingleThreadExecutor(
                    Thread.ofVirtual().name("telegram-" + id).factory()
            );
            executor.submit(() -> runSender(id, q));
            roomExecutors.put(id, executor);
            return q;
        });
        queue.offer(() -> TelegramApi.send(chatId, token, message));
    }

    private void runSender(String chatId, BlockingQueue<Runnable> queue) {
        while (running) {
            try {
                Runnable task = queue.poll(500, TimeUnit.MILLISECONDS);
                if (task == null) continue;
                task.run();
                Thread.sleep(3000);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                break;
            } catch (Exception e) {
                log.error("텔레그램 메시지 전송 실패 [chatId={}]", chatId, e);
            }
        }
        drainQueue(chatId, queue);
    }

    private void drainQueue(String chatId, BlockingQueue<Runnable> queue) {
        log.info("텔레그램 잔여 메시지 전송 [chatId={}, count={}]", chatId, queue.size());
        Runnable task;
        while ((task = queue.poll()) != null) {
            try {
                task.run();
            } catch (Exception e) {
                log.error("종료 중 메시지 전송 실패 [chatId={}]", chatId, e);
            }
        }
    }

    @PreDestroy
    public void shutdown() {
        log.info("텔레그램 발송 스레드 종료 시작 - 잔여 메시지 전송 중...");
        running = false;
        roomExecutors.values().forEach(ExecutorService::shutdown);
        roomExecutors.forEach((id, executor) -> {
            try {
                if (!executor.awaitTermination(10, TimeUnit.MINUTES)) {
                    log.warn("텔레그램 발송 타임아웃 [chatId={}]", id);
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        });
        log.info("텔레그램 발송 스레드 종료 완료");
    }
}

종료 테스트 로그

[Obsidian] Notion에서 Obsidian으로 문서 관리 전환 후기

giraffe_ — Tue, 21 Apr 2026 22:40:44 +0900

노션과 함께한 시간들

이전에 취업 준비를 시작하면서 노션을 처음 썼다. 자기소개서, 지원 현황 트래킹, 면접 기록까지. 이후에는 사이드 프로젝트 기획서, 회사 업무 메모, 일상 기록까지 노션 하나로 다 해결했다. 그만큼 노션은 쓰기 편하고 예쁘다. 페이지 공유도 링크 하나면 끝이고, 팀원과 협업하기도 좋다. 처음 접하는 사람도 금방 적응할 수 있는 낮은 진입장벽이 가장 큰 장점이었다.

그러다 한 번 옵시디언을 시도해봤다. 결론은 포기. 플러그인 설치에 볼트 구조 잡는 것도 낯설었고, 노션처럼 블록 드래그로 바로 레이아웃을 잡을 수 없다는 것도 불편했다. 나는 개발자라 마크다운에 익숙하지만 마크다운으로만 작성해야 한다는 것도 당시엔 번거롭게 느껴졌다.

갈아탄 이유

노션 무료 플랜의 블록 제한

노션 무료 플랜에는 블록 수 제한이 있다. 처음엔 크게 신경 안 썼는데, 기록이 쌓일수록 제법 압박이 온다. 유료 전환을 고민하다가 '그러면 차라리 다른 걸 써보자'는 생각이 들었다.

가끔씩 터지는 서버 장애

노션은 클라우드 기반이라, 서버에 문제가 생기면 문서를 아예 열 수 없다. 대부분은 짧게 지나가지만, 하필 급하게 뭔가를 찾아봐야 할 때 이런 일이 생기면 꽤 당황스럽다. 나같은 경우에는 노션에 업무 관련된 내용을 모두 정리했었다. 노션 서버에 문제가 생기면 일이 어려울 것이다. 로컬에 데이터가 없다는 사실이 새삼 불안하게 느껴졌다.

AI 시대, 마크다운이 유리하다

Claude Code를 쓰기 시작하면서 인식이 완전히 바뀌었다. 옵시디언 문서는 전부 .md 파일이라 LLM이 바로 읽고 편집할 수 있다. 문서 정리를 Claude Code에게 시키고, 정리된 문서를 기반으로 다른 문서를 작성하거나 개발 작업의 컨텍스트로 활용할 수 있다. 개발 관련 기록을 옵시디언으로 옮기고 나서 이 부분의 효율이 확실히 올라갔다.

옵시디언 쓰면서 좋은 점

마크다운 기반이라 LLM 활용이 쉽다

앞서 언급했지만, 이게 지금 가장 큰 장점이다. 회사에서 프로젝트 정리, 내가 개발한 기능 기록, 트러블슈팅 정리, 개인적인 개발 공부 등을 옵시디언에 쌓아두면 Claude Code를 통해 재료로 바로 쓸 수 있다. 노션 문서는 API를 따로 연동해야 하거나 복붙이 필요한 반면, 옵시디언은 파일 경로만 넘기면 된다.

PARA 기법으로 구조 잡기

Project: 현재 진행 중인 작업들 (사이드 프로젝트, 블로그 초안 등)
Area: 지속적으로 관리하는 영역 (커리어, 학습 등)
Resource: 나중에 참고할 자료들
Archive: 완료되었거나 더 이상 활성화하지 않는 것들

이 구조를 잡고 나니 어디에 뭘 써야 할지 고민이 줄었다. 노션에서는 페이지를 어디에 넣어야 할지 항상 애매했는데, PARA는 기준이 명확해서 좋다.

그래프 뷰

내 옵시디언 그래프 뷰

문서 간 링크를 걸어두면 그래프 뷰에서 시각적으로 연결 관계를 볼 수 있다. 처음엔 "이게 실용적인가?" 싶었는데, 기록이 쌓일수록 내가 어떤 주제에 집중하고 있는지, 어떤 개념들이 연결되어 있는지 한눈에 파악할 수 있어서 유용하다.

아쉬운 점

동기화가 번거롭다

로컬 저장소라는 특성상, 여러 기기에서 쓰려면 동기화를 직접 해야 한다. iCoud 구글드라이브 등이 있는데 나는 GitHub에 백업하는 방식을 선택했다. 회사 컴퓨터와 개인 노트북에서 git pull / git push를 하면서 쓰고 있다. 물론 직접할 필요없고 옵시디언에 Git 플러그인이 있다. 습관이 들면 크게 불편하지는 않은데, 처음엔 세팅하고 매번 push & pull을 하는 것이 좀 귀찮다.

모바일 동기화는 사실상 유료

옵시디언 공식 동기화 서비스인 Obsidian Sync는 유료다. 핸드폰에서 바로 접근하고 싶을 때 이 부분이 아쉽다. GitHub 연동으로 모바일에서 읽는 방법도 있긴 한데 가볍게 열람용으로만 좋다. 편하게 편집까지 하려면 결국 Obsidian Sync를 써야 한다.

처음 세팅이 어렵다

내 옵시디언 폴더 구조

볼트 구조, 플러그인 선택, 테마 등 초기 설정이 생각보다 손이 간다. 노션처럼 켜자마자 쓸 수 있는 환경이 아니다. 다만 한 번 자기 스타일에 맞게 세팅해두면 그 이후엔 꽤 편하다.

결론

노션을 완전히 버린 건 아니다. 팀 협업이나 외부 공유가 필요한 경우에는 여전히 노션이 낫다. 하지만 개인 문서 관리, 특히 개발 관련 기록을 쌓고 LLM과 함께 활용하는 용도로는 옵시디언이 훨씬 유리하다.

진입장벽이 있는 건 맞다. 나도 한 번 포기했다. 그런데 Claude Code를 쓰기 시작하면서 마크다운 기반의 로컬 파일이 얼마나 강력한지 실감하게 됐고, 지금은 잘 쓰고 있다. 도구 자체보다 어떻게 쓸지를 먼저 고민하는 게 맞겠지만, 옵시디언은 그 방향이 맞는 사람에게는 노션보다 훨씬 좋은 선택지가 될 수 있다.

[ClickHouse] Distributed 테이블 - DROP PARTITION이 왜 일부 데이터만 지워질까?

giraffe_ — Thu, 2 Apr 2026 22:46:49 +0900

ClickHouse 클러스터를 처음 사용하다 보면 당황스럽다.

분명히 특정 날짜 데이터를 삭제했는데, 조회해보면 데이터가 여전히 남아있다. 분명 DROP PARTITION을 실행했는데. 알고 보면 삭제된 건 클러스터 전체가 아니라 일부 Shard의 데이터뿐이다.

이 글에서는 왜 이런 일이 생기는지, 그리고 어떻게 해야 클러스터 전체에 올바르게 적용할 수 있는지 정리한다.

배경: Distributed 테이블은 라우터다

앞선 글에서 다뤘지만 다시 짚고 넘어가자.

ClickHouse 클러스터에서 테이블은 두 벌이다.

default.user_events          ← Distributed 테이블 (라우터, 데이터 없음)
local.user_events_local      ← 로컬 테이블 (실제 데이터 저장)

https://clickhouse.com/docs/assets/ideal-img/shards_replicas_01.f8da341.2048.png

애플리케이션은 보통 default.user_events (Distributed 테이블)만 바라본다. SELECT, INSERT 모두 여기로 날리면 내부적으로 각 Shard로 분산된다.

문제는 DDL 동작이 SELECT/INSERT와 다르다는 점이다.

무슨 일이 일어나는가?

Distributed 테이블에서 DROP PARTITION을 실행하면 어떻게 될까?

-- Distributed 테이블에서 실행
ALTER TABLE default.user_events
DROP PARTITION '20260318';

직관적으로는 클러스터 전체에서 해당 날짜 데이터가 삭제될 것 같다.

하지만 실제로는 쿼리를 수신한 노드 하나의 로컬 데이터만 삭제된다.

클러스터 구성
├── Shard 1 (서버 A, B)
└── Shard 2 (서버 C)

ALTER TABLE default.user_events DROP PARTITION '20260318'
→ 쿼리가 서버 A로 접속된 경우: 서버 A의 로컬 데이터만 삭제
→ 서버 C의 데이터는 그대로 남음

조회해보면 데이터가 여전히 보인다. Distributed 테이블은 모든 Shard를 합쳐서 보여주기 때문에, Shard 2의 데이터가 남아있으면 삭제가 안 된 것처럼 보인다.

왜 이렇게 동작하나?

Distributed 테이블은 SELECT/INSERT는 각 Shard에 분산시키지만, DDL은 분산시키지 않는다.

ClickHouse 공식 문서에도 명시되어 있다.

Distributed table does not store any data itself. It only routes queries to remote servers.
DDL queries (like ALTER) are applied only to the current server.

즉 Distributed 테이블에서 ALTER를 실행하면 해당 서버의 로컬 테이블에만 적용된다. 다른 Shard로 전파되지 않는다.

올바른 방법: 로컬 테이블 + ON CLUSTER

해결책은 두 가지다.

방법 1: ON CLUSTER 사용 (권장)

로컬 테이블을 직접 지정하되, ON CLUSTER 구문을 붙이면 ClickHouse가 ZooKeeper를 통해 클러스터 내 모든 노드에 자동으로 DDL을 배포한다.

-- 올바른 방법: 로컬 테이블 + ON CLUSTER
ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DROP PARTITION '20260318';

한 번의 쿼리로 서버 A, B, C 모두에서 해당 파티션이 삭제된다.

방법 2: 각 노드에 직접 접속해서 실행

ON CLUSTER 없이 각 Shard 서버에 직접 접속해서 로컬 테이블에 실행하는 방법도 있다.

-- 서버 A에 접속해서 실행
ALTER TABLE local.user_events_local DROP PARTITION '20260318';

-- 서버 C에 접속해서 실행
ALTER TABLE local.user_events_local DROP PARTITION '20260318';

동일한 결과지만, 서버가 늘어날수록 번거롭고 실수할 여지가 생긴다. ON CLUSTER를 쓰는 게 훨씬 낫다.

정리

실행 대상	ON CLUSTER	결과
Distributed 테이블	X	쿼리 수신 노드 1개만 적용
로컬 테이블	X	해당 노드 1개만 적용
로컬 테이블	O	클러스터 전체 적용

Distributed 테이블은 SELECT/INSERT만 분산시킨다. DDL은 로컬 테이블 + ON CLUSTER로 실행해야 한다.

덧붙임: Replica 동기화는 자동이다

ON CLUSTER로 실행하면 각 Shard의 Primary 노드에 DDL이 전달된다. 그러면 Replica는 어떻게 되나?

Replica 간 동기화는 ZooKeeper가 담당한다. Primary에 DDL이 적용되면 ZooKeeper를 통해 같은 Shard의 Replica에 자동으로 반영된다. 별도로 Replica 서버에 접속해서 실행할 필요가 없다.

ALTER TABLE local.user_events_local ON CLUSTER my_cluster DROP PARTITION '20260318'
    │
    ├── Shard 1 - 서버 A (Primary) → ZooKeeper → 서버 B (Replica) 자동 반영
    └── Shard 2 - 서버 C → (Replica 없으면 바로 완료)

마치며

처음엔 "Distributed 테이블에 쿼리 날리면 다 되는 거 아니야?"라고 생각했는데, DDL만큼은 예외라는 걸 직접 겪어보고 나서야 제대로 이해했다.

SELECT/INSERT와 DDL의 동작 방식이 다르다는 점, ON CLUSTER가 어떤 역할을 하는지를 이해하면 ClickHouse 클러스터 운영에서 의도치 않은 실수를 줄일 수 있다.

참고

[ClickHouse] 데이터 삭제 - ALTER DELETE vs DROP PARTITION

giraffe_ — Tue, 31 Mar 2026 22:54:45 +0900

ClickHouse에서 잘못 적재된 데이터를 지워야 하는 상황이 생겼다.

MySQL이라면 그냥 DELETE FROM ... WHERE ... 날리면 끝인데, ClickHouse 클러스터 환경에서는 그게 안 된다. DELETE FROM 문법 자체는 존재하지만, ON CLUSTER를 지원하지 않아 클러스터 전체에 적용되지 않는다. 클러스터 환경에서는 반드시 ALTER TABLE ... DELETE나 DROP PARTITION을 써야 한다.

이 글은 클러스터 환경을 전제로 데이터를 삭제하는 두 가지 방법인 ALTER DELETE와 DROP PARTITION을 비교하고, 각각 언제 쓰는 게 맞는지 정리한다.

방법 선택의 기준은 데이터 양이 아니라 삭제 패턴이다. 작은 양이라도 ALTER DELETE는 파트 재작성이 필요한 구조라 느리고, DROP PARTITION은 용량과 무관하게 빠르다. 파티션 단위로 통째로 교체할 수 있는 상황인가가 기준이다.

ClickHouse에서 DELETE가 느린 이유

https://clickhouse.com/docs/assets/ideal-img/part.323bb36.2048.png

ClickHouse는 데이터를 파트(Part) 단위로 디스크에 저장한다. INSERT가 들어올 때마다 새로운 파트가 생성되고, 백그라운드에서 주기적으로 파트들을 병합(Merge)한다.

이 구조 덕분에 대용량 INSERT와 SELECT가 빠르지만, 반대로 특정 행만 골라서 삭제하는 건 비용이 많이 드는 작업이다. 해당 파트 전체를 읽어서 조건에 맞는 행을 제외한 뒤 새 파트로 다시 써야 하기 때문이다.

이게 바로 ClickHouse의 삭제 방식인 Mutation이다.

방법 1: ALTER DELETE (Mutation)

ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DELETE WHERE event_date = '2026-03-18';

동작 방식

https://clickhouse.com/uploads/mutation_01_24b8cb7f88.png

삭제 작업이 Mutation 큐에 등록되고, 백그라운드에서 비동기로 처리된다. 대상 파트를 디스크에서 읽어 조건에 해당하는 행을 제외한 뒤 새 파트로 재작성한다.

기본값은 비동기라 쿼리가 바로 반환되지만, 삭제가 완전히 끝났다는 보장이 없다. 모든 Replica에서 완료될 때까지 기다리려면 mutations_sync 설정을 추가한다.

ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DELETE WHERE event_date = '2026-03-18'
SETTINGS mutations_sync = 2;  -- 0: 비동기(기본), 1: 현재 서버 완료 대기, 2: 모든 Replica 완료 대기

특징

조건부 삭제 가능 : WHERE 절로 원하는 행만 정확히 제거할 수 있다.
느리고 높은 I/O 비용 : 파트 전체를 재작성하기 때문에 느리다.
ON CLUSTER 지원 : 각 Shard로 자동 전파된다. 클러스터 환경에서 조건부 삭제가 필요하다면 이 방법만 가능하다.

방법 2: DROP PARTITION

-- 반드시 로컬 테이블 + ON CLUSTER 조합으로 실행
ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DROP PARTITION '20260318';

동작 방식

https://clickhouse.com/uploads/partition_delete_3ee4669374.png

파티션을 비활성 상태로 표시하고 약 10분 후 완전히 삭제한다. 파트를 읽거나 재작성하지 않고 통째로 버리기 때문에 매우 빠르다. 쿼리 반환 시점에는 이미 해당 파티션이 조회에서 제외되므로 체감상 즉시 삭제처럼 동작한다.

특징

빠르고 낮은 I/O 비용
파티션 단위로만 삭제 가능 : 조건부 삭제 불가. 파티션 키 단위로만 끊어서 지울 수 있다.
Distributed 테이블에서 실행하면 안 됨 : 반드시 로컬 테이블 + ON CLUSTER 조합으로 실행해야 한다.

비교

항목	ALTER DELETE	DROP PARTITION
속도	느림	빠름
I/O	높음	낮음
삭제 단위	행 단위 (조건부)	파티션 단위
`ON CLUSTER` 지원	지원	로컬 테이블에서만
Distributed 테이블 실행	자동 전파	한 노드에만 적용
즉시 반영	비동기 (기본)	비활성 즉시 / 실제 삭제 ~10분 후
적합한 경우	특정 조건의 일부 행 삭제	날짜 단위 전체 재처리

언제 뭘 써야 하나?

DROP PARTITION을 쓰는 경우

테이블 파티션이 날짜 단위로 나뉘어 있고, 특정 날짜 데이터를 통째로 다시 적재해야 할 때 적합하다.

예를 들어 배치 잡이 특정 날짜에 잘못된 데이터를 적재했고, 해당 날짜 전체를 지우고 다시 넣어야 하는 상황이다. 데이터 양에 상관없이 빠르고, 지우고 다시 넣는 패턴이 가장 깔끔하다.

-- 1. 잘못된 파티션 삭제
ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DROP PARTITION '20260318';

-- 2. 올바른 데이터 재적재
INSERT INTO default.user_events SELECT ...

ALTER DELETE를 쓰는 경우

파티션 경계와 무관하게 특정 조건의 행만 골라서 지워야 할 때 사용한다. 여러 파티션에 걸쳐있는 특정 조건의 데이터를 지워야 하거나, 파티션 단위로 끊기 어려운 경우다. 단, 느리다는 점을 감수해야 한다.

-- 특정 사용자의 이벤트 데이터만 삭제
ALTER TABLE local.user_events_local ON CLUSTER my_cluster
DELETE WHERE user_id = 12345
SETTINGS mutations_sync = 2;

참고로 DELETE FROM table WHERE ... 문법은 클러스터 환경에서 쓸 수 없다. ON CLUSTER를 지원하지 않기 때문에 단일 노드에만 적용된다. 클러스터 환경에서는 반드시 ALTER TABLE ... DELETE ON CLUSTER 형태로 실행해야 한다.

정리

특정 날짜(파티션) 데이터를 통째로 재처리해야 한다 → DROP PARTITION. 데이터 양에 상관없이 빠르다.
파티션 경계와 무관하게 특정 조건의 행만 골라서 지워야 한다 → ALTER DELETE ON CLUSTER. 느린 건 감수해야 한다.
소량 row 삭제가 잦다 → ClickHouse 자체가 맞지 않는다.

마치며

ClickHouse에서 데이터를 지우는 건 MySQL처럼 가볍지 않다. 특히 클러스터 환경에서는 DELETE FROM 같은 편의 문법도 쓸 수 없다. 그래서 처음부터 "잘못 들어오면 어떻게 고칠 것인가"를 설계 단계에서 함께 고려하는 게 좋다.

파티션을 잘 설계해두면 재처리가 필요할 때 DROP PARTITION으로 빠르게 처리할 수 있다. 반대로 파티션 설계가 잘못되면 매번 느린 ALTER DELETE에 의존하게 된다.

결국 보정 방식의 선택은 테이블 설계에서 이미 결정된다고 할 수 있다.

참고

https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse

Handling Updates and Deletes in ClickHouse

With the recent addition of Lightweight Deletes, read about the latest best practices for handling updates and deletes in ClickHouse.

clickhouse.com