Kafka 기반 데이터 이관 실행 계획 정리

1. 정리 배경

대용량 PostgreSQL 데이터를 Oracle로 이관하면서,
단순한 “이론적 설계”가 아니라 실제 실행 단계에서 필요한 준비·순서·주의사항을
명확히 정리할 필요가 있었다.

Kafka + Debezium 기반 CDC 구조는
구성 요소가 많고, 순서를 잘못 잡으면 장애나 데이터 정합성 문제가 발생하기 쉽다.

이 글은 실제 운영 환경을 일반화하여 재구성한 Kafka 실행 계획과 체크리스트를
기술 블로그 형태로 정리한 것이다.

---

2. 전체 실행 흐름 요약

Kafka 기반 데이터 이관은 다음 흐름으로 진행된다.

1. PostgreSQL DB 백업
2. 백업본 외부 저장
3. Kafka 및 관련 컴포넌트 설치
4. Kafka를 통한 초기 데이터 이관 실행
5. 이관 결과 검증
6. 기존 데이터 정리
7. 실시간 CDC 이관 전환

핵심은
“백업 → 일괄 이관 → 검증 → 실시간 이관” 단계가 명확히 분리되어야 한다는 점이다.

---

3. PostgreSQL DB 백업 단계

3.1 백업 실행

• 관리자 또는 충분한 권한을 가진 계정으로 수행
• pg_dump를 이용한 전체 DB 백업

예시:

 

pg_dump -U postgres -h localhost -p 5432 -F c -f "/backup/postgres.dump" postgres

3.2 백업 검증

• 백업 파일 생성 여부 확인
• 파일 용량 확인
• 백업본 내부에 테이블이 정상적으로 포함되어 있는지 확인

3.3 외부 저장소 복사

• 외장 스토리지 또는 별도 저장 매체에 백업본 복사
• 로컬 서버 단일 보관 금지

👉 이 단계는
Kafka 이관 중 문제가 발생했을 때 되돌아갈 수 있는 유일한 안전장치다.

---

4. Kafka 설치 및 기본 설정

4.1 Kafka 설치

• 오프라인/온라인 환경에 맞게 설치
• Kafka 최신 안정 버전 사용
• KRaft 모드 기준 구성 (Zookeeper 미사용)

4.2 설정 파일 준비

사전에 작성된 설정 파일을 Kafka 설정 경로에 배치한다.

• server.properties
• connect-standalone.properties
• Source Connector 설정
• Sink Connector 설정

---

4.3 Cluster ID 생성 및 스토리지 포맷

Kafka KRaft 모드에서는
Cluster ID 기반 스토리지 포맷이 필수다.

 

# UUID 생성 (New-Guid).Guid

 

# 스토리지 포맷 kafka-storage.bat format \ --config server.properties \ --cluster-id {generated-uuid}

---

5. Kafka Connect 플러그인 준비

Kafka Connect 실행을 위해 필요한 플러그인을 준비한다.

필수 플러그인 예시

• PostgreSQL Source Connector (Debezium)
• JDBC Sink Connector
• Oracle JDBC Driver

👉 모든 플러그인은
Kafka의 plugins 디렉토리 하위에 위치해야 한다.

---

6. PostgreSQL CDC 설정

6.1 postgresql.conf 수정

논리 복제를 위한 설정 추가:

 

wal_level = logical max_replication_slots = 10 max_wal_senders = 10

설정 변경 후 PostgreSQL 재시작 필수

---

6.2 CDC 전용 사용자 생성

Debezium 전용 계정을 생성하고 권한을 부여한다.

 

CREATE USER debezium WITH REPLICATION LOGIN PASSWORD 'password';

 

GRANT CONNECT ON DATABASE postgres TO debezium; GRANT USAGE ON SCHEMA public TO debezium; GRANT SELECT ON ALL TABLES IN SCHEMA public TO debezium; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO debezium;

---

6.3 논리 복제 슬롯 생성

 

SELECT * FROM pg_create_logical_replication_slot( 'debezium_slot', 'pgoutput' );

👉 이 슬롯이 WAL 로그 보관과 CDC 흐름의 핵심 포인트가 된다.

---

7. Primary Key(SEQ) 컬럼 보완

Kafka Sink Connector를 통한 안정적인 적재를 위해
각 테이블에 PK 컬럼이 필요하다.

예시:

 

ALTER TABLE tb_sample ADD COLUMN seq BIGSERIAL; ALTER TABLE tb_sample ADD CONSTRAINT tb_sample_pkey PRIMARY KEY (seq);

이 작업 중에는
외부 시스템(예: 장비, 센서)으로부터의 데이터 수신이 중단될 수 있으므로
사전 공지가 필요하다.

---

8. 컬럼 타입 정비 (정합성 대비)

• 숫자 컬럼의 Precision / Scale 명확화
• Kafka → Oracle 이관 시 타입 불일치 방지 목적

예시 개념:

 

ALTER TABLE tb_sample ALTER COLUMN value1 TYPE NUMERIC(20,10);

대량 컬럼 수정 시
PL/pgSQL 루프를 사용해 일괄 처리 가능하다.

---

9. Oracle 측 사전 준비

• 대상 테이블 존재 여부 확인
• 필요 시 테이블 수정 또는 신규 생성
• Kafka Sink 계정에 권한 부여

 

GRANT INSERT ON target_table TO kafka_user; GRANT SELECT ON target_table TO kafka_user;

---

10. Kafka 기반 이관 실행

10.1 Kafka 서버 실행

 

kafka-server-start.bat server.properties

---

10.2 Kafka Connect 실행

• Standalone 모드 기준
• Source / Sink Connector 동시 실행

 

connect-standalone.bat \ connect-standalone.properties \ oracle-sink.json \ postgres-source.json

---

10.3 이관 검증

• 테이블 단위로 순차 진행
• 각 테이블별:
  • row count 비교
  • 샘플 데이터 검증
  • 에러 로그 확인

---

11. 기존 데이터 정리 및 실시간 CDC 전환

• 초기 이관 완료된 테이블은 검증 후 정리
• 이후 Kafka CDC를 통해 실시간 데이터 동기화 유지

이 시점부터는:

• 신규 데이터가 자동으로 Oracle로 반영됨
• PostgreSQL은 Source 역할만 수행

---

12. 실행 계획의 핵심 포인트

• 백업 없이는 절대 시작하지 않는다
• “일괄 이관”과 “실시간 이관”을 명확히 분리한다
• CDC 슬롯과 WAL 상태를 지속적으로 모니터링한다
• PK/타입 정합성은 사전에 최대한 맞춘다
• 한 번에 모든 테이블을 하지 않는다

---

13. 마무리

Kafka 기반 데이터 이관은
기술 자체보다 실행 순서와 운영 판단이 훨씬 중요하다.

• 어떤 설정을 언제 적용하는지
• 언제 검증하고, 언제 다음 단계로 넘어가는지
• 문제가 생겼을 때 어디로 되돌아갈 수 있는지

이 실행 계획은
그 판단을 구조화하기 위한 하나의 기준점이다.

---

 

※ 본 글은 실제 운영 환경을 일반화하여 재구성한 실행 계획 예시이며, 특정 회사·고객사·프로젝트의 내부 정보를 포함하지 않습니다.