Debezium을 사용한 Microsoft SQL Server 변경 데이터 캡처(CDC) 설정 가이드

Microsoft SQL Server에서 Debezium을 활용하여 변경 데이터를 캡처(CDC)하는 방법을 설명합니다. 이 가이드는 SQL Server Standard Edition 이상의 CDC 기능을 활용하여 Debezium 커넥터를 구성하는 방법을 다룹니다.

---

1. 전제 조건 (SQL Server 설정)

Debezium을 사용하여 SQL Server의 변경 데이터를 캡처하려면 먼저 CDC 기능을 활성화하고 필요한 환경을 설정해야 합니다.

1.1 SQL Server 설치 및 네트워크 설정

• SQL Server Standard/Enterprise/Developer/Express Edition이 설치되어 있어야 합니다.
• 네트워크를 통해 Debezium이 접근할 수 있도록 TCP/IP를 활성화해야 합니다.
  • SQL Server 구성 관리자 → SQL Server 네트워크 구성 → 해당 인스턴스의 프로토콜 → TCP/IP 활성화
• 고정 포트(1433) 사용 권장
  • SQL Server 구성 관리자 → TCP/IP 설정 → IPAll → TCP 포트를 1433으로 설정

1.2 CDC (Change Data Capture) 활성화

CDC를 사용하려면 먼저 데이터베이스 및 테이블에 CDC 기능을 활성화해야 합니다.

1) 데이터베이스 수준에서 CDC 활성화

USE YourDatabaseName;
EXEC sys.sp_cdc_enable_db;

2) 테이블 수준에서 CDC 활성화

USE YourDatabaseName;
EXEC sys.sp_cdc_enable_table
    @source_schema = N'dbo',         -- 스키마 (일반적으로 dbo)
    @source_name = N'YourTableName', -- CDC를 활성화할 테이블
    @role_name = NULL,               -- CDC 데이터 접근 권한 (NULL: 모든 사용자)
    @supports_net_changes = 1;       -- Net Changes 기능 활성화 (Express에서는 0으로 설정)

Express Edition 주의:
Express Edition은 net changes 기능을 지원하지 않으므로 @supports_net_changes = 0으로 설정해야 합니다.
Standard/Enterprise/Developer Edition에서는 1로 설정하면 성능 최적화에 도움이 됩니다.

1.3 Debezium 사용자 및 권한 설정

Debezium이 SQL Server에서 CDC 데이터를 읽을 수 있도록 사용자 및 최소 권한을 부여해야 합니다.

1) Debezium 전용 로그인 생성

USE master;
CREATE LOGIN DebeziumLogin WITH PASSWORD = 'your_password';
USE YourDatabaseName;
CREATE USER DebeziumUser FOR LOGIN DebeziumLogin;

2) 최소 권한 부여 (권장)

GRANT SELECT ON SCHEMA::cdc TO DebeziumUser;
GRANT SELECT ON SCHEMA::dbo TO DebeziumUser;
GRANT EXECUTE ON SCHEMA::cdc TO DebeziumUser;
GRANT VIEW ANY DEFINITION TO DebeziumUser;
GRANT CONNECT TO DebeziumUser;
GRANT SELECT ON cdc.captured_columns TO DebeziumUser;
GRANT SELECT ON cdc.change_tables TO DebeziumUser;
GRANT SELECT ON cdc.lsn_time_mapping TO DebeziumUser;

대안:
전체 권한을 부여하려면 아래와 같이 db_owner 역할을 할당할 수도 있습니다. (비권장)

ALTER ROLE db_owner ADD MEMBER DebeziumUser;

---

2. Debezium 커넥터 설정 (JSON)

SQL Server용 Debezium 커넥터를 설정할 때, JSON 구성 파일을 작성하여 Kafka Connect에 등록합니다.

{
  "name": "mssql-cdc-connector",
  "config": {
    "connector.class": "io.debezium.connector.sqlserver.SqlServerConnector",
    "tasks.max": "1",
    "database.hostname": "your_server_address",
    "database.port": "1433",
    "database.user": "DebeziumUser",
    "database.password": "your_password",
    "database.dbname": "YourDatabaseName",
    "topic.prefix": "mssql",
    "table.include.list": "dbo.Customers,dbo.Orders",
    "schema.include.list": "dbo",
    "database.history.kafka.bootstrap.servers": "your_kafka_broker:9092",
    "database.history.kafka.topic": "dbhistory.mssql",
    "include.schema.changes": "true",

    "snapshot.mode": "initial",
    "snapshot.locking.mode": "shared",
    "snapshot.isolation.mode": "read_committed",
    "time.precision.mode": "connect",
    "decimal.handling.mode": "double",
    "binary.handling.mode": "bytes",
    "skipped.operations": "none",
    "max.batch.size": "2048",
    "max.queue.size": "8192",
    "poll.interval.ms": "500",

    "database.encrypt": "false",
    "database.trustServerCertificate": "true",
    "column.exclude.list": "dbo.Customers.SensitiveColumn",
    "datatype.propagate.source.type": "true",
    "schema.history.internal.kafka.topic": "schemahistory.mssql",
    "schema.history.internal.kafka.bootstrap.servers": "localhost:9092"
  }
}

---

3. 주요 설정 옵션 설명

필수 옵션

옵션 설명

connector.class	SQL Server용 Debezium 커넥터 (io.debezium.connector.sqlserver.SqlServerConnector)
database.hostname	SQL Server 인스턴스의 IP 또는 호스트 이름
database.port	SQL Server 포트 (기본: 1433)
database.user	Debezium이 사용할 사용자 이름
database.password	해당 사용자의 비밀번호
database.dbname	CDC를 활성화한 데이터베이스 이름
topic.prefix	Kafka 토픽 이름 접두사
table.include.list	캡처할 테이블 목록 (쉼표 구분)
schema.include.list	캡처할 스키마 목록

스냅샷 및 변경 사항 캡처

옵션 설명

snapshot.mode	initial(최초 스냅샷 후 CDC), schema_only, never, when_needed
snapshot.locking.mode	shared(잠금 최소화), exclusive(배타적 잠금), none(잠금 없음)
snapshot.isolation.mode	read_committed(권장), repeatable_read, snapshot

고급 설정

옵션 설명

time.precision.mode	connect(기본), adaptive, adaptive_time_microseconds
decimal.handling.mode	double(기본), precise, string
binary.handling.mode	bytes, base64, hex
skipped.operations	none(기본), t(truncate), d(delete), c(create), u(update)
max.batch.size	최대 배치 크기 (기본: 2048)
max.queue.size	큐 최대 크기 (기본: 8192)
poll.interval.ms	폴링 간격 (기본: 500ms)

---

4. 마무리 및 참고사항

1. SQL Server Standard/Enterprise/Developer Edition에서는 net changes를 사용할 수 있어 성능 최적화 가능.
2. Express Edition은 net changes를 지원하지 않으므로 @supports_net_changes = 0으로 설정해야 함.
3. CDC 로그 크기를 관리하지 않으면 디스크가 가득 찰 수 있음 → 주기적으로 sys.sp_cdc_cleanup_change_table 실행 필요.
4. 테스트 환경에서는 database.trustServerCertificate=true를 설정하되, 프로덕션 환경에서는 인증서를 설정해야 함.

공식 문서 참고:
🔗 Debezium SQL Server Connector 공식 문서