Suhwanc

Flink CDC는 어떻게 스냅샷을 병렬로 읽을까?

suhwanc — Sun, 12 Apr 2026 16:44:49 +0900

CDC 작업을 수행할 때 Flink CDC 라이브러리를 사용하면 얻게되는 장점은 parallelism을 2이상으로 높일 수 있다는 것입니다.

반면 Debezium 기반 Kafka Connect는 단일 태스크로만 동작하기 때문에 병렬성(tasks.max)가 1로 고정되는 단점이 존재합니다.

그런데 문득 Flink CDC도 내부적으로 Debezium을 사용하는데 왜 Flink CDC는 병렬 소싱이 가능하고, Kafka Connect는 불가능한지 구조적인 차이가 궁금해 조사해보았습니다.

결론부터 말하면, 차이의 핵심은 Debezium 자체가 아니라 그 위에 올라가는 실행 프레임워크(Kafka Connect vs Flink)의 아키텍처에 있습니다.

Debezium 기반 Kafka Connect - 병렬성이 1인 이유

Kafka Connect의 태스크 모델

Kafka Connect는 Connector와 Task라는 두 가지 개념으로 동작합니다. Connector가 설정을 관리하고, 실제 데이터를 읽는 건 Task입니다. 일반적인 Source Connector(예: JDBC Source)는 tasks.max를 높여서 여러 태스크를 병렬로 실행할 수 있습니다.

그런데 Debezium의 CDC 커넥터는 tasks.max=1로 고정됩니다. MySQL, PostgreSQL, SQL Server 할 것 없이 모두 단일 태스크입니다.

단일 태스크일 수밖에 없는 이유

이유는 CDC의 근본적인 메커니즘에 있습니다.

DB	CDC 메커니즘	제약
MySQL	Binlog	하나의 binlog 스트림은 순차적이며, 읽기 위치(offset)가 단일
PostgreSQL	Replication Slot	하나의 슬롯은 동시에 하나의 컨슈머만 사용 가능
SQL Server	CT(Change Tracking)	변경 캡처 인스턴스가 단일 읽기 지점을 유지

The MySQL connector always uses a single task and therefore does not use this value. — Confluent Documentation

핵심은 데이터베이스의 변경 로그(binlog, WAL 등)는 본질적으로 단일 스트림이라는 것입니다. 하나의 파일에 순서대로 기록되는 로그를 여러 태스크가 나눠 읽으면, 이벤트 순서가 보장되지 않습니다. Debezium은 이 순서 보장을 위해 단일 태스크를 강제합니다.

스냅샷 단계도 마찬가지

"변경 로그는 단일 스트림이니까 그렇다 치고, 스냅샷은 병렬로 할 수 있지 않을까?"라고 생각할 수 있습니다.

하지만 Debezium의 Kafka Connect 구현에서는 스냅샷과 binlog 읽기가 하나의 태스크 안에서 순차적으로 이루어집니다. 스냅샷 완료 후 binlog 읽기로 전환하는 과정에서 정확한 오프셋을 넘겨야 하기 때문에, 이 둘을 분리하기 어려운 구조입니다.

Debezium에서 snapshot.max.threads 설정을 통해 여러 테이블에 대한 병렬 스냅샷은 지원하지만, 하나의 테이블을 여러 태스크로 쪼개서 읽는 것은 불가능합니다.

Flink CDC: 같은 Debezium인데 어떻게 병렬로?

Flink CDC와 Debezium의 관계

Flink CDC는 Debezium을 라이브러리(Embedded Engine) 형태로 사용합니다.

Embedded Engine이란 Debezium이 제공하는 별도 API로 Kafka Connect 없이, 아무 Java 애플리케이션 안에서 Debezium의 CDC 기능만 꺼내 쓸 수 있는 옵션을 의미합니다.

따라서 Flink CDC의 내부 코드를 보면 단순히 Debezium 의존성을 추가한 것이 아니라, binlog 추출 같은 Debezium의 CDC 핵심 로직을 추출해 Flink 코드 위에 올린 형태로 이루어져 있습니다. 참고

FLIP-27 Source API: 병렬 읽기의 기반

Flink CDC 2.0부터는 Flink의 FLIP-27 Source API (FLINK-10740)를 기반으로 동작합니다. 이 API의 핵심은 두 가지 역할의 분리입니다:

역할	구현 클래스	하는 일
SplitEnumerator	`MySqlSourceEnumerator`	테이블을 chunk로 분할하고, 각 SourceReader에 할당
SourceReader	`MySqlSourceReader`	할당받은 chunk를 실제로 읽음 (병렬 실행)

SplitEnumerator는 JobManager에서 실행되고, SourceReader는 TaskManager에서 parallelism 수만큼 실행됩니다. 이 분리 덕분에 "무엇을 읽을지 결정하는 것"과 "실제로 읽는 것"을 독립적으로 스케일링할 수 있습니다.

실제로 MySqlSource.java의 클래스 Javadoc을 보면, 이 세 가지 특성이 명시되어 있습니다:

The MySQL CDC Source based on FLIP-27 and Watermark Signal Algorithm which supports parallel reading snapshot of table and then continue to capture data change from binlog.

The source supports parallel capturing table change.

The source supports checkpoint in split level when read snapshot data.

The source doesn't need apply any lock of MySQL.

이번에 조사하면서 알게된 사실인데 스냅샷 과정에서 chunk 단위로 체크포인트를 찍는다고 하는건 조금 새로웠습니다.

Incremental Snapshot: 테이블을 Chunk로 쪼개기

Flink CDC는 라이브러리 버전 2.0부터 Incremental Snapshot 알고리즘을 통해 병렬 소싱을 지원하게 되었습니다.

원리는 이전에 제 블로그 글에서 언급한 Netflix의 DBLog 논문 기반의 알고리즘인데요, 다음과 같이 동작합니다.

1단계: Chunk 분할

ChunkSplitter가 테이블의 Chunk Key 범위를 기준으로 데이터를 여러 chunk로 나눕니다. (Chunk Key는 PK가 될수도 있고, 따로 지정할 수도 있습니다)

이 인터페이스의 핵심 메서드는 아래과 같습니다.

/** Generates all snapshot splits (chunks) for the give data collection. */
Collection<SnapshotSplit> generateSplits(TableId tableId) throws Exception;

MySQL의 경우 MySqlChunkSplitter가 이를 구현합니다.

예시: users 테이블 (PK: id, 1000만 건)

Chunk 1: id [1, 100000)
Chunk 2: id [100000, 200000)
Chunk 3: id [200000, 300000)
...
Chunk 100: id [9900000, 10000000]

chunk 크기는 scan.incremental.snapshot.chunk.size (기본 8,096행)로 설정할 수 있습니다. PK가 auto increment인 경우 evenly로 판단되어 균등 분할이 되며, 그렇지 않은 경우엔 unevenly로 판단되어 자체적인 분할 방식으로 처리합니다. (unevenly인 경우 성능 차이가 꽤나 존재하여 조심해야 합니다)

2단계: 병렬 읽기

SnapshotSplitAssigner가 생성된 chunk들을 여러 SourceReader에 분배합니다. 내부적으로 비동기 스레드(snapshot-splitting)에서 테이블을 chunk로 분할하고, getNext() 호출 시 remainingSplits에서 하나씩 꺼내 각 SourceReader에 할당합니다. parallelism=4로 설정했다면, 4개의 SourceReader가 각각 다른 chunk를 동시에 읽습니다.

// 개념적 구조 (실제 코드 단순화)
// SourceReader 1: SELECT * FROM users WHERE id >= 1 AND id < 100000
// SourceReader 2: SELECT * FROM users WHERE id >= 100000 AND id < 200000
// SourceReader 3: SELECT * FROM users WHERE id >= 200000 AND id < 300000
// SourceReader 4: SELECT * FROM users WHERE id >= 300000 AND id < 400000

3단계: Binlog 전환

모든 chunk의 스냅샷이 완료되면, MySqlHybridSplitAssigner가 내부의 SnapshotSplitAssigner에서 BinlogSplitAssigner로 전환됩니다. 이후의 변경 이벤트는 단일 binlog reader가 처리합니다. 여기서 Debezium의 binlog 읽기 코드가 그대로 활용됩니다.

Watermark 기반 일관성 보장 (Lock-Free)

여기서 궁금한 점은 "스냅샷을 읽는 동안 데이터가 변경되면 어떡하지?" 라는 생각이 들 수 있습니다.

Flink CDC는 Watermark 알고리즘으로 이 문제를 해결합니다. 각 chunk를 읽을 때 다음 과정을 거칩니다.

chunk 읽기 시작 전: 현재 binlog 위치를 Low Watermark로 기록
chunk의 SELECT 쿼리 실행 (스냅샷 데이터 읽기)
chunk 읽기 완료 후: 현재 binlog 위치를 High Watermark로 기록
Low~High Watermark 사이의 binlog 이벤트 중 이 chunk 범위에 해당하는 변경을 추후에 보정(back-fill)

이 방식 덕분에 MySQL의 Global Read Lock이 필요 없습니다. Debezium의 기존 스냅샷 방식은 데이터 일관성을 위해 이 글로벌 락을 사용했는데, 이는 아무래도 운영 DB에 부하가 갈 수 있습니다.

위에서 언급했던 것처럼 Apache Flink CDC docs 중 scan.incremental.snapshot.enabled 부분에 해당 내용이 명확히 나와있습니다.

Compared to the old snapshot mechanism, the incremental snapshot has many advantages, including: (1) MySQL CDC Source can be parallel during snapshot reading (2) MySQL CDC Source can perform checkpoints in the chunk granularity during snapshot reading (3) MySQL CDC Source doesn't need to acquire global read lock before snapshot reading.

구조 비교: 한눈에 보기

항목	Debezium + Kafka Connect	Flink CDC
Debezium 사용 방식	Kafka Connect Source Connector	Embedded Engine (라이브러리)
실행 프레임워크	Kafka Connect	Apache Flink
스냅샷 병렬성	단일 태스크 (테이블 간 병렬만 가능)	Chunk 기반 다중 SourceReader
스냅샷 단위	테이블 전체	Chunk (PK 범위 기반)
글로벌 락 필요	필요 (FLUSH TABLES WITH READ LOCK)	불필요 (Watermark 알고리즘)
체크포인트 단위	테이블 단위	Chunk 단위
장애 복구	처음부터 다시 스냅샷	마지막 미완료 chunk부터 재개
변경 이벤트 읽기	단일 태스크	단일 Binlog Reader (스냅샷 완료 후)

그렇다면 Binlog Stream 단계는?

Flink CDC의 병렬성은 스냅샷 단계에서만 효과적입니다. 스냅샷이 끝나고 binlog stream로 전환되면, 단일 Binlog Reader가 변경 이벤트를 처리하기 때문에 Debezium과 동일하게 Parallelism이 1로 설정됩니다.

마무리

정리하면, Flink CDC가 Debezium 기반 Kafka Connect에 비해 스냅샷 단계에서 병렬성이 높은 이유는 Debezium 자체의 차이가 아니라, 실행 프레임워크의 아키텍처 차이입니다.

Kafka Connect는 CDC 커넥터를 단일 태스크로 실행하며, 이는 binlog의 순차적 특성 때문에 불가피한 설계입니다.
Flink CDC는 Source API의 SplitEnumerator/SourceReader 분리 모델을 활용하여, 스냅샷 단계를 chunk 단위로 분할하고 병렬 실행합니다. Debezium은 binlog 읽기와 데이터 변환에만 활용합니다.

LSM Tree in Flink

suhwanc — Sat, 28 Mar 2026 22:39:53 +0900

Apache Flink에서 주로 State Backend로 사용되는 RocksDB는 쓰기 속도가 빠르다고 알려져 있는데요, 그 동안 왜 빠른지에 대해서는 한 번도 찾아본 적이 없어 찾아보게 되었습니다.

정답부터 말하면 LSM Tree(Log-Structured Merge-Tree)를 선택했기 때문입니다.

이 글에서는 LSM Tree의 아키텍처와 동작 원리를 1996년 원본 논문을 기반으로 살펴보고, 이후 Flink에서 이걸 어떻게 활용하는지 간단히 정리합니다.

1. 왜 LSM Tree가 필요했을까?

B-Tree의 쓰기 비용 문제

LSM Tree를 이해하려면 먼저 B-Tree의 한계를 알아야 합니다.

1996년 Patrick O'Neil 등이 발표한 원본 논문 "The Log-Structured Merge-Tree (LSM-Tree)" 에서는 다음과 같은 문제를 제기합니다. (1p)

"Standard disk-based index structures such as the B-tree will effectively double the I/O cost of the transaction to maintain an index in real time, increasing the total system cost up to fifty percent."

B-Tree 인덱스를 실시간으로 유지하면 트랜잭션의 I/O 비용이 두 배가 되어, 전체 시스템 비용이 최대 50%까지 증가합니다. -> 흠 B-Tree가 이렇게나 비효율적인 자료구조였다는 게 이해가 되지 않습니다.

B-Tree에 레코드 하나를 삽입하는 과정을 보면 이해가 됩니다.

해당 leaf 페이지(보통 4KB~16KB)를 디스크에서 읽고
메모리에서 페이지를 수정한 뒤
수정된 페이지 전체를 디스크에 다시 쓰고
WAL(Write-Ahead Log)에도 기록합니다

10바이트를 수정하는데 16KB 페이지 전체를 다시 쓰게 됩니다. 논문에서 언급되진 않지만, 이러한 현상을 Write Amplification(쓰기 증폭)이라고 종종 부릅니다.

핵심 원인은 B-Tree의 삽입이 랜덤 위치에 발생한다는 점입니다. 연속된 삽입이 트리의 이곳저곳에 흩어지면서, 매번 디스크 암이 물리적으로 이동해야 합니다. 여기서 랜덤 I/O는 디스크에서 가장 비싼 연산입니다.

순차 쓰기와 랜덤 쓰기

순차 쓰기 vs 랜덤 쓰기

택배 상하차로 비유해보자면 순차 쓰기는 들어오는 택배를 순서대로 쌓으면 되지만, 랜덤 쓰기는 들어오는 택배의 주소지를 알파벳 순으로 정렬해서 맞춰야 합니다. 쓰기 속도가 느릴 수밖에 없습니다.

논문이 제시한 해결 아이디어

논문의 핵심 아이디어는 한 문장으로 요약됩니다.

"The LSM-tree uses an algorithm that defers and batches index changes, cascading the changes from a memory-based component through one or more disk components in an efficient manner reminiscent of merge sort."

LSM 트리의 알고리즘은 인덱스 변경을 지연(defer)하고 일괄 처리(batch)해서, 메모리 컴포넌트에서 디스크 컴포넌트로 머지 소트와 유사한 방식으로 전파하는 것

간단히 말하면 "인덱스 변경을 즉시 반영하지 말고, 모아서 한꺼번에 순차적으로 쓰자"

-> 이것이 논문에서 제시한 LSM Tree의 근본 원리입니다.

2. 아키텍처

논문의 원래 설계: C0와 C1

https://www.cs.umb.edu/~poneil/lsmtree.pdf

원본 논문에서 LSM Tree는 두 개의 컴포넌트로 구성됩니다.

C0 (메모리 컴포넌트): 메모리에 저장된 작은 트리. 모든 새 레코드는 먼저 여기에 삽입됩니다.
C1 (디스크 컴포넌트): 디스크에 저장된 큰 트리. 완전히 채워진 페이지 노드들로 구성됩니다.

https://www.cs.umb.edu/~poneil/lsmtree.pdf

각 컴포넌트는 자기가 위치한 저장 매체의 특성에 맞게 최적화됩니다. C0는 메모리 접근 속도에, C1은 디스크의 순차 I/O에 맞춰 튜닝됩니다. (예를 들어, C0는 Red-Black Tree나 Skip List를 사용합니다)

C0가 임계값에 도달하면, Rolling Merge라는 프로세스가 C0의 데이터를 C1으로 병합합니다. 논문에서는 이 과정을 다음과 같이 묘사합니다.

"The rolling merge process has a conceptual cursor which slowly circulates in quantized steps through equal key values of the C0 tree and C1 tree components, drawing indexing data out from the C0 tree to the C1 tree on disk."

개념적인 커서가 C0와 C1의 동일한 키 범위를 순환하면서, C0에서 데이터를 꺼내 C1의 디스크로 병합하는 것입니다. 이때 multi-page block 단위로 I/O를 수행하기 때문에 seek time이 거의 발생하지 않습니다.

다중 컴포넌트 확장

논문은 여기서 멈추지 않고, K+1개의 컴포넌트로 일반화합니다. C0(메모리), C1, C2, ..., CK(디스크) 순으로 크기가 커지고, 인접한 컴포넌트 쌍마다 Rolling Merge가 동작합니다. (C1-C2, C5-C6 ...)

C0 (Memory): 가장 작지만 가장 빠른 메모리
C1, C2, ..., Ck (Disk): 뒤로 갈수록 용량이 커지는 디스크. Ck가 가장 큰 최종 저장소가 된다.

논문의 Theorem 3.1에 따르면, 모든 인접 컴포넌트의 크기 비율이 동일한 값 r일 때 전체 I/O가 최소화됩니다. 즉 S1/S0 = S2/S1 = ... = SK/SK-1 = r이 되어야 합니다.

현대적 구현: MemTable + SSTable + Level

현대의 LSM Tree 구현체(RocksDB, LevelDB 등)는 논문의 아이디어를 따라가지만, 용어와 구조가 좀 더 구체화되었습니다.

용어 정리로 앞에 WAL 부분은 생략했습니다. 밑에 나올 예정

논문 용어	현대 용어	설명
C0	MemTable	메모리의 정렬된 버퍼 (Skip List / Red-Black Tree)
C1, C2, ...	Level 0, 1, 2, ...	디스크의 SSTable 파일 계층
Rolling Merge	Compaction	하위 레벨 → 상위 레벨로 데이터 병합

MemTable

쓰기 요청이 들어오면 먼저 MemTable에 기록됩니다. MemTable은 메모리 내의 정렬된 자료구조로, 보통 Skip List로 구현됩니다. 삽입과 검색 모두 O(log N)입니다.

MemTable은 반드시 WAL(Write-Ahead Log)과 함께 동작합니다. (⭐️)

모든 쓰기는 MemTable에 넣기 전에 WAL에 먼저 기록되어, 프로세스 crash 시 복구할 수 있습니다.

SSTable (Sorted String Table)

MemTable이 임계값(보통 64MB)에 도달하면, 내용 전체를 디스크에 정렬된 상태로 flush합니다. (순차 쓰기)

이렇게 만들어진 파일이 SSTable입니다.

SSTable의 핵심 특성 세 가지:

불변(Immutable): 한 번 쓰면 절대 수정하지 않습니다
정렬(Sorted): 키 순서대로 정렬되어 있습니다
순차 쓰기(Sequential Write): 디스크에 처음부터 끝까지 순서대로 씁니다

SSTable 내부는 다음과 같이 구성됩니다.

https://medium.com/@dwivedi.ankit21/lsm-trees-the-go-to-data-structure-for-databases-search-engines-and-more-c3a48fa469d2

3. 동작 원리

쓰기

쓰기의 흐름을 따라가 보겠습니다.

쓰기 연산 발생
WAL에 Append 수행 (순차 쓰기, 1회 디스크 I/O)
MemTable 삽입 (메모리 연산)
완료

디스크 I/O는 WAL의 순차적 append 딱 1회입니다. B-Tree가 매번 랜덤 위치의 페이지를 읽고-수정하고-다시 쓰는 것과 비교하면, 이 차이가 LSM Tree를 쓰는 가장 큰 이유라고 볼 수 있습니다.

논문에서는 이 효율성을 Batch-Merge Parameter M이라는 개념으로 정량화합니다. C0와 C1의 크기 비율이 클수록 한 번의 디스크 페이지에 더 많은 항목을 배치 병합할 수 있어 효율이 높아진다는 것입니다.

읽기

쓰기를 최적화한 대가로, 읽기는 조금 복잡해집니다.

최신 데이터가 어디에 있는지 모르기 때문에 위에서부터 아래로 순서대로 찾아야 합니다. (C0, C1, ..., Ck)

MemTable 검색
Level 0 SSTable 검색
Level 1 SSTable 검색
Level 2, 3, ...

최악의 경우 모든 레벨을 탐색해야 합니다. LSM Tree의 최대 단점입니다.

다만, 실제로는 몇 가지 장치가 이 비용을 크게 줄여줍니다.

Bloom Filter: 각 SSTable에 존재하며 "이 키가 여기 없다"는 것을 O(1)에 판별
Block Cache: 자주 읽히는 블록은 메모리에 캐싱
Index Block: SSTable 내 binary search 지원

Compaction

시간이 지나면 SSTable 파일이 계속 쌓입니다. 같은 키에 대한 여러 버전이 여러 파일에 흩어지게 됩니다. 이걸 정리하는 과정이 Compaction이고, 논문에서의 Rolling Merge에 해당합니다.

Compaction 전:
  Level 0:  [a:1, c:3, f:6]  [b:2, c:5, d:4]   ← 같은 키 c가 두 파일에
                    │
                    ▼  merge sort + 중복 제거
Compaction 후:
  Level 1:  [a:1, b:2, c:5, d:4, f:6]            ← 최신값(c:5)만 유지

삭제는 어떻게?

개인적으로 이 부분이 꽤 재미있었는데요, LSM Tree와 같은 불변 구조에서는 파일을 수정할 수 없으니 삭제도 "쓰기"로 처리합니다.

DELETE(id=1) 요청이 오면, MemTable에 (id=1, TOMBSTONE)이라는 특수한 마커를 삽입합니다. 이후 읽기 시 tombstone을 만나면 "이 키는 삭제되었다"고 판단합니다. 실제 물리적 삭제는 compaction 때 일어납니다. INSERT, UPDATE, DELETE 모두 결국 같은 쓰기 경로를 탄다는 점이 중요합니다.

Flink에서 사용하는 LSM Tree

Flink에서는 상태 저장소로 RocksDB(LSM Tree 기반)를 사용합니다.

Flink + RocksDB

Flink의 EmbeddedRocksDBStateBackend은 operator state를 RocksDB에 저장합니다. 스트림 처리에서 이 조합이 잘 맞는 이유는 세 가지입니다.

1. 스트림 처리는 쓰기 중심입니다.

// 이벤트마다 상태를 읽고 쓴다
public void processElement(Event event, Context ctx, Collector<Result> out) {
Long count = countState.value();   // 1회 읽기
    countState.update(count + 1);      // 1회 쓰기
}

초당 수십만 이벤트가 들어오면, 상태 쓰기 횟수도 초당 수십만 회입니다. 이는 Flink 상태 처리에서 매우 일반적인 상황입니다.

2. 메모리보다 큰 상태를 다룰 수 있습니다.

HashMapStateBackend은 모든 상태를 JVM 힙에 올립니다. 상태가 수십 GB를 넘으면 GC 지옥에 빠져 헤어나오지 못합니다. RocksDB는 MemTable과 Block Cache만 메모리에 두고 나머지는 디스크에 두기 때문에, TB 규모의 상태도 안정적으로 처리할 수 있습니다.

3. Incremental Checkpoint와 궁합이 좋습니다.

SSTable은 불변이기 때문에, 마지막 체크포인트 이후 새로 생긴 SSTable 파일만 업로드하면 됩니다. Flink에서 RocksDB를 쓰는 가장 큰 이유입니다.

LSM Tree를 사용하는 다른 시스템들

LSM Tree를 사용하는 다른 시스템들에는 아래가 있습니다. 이 밖에도 엄청 많습니다.

시스템	사용 맥락	LSM 구현체
Apache Cassandra	분산 NoSQL DB	자체 구현
Apache HBase	대용량 칼럼형 스토어	자체 구현
Kafka Streams	상태 저장소	RocksDB

마치며

LSM Tree에 대해 찾아보기 전까지는 단순히 옆에 메모리 하나 더 두는 개념으로 생각했었는데요, 그 안에서는 WAL로 데이터를 먼저 쓰고, MemTable에 데이터를 모으고, SSTable로 flush하고, Compaction으로 정리하는 일을 반복하고 있었습니다.

결국 핵심은 "랜덤 쓰기를 순차 쓰기로 변환한다"는 아이디어를 바탕으로 쓰기 속도를 극단적으로 높였고, 블룸 필터 등으로 읽기 속도를 개선했다고 볼 수 있습니다. 특히 최근 NoSQL, 시계열 데이터베이스가 성장하면서 이렇게 쓰기 효율을 높이는 방법이 많이 등장하고 있다고 합니다.

참고 자료

O'Neil, Cheng, Gawlick, O'Neil. "The Log-Structured Merge-Tree (LSM-Tree)", Acta Informatica, 1996 (PDF)
Log-structured merge-tree - Wikipedia
RocksDB Wiki
Apache Flink - State Backends

CASCADE DELETE, Debezium은 알고 있을까?

suhwanc — Sat, 21 Mar 2026 12:30:46 +0900

Debezium 기반의 CDC(Change Data Capture) 파이프라인을 운영하다 문득 다음과 같은 섬뜩한 의문이 들었습니다.

소싱하는 DB의 CASCADE가 발생하는 경우 변경 이벤트 감지를 할 수 있을까?

결론은 Debezium 자체는 CASCADE에 대해서 어떠한 처리도 하지 않습니다. 하지만 소싱 DB의 이벤트 저장 방식에 따라 변경 이벤트는 유실될 수도, 안될 수도 있습니다.

이 글에서는 MySQL, PostgreSQL, MongoDB 3개 DB에서 Debezium이 cascade를 어떻게 처리하는지를 확인해 보았습니다.

1. MySQL - Binlog에서 CASCADE를 표현하는 방식

InnoDB FK CASCADE의 내부 동작

MySQL InnoDB에서 FK CASCADE가 동작하는 흐름은 다음과 같습니다.

클라이언트가 DELETE FROM orders WHERE order_id = 1001 실행
InnoDB 엔진이 FK 제약조건을 확인
order_items에 ON DELETE CASCADE가 있으므로, 해당 자식 행을 InnoDB가 내부적으로 DELETE
이 내부 DELETE가 binlog에 별도의 DELETE_ROWS_EVENT로 기록됨

핵심은 "별도의 row event로 기록된다"는 점입니다. (⭐️⭐️⭐️)
MySQL binlog의 row event 형식에는 "이것이 cascade에 의한 삭제"를 나타내는 플래그나 메타데이터가 존재하지 않습니다. 그저 같은 트랜잭션(GTID) 내에서 부모 테이블 DELETE가 먼저 기록되고, 이어서 자식 테이블 DELETE가 기록될 뿐입니다.

Debezium 소스코드 분석

BinlogStreamingChangeEventSource.java의 handleDelete() 메서드를 보면 Debezium이 binlog의 DELETE 이벤트를 어떻게 처리하는지 알 수 있습니다.

protected void handleDelete(P partition, O offsetContext, Event event) throws InterruptedException {
    // 단순히 handleChange에 Delete를 넘겨 호출합니다.
    handleChange(partition, offsetContext, event, Envelope.Operation.DELETE, DeleteRowsEventData.class,
            x -> schema.getTableId(x.getTableId()),
            DeleteRowsEventData::getRows,
            (tableId, row) -> eventDispatcher.dispatchDataChangeEvent(partition, tableId,
                    new BinlogChangeRecordEmitter<>(partition, offsetContext, clock, Envelope.Operation.DELETE, row, null, connectorConfig)),
            (tableId, row) -> validateChangeEventWithTable(schema.tableFor(tableId), row, null));
}

이 코드에서 주목할 점은, Cascade로 인한 삭제인지 직접 삭제인지 구분하는 조건문이나 분기 로직이 전혀 없다는 점입니다.
(단편적으로 이 코드만 봐서 알 수는 없지만, 적어도 debezium 라이브러리에서 MySQL의 cascade 관련 처리 로직은 존재하지 않습니다.)

실제 이벤트를 비교해 보면

orders 테이블의 부모 행을 직접 DELETE 했을 때 발생하는 Debezium 이벤트:

{
  "before": {
    "order_id": 1001,
    "customer_id": 42,
    "total": 50000
  },
  "after": null,
  "source": {
    "connector": "mysql",
    "db": "ecommerce",
    "table": "orders",
    "gtid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:42",
    "file": "mysql-bin.000003",
    "pos": 1081,
    "thread": 15
  },
  "op": "d",
  "ts_ms": 1711000000000
}

그리고 cascade로 자동 삭제된 order_items 행의 이벤트:

{
  "before": {
    "item_id": 5001,
    "order_id": 1001,
    "product_name": "키보드",
    "price": 50000
  },
  "after": null,
  "source": {
    "connector": "mysql",
    "db": "ecommerce",
    "table": "order_items",
    "gtid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:42",
    "file": "mysql-bin.000003",
    "pos": 1205,
    "thread": 15
  },
  "op": "d",
  "ts_ms": 1711000000000
}

두 이벤트를 나란히 놓고 비교하면, 차이점은 table, pos뿐입니다.

그리고 gtid와 thread는 동일하다는 것을 통해 같은 트랜잭션에서 발생했다는 것을 알 수 있습니다.

그러나 이 공통된 gtid와 thread만으로는 "cascade 관계인가"와 "같은 트랜잭션에서 실행된 별개의 DELETE인가"를 구분할 수 없습니다. 개발자가 하나의 트랜잭션 안에서 orders와 order_items를 명시적으로 순서대로 DELETE 했다면, 위와 이벤트 형태가 완전히 동일하기 때문입니다.

또한 source 블록 전체를 살펴봐도 "cascade" 여부를 나타내는 전용 필드가 존재하지 않습니다. MySQL binlog 자체가 해당 정보를 기록하지 않기 때문입니다.

2. PostgreSQL — WAL에서의 CASCADE 처리

WAL/pgoutput 기반 CDC

PostgreSQL도 MySQL과 마찬가지로, FK CASCADE로 인한 DELETE를 WAL에 별도 row 이벤트로 기록합니다.
그리고 Debezium은 pgoutput 논리 복제 플러그인을 통해 이 이벤트를 수신합니다.

PgOutputMessageDecoder.decodeDelete() 메서드는 WAL의 DELETE 메시지를 처리하며, MySQL과 동일하게 cascade 구분 플래그 없이 모든 DELETE를 동일하게 처리합니다.

예외: TRUNCATE CASCADE

단, Debezium 라이브러리에서 cascade를 검색하면 딱 하나 PostgreSQL에서 이를 파싱 하는 부분이 있습니다.
바로 TRUNCATE 처리 부분입니다.

PgOutputMessageDecoder.decodeTruncate()

// debezium-connector-postgresql/src/main/java/io/debezium/connector/postgresql/connection/pgoutput/PgOutputMessageDecoder.java:558-601
private void decodeTruncate(ByteBuffer buffer, TypeRegistry typeRegistry,
        ReplicationMessageProcessor processor) throws SQLException, InterruptedException {
    // As of PG11, the Truncate message format is as described:
    // Byte Message Type (Always 'T')
    // Int32 number of relations described by the truncate message
    // Int8 flags for truncate; 1=CASCADE, 2=RESTART IDENTITY
    // Int32[] Array of number of relation ids

    int numberOfRelations = buffer.getInt();
    int optionBits = buffer.get();
    // ignored / unused
    List<String> truncateOptions = getTruncateOptions(optionBits);
    // ... 이하 각 테이블별 TRUNCATE 이벤트 생성
}

private List<String> getTruncateOptions(int flag) {
    switch (flag) {
        case 1:  return Collections.singletonList("CASCADE");
        case 2:  return Collections.singletonList("RESTART IDENTITY");
        case 3:  return Arrays.asList("RESTART IDENTITY", "CASCADE");
        default: return null;
    }
}

이 코드에서 주목할만한 점은, 프로토콜의 T (Truncate) 메시지에 cascade 여부를 비트 플래그로 포함한다는 점입니다. (PG11+)

즉, 앞서 살펴본 MySQL과 달리 프로토콜 레벨에서 cascade 정보 자체는 제공한다는 것이죠.

또한 이에 대해 Debezium은 getTruncateOptions()로 이 플래그를 파싱 합니다.
하지만 바로 위의 주석 // ignored / unused처럼, 파싱 한 결과를 PgOutputTruncateReplicationMessage 생성 시 전달하지는 않습니다.

따라서 PostgreSQL이 유일하게 cascade 정보를 프로토콜 레벨에서 제공하지만, 현재 Debezium은 이를 활용하지 않고 있습니다.
아마도 PK CASCADE로 인한 DELETE를 WAL에 별도 row 이벤트로 기록하기 때문에 굳이 사용하진 않는 것으로 보입니다.

3. MongoDB — CASCADE라는 개념 자체가 없다

Document DB의 근본적 차이

MongoDB는 앞의 두 DB와 패러다임 자체가 다릅니다. MongoDB에는 FK 제약조건이 없기 때문에, CASCADE도 없습니다.

관련해서 조금 찾아본 바로는, Document DB에서 관련 테이블(Document)의 관리는 전적으로 애플리케이션의 책임이라고 합니다.
따라서 두 DB가 연관되어 있다면, 애플리케이션 레벨에서 두 테이블 각각에 대해 명시적으로 변경을 해야 한다는 것이죠.

4. 결론

1. Debezium은 DB 로그를 그대로 복제

DB 엔진에서 cascade를 일반 DML로 기록하면, Debezium도 일반 DML로 처리합니다.
따로 Debezium에서 cascade에 대한 별도의 처리가 존재하지 않습니다. 이는 Debezium의 설계 철학이기도 한 게, 로그에 기록된 것을 그대로 전달하는 것이 CDC의 기본 원칙입니다.

2. Cascade가 안 되는 것은 Debezium의 한계가 아니라 DB 로그의 한계

MySQL binlog와 PostgreSQL WAL 모두 DML 이벤트 레벨에서 cascade 여부를 기록하지 않습니다.
처음부터 Debezium이 cascade를 구분하기 위해선 DB 로그 자체가 해당 정보를 담고 있어야 합니다. 로그에 없는 정보를 Debezium이 만들어낼 수는 없습니다.

결론적으로 CDC 파이프라인을 설계할 때 cascade 동작을 고려해야 한다면, 원천 DB에서 이벤트를 남기는 포맷을 적절히 설정하는 것이 가장 현실적인 접근입니다. 예를 들어, MySQL의 binlog_format을 'row'로 설정하는 것처럼 말이죠.

Flink CDC MySQL Snapshot은 정말 중복 없이 동작할까?

suhwanc — Sun, 1 Mar 2026 12:44:12 +0900

의문의 시작

Flink CDC의 MySQL snapshot은 청크 단위로 SELECT문을 이용해 데이터를 복사하고, SHOW MASTER STATUS문을 이용해 GTIDs 값을 기록합니다.

이후 binlog streaming 단계로 전환할 때, 모든 청크의 GTIDs 값 중 가장 낮은(오래된) 값부터 binlog event를 읽기 시작합니다. 이걸 보는데 문득 이런 생각이 들었습니다.

snapshot에서 이미 가져온 데이터가 binlog에서 다시 나와서, sink가 upsert 모드가 아니면 중복 insert가 쌓이는 것 아닐까?

결론부터 말하면, 중복은 발생하지 않았습니다.

Flink CDC는 Netflix의 DBLog 논문에 기반한 2단계 중복 방지 메커니즘을 갖고 있기 때문입니다.

아래는 그 과정을 설명합니다.

1단계: Chunk 정규화 (Normalization)

각 chunk를 읽을 때는 3개의 step이 순차적으로 실행됩니다.

MySqlSnapshotSplitReadTask.java

// Step 1: Low Watermark 기록
final BinlogOffset lowWatermark = DebeziumUtils.currentBinlogOffset(jdbcConnection);

// Step 2: SELECT 실행 - chunk 데이터 읽기
createDataEvents(ctx, snapshotSplit.getTableId());

// Step 3: High Watermark 기록
highWatermark = DebeziumUtils.currentBinlogOffset(jdbcConnection);

여기서 currentBinlogOffset()은 내부적으로 SHOW MASTER STATUS를 실행하여 현재 binlog file, position, GTID set을 가져옵니다.

그다음이 정규화의 핵심으로, SnapshotSplitReader.java에서 backfill 과정이 이어집니다

// Step 1: execute snapshot read task
SnapshotResult<MySqlOffsetContext> snapshotResult = snapshot(sourceContext);

// Step 2: read binlog events between low and high watermark and backfill changes into snapshot
backfill(snapshotResult, sourceContext);

backfill은 Low~High Watermark 사이의 binlog을 읽어 snapshot 데이터에 PK 기준 upsert 합니다.

특히 SnapshotSplitReader.pollWithBuffer() 메서드의 주석이 이를 명확히 설명하고 있습니다

// data input:  [low watermark event][snapshot events][high watermark event]
//              [binlog events][binlog-end event]
// data output: [low watermark event][normalized events][high watermark event]

pollWithBuffer() 메서드 수행 후 정규화가 되면서 binlog events가 snapshot events에 upsert 되고 normalized events로 바뀐 모습을 볼 수 있습니다.

실제 정규화 코드 (SnapshotSplitReader.java):

if (!reachBinlogStart) {
    // snapshot 데이터를 PK 기준 Map에 저장
    snapshotRecords.put((Struct) record.key(), Collections.singletonList(record));
} else {
    // binlog 이벤트로 snapshot 데이터를 upsert
    RecordUtils.upsertBinlog(snapshotRecords, record, ...);
}

RecordUtils.upsertBinlog()는 binlog 이벤트의 operation 타입에 따라 동작합니다.

RecordUtils.java L:121-167

INSERT(CREATE): 해당 PK의 snapshot 레코드를 교체
UPDATE: AFTER 이미지로 교체 (단, Split 범위 밖이라면 warn log를 뱉고 처리하지 않음)
DELETE: 해당 PK의 레코드를 제거

이 과정을 거치면 각 chunk는 High Watermark 시점의 일관된 스냅샷으로 정규화됩니다.

2단계: Binlog Streaming의 Per-Chunk 필터링

모든 snapshot chunk가 완료되면 binlog streaming이 시작됩니다. 시작 위치는 모든 chunk의 High Watermark 중 가장 낮은 값입니다.

RecordUtils.java L:375-386

public static BinlogOffset getStartingOffsetOfBinlogSplit(
        List<FinishedSnapshotSplitInfo> finishedSnapshotSplits) {
    BinlogOffset startOffset = finishedSnapshotSplits.get(0).getHighWatermark();
    for (FinishedSnapshotSplitInfo finishedSnapshotSplit : finishedSnapshotSplits) {
        if (finishedSnapshotSplit.getHighWatermark().isBefore(startOffset)) {
            startOffset = finishedSnapshotSplit.getHighWatermark();
        }
    }
    return startOffset;
}

여기서 맨 처음 의문이 든 "가장 낮은 값부터 시작하면 중복 아니냐?"라는 질문이 나오게 되었는데, 이를 아래 코드에서 명쾌하게 해결하는 걸 알 수 있었습니다.

답은 BinlogSplitReader.shouldEmit() 메서드입니다.

BinlogSplitReader.java L:250-291

/**
* Returns the record should emit or not.
*
* <p>The watermark signal algorithm is the binlog split reader only sends the binlog event that
* belongs to its finished snapshot splits. For each snapshot split, the binlog event is valid
* since the offset is after its high watermark.
*
* <pre> E.g: the data input is :
*    snapshot-split-0 info : [0,    1024) highWatermark0
*    snapshot-split-1 info : [1024, 2048) highWatermark1
*  the data output is:
*  only the binlog event belong to [0,    1024) and offset is after highWatermark0 should send,
*  only the binlog event belong to [1024, 2048) and offset is after highWatermark1 should send.
* </pre>
*/
private boolean shouldEmit(SourceRecord sourceRecord) {
    // ...
    Object[] chunkKey = SplitKeyUtils.getSplitKey(splitKeyType, nameAdjuster, target);

    FinishedSnapshotSplitInfo matchedSplit =
            SplitKeyUtils.findSplitByKeyBinary(finishedSplitsInfo.get(tableId), chunkKey);

    return matchedSplit != null && position.isAfter(matchedSplit.getHighWatermark());
}

BinlogSplitReader.shouldEmit()에서는 어떤 binlog 이벤트에 대해 메인 스트림에 내보낼지 여부를 결정합니다. 따라서 만약 값이 false라면 타겟에 반영되지 않는 것이죠.

동작 원리

binlog 이벤트의 PK값으로 어떤 snapshot chunk에 속하는지 binary search
해당 chunk의 개별 High Watermark 이후인 이벤트만 emit
이전이면 버림 (이미 chunk 정규화에서 반영된 데이터)

구체적 예시

chunk-0: PK [0, 1000)    → highWatermark = 150
chunk-1: PK [1000, 2000) → highWatermark = 280
chunk-2: PK [2000, 3000] → highWatermark = 350

binlog streaming 시작 위치: min(150, 280, 350) = 150

binlog pos	이벤트	PK	속한 chunk	HW	판정
155	INSERT	500	chunk-0	150	155 > 150 → emit
160	INSERT	1500	chunk-1	280	160 < 280 → drop
290	UPDATE	1500	chunk-1	280	290 > 280 → emit

position 160의 PK=1500 INSERT의 경우 position이 highWatermark보다 낮기 때문에 이미 반영된 것으로 판단 후 버립니다.
이처럼 chunk별 개별 High Watermark 기준 필터링 덕분에 중복이 발생하지 않는 것을 보장할 수 있습니다.

예외: backfill skip 옵션

MySqlSnapshotSplitReadTask.java에서 scan.incremental.snapshot.backfill.skip 옵션이 true이면 backfill을 건너뛰고 High Watermark를 Low Watermark와 동일하게 설정하는 경우가 있습니다.

if (isBackfillSkipped) {
    // Directly set HW = LW if backfill is skipped. Binlog events created during snapshot
    // phase could be processed later in binlog reading phase.
    //
    // Note that this behaviour downgrades the delivery guarantee to at-least-once. We can't
    // promise that the snapshot is exactly the view of the table at low watermark moment,
    // so binlog events created during snapshot might be replayed later in binlog reading
    // phase.
    highWatermark = lowWatermark;

이 경우에는 중복 가능성이 존재합니다. 다만 기본값은 false이므로 정상 사용 시 exactly-once가 보장됩니다.

궁금해서 이 옵션이 왜 존재하는지 한 번 찾아봤는데요, 아래와 같은 이슈와 동기를 찾을 수 있었습니다.

https://github.com/apache/flink-cdc/issues/2553

이슈 & 동기

Exactly-once를 보장하는 이런 Backfill Log 과정이 때에 따라서는 무겁고, 소스에 부하가 많이 가는 작업일 수 있습니다.

이슈에서 예시로 든 Postgres의 경우 변경 데이터를 읽기 위해 Replication Slot과 연결이 필요한데, Parallelism 수에 맞게 개별적인 연결을 유지하면서 + 동시에 스냅샷을 읽는 도중 데이터가 바뀌면 보정(Backfill) 합니다.

Parallelism을 4로 두면, 일단 4개의 커넥터가 필요하고, Enumerator에서 관리자용 연결이 또 하나 필요합니다. (일단 5개)

만약 DB 소스가 10개라면 5 * 10 = 50개나 되어버리는 것이죠.

따라서 이 작업은 At-least-once로 처리해 부하를 줄이자!라는 것입니다.

어차피 타겟 DB에서 upsert 옵션이 되어있다면, 같은 이벤트가 여러 번 가도 멱등성을 보장하기 때문에 정합성에 문제가 없다는 판단입니다. 이러면 backfill 과정도 생략되며 계속 연결을 유지해야 하는 커넥션의 수도 줄어듭니다.

Flink에서는 Exactly-once를 위해 더 정교한 작업을 처리하려다 보니 이런 이슈도 발생할 수 있는 것 같습니다.

만약 굳이 필요 없다면 scan.incremental.snapshot.backfill.skip 옵션을 true로 두는 것도 충분히 괜찮은 선택 같네요.

정리

단계	역할	핵심 코드
Chunk 정규화	snapshot + binlog merge로 HW 시점 일관성 확보	`SnapshotSplitReader.pollWithBuffer()`
Per-Chunk 필터링	PK 기반으로 chunk별 HW 이후 이벤트만 통과	`BinlogSplitReader.shouldEmit()`

"가장 낮은 High Watermark부터 binlog을 읽지만, 각 레코드가 속한 chunk의 개별 HW 이후 이벤트만 emit 한다." 이것이 exactly-once를 달성하는 DBLog 알고리즘의 핵심입니다.

그리고 이 알고리즘은 Debezium의 Incremental Snapshot이 동작하는 원리와 동일합니다.

코드를 보다 보니 이 부분에 대한 설명이 주석에 잘 적혀있는 것을 보았습니다.
혹시 좀 더 깊게 보고 싶으신 분들은 링크에 표기된 코드 본문을 따라가면 블로그 글에 기재된 내용 이상의 무언가(?)을 얻으실 수도!

참고

DBLog: A Watermark Based Change-Data-Capture Framework (Netflix, 2020)

Flink CDC에서 Upsert가 재처리를 가능하게 하는 이유

suhwanc — Wed, 18 Feb 2026 11:03:34 +0900

1. 개요

Flink CDC 파이프라인은 "재처리"를 피할 수 없다.

분산 스트리밍 시스템은 이론적으로는 아름답지만, 현실은 변수가 많습니다. 소싱하는 Kafka 토픽의 파티션이 갑자기 늘어나고, 노드가 OOM으로 죽고, 디스크가 가득 차고, GC로 인해 타임아웃이 발생할 수 있습니다.

Apache Flink 기반의 CDC 파이프라인도 마찬가지입니다.

현시점 기준으로 스트리밍 파이프라인 중 운영 환경에서 장애를 고려하지 않은 시스템은 아마 없을 것이라 생각합니다.

Flink는 이러한 장애에 대응하기 위해 체크포인트(Checkpoint) 메커니즘을 제공하고 있습니다. 주기적으로 스트림 처리 상태를 스냅샷으로 저장하고, 장애 발생 시 마지막으로 성공한 체크포인트로부터 복구합니다.

단, 이번 포스팅에서 이야기하고 싶은 내용은 여기서 발생하는 핵심적인 문제입니다.

체크포인트 이후에 처리되었지만 아직 다음 체크포인트에 포함되지 않은 이벤트들은, 체크포인트 복구 후 다시 한 번 전달됩니다. 즉, 같은 이벤트가 싱크(Sink)에 두 번 이상 도착할 수 있습니다.

이것은 Flink만의 문제는 아닌 게, Kafka Consumer의 오프셋 리셋, Debezium CDC 소스 커넥터의 binlog position 재설정이 이런 문제를 야기할 수 있고, 심지어 "그냥" 잘못 보내줬던 케이스가 존재할 수도 있어서 실 서비스에서 같은 데이터가 두 번 이상 처리되는 상황은 자연스러운 현상입니다.

그럼 항상 섬뜩한 생각이 따라오는데,, "같은 이벤트가 두 번 싱크되면 데이터가 꼬이지 않을까?"라는 것입니다.

여러 답변이 있을 수 있겠지만, 이번 글에서는 Flink CDC 코드베이스의 실제 구현을 통해 이 질문에 대한 답을 알아보려 합니다.

결론부터 말하면 Upsert 기반의 멱등한 쓰기(idempotent write)가 그 해답입니다.

2. 배경 - Delivery Semantics 3종 비교

일반적으로 분산 메시징 시스템에서 메시지 전달 보장(Delivery Semantics)은 세 가지 수준으로 나뉘게 됩니다.

보장 수준	의미	비용
At-most-once	유실 가능, 중복 없음	낮음
At-least-once	유실 없음, 중복 가능	중간
Exactly-once	유실 없음, 중복 없음	높음 (2PC 등 필요)

At-most-once (최대 한 번): 가장 단순하게, 메시지를 보내고 확인하지 않는 방법입니다. 유실은 될 수 있지만 중복은 허용하지 않습니다. 로그 수집처럼 일부 유실이 허용되는 경우에 적합하지만, CDC 파이프라인에서는 데이터 유실이 곧 데이터 불일치이므로 선택지가 될 수 없습니다.
Exactly-once (정확히 한 번): 모든 시스템이 원하는 이상적인 방법입니다. 메시지 유실도 없고, 중복도 없습니다. 이를 달성하려면 2-Phase Commit(2PC)이나 트랜잭셔널 싱크 같은 무거운 메커니즘이 필요하게 됩니다. 분산 환경에서 2PC는 코디네이터 장애, 타임아웃, 참여자 간 불일치 등 수많은 엣지 케이스를 처리해야 하며, 처리량(throughput)도 크게 떨어지게 됩니다.
At-least-once (최소 한 번): 많은 CDC 시스템이 선택하는 현실적인 타협점입니다. 메시지 유실은 막되, 중복은 허용합니다. Flink에서는 Exactly-once를 제공한다고 하지만, 이는 Flink State의 일관성이고 Flink CDC에서는 동일한 레코드의 Sink가 여러 번 될 수 있습니다.

따라서 Flink CDC의 주요 싱크 커넥터들(Iceberg, Paimon, Doris, Fluss..)은 대부분 이 현실적인 선택을 따릅니다.

공식 문서에서도 아래와 같은 문구가 명시되어 있습니다.

"Not support exactly-once. The connector uses at-least-once + primary key table for idempotent writing."

단, 여기서 눈여겨봐야 할 점은 Exactly-once를 구현하지 않아도 upsert + PK 기반 멱등성으로 동일한 결과를 달성할 수 있다는 것입니다. 언뜻 보면 말장난 같은데, 이게 어떻게 가능한지 살펴봅니다.

3. 멱등성(Idempotency)이란?

멱등성(Idempotency) 은 수학 용어입니다. 함수 f가 멱등하다는 것은 다음을 만족하게 됩니다.

f(f(x)) = f(x)

같은 연산을 한 번 적용하든 두 번 적용하든, 결과가 동일하다는 뜻입니다.

대표적으로 절댓값 함수의 경우 ||-3|| = |-3| = 3 처럼 여러 번 씌워도 결과는 동일합니다.

이 성질이 분산 시스템에서 왜 중요한지는 DB 테이블에 발생 가능한 DML을 통해 직관적으로 이해할 수 있습니다.

INSERT는 멱등하지 않습니다.
- INSERT INTO users VALUES (1, 'Alice')를 두 번 실행하면, 첫 번째는 성공하지만 두 번째는 Primary Key 충돌 에러가 발생합니다. (PK가 없다면 같은 행이 두 개 삽입됩니다.) 어느 쪽이든 "한 번 실행한 것과 같은 결과"가 아니다.
UPSERT는 멱등합니다.
- UPSERT INTO users VALUES (1, 'Alice')를 두 번 실행하면, 첫 번째는 행을 삽입하고, 두 번째는 이미 존재하는 행을 같은 값으로 덮어씁니다. 결과는 동일하게 (1, 'Alice') 한 행이 남습니다.
DELETE도 멱등합니다.
- DELETE FROM users WHERE pk = 1을 두 번 실행하면, 첫 번째는 행을 삭제하고, 두 번째는 삭제할 행이 없으므로 아무 일도 하지 않는다. (단, 에러를 던지지 않아야 합니다.)

여기서 주목할 점은 당연하게도 UPSERT입니다.

UPSERT의 의미를 한 문장으로 정리하면 "존재하면 덮어쓰고, 없으면 삽입한다."라는 것이고, 이 연산은 본질적으로 멱등합니다. 같은 PK에 같은 값을 몇 번을 써도 최종 상태는 항상 같습니다.

바로 이 성질을 이용해 Flink CDC에서는 at-least-once 환경에서의 중복 전달 문제를 해결합니다.

4. Flink CDC 커넥터별 구현

실제 Sink 커넥터들은 이를 어떻게 구현하고 있는지 살펴봅니다.

4-1. Iceberg: Equality Delete + Checkpoint Deduplication

Iceberg 싱크 커넥터는 두 단계로 멱등성을 보장합니다.

1단계: 이벤트를 Upsert 시맨틱으로 변환

RowDataUtils.java는 CDC의 DataChangeEvent를 Iceberg가 이해하는 RowData로 변환하는 역할을 합니다. 여기서 핵심은 INSERT, UPDATE, REPLACE를 모두 RowKind.INSERT로 매핑한다는 점입니다.

// RowDataUtils.java (Lines 36-53)
// flink-cdc-pipeline-connector-iceberg/.../utils/RowDataUtils.java
switch (dataChangeEvent.op()) {
    case INSERT:
    case UPDATE:
    case REPLACE:
        {
            recordData = dataChangeEvent.after();
            kind = RowKind.INSERT;
            break;
        }
    case DELETE:
        {
            recordData = dataChangeEvent.before();
            kind = RowKind.DELETE;
            break;
        }
    default:
        throw new IllegalArgumentException("don't support type of " + dataChangeEvent.op());
}

단순히 UPDATE를 INSERT로 변환해 버리면 기존 행이 남는다고 생각할 수 있는데요, 여기서 Iceberg의 equality-delete 메커니즘이 등장합니다.

IcebergWriter.java에서 RowDataTaskWriterFactory를 생성할 때, 테이블 스키마의 identifierFieldIds(= PK 필드 ID 목록)을 같이 전달하게 됩니다.

// IcebergWriter.java (Lines 133-147)
// flink-cdc-pipeline-connector-iceberg/.../v2/IcebergWriter.java
private RowDataTaskWriterFactory getRowDataTaskWriterFactory(TableId tableId) {
    Table table = catalog.loadTable(TableIdentifier.parse(tableId.identifier()));
    RowType rowType = FlinkSchemaUtil.convert(table.schema());
    RowDataTaskWriterFactory rowDataTaskWriterFactory =
            new RowDataTaskWriterFactory(
                    table,
                    rowType,
                    DEFAULT_MAX_FILE_SIZE,
                    FileFormat.fromString(DEFAULT_FILE_FORMAT),
                    new HashMap<>(),
                    new ArrayList<>(table.schema().identifierFieldIds()),
                    true);
    rowDataTaskWriterFactory.initialize(taskId, attemptId);
    return rowDataTaskWriterFactory;
}

table.schema().identifierFieldIds()는 Iceberg 테이블 스키마에서 PK(식별자 필드)들의 ID 목록을 가져옵니다. 이 목록이 비어 있지 않으면, Iceberg는 내부적으로 PartitionedDeltaWriter를 생성하게 됩니다. 이 Writer는 INSERT 행을 기록할 때, 같은 PK를 가진 기존 행을 무효화하는 동등 삭제(equality-delete) 파일을 함께 생성합니다. 따라서 UPDATE를 RowKind.INSERT로 내려보내도 equality-delete 파일이 함께 생성되어 올바른 upsert 시맨틱이 보장되는 것이죠.

단, 같은 PK(pk=1)에 대해 UPSERT가 두 번 도착하는 경우엔 두 가지 상황이 존재할 수 있습니다.

동일한 체크포인트에 포함되지 않는 경우
- 동등 삭제 파일의 경우 이전 체크포인트(커밋)된 데이터 파일에 대해서만 적용이 되기 때문에 두 번째 UPSERT의 데이터만 남게 되어 중복 적용의 영향이 없습니다.
두 개의 UPSERT가 동일한 체크포인트에 포함되는 경우
- Writer는 이미 삽입한 키를 insertedRows Map으로 추적하고 있기 때문에 position delete 기록 후 가장 마지막 UPSERT의 데이터만 남깁니다. 결과적으로 둘 다 중복 적용의 영향이 없습니다.

2단계: Checkpoint ID 기반 중복 커밋 방지

Writer 수준의 멱등성에 더해, Committer 수준에서도 중복된 체크포인트 커밋을 막습니다.

IcebergCommitter.java는 커밋 전에 현재 테이블의 스냅샷 히스토리를 조회하여, 같은 Checkpoint ID로 이미 커밋이 되었는지 확인합니다.

// IcebergCommitter.java (Lines 114-127)
// flink-cdc-pipeline-connector-iceberg/.../v2/IcebergCommitter.java
Snapshot snapshot = table.currentSnapshot();
if (snapshot != null) {
    Iterable<Snapshot> ancestors =
            SnapshotUtil.ancestorsOf(snapshot.snapshotId(), table::snapshot);
    long lastCheckpointId =
            getMaxCommittedCheckpointId(ancestors, newFlinkJobId, operatorId);
    if (lastCheckpointId == checkpointId) {
        LOGGER.warn(
                "Checkpoint id {} has been committed to table {}, skipping",
                checkpointId,
                tableId.identifier());
        continue;
    }
}

커밋이 실제로 실행될 때는 Checkpoint ID를 스냅샷 메타데이터에 기록합니다.

// IcebergCommitter.java (Lines 183-192)
private static void commitOperation(
        SnapshotUpdate<?> operation,
        String newFlinkJobId,
        String operatorId,
        long checkpointId) {
    operation.set(SinkUtil.MAX_COMMITTED_CHECKPOINT_ID, Long.toString(checkpointId));
    operation.set(SinkUtil.FLINK_JOB_ID, newFlinkJobId);
    operation.set(SinkUtil.OPERATOR_ID, operatorId);
    operation.commit();
}

이렇게 Iceberg 싱크는 두 단계로 멱등성을 보장합니다.

step 1 (레코드 수준): Upsert 시맨틱 + equality-delete로 같은 PK의 중복 레코드가 와도 최종 상태가 동일하다.
step 2 (커밋 수준): Checkpoint ID를 스냅샷에 기록하여, 같은 체크포인트의 파일을 두 번 커밋하는 것 자체를 방지한다.

4-2. Paimon: LSM-Tree Merge

Apache Paimon은 LSM-Tree 기반의 테이블 스토어로, PK 테이블에서 같은 키의 다중 레코드는 compaction 시 merge됩니다. Paimon의 merge 전략에서 기본값은 "deduplicate" -> 즉, 같은 PK의 가장 최신 레코드를 유지하는 것입니다.

PaimonWriterHelper.java는 두 가지 변환 메서드를 제공하는데요. 첫 번째는 단순 변환으로, Iceberg과 동일하게 INSERT/UPDATE/REPLACE를 모두 RowKind.INSERT로 매핑하는 방식입니다.

// PaimonWriterHelper.java (Lines 210-236)
// flink-cdc-pipeline-connector-paimon/.../v2/PaimonWriterHelper.java
public static GenericRow convertEventToGenericRow(
        DataChangeEvent dataChangeEvent, List<RecordData.FieldGetter> fieldGetters) {
    GenericRow genericRow;
    RecordData recordData;
    switch (dataChangeEvent.op()) {
        case INSERT:
        case UPDATE:
        case REPLACE:
            {
                recordData = dataChangeEvent.after();
                genericRow = new GenericRow(RowKind.INSERT, recordData.getArity());
                break;
            }
        case DELETE:
            {
                recordData = dataChangeEvent.before();
                genericRow = new GenericRow(RowKind.DELETE, recordData.getArity());
                break;
            }
        ...
    }
    ...
}

두 번째는 full changelog 변환으로, UPDATE를 UPDATE_BEFORE + UPDATE_AFTER 쌍으로 분리하는 방식입니다.

// PaimonWriterHelper.java (Lines 239-280)
public static List<GenericRow> convertEventToFullGenericRows(
        DataChangeEvent dataChangeEvent,
        List<RecordData.FieldGetter> fieldGetters,
        boolean hasPrimaryKey) {
    List<GenericRow> fullGenericRows = new ArrayList<>();
    switch (dataChangeEvent.op()) {
        case INSERT:
            {
                fullGenericRows.add(
                        convertRecordDataToGenericRow(
                                dataChangeEvent.after(), fieldGetters, RowKind.INSERT));
                break;
            }
        case UPDATE:
        case REPLACE:
            {
                if (hasPrimaryKey) {
                    fullGenericRows.add(
                            convertRecordDataToGenericRow(
                                    dataChangeEvent.before(),
                                    fieldGetters,
                                    RowKind.UPDATE_BEFORE));
                }
                fullGenericRows.add(
                        convertRecordDataToGenericRow(
                                dataChangeEvent.after(), fieldGetters, RowKind.UPDATE_AFTER));
                break;
            }
        case DELETE:
            {
                if (hasPrimaryKey) {
                    fullGenericRows.add(
                            convertRecordDataToGenericRow(
                                    dataChangeEvent.before(), fieldGetters, RowKind.DELETE));
                }
                break;
            }
        ...
    }
    return fullGenericRows;
}

여기서 주목할 점은 hasPrimaryKey 조건입니다.

PK가 있는 테이블에서는 UPDATE_BEFORE + UPDATE_AFTER 쌍을 생성하고, PK가 없으면 UPDATE_AFTER만 생성합니다. PK 테이블의 경우 UPDATE_BEFORE와 UPDATE_AFTER가 중복 적용되어도, Paimon의 LSM-Tree merge 과정에서 같은 키의 레코드들은 "가장 최신 값"으로 merge되기 때문에 Compaction이 완료되면 PK당 하나의 최종 행만 남으므로 결과적으로 멱등합니다.

PK가 없는 테이블의 경우 어떤 행을 삭제할지 식별할 키가 없기 때문에 보통 append-only로 쓰입니다. 따라서 UPDATE_AFTER만 생성하게 됩니다.

4-3. Fluss: PK 유무에 따른 자동 분기

Fluss 싱크 커넥터는 테이블에 Primary Key가 있는지 없는지에 따라 완전히 다른 Writer를 생성합니다.

FlussSinkWriter.java를 보면

// FlussSinkWriter.java (Lines 115-124)
// flink-cdc-pipeline-connector-fluss/.../v2/FlussSinkWriter.java
Table table = connection.getTable(tablePath);
TableWriter writer;
if (table.getTableInfo().hasPrimaryKey()) {
    writer = table.newUpsert().createWriter();
} else {
    writer = table.newAppend().createWriter();
}
tableMap.put(tablePath, table);
writerMap.put(tablePath, writer);

PK가 있으면 UpsertWriter를, 없으면 AppendWriter를 사용합니다.

당연하게도 실제 쓰기 시에 Writer 타입에 따라 연산이 분기됩니다.

// FlussSinkWriter.java (Lines 160-191)
private CompletableFuture<?> write(
        TableWriter writer, FlussOperationType opType, InternalRow row, TablePath tablePath)
        throws IOException {
    if (writer instanceof UpsertWriter) {
        UpsertWriter upsertWriter = (UpsertWriter) writer;
        if (opType == FlussOperationType.UPSERT) {
            return upsertWriter.upsert(row);
        } else if (opType == FlussOperationType.DELETE) {
            return upsertWriter.delete(row);
        } else {
            throw new UnsupportedOperationException(
                    String.format(
                            "Unsupported operation type: %s for primary key table %s",
                            opType, tablePath));
        }
    } else if (writer instanceof AppendWriter) {
        AppendWriter appendWriter = (AppendWriter) writer;
        if (opType == FlussOperationType.APPEND) {
            return appendWriter.append(row);
        } else {
            throw new UnsupportedOperationException(
                    String.format(
                            "Unsupported operation type: %s for log table %s",
                            opType, tablePath));
        }
    } else {
        throw new UnsupportedOperationException(...);
    }
}

UpsertWriter는 upsert와 delete 두 가지 연산만 지원한다. 위에서 언급했듯이 upsert는 멱등하고 delete도 멱등하므로, 중복 적용에 안전합니다. 반면 AppendWriter는 append 연산만 지원합니다. PK가 없는 append-only 테이블에서는 upsert가 불가능하고, 중복 이벤트가 도착하면 같은 행이 두 번 삽입됩니다.

Paimon에서도 그렇듯, PK가 없는 경우엔 upsert 기반 멱등성의 한계를 보여주게 됩니다.

5. Upsert가 재처리를 할 수 있게 하는 3가지 조건

지금까지 Flink CDC에서 여러 싱크 커넥터가 재처리에 대한 중복 적용 위험에 대해 UPSERT 시멘틱을 통해 해결하는 것을 살펴보았습니다. 마지막으로 UPSERT가 재처리를 가능하게끔 하는 필수 요건에 대해 살펴보고 마무리합니다.

PK가 반드시 필요합니다.
DELETE 연산 시, 없는 레코드를 삭제해도 에러가 발생하면 안 됩니다.
같은 키에 여러 번 업데이트가 발생했을 때, 가장 마지막에 쓰인 값이 최종 값이 되어야 합니다.

글을 작성하며 여러 공식 문서를 살펴보았는데요, 가장 중요한 전제 조건은 Primary Key의 존재입니다.

PK가 없는 테이블에서는 upsert가 불가능하기 때문인데요, 이 밖에도 초기 스냅샷 시 PK가 없다면 정합성이 어긋날 위험도 있는 등 CDC 연동 과정에서 반드시 필요한 필드입니다. 만약 CDC 파이프라인 연동 과정에서 PK가 존재하지 않는 테이블이라면.. 다시 생각해 볼 필요가 있겠습니다.

[flink-cdc] Iceberg sink connector에서의 default value 지원

suhwanc — Sat, 14 Feb 2026 16:31:34 +0900

https://github.com/apache/flink-cdc/pull/4277

[FLINK-39055] [Iceberg] Support default column values in Iceberg sink connector by suhwan-cheon · Pull Request #4277 · apache/

Summary In the Iceberg table version 3, default value support for columns https://iceberg.apache.org/spec/#version-3-extended-types-and-capabilities Add default column value support for Iceberg...

github.com

Iceberg 1.8.0부터 소개된 table format 3에는 칼럼에 대해서 default value를 지원하는 기능이 포함되어 있습니다. 이에 대응하여 flink-cdc에서도 default value를 지원할 수 있도록 수정한 내용을 소개합니다.

배경

왜 Default Values가 필요한가?

실시간 CDC(Change Data Capture) 파이프라인을 운영하다 보면, 소스 데이터베이스에서 스키마 변경이 발생하는 것은 피할 수 없습니다. 특히 ALTER TABLE ADD COLUMN... DEFAULT 'value'처럼 기본값이 있는 컬럼을 추가하는 경우, 싱크 테이블에서도 이 기본값이 올바르게 반영되어야 합니다.

Flink CDC의 Iceberg 싱크 커넥터는 스키마 변경(컬럼 추가, 삭제, 타입 변경 등)은 지원했지만, 칼럼의 기본값(default value)은 무시하고 있었습니다. 이로 인해 다음과 같은 문제가 발생할 수 있습니다.

AI로 만들어 보았어요

소스 DB에서 DEFAULT 'active'로 정의된 칼럼이 Iceberg에는 기본값 없이 생성됨 (스키마가 동일하지 않음)
새로 추가된 컬럼에 값이 없으면 null로 처리되어 소스와 싱크 간 데이터 불일치 발생

이 문제를 Iceberg에서 제공하는 API를 이용해 CDC 적재 시 메타데이터를 변경하여 해결해 보았습니다.

해결 방법

1. 기본값 파싱 및 변환

Flink CDC에서는 default value를 파싱 하는 함수는 기본적으로 지원하는데요, 이를 Iceberg가 이해할 수 있는 타입별 Literal <?> 객체로 변환하는 로직이 추가로 필요했습니다.

@Nullable
public static Literal<?> parseDefaultValue(
        @Nullable String defaultValueExpression, DataType cdcType) {
    if (defaultValueExpression == null) {
        return null;
    }
    try {
        switch (cdcType.getTypeRoot()) {
            case CHAR:
            case VARCHAR:
                return Literal.of(defaultValueExpression);
            case BOOLEAN:
                if ("true".equalsIgnoreCase(defaultValueExpression)) {
                    return Literal.of(true);
                } else if ("false".equalsIgnoreCase(defaultValueExpression)) {
                    return Literal.of(false);
                } else {
                    LOG.warn(
                            "Invalid boolean default value '{}', skipping default value.",
                            defaultValueExpression);
                    return null;
                }
            case TINYINT:
            case SMALLINT:
            case INTEGER:
                return Literal.of(Integer.parseInt(defaultValueExpression));
            case BIGINT:
                return Literal.of(Long.parseLong(defaultValueExpression));
            case FLOAT:
                return Literal.of(Float.parseFloat(defaultValueExpression));
            case DOUBLE:
                return Literal.of(Double.parseDouble(defaultValueExpression));
            case DECIMAL:
                int scale = DataTypes.getScale(cdcType).orElse(0);
                return Literal.of(
                        new java.math.BigDecimal(defaultValueExpression)
                                .setScale(scale, java.math.RoundingMode.HALF_UP));
            default:
                LOG.warn(
                        "Unsupported default value type {} for expression '{}', skipping default value.",
                        cdcType.getTypeRoot(),
                        defaultValueExpression);
                return null;
        }
    } catch (NumberFormatException e) {
        LOG.warn(
                "Failed to parse default value '{}' for type {}, skipping default value.",
                defaultValueExpression,
                cdcType.getTypeRoot(),
                e);
        return null;
    }
}

지원하는 타입은 Flink CDC의 파싱 로직에 의존합니다.

여기서는 uuid(), CURRENT_TIMESTAMP()와 같은 불명확한 default value 값의 경우 처리하지 않는 것을 원칙으로 합니다.

2. 스키마 변경 시 default values 적용

default values가 적용되는 시나리오는 두 가지입니다.

#1. CREATE TABLE (테이블 최초 생성 시)

소스 DB 테이블을 Iceberg에 최초 생성할 때, 칼럼에 정의된 기본값을 함께 설정합니다.

// 테이블 생성 후 기본값 적용
Table table = catalog.createTable(tableIdentifier, icebergSchema, partitionSpec,
 tableOptions);
applyDefaultValues(table, cdcSchema);


// applyDefaultValues는 Iceberg의 updateColumnDefault API를 사용합니다
private void applyDefaultValues(Table table, Schema cdcSchema) {
    UpdateSchema updateSchema = null;
    for (Column column : cdcSchema.getColumns()) {
        Literal<?> defaultValue = IcebergTypeUtils.parseDefaultValue(
                column.getDefaultValueExpression(), column.getType());
        if (defaultValue != null) {
            if (updateSchema == null) {
                updateSchema = table.updateSchema();
            }
            updateSchema.updateColumnDefault(column.getName(), defaultValue);
        }
    }
    if (updateSchema != null) {
        updateSchema.commit();
    }
}

코드 주석에도 명시했듯이 Iceberg의 updateColumnDefault API를 사용해 칼럼명과 기본값을 넘겨주면 됩니다.

이 방식은 Iceberg 메타데이터에 write-default를 설정합니다. 테이블이 방금 생성되어 기존 데이터가 없으므로, 이후 쓰기 시 기본값이 적용됩니다. write-default에 대해서는 밑에서 좀 더 자세히 설명하겠습니다.

#2. ADD COLUMN (칼럼을 추가할 때)

운영 중인 테이블에 default values를 가진 새 칼럼이 추가되는 상황입니다.

Literal<?> defaultValue = IcebergTypeUtils.parseDefaultValue(
        addColumn.getDefaultValueExpression(), addColumn.getType());
if (defaultValue != null) {
    updateSchema.addColumn(columnName, icebergType, columnComment,
defaultValue);
} else {
    updateSchema.addColumn(columnName, icebergType, columnComment);
}

이 경우 좀 더 단순하게 Iceberg의 addColumn API에 기본값을 같이 넣어 전달합니다.

이 방식은 Iceberg 메타데이터에 initial-default, write-default 모두를 설정합니다.

initial-default, write-default 설명

write-default: 이후 새로운 행을 쓸 때, 해당 칼럼에 값이 없으면 이 기본값 사용
initial-default: 컬럼 추가 이전에 이미 기록된 데이터 파일을 읽을 때, 해당 칼럼의 기본값으로 사용 (Iceberg format v3부터 사용 가능)

Iceberg가 사용하는 메타데이터 구조의 최적화된 성질로 인해 이런 값을 추가로 넣는 것으로 보입니다.

굳이 데이터 파일에 default 값을 전부 넣을 필요 없이 조회 시점에 기본 값을 채워 넣는 것이죠.

주의 사항

initial-default는 Iceberg format v3에서 지원하는데요, 이게 쿼리 엔진(Spark, trino..)에서 이 기능을 지원하는지 확인이 필요합니다.

결국 이 키 값은 쿼리 엔진의 영향을 크게 받기 때문입니다.

Spark의 경우 Iceberg 1.8.0+에서 parquet reader로 initial default 값에 대한 처리를 지원해 주는 것으로 확인됩니다.
- (https://github.com/apache/iceberg/pull/11803)

Iceberg - Deletion Vectors 기능 탐구

suhwanc — Sat, 7 Feb 2026 18:24:56 +0900

https://iceberg.apache.org/spec/?h=deletion+vec

Spec - Apache Iceberg™

Iceberg Table Spec This is a specification for the Iceberg table format that is designed to manage a large, slow-changing collection of files in a distributed file system or key-value store as a table. Format Versioning Versions 1, 2 and 3 of the Iceberg s

iceberg.apache.org

Iceberg table format version 3에 소개된 Deletion Vectors 기능에 대해 살펴봅니다.

탄생 배경

Iceberg는 기존에 다음과 같은 문제점을 겪고 있었습니다.

쓰기 효율(MoR)과 읽기 성능(CoW) 사이의 고질적인 트레이드오프, 그리고 삭제 파일 누적으로 인한 성능 저하 문제

대표적으로 Iceberg의 테이블 버전 2에는 데이터를 업데이트 하거나 삭제하는 Write 과정에서 두 가지 전략을 사용할 수 있습니다.

Copy on Write (CoW): 새로운 데이터 파일을 만들고, 다음부터 이 버전의 파일을 사용하도록 합니다.
Merge on Read (MoR): 수정/삭제된 정보만 별도의 삭제 파일에 기록합니다.

출처: https://medium.com/@amananand1701/efficient-data-management-with-apache-iceberg-cow-vs-mor-b7d6fb95f36c

그리고 이 두 전략은 다음과 같은 장단점이 존재합니다.

CoW
- Write: 새로운 파일을 만드는 것에 대한 오버헤드가 존재합니다. (Bad)
- Read: 그대로 읽기만하면 되므로 매우 빠릅니다. (Good)
MoR
- Write: 변경된 내용만 기록하면 되므로 쓰기 속도가 매우 빠릅니다. (Good)
- Read: 데이터를 읽을 때 삭제 파일과 비교 과정을 거치므로 오버헤드가 존재합니다. (Bad)

또한 MoR 방식은 삭제 파일을 만든다고 언급했는데요, 이 삭제 파일의 종류는 두 가지가 있습니다.

Equality delete
- 삭제해야 할 레코드의 PK 값을 저장합니다.
- 예를 들어, id = 100인 행을 모두 삭제 (Upsert와 비슷한 동작 방식)
- 데이터를 읽을 때 모든 레코드를 삭제 파일에 있는 값들과 일일이 비교(Join) 해야 하므로 읽기 성능이 떨어질 수 있습니다.
Position delete
- 삭제해야 할 데이터의 정확한 위치를 기록합니다.
- 파일의 경로(File Path)와 해당 파일 내의 행 번호(Row Position)를 저장합니다.
- 삭제하려는 데이터가 정확히 어느 파일의 몇 번째 줄에 있는지 먼저 찾아내야하므로 쓰기 시점에 약간의 오버헤드가 발생할 수 있습니다.

이러한 트레이드오프가 있기 때문에 기존의 사용자들은 자신의 프로젝트 특성에 알맞게 CoW, MoR 중 하나를 고르고는 했습니다.

대표적으로 CDC 프로젝트의 경우 실시간으로 파일을 쓰는 연산이 주를 이루기 때문에, Iceberg에 데이터를 적재하는 경우 MoR + Equality delete 방식이 좀 더 적합할 수 있습니다.

여기서 Iceberg는 MoR 방식 중 Position delete 과정을 더 효율적으로 최적화하기 시작합니다.

Partition-scoped Deletes (AS-IS)
- 특정 파티션 내 데이터가 삭제되면, 해당 파티션에 속한 Position Delete 파일이 생성된다.
- 예를 들어, date=2026-02-07 파티션에 Equality Delete 파일이 생성되면, Iceberg 엔진은 해당 날짜 파티션의 어떤 데이터 파일을 읽더라도 반드시 이 삭제 파일을 불러와서 비교(Join) 해야 합니다.
File-scoped Deletes (TO-BE)
- Iceberg v1.8.0에 나온 삭제 방식으로, table format 2 설정 시 동작합니다.
- 삭제 파일이 특정 데이터 파일에만 종속되도록 범위를 좁히는 방식입니다.
  - 쓰기 시점: 삭제 파일이 어떤 데이터 파일들에 적용되는지 명시 (데이터 파일 A, B, C에 영향)
  - 읽기 시점: 데이터 파일 A를 읽을 때, A에 링크를 걸어둔 삭제 파일만 확인합니다.

아무래도 File-scoped 방식이 쓰기 시점에는 조금 느리더라도 삭제 파일을 찾는 과정이 워낙 빠르다 보니 읽기에서 압도적으로 좋습니다.

다만 이 과정도 결국엔 삭제 파일을 생성해야 하며, 삭제 파일 조인의 유혹(?)을 피할 수 없게 됩니다.

Deletion Vectors는 이런 문제를 파일이 아닌 벡터, 비트맵 단위로 해결합니다.

Deletion Vectors

이제는 삭제 파일이 아니라, 삭제 벡터입니다. 본능적으로 일단 더 효율적일 것만 같습니다

출처: https://www.starburst.io/blog/iceberg-v3/

Deletion Vector(DV)는 기존의 Position Delete 방식을 훨씬 더 가볍고 빠르게 개선한 방식으로, 삭제된 위치 정보를 파일 형태가 아니라 비트맵(Bitmap) 형태로 압축해서 관리하는 기술입니다.

Deletion Vector의 특징

1. Bitmap을 활용한 초고속 검색

삭제된 행의 위치(Position P)를 0과 1로 이루어진 비트맵에 표시합니다. 예를 들어, 5번째 행이 삭제되었다면 비트맵의 5번 인덱스를 1(Set)로 바꿉니다.

기존 Position Delete 파일은 삭제된 번호 목록을 일일이 읽어서 비교해야 했지만, DV는 메모리 효율이 극도로 높은 Roaring Bitmap을 사용하여 특정 행이 삭제되었는지 즉시(O(1)에 가깝게) 확인할 수 있습니다.

2. Roaring Bitmaps을 사용한 위치 정보 최적화

Roaring Bitmaps은 대규모 데이터 시스템 전반에 사용되는 비트맵 관리 전략입니다.

DV에서는 32비트 Key/Value 분할 방식을 사용합니다. 앞의 32비트는 Key, 뒤의 32비트는 Sub-position으로 나눕니다.

Key 값은 어느 구역(Bucket)에 속하는가? 를 의미하고, Sub-position은 그 구역 안에서 정확히 몇 번째 행인가?를 결정합니다.

이를 기반으로 매우 큰 숫자를 저장할 때 공간 효율적인 특성을 가집니다.

참고

Roaring Bitmaps은 그 자체로 상당히 복잡한 방식이라 잘 정리된 문서를 보시는 것을 추천드립니다.

https://machine-learning-made-simple.medium.com/an-introduction-to-roaring-bitmaps-for-software-engineers-dd988 59dd29a

An Introduction to Roaring Bitmaps for Software Engineers

How Roaring Bitmaps improve sets.

machine-learning-made-simple.medium.com

3. Puffin Files

DV는 일반 데이터 파일이 아닌, Iceberg 전용 통계 저장 포맷인 Puffin File 내에 Blob의 형태로 저장됩니다.

기존 MoR 방식에서는 삭제 파일의 형태는 일반적으로 parquet/ORC로 디스크에 저장되어 처리 시 Deserialization 과정을 거쳤는데요, Puffin 파일로 저장할 경우 이러한 변환 과정(Deserialization)이 생략되기 때문에 I/O 효율이 매우 좋아집니다.

또한 기존 Position Delete 방식에서는 데이터 파일 하나에 여러 개의 삭제 파일이 연결될 수 있었습니다. 이런 성향으로 인해 수 많은 삭제 파일이 쌓이면서 I/O 성능을 저하시키는 현상이 발생했습니다.

하지만 Puffin File에는 여러 개의 DV를 넣을 수 있기 때문에 삭제 파일이 과하게 생기는 문제를 해결할 수 있습니다.

4. 데이터 파일 당 최대 하나의 DV

하지만 DV에서는 특정 행에 삭제가 아무리 많이 일어나도, 하나의 데이터 파일에는 논리적으로 최대 한 개의 DV가 생기는 것을 보장합니다.

만약 어떤 데이터 파일에 DV가 쓰였고, 이 데이터 파일에 변화가 일어나면 Bitwise OR 연산을 하기 때문에, 하나의 DV(비트맵)로 관리할 수 있는 것이죠.

이는 삭제 파일 수의 감소뿐만아니라, 로직으로도 데이터 파일을 가져올 때 최대 한 개의 DV만 필터링하면 되므로 꽤나 단순해지는 효과가 있습니다.

정리하자면 Deletion Vectors 방식은 쓰기 및 저장 방식이 복잡해졌지만 읽기/쓰기의 성능 효율이 매우 좋아졌습니다.

연산 속도 개선: Bitmap을 활용해 Read/Write 연산 속도가 아주 빨라졌습니다.
저장 방식 효율화: Roaring Bitmap으로 저장 방식이 효율적으로 개선되었습니다.
디스크 I/O 개선: Puffin 파일 형태로 저장하여 디스크 I/O를 개선할 수 있습니다.
삭제 파일 감소 및 일관성 보장: "데이터 파일 당 최대 하나의 DV"라는 일관성을 보장할 수 있습니다.

사용자 입장에서는 데이터가 어떻게 변화되었든 단 하나의 비트맵 필터만 거치면 되기 때문에, MoR 방식임에도 불구하고 CoW에 근접하는 읽기 성능을 낼 수 있게 된 것입니다.

여담

Deletion Vectors의 메인 아이디어는 Iceberg에서 독자적으로 생각한 것이라기 보단, Databricks의 Delta Lake의 아이디어에서 파생된 것이라고 합니다. (출처 - Iceberg 공식 유튜브 소개)

참고

https://iceberg.apache.org/puffin-spec/

https://lestermartin.blog/2025/10/08/understanding-iceberg-deletion-vectors-and-enjoying-some-humble-pie/

https://www.youtube.com/watch?v=WqViqjpLsnE

OLAP 시스템 디자인 기초

suhwanc — Sat, 7 Feb 2026 10:26:40 +0900

System Design for OLAP Workloads

OLAP(Online Analytical Processing) 시스템의 가장 기본적인 컴포넌트 구조는 위와 같이 정리할 수 있습니다.

가장 기초적인 컴포넌트부터 알아봅시다.

Storage

OLAP은 기본적으로 방대한 데이터를 저장하고, 분석하는 것을 목표로 합니다.

만약 아주 적은 데이터라면 굳이 OLAP을 쓸 필요 없이 OLTP로 트랜잭션, 분석을 동시에 해도 상관 없기 때문입니다.

OLAP에서 사용하는 스토리지는 이런 선택지가 있습니다.

로컬 파일 시스템
분산 파일 시스템 (HDFS)
객체 스토리지 (S3)

또한 저장 방식의 유형과 관련해, 행 지향(Row-oriented) 데이터베이스와 열 지향(Columnar) 데이터베이스를 사용할 수 있습니다.

최근에는 열 지향 데이터베이스가 방대한 양의 데이터를 처리할 때 더 효율적임이 입증되면서 많이 사용하고 있습니다.

보통 분석 시스템에서는 특정 항목의 통계를 내는 일이 많은데, 예를 들면 "지난달의 총 매출은?", "어제 방문자 수는?" 이런 분석을 할 때 "매출" 또는 "방문자 ID"에 해당하는 컬럼의 데이터만 집계하면 되기 때문에 열 지향 데이터베이스가 효율적인 경우가 많습니다.

File format

파일 포맷은 일반적으로 세 가지 범주가 있습니다.

정형(CSV)
반정형(JSON)
비정형(Text)

그리고 정형과 반정형 범주에서 파일 포맷은 또 행 지향(Row-Oriented), 열 지향(Columnar)으로 나뉩니다.

대표적으로 행 지향 파일 포맷에는 CSV, Avro, 열 지향 파일 포맷에는 Parquet, ORC가 있습니다.

특징은 위 데이터베이스에서 설명한 것과 마찬가지인데, 그럼 행 지향이 유리한 경우는 없을까? 물어본다면 다음과 같은 상황이 있을 수 있습니다.

매번 적은 행의 데이터만 추출하고자 할 때

만약 10억 건의 데이터가 있고, 그 중 100개의 행을 추출하고자 할 때

행 지향의 경우 100번의 접근을 하면 됩니다. 같은 행에 있는 데이터는 모두 붙어있기 때문입니다.

열 지향의 경우 행 마다 100개의 다른 컬럼 파일에 접근해야 합니다. 같은 컬럼끼리 데이터가 붙어있기 때문입니다. 따라서 1만 번의 읽기 연산이 필요합니다.

Table format

테이블 포맷은 파일 포맷 상단의 메타데이터 레이어의 역할을 합니다.

각 데이터 파일들이 스토리지에 어떻게 배치되어야 하는지를 규정하며, 사용자가 수천 개의 데이터 파일을 직접 관리할 필요 없이 마치 하나의 테이블처럼 다룰 수 있도록 도와줍니다. 직접 쿼리를 할 때는 하나의 데이블에 대해서만 작성하므로 테이블 포맷에서 이를 추상화했다고 볼 수 있습니다.

또한 ACID 트랜잭션을 보장해주기 때문에, 데이터 레이크에서도 마치 OLTP처럼 안전한 CRUD 연산이 가능해집니다.

Storage engine

테이블 포맷이 규정한 형태로 데이터를 배치해주는 역할을 합니다.

주로 물리적인 데이터 최적화, 인덱스 관리, 오래된 데이터의 삭제(Iceberg의 maintenance) 역할을 맡습니다.

Catalog

주로 중앙에 위치하여 테이블의 메타데이터를 활용해 데이터를 최대한 빠르게 찾을 수 있도록 도와주는 역할을 합니다.

비유가 적절할지 모르겠지만, 책의 목차와 비슷하다고 볼 수 있어요.

주로 hive 카탈로그를 많이 쓰는데, 그 이유는 여러 테이블 포맷에서 쓸 수 있도록 개방해두었기 때문입니다.

Compute engine

방대한 양의 데이터를 효율적으로 처리하는 역할을 합니다.

주로 대량 병렬 처리 엔진을 자주 쓰며, 대표적인 예로 Spark가 있습니다.

출처

https://product.kyobobook.co.kr/detail/S000208452383

Apache Iceberg | Tomer Shiran - 교보문고

Apache Iceberg | By following the lessons in this book, you'll be able to achieve interactive, batch, machine learning, and streaming analytics with this lakehouse. Authors Tomer Shiran, Jason Hughes, Alex Merced, and Dipankar Mazumdar from Dremio guide yo

product.kyobobook.co.kr

[flink-cdc] VARIANT 타입과 PARSE_JSON 함수

suhwanc — Sat, 31 Jan 2026 10:21:29 +0900

https://github.com/apache/flink-cdc/pull/4249

[FLINK-38985][docs] Add documentation for VARIANT type and PARSE_JSON functions by suhwan-cheon · Pull Request #4249 · apache/

Summary Add documentation for VARIANT type support and PARSE_JSON/TRY_PARSE_JSON functions introduced in recent PRs. (in https://issues.apache.org/jira/browse/FLINK-38874 issue - sub tasks) Notes ...

github.com

Flink 2.1.0에서 반정형 데이터를 지원하는 VARIANT 타입과 이를 파싱하기 위한 PARSE_JSON가 도입되었습니다.

Flink cdc 라이브러리에서도 YAML 형태의 파이프라인에서 이에 대응하기 위해 기능을 추가했고, 이에 대한 Docs 작업 중 알게된 것들을 정리합니다.

VARIANT 타입

https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/dev/table/types/#variant

Data Types

Data Types # Flink SQL has a rich set of native data types available to users. Data Type # A data type describes the logical type of a value in the table ecosystem. It can be used to declare input and/or output types of operations. Flink’s data types are

nightlies.apache.org

VARIANT는 반정형 데이터(semi-structured data)를 위한 타입입니다

반정형 데이터란 정해진 규격이 없는 데이터로 JSON, MAP과 같이 유연하게 사용할 수 있는 타입을 의미합니다.

예를 들어 동일한 JSON 타입이래도 어떤 레코드에는 있는 필드가 다른 레코드에는 없을 수도 있습니다.

{
  "이름": "홍길동",
  "직업": "개발자",
  "기술": ["Python", "SQL", "Cloud"]
}

해당 타입의 장점은 테이블 스키마의 변경 없이도 새로운 필드를 추가할 수 있다는 점입니다.

일반적으로 NOSQL에 저장되는 데이터가 그러하며, MySQL과 같은 RDBMS에서도 이런 필드를 지원합니다.

PARSE_JSON 함수

https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/dev/table/functions/systemfunctions/#variant-functions

System (Built-in) Functions

System (Built-in) Functions # Flink Table API & SQL provides users with a set of built-in functions for data transformations. This page gives a brief overview of them. If a function that you need is not supported yet, you can implement a user-defined funct

nightlies.apache.org

JSON 문자열을 VARIANT 타입으로 파싱하는 기능을 합니다.

Flink에서는 두 번째 인자로 allow_duplicate_keys 옵션을 제공하는데요, 이는 중복 키에 대해 어떻게 처리할지 여부를 지정합니다.

만약 allow_duplicate_keys 값이 true라면 키의 중복을 허용하고, 나중에 나온 Value를 최종값으로 정합니다.

예를 들어 아래와 같은 JSON 값이 있을 때

{
  "name": "suhwan",
  "age": 20,
  "age": 25 <-- 나중에 나온 25가 채택
}

처음 나온 20은 무시되며, 25가 age의 Value로 채택되는 것이죠.

보통 이런 옵션은 예측이 불가능하기 때문에 잘 사용하지 않을 것 같고.. 기본값도 false입니다. 중복시 에러를 뱉어내게 됩니다.

추가로 TRY_PARSE_JSON 함수가 있는데요, 이 함수는 PARSE_JSON과 거의 비슷하나 JSON 형식에 맞지 않는 경우 NULL을 반환하도록 합니다. JSON 파싱 실패 시 전체 작업이 실패하는 것을 방지하거나, COALESCE(TRY_PARSE_JSON(col), default_value) 같은 패턴으로 fallback 처리하고 싶은 경우 사용할 수 있습니다.

Flink CDC에서 이 타입을 지원한 이유

만약 Flink CDC가 지원하는 Source, Sink DB에 VARIANT 타입을 지원하는 곳이 없다면, 이 기능은 의미가 없습니다.

제가 사용하는 MySQL, Iceberg에는 이러한 타입이 없어서 찾아본 결과, Apache Paimon에서 이런 타입을 제공해주고 있었습니다.

따라서 Paimon의 Sink connector 부분에 관련 PR이 반영되었고, 이를 지원하기 위해 VARIANT 타입 관련 코드가 정말 많이 추가되었습니다. 대부분 Flink 코어 레포의 변경 사항을 그대로 가져온거긴 하지만 CDC 라이브러리 운영도 참 쉽지 않다는 생각을 했네요..

TO DO

작업 중 Flink SQL은 Calcite -> Janino 형태로 해석 및 처리되는 것을 알았습니다.

Calcite는 사용자가 입력한 SQL 문장을 컴퓨터가 이해할 수 있는 트리 구조로 변환 및 최적화하는 기능이며

Janino는 Calcite가 세운 계획을 실제 실행 가능한 Java 코드로 변환한 뒤 실시간으로 컴파일해서 실행하는 역할을 한다고 합니다.

-> 추후 Flink SQL 내부 코드를 보며 공부해보기

[flink-cdc] MySQL 커넥터의 BIGINT UNSIGNED 무한 Chunk Splitting 버그

suhwanc — Sun, 18 Jan 2026 19:47:06 +0900

Issue

https://issues.apache.org/jira/browse/FLINK-38247

[FLINK-38247] MySqlChunkSplitter may continuously generate splits when using BIGINT UNSIGNED as primary key - ASF Jira

MySqlChunkSplitter may continuously generate splits when using BIGINT UNSIGNED as primary key, The following log illustrates this point: 2025-08-12 18:10:37,885 INFO org.apache.flink.cdc.connectors.mysql.source.assigners.MySqlChunkSplitter [] - Use unevenl

issues.apache.org

증상

(현재 flink-cdc 3.5.0 이하 버전에서 MySQL 커넥터를 사용해 BIGINT UNSIGNED 타입의 PK를 사용 시 발생하는 이슈입니다.)

MySqlChunkSplitter가 테이블을 chunk로 분할할 때 무한 루프에 빠지는 현상이 발생합니다.

발생 로그

2025-08-12 18:10:37,885 INFO MySqlChunkSplitter - Use unevenly-sized chunks for table lms_orderservice_0.order_attach_volume_charge_0, the chunk size is 8096 from 9159518964553691904
2025-08-12 18:10:37,892 INFO MySqlChunkSplitter - Use unevenly-sized chunks for table lms_orderservice_0.order_attach_volume_charge_0, the chunk size is 8096 from 9228590553717701376
2025-08-12 18:10:37,899 INFO MySqlChunkSplitter - Use unevenly-sized chunks for table lms_orderservice_0.order_attach_volume_charge_0, the chunk size is 8096 from 68365677240266752
2025-08-12 18:10:37,907 INFO MySqlChunkSplitter - Use unevenly-sized chunks for table lms_orderservice_0.order_attach_volume_charge_0, the chunk size is 8096 from 136590545025291264
2025-08-12 18:10:38,015 INFO MySqlChunkSplitter - ChunkSplitter has split 39800 chunks for table lms_orderservice_0.order_attach_volume_charge_0

이상한 점
로그를 자세히 보면 chunk의 시작 값이 비정상적으로 변합니다

순서	Chunk 시작 값	분석
1	9,159,518,964,553,691,904	Long.MAX_VALUE 근처
2	9,228,590,553,717,701,376	Long.MAX_VALUE 초과
3	68,365,677,240,266,752	갑자기 작은 값으로 떡락!
4	136,590,545,025,291,264	다시 여기서부터 증가

-> 정상적이라면 값이 계속 증가하다가 테이블의 최댓값에 도달하면 종료되어야 하는데, 이런 식의 무한 루프에 빠지고 있었습니다.

원인

1. 데이터 타입 범위 차이

MySQL의 BIGINT UNSIGNED 타입과 Java의 Long 타입은 서로 다른 범위를 가지고 있습니다.

MySQL BIGINT UNSIGNED
- 범위: 0 ~ 18,446,744,073,709,551,615 (2^64 - 1)
Java long
- 범위: -9,223,372,036,854,775,808 ~ 9,223,372,036,854,775,807 (2^63 - 1)

-> Java의 long은 MySQL BIGINT UNSIGNED 최대값의 절반밖에 표현하지 못합니다.

이 타입 범위가 문제인 이유는 MySQL 커넥터의 동작 방식이 문제가 있기 때문입니다.

2. MySQL Connector/J의 setObject() 동작

https://github.com/mysql/mysql-connector-j/blob/8.0.28/src/main/core-impl/java/com/mysql/cj/AbstractQueryBindings.java#L920

if (parameterObj instanceof BigInteger) {
    setLong(parameterIndex, ((BigInteger) parameterObj).longValue());
}

flink-cdc는 Chunk 과정에서 MySQL에 "여기부터 여기까지 가져갈거야~" 라는 값을 전달하게 되는데, 이때 BigInteger 값을 전달하면 MySQL 커넥터는 내부적으로 long으로 변환해 버립니다.

따라서 Long.MAX_VALUE를 초과하는 값은 오버플로우가 발생하게 되어 음수가 되어버릴 수 있는 위험이 있습니다.

3. 무한 Chunk Splitting 발생 메커니즘

flink-cdc의 Chunk Splitting 과정은 간략하게 설명하자면 다음과 같습니다.

테이블 PK의 MIN, MAX 값을 조회합니다. 여기서 PK는 CDC 파이프라인 실행 시, 사용자가 ChunkKeyColumn을 명시한 값을 의미합니다.
테이블의 대략적인 ROW 분포를 확인 후 Chunk 분할 방식을 결정합니다.
1. Evenly-sized chunks: 균등하게 분포되어 있어 사용자가 명시한 SplitSize 만큼씩 가져오게 됩니다.
2. Unevenly-sized chunks: 균등하지 않은 skew 상태로, 동적으로 chunk 경계를 찾게 됩니다.

이번 상황은 Unevenly-sized chunks으로, 동적으로 계속해서 chunk 경계를 찾는 과정을 반복합니다.

위에 적은 발생 로그가 그 과정의 일부라고 보면 됩니다.

(참고: https://github.com/apache/flink-cdc/blob/538b8faa1d8826f8d15a902a94a2e77b13e12093/flink-cdc-connect/flink-cdc-source-connectors/flink-connector-mysql-cdc/src/main/java/org/apache/flink/cdc/connectors/mysql/source/assigners/MySqlChunkSplitter.java#L325-L359)

그런데 이때, 다음 Chunk 값을 가져오는 과정에서 오버플로우가 발생해 음수가 반환되고 -> 다시 큰 값으로 증가 -> 다시 음수.. 과정을 반복하다 보니 무한 루프에 걸리게 된 것입니다.

해결

public static void setSafeObject(PreparedStatement ps, int parameterIndex, Object value)
        throws SQLException {
    if (value instanceof BigInteger) {
        ps.setBigDecimal(parameterIndex, new BigDecimal((BigInteger) value));
    } else {
        ps.setObject(parameterIndex, value);
    }
}

MySQL 커넥터에 chunk 계산에 필요한 값을 넘겨주는 부분에 위와 같은 함수를 거치도록 변경했습니다.

BigInteger 타입을 BigDecimal로 세팅하였고, MySQL 커넥터에서도 이 값은 그대로 BigDecimal로 해석하기 때문에 오버플로우의 염려는 없습니다.

또한 flink-cdc 공식 문서에도 BIGINT UNSIGNED 타입의 경우 Decimal(20,0)으로 변환하기 때문에, 이러한 처리는 문제없을 것으로 예상됩니다. (레코드 값에는 영향 X, 단지 chunkKey 계산 시에만 전달하는 값)

Github PR

https://github.com/apache/flink-cdc/pull/4117

[FLINK-38247] Handle BIGINT UNSIGNED overflow in PreparedStatement by suhwan-cheon · Pull Request #4117 · apache/flink-cdc

issue: https://issues.apache.org/jira/browse/FLINK-38247 Issue An infinite loop occurred when using the MySqlChunkSplitter to split a table with a MySQL BIGINT UNSIGNED primary key. (This problem h...

github.com

참고

- https://nightlies.apache.org/flink/flink-cdc-docs-release-3.5/docs/connectors/flink-sources/mysql-cdc/#data-type-mapping
- https://github.com/mysql/mysql-connector-j/blob/8.0.28/src/main/core-impl/java/com/mysql/cj/AbstractQueryBindings.java#L920