Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

일반 PostgreSQL 소스 커넥터 만들기

이 문서에서는 일반 PostgreSQL 소스 커넥터를 만드는 방법을 설명합니다.

일반 PostgreSQL 소스 커넥터는 Debezium PostgreSQL 커넥터의 인스턴스입니다. PostgreSQL 데이터베이스에서 행 수준 변경사항을 읽고 Managed Service for Apache Kafka 클러스터의 주제에 씁니다.

이 커넥터의 사용 사례는 다음과 같습니다.

행 수준 데이터베이스 변경사항을 실시간으로 모니터링합니다.
데이터베이스 변경 이벤트를 이벤트 기반 아키텍처에 통합합니다.
행 삽입 또는 삭제와 같은 데이터베이스 이벤트에 응답합니다.
데이터베이스 변경사항을 다른 시스템에 복사합니다.
PostgreSQL 테이블을 복제하거나 복원합니다.

시작하기 전에

일반 PostgreSQL 소스 커넥터를 만들기 전에 다음이 있는지 확인합니다.

PostgreSQL 데이터베이스
Kafka 클러스터와 연결된 Connect 클러스터
데이터베이스 비밀번호를 저장하는 Secret Manager 보안 비밀을 만듭니다. 구성에서 데이터베이스 SSL을 사용하는 경우 데이터베이스 SSL 비밀번호의 보안 비밀도 만듭니다. 보안 비밀로 Connect 클러스터를 구성합니다. 자세한 내용은 Secret Manager 리소스를 참조하세요.

참고: 일반 텍스트 비밀번호는 지원되지 않습니다. database.password 및 database.sslpassword 구성에서 보안 비밀 경로만 지원됩니다. 백엔드에서는 이러한 구성이 다음 형식을 사용해야 합니다. ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

필수 역할 및 권한

커넥터를 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 관리형 Kafka 커넥터 편집자 (roles/managedkafka.connectorEditor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 커넥터를 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

커넥터를 만들려면 다음 권한이 필요합니다.

커넥터 만들기: managedkafka.connectors.create

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

Secret Manager 보안 비밀에 액세스할 수 있는 권한 부여

관리형 Kafka 서비스 계정에는 Secret Manager에 저장된 보안 비밀을 보고 액세스할 수 있는 권한이 필요합니다. 서비스 계정에 다음 IAM 역할을 부여합니다.

Secret Manager 뷰어 (roles/secretmanager.viewer)
Secret Manager 보안 비밀 접근자 (roles/secretmanager.secretAccessor)

관리형 Kafka 서비스 계정의 형식은 service-PROJECT_NUMBER@gcp-sa-managedkafka.iam.gserviceaccount.com, 입니다. 여기서 PROJECT_NUMBER는 Connect 클러스터의 프로젝트 번호입니다.

Connect 클러스터가 Managed Service for Apache Kafka 클러스터와 다른 프로젝트에 있는 경우 다른 프로젝트에서 Connect 클러스터 만들기를 참조하세요.

PostgreSQL 데이터베이스 구성

커넥터가 데이터베이스에서 데이터 변경 이벤트를 읽을 수 있도록 하려면 다음 설정을 구성하세요.

서버의 wal_level 을 logical로 설정합니다.
```
ALTER SYSTEM SET wal_level = logical;
```
서버를 다시 시작하여 설정을 적용합니다.
커넥터가 PostgreSQL에 인증할 데이터베이스 사용자를 만듭니다. 데이터베이스 사용자는 복제 모드에서 서버에 연결할 수 있도록 하는 복제 역할이어야 합니다.
```
CREATE ROLE ROLE_NAME WITH REPLICATION LOGIN PASSWORD 'ROLE_PASSWORD';
```
다음을 바꿉니다.
- ROLE_NAME: 사용자 이름(예: debezium_user)
- ROLE_PASSWORD: 사용자 비밀번호
캡처할 테이블의 게시물 을 만듭니다. 커넥터는 데이터 변경 이벤트를 수신하기 위해 게시물을 구독합니다.
```
CREATE PUBLICATION dbz_publication FOR TABLE "SCHEMA_NAME"."TABLE_NAME";
```
다음을 바꿉니다.
- SCHEMA_NAME: 테이블의 스키마
- TABLE_NAME: 테이블의 이름
이름에 특수문자 또는 대문자가 포함된 경우 구문 오류를 방지하려면 스키마 및 테이블 이름을 표시된 대로 큰따옴표로 묶는 것이 좋습니다.

또는 데이터베이스의 모든 테이블에 대한 변경사항을 복제하는 게시물을 만들 수 있습니다.
```
CREATE PUBLICATION dbz_publication FOR ALL TABLES;
```
커넥터의 publication.autocreate.mode 설정에 따라 게시물을 수동으로 만들거나 커넥터가 자동으로 만들도록 할 수 있습니다. 자세한 내용은 게시 모드를 참조하세요.
각 테이블에 대해 데이터베이스 사용자에게 테이블에 대한 SELECT 권한을 부여합니다.
```
GRANT SELECT ON TABLE "SCHEMA_NAME"."TABLE_NAME" TO ROLE_NAME;
```
또는 스키마의 모든 테이블에 선택을 부여할 수 있습니다.
```
GRANT SELECT ON ALL TABLES IN SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```
각 테이블에 대해 데이터베이스 사용자에게 테이블 스키마에 대한 USAGE 권한을 부여합니다. 테이블이 기본 public 스키마에 있는 경우 이 단계를 건너뛸 수 있습니다.
```
GRANT USAGE ON SCHEMA "SCHEMA_NAME" TO ROLE_NAME;
```

일반 PostgreSQL 소스 커넥터 만들기

일반 PostgreSQL 소스 커넥터를 만들려면 다음 단계를 수행하세요.

커넥터가 초기화되면 다음 작업을 실행합니다.

데이터베이스의 초기 스냅샷을 만듭니다.
행이 있는 모든 테이블에 대해 Kafka 주제를 만듭니다.
각 데이터베이스 행에 대해 변경 이벤트를 해당 주제로 보냅니다.

커넥터가 실행되는 동안 변경 이벤트를 계속 주제로 보냅니다. 초기 스냅샷에 대한 자세한 내용은 Debezium 문서의 스냅샷 을 참조하세요.

콘솔

콘솔 Google Cloud 에서 Connect 클러스터 페이지로 이동합니다.

Connect 클러스터로 이동
커넥터를 만들려는 Connect 클러스터를 클릭합니다.
커넥터 만들기 를 클릭합니다.
커넥터 이름에 문자열을 입력합니다.

커넥터 이름 지정 방법에 대한 가이드라인은 Managed Service for Apache Kafka 리소스 이름 지정 가이드라인을 참조하세요.
커넥터 플러그인에서 일반 PostgreSQL 소스를 선택합니다.
데이터베이스 호스트 이름 필드에 PostgreSQL 서버의 호스트 이름 또는 IP 주소를 입력합니다.
데이터베이스 이름 필드에 데이터베이스 이름을 입력합니다.
데이터베이스 사용자 필드에 복제본 역할의 이름을 입력합니다. 커넥터는 이 역할을 사용하여 PostgreSQL 서버에 인증합니다.
주제 접두사 필드에 Kafka 주제 이름에 사용할 접두사를 입력합니다.
보안 비밀 목록에서 데이터베이스 비밀번호가 포함된 보안 비밀을 선택합니다.
선택사항: 구성 상자에 구성 속성을 추가하거나 기본 속성을 수정합니다. 자세한 내용은 커넥터 구성을 참조하세요.
선택사항: 작업 다시 시작 정책 을 선택합니다. 자세한 내용은 작업 다시 시작 정책을 참조하세요.
만들기 를 클릭합니다.

gcloud

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

콘솔 Google Cloud 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
gcloud managed-kafka connectors create 명령어를 실행합니다.
```
gcloud managed-kafka connectors create CONNECTOR_ID \
    --location=LOCATION \
    --connect-cluster=CONNECT_CLUSTER_ID \
    --config-file=CONFIG_FILE
```
다음을 바꿉니다.
- CONNECTOR_ID: 커넥터의 ID 또는 이름 커넥터 이름 지정 방법에 대한 가이드라인은 Managed Service for Apache Kafka 리소스 이름 지정 가이드라인을 참조하세요. 커넥터의 이름은 변경할 수 없습니다.
- LOCATION: 커넥터를 만드는 위치 Connect 클러스터를 만든 위치와 동일해야 합니다.
- CONNECT_CLUSTER_ID: 커넥터가 생성되는 Connect 클러스터의 ID
- CONFIG_FILE: 커넥터의 YAML 구성 파일 경로
다음은 일반 PostgreSQL 소스 커넥터의 구성 파일 예시입니다.
```
connector.class: io.debezium.connector.postgresql.PostgresConnector
database.dbname: DATABASE_NAME
database.hostname: HOSTNAME
database.password: CREDENTIALS
database.user: DATABASE_USER
key.converter: org.apache.kafka.connect.json.JsonConverter
key.converter.schemas.enable: "false"
plugin.name: pgoutput
topic.prefix: TOPIC_PREFIX
value.converter: org.apache.kafka.connect.json.JsonConverter
value.converter.schemas.enable: "true"
```
다음을 바꿉니다.
- HOSTNAME: 읽을 PostgreSQL 데이터베이스의 호스트 이름
- DATABASE_NAME: 읽을 PostgreSQL 데이터베이스의 이름
- DATABASE_USER: 데이터베이스에 인증할 때 사용할 PostgreSQL 데이터베이스 사용자
- CREDENTIALS: 데이터베이스 비밀번호가 포함된 Secret Manager 보안 비밀의 경로 다음 형식을 사용하여 보안 비밀을 지정합니다.
```
${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}
```
- TOPIC_PREFIX: Kafka 주제 이름에 사용할 접두사

커넥터 구성

이 섹션에서는 커넥터에서 설정할 수 있는 몇 가지 구성 속성을 설명합니다. 전체 목록은 Debezium 문서의 PostgreSQL용 Debezium 커넥터 를 참조하세요.

비밀번호 및 SSL 비밀번호 구성

database.password 및 database.sslpassword 구성에서 보안 비밀 경로만 지원됩니다. 백엔드에서는 이러한 구성이 다음 형식을 사용해야 합니다. ${directory:/var/secrets:PROJECT_ID-SECRET_NAME-SECRET_VERSION}.

IP 주소 유형

driver.ipTypes 속성은 커넥터가 데이터베이스에 연결하는 데 사용하는 IP 주소 유형을 지정합니다.

PRIVATE: 비공개 IP
PSC: Private Service Connect
PUBLIC: 공개 IP

driver.ipTypes 속성에는 쉼표로 구분된 IP 유형 목록이 기본 순서로 포함되어 있습니다(예: driver.ipTypes=PRIVATE,PUBLIC).

게시 모드

일반 PostgreSQL 소스 커넥터는 데이터베이스의 게시물 에서 변경 이벤트를 스트리밍합니다. 게시물을 수동으로 만들거나 커넥터가 자동으로 만들도록 할 수 있습니다.

publication.autocreate.mode 설정은 커넥터가 게시물을 만드는 방법과 여부를 지정합니다.

filtered. 게시물이 없으면 커넥터는 캡처된 테이블만 포함하는 새 게시물을 만듭니다. 데이터베이스 사용자에게 데이터베이스에 대한 CREATE 권한이 있어야 하며 포함된 테이블의 소유자여야 합니다.

게시물이 이미 있는 경우 커넥터는 캡처된 테이블을 포함하도록 게시물을 변경합니다. 기존 게시물을 변경하려면 데이터베이스 사용자가 게시물의 소유자이자 포함된 테이블의 소유자여야 합니다.
all_tables. 게시물이 없으면 커넥터는 FOR ALL TABLES 매개변수를 사용하여 새 게시물을 만듭니다. 데이터베이스 사용자는 수퍼유저여야 합니다.

수퍼유저 역할은 데이터베이스의 모든 권한 확인을 무시하므로 데이터베이스 사용자에게 SUPERUSER를 부여하지 않는 것이 좋습니다. 대신 게시물을 수동으로 만들거나 publication.autocreate.mode=filtered를 설정합니다.
disabled. 게시물이 없으면 오류가 발생합니다. 커넥터는 새 게시물을 만들지 않습니다.

기본값은 all_tables입니다.

간행물 이름

기본적으로 커넥터는 dbz_publication이라는 게시물에서 스트리밍하려고 합니다. 다른 게시물을 지정하려면 구성에 publication.name=PUBLICATION_NAME을 추가합니다. 여기서 PUBLICATION_NAME은 게시물 이름입니다. 예: publication.name=my_publication.

복제 슬롯

PostgreSQL은 복제 슬롯 을 사용하여 데이터베이스 테이블 변경사항을 스트리밍합니다. 기본적으로 커넥터는 debezium이라는 복제 슬롯을 만듭니다. 다른 슬롯 이름을 사용하려면 slot.name 속성을 설정합니다.

동일한 데이터베이스에 대해 커넥터의 인스턴스를 두 개 만드는 경우 각 커넥터에 고유한 슬롯 이름을 지정해야 합니다.

기본적으로 커넥터는 slot.drop.on.stop 속성을 false로 설정하여 데이터 손실을 방지합니다. 커넥터를 영구적으로 삭제할 때는 커넥터가 사용 중인 복제 슬롯을 수동으로 삭제해야 합니다. 복제 슬롯 이름은 debezium 속성을 사용하여 다르게 구성하지 않는 한 기본적으로 slot.name입니다.

소스 PostgreSQL 데이터베이스 서버에서 WAL 디스크 사용량을 모니터링하고 사용하지 않는 복제 슬롯을 삭제하도록 알림을 설정하는 것이 좋습니다.

테이블 필터

기본적으로 커넥터는 데이터베이스의 모든 비시스템 테이블에서 변경 데이터를 캡처합니다. 캡처할 테이블을 필터링하려면 다음 설정 중 하나 이상을 지정하세요.

schema.include.list. 포함할 스키마 목록
schema.exclude.list. 제외할 스키마 목록 와 함께 사용할 수 없습니다schema.include.list.
table.include.list. 포함할 테이블 목록
table.exclude.list. 제외할 테이블 목록 table.include.list와 함께 사용할 수 없습니다.

주제 이름

기본적으로 커넥터는 topic_prefix.schema.table_name 이름 지정 규칙을 사용하여 Kafka 주제를 만듭니다. 여기서 topic.prefix는 topic.prefix 구성의 값입니다.

자세한 내용은 Debezium 문서의 주제 이름을 참조하세요.

일반 PostgreSQL 소스 커넥터 만들기 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필수 역할 및 권한

필수 권한

Secret Manager 보안 비밀에 액세스할 수 있는 권한 부여

PostgreSQL 데이터베이스 구성

일반 PostgreSQL 소스 커넥터 만들기

콘솔

gcloud

커넥터 구성

비밀번호 및 SSL 비밀번호 구성

IP 주소 유형

게시 모드

간행물 이름

복제 슬롯

테이블 필터

주제 이름

다음 단계

일반 PostgreSQL 소스 커넥터 만들기