PostgreSQL logical decoding과 Kafka 연동 전략

소개

PostgreSQL의 logical decoding은 WAL(Write-Ahead Log)을 읽어 데이터 변경을 논리적 이벤트로 변환하는 기능이다. 이를 Kafka와 연동하면 변경 데이터 캡처(Change Data Capture, CDC)를 통해 마이크로서비스, 데이터웨어하우스, 검색 인덱스 등으로 실시간 전파가 가능하다. 본문은 logical decoding postgres kafka 연동을 처음 접하는 사람도 이해하기 쉽도록 개념부터 설정, 실제 연동 방법을 단계별로 설명한다.

logical decoding 기본 개념

무엇을 하는가

logical decoding은 트랜잭션 단위의 INSERT/UPDATE/DELETE 이벤트를 추출한다. 물리적 WAL 복제와 달리 논리적으로 의미 있는 변경을 제공하기 때문에, 특정 테이블의 변경만 선택해서 처리할 수 있다.

핵심 요소

• wal_level: logical 모드가 필요
• replication slot: 변경 데이터를 유지하기 위한 슬롯
• output plugin: pgoutput, wal2json 등으로 포맷 선택

사전 준비

PostgreSQL 설정

PostgreSQL 측에서 몇 가지 설정이 필요하다. 크게 wal_level, max_replication_slots, max_wal_senders 등을 조정한다. 예시 SQL이나 설정 변경은 운영 환경 영향을 고려해 적용한다.

-- postgresql.conf 예시
wal_level = 'logical'
max_replication_slots = 10
max_wal_senders = 10

설정 변경 후에는 서버 재시작이나 reload가 필요하다.

플러그인과 버전

기본 제공되는 pgoutput를 사용하거나, JSON 형식을 선호하면 wal2json을 설치할 수 있다. pgoutput는 PostgreSQL 10 이상에서 기본 지원된다.

방법 1 — Debezium과 Kafka Connect 사용

개요

Debezium는 널리 쓰이는 CDC 솔루션으로 Kafka Connect와 함께 동작한다. 설정 난이도가 낮고 스키마 관리, 토폴로지 등 운영 편의 기능을 제공한다. pgoutput kafka 연동 postgres 환경에서 자주 사용된다.

Debezium connector 예제

아래는 Kafka Connect에 등록하는 Debezium PostgreSQL 커넥터의 최소 예시이다. connector.class와 database.server.name 등 필수 항목을 포함한다.

{
  "name": "inventory-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "plugin.name": "pgoutput",
    "database.hostname": "db-host",
    "database.port": "5432",
    "database.user": "debezium",
    "database.password": "dbpassword",
    "database.dbname": "mydb",
    "database.server.name": "dbserver1",
    "slot.name": "debezium_slot",
    "publication.name": "dbserver1_pub",
    "table.include.list": "public.products,public.orders"
  }
}

설치 이후 Kafka 토픽으로 변환된 이벤트를 소비하면 된다. Debezium은 스키마 변경도 자동으로 처리하도록 도와준다.

방법 2 — 직접 스트리밍 구현 (wal2json 또는 pg_recvlogical)

개요

간단한 파이프라인이나 커스터마이즈된 메시지 포맷이 필요하면 직접 읽어서 Kafka로 전송하는 방식이 유리하다. 예를 들어 wal2json을 사용하면 JSON으로 변환해 쉽게 파싱할 수 있다.

wal2json + kafkacat 예시

-- 복제 슬롯 생성
SELECT pg_create_logical_replication_slot('slot_wal2json', 'wal2json');

-- pg_recvlogical 사용 예시 (stdout로 스트리밍)
pg_recvlogical -d mydb -S slot_wal2json --start -f - --plugin wal2json

-- stdout를 받아 kafkacat로 전송 (Linux 파이프 예)
pg_recvlogical -d mydb -S slot_wal2json --start -f - --plugin wal2json | kafkacat -P -b kafka:9092 -t db-changes

또는 파이썬/자바로 복제 스트림을 읽어 Kafka 클라이언트로 전송하는 맞춤형 애플리케이션을 개발할 수 있다.

운영 시 고려사항

• 복제 슬롯이 제거되지 않으면 WAL이 계속 보관돼 디스크 사용량 증가 발생
• 논리적 슬롯은 소비 속도에 영향을 받으므로 모니터링 필요
• 스키마 진화 관리: 필드 추가/삭제 시 소비자 쪽 호환성 검토
• 메시지 순서 보장: 파티셔닝 키 설계로 일관성 유지

성능 팁

• 필요한 테이블만 publication에 포함해서 전송량 최소화
• 배치 사이즈와 Kafka 프로듀서 설정으로 전송 효율 최적화
• 모니터링을 통해 replication lag과 슬롯 보유 시간 점검

요약

postgres logical decoding 사용법의 핵심은 WAL을 논리 이벤트로 바꾸는 설정과 적절한 output plugin 선택이다. Kafka 연동은 Debezium을 활용하면 빠르게 도입 가능하고, 직접 구현하면 포맷과 흐름을 세밀하게 제어할 수 있다. 운영 환경에서는 복제 슬롯과 WAL 보관, 스키마 변화 관리에 주의하면서 설계하면 안정적인 CDC 파이프라인 구축이 가능하다.