MySQL용 Openflow 커넥터 설정

이 문서에서는 MySQL용 Openflow 커넥터를 설정하는 단계를 설명합니다.

출처: Snowflake 문서

본문

사전 준비 사항

시작하기 전에

MySQL용 Openflow 커넥터 소개 문서를 검토했는지 확인하세요.
Snowflake와 데이터를 동기화하려면 MySQL 8 이상이 있는지 확인하세요.
이 커넥터용 Openflow 배포와 런타임이 있는지 확인하세요. 없다면 'Set up Openflow - Snowflake Deployments' 또는 'Set up Openflow - BYOC'를 참조하세요. 런타임 크기는 만들 때 고정되므로 런타임을 만들기 전에 크기를 결정하세요. CDC 커넥터용 Runtime sizing and packing을 참조하세요.
Snowflake 배포를 사용한다면 필수 도메인 구성 문서를 검토하고, MySQL 커넥터에 필요한 필수 도메인에 대한 접근 권한을 부여했는지 확인하세요.

소스 데이터베이스 설정

데이터베이스 관리자는 다음 작업을 수행하세요.

바이너리 로그를 활성화한 뒤 저장하고 형식을 다음과 같이 구성합니다.

log_bin	on으로 설정. 구조적·데이터 변경을 기록하는 바이너리 로그를 활성화함
binlog_format	row로 설정. 커넥터는 행 기반 복제만 지원. MySQL 8.x 버전이 이 설정을 마지막으로 지원할 수 있으며, 향후 버전은 행 기반 복제만 지원. 올바른 값으로 고정된 GCP Cloud SQL에서는 해당 없음
binlog_row_metadata	full로 설정. 커넥터는 모든 행 메타데이터, 특히 열 이름과 기본 키 정보가 있어야 동작함. Microsoft Azure Database for MySQL에서는 binlog_row_metadata 필드를 사용자가 수정할 수 없음. 이 값을 변경하려면 Microsoft 지원 티켓을 제기하세요
binlog_row_image	full로 설정. 커넥터는 모든 열이 바이너리 로그에 기록되어야 함. 올바른 값으로 고정된 Amazon Aurora에서는 해당 없음
binlog_row_value_options	비워 둠. 이 옵션은 JSON 열에만 영향을 주며, UPDATE 문에 대해 JSON 문서의 수정된 부분만 포함하도록 설정할 수 있음. 커넥터는 전체 문서가 바이너리 로그에 기록되어야 함
binlog_expire_logs_seconds	Snowflake는 바이너리 로그 만료 기간(binlog_expire_logs_seconds)을 최소 72시간(259200)으로 설정할 것을 권장. 보존은 복제 문제가 시작되고, 누군가가 알아차리고, 수정이 적용되는 전체 기간을 커버해야 함. 만료 기간이 지나면 MySQL이 바이너리 로그 파일을 자동으로 제거할 수 있고, Openflow는 더 이상 존재하지 않는 파일에서 데이터를 복제할 수 없어 데이터가 손실됨. 계획된 유지 관리든 인지하지 못한 실패든, 일시 중지된 시간이 그 기간에 포함됨. 예약된 복제를 사용한다면 값이 구성된 일정보다 길어야 함
binlog_legacy_event_pos	ON으로 설정. 소스가 MariaDB일 때만 필요. 커넥터는 복제 중 바이너리 로그 위치를 올바르게 추적하려면 이 플래그가 필요함. MySQL에는 해당 없음

예:

log_bin = on
binlog_format = row
binlog_row_metadata = full
binlog_row_image = full
binlog_row_value_options =

sort_buffer_size 값을 늘립니다.

sort_buffer_size = 4194304

sort_buffer_size는 ORDER BY 같은 메모리 내 정렬 작업을 위해 쿼리 스레드당 할당되는 메모리(바이트)를 정의합니다. 값이 너무 작으면 커넥터가 다음 오류 메시지로 실패할 수 있습니다: 'Out of sort memory, consider increasing server sort buffer size.' 이는 sort_buffer_size를 높여야 한다는 뜻입니다.

Amazon RDS 데이터베이스를 사용한다면 rds_set_configuration으로 binlog_expire_logs_seconds와 관련된 보존 기간을 늘립니다. 예: binlog를 24시간 저장하려고 하면 mysql.rds_set_configuration('binlog retention hours', 24)를 호출하세요.
읽기 복제본으로 연결할 때는 복제본에서 바이너리 로깅이 활성화되어야 합니다.
바이너리 로깅이 활성화된 뒤, 소스에서 받은 이벤트를 자체 바이너리 로그에 기록하도록 복제본을 구성하세요.

log_replica_updates = ON

log_replica_updates는 복제본이 소스에서 받은 이벤트를 자체 바이너리 로그에 기록해, 그 변경을 복제본에서 복제하는 모든 데이터베이스가 사용할 수 있게 합니다.

SSL로 연결하세요. MySQL에 SSL 연결을 사용할 계획이라면 데이터베이스 서버의 루트 인증서를 준비하세요. 구성 중에 필요합니다.
커넥터용 사용자를 만듭니다. 커넥터는 바이너리 로그를 읽기 위해 REPLICATION SLAVE와 REPLICATION CLIENT 권한이 있는 사용자가 필요합니다. 다음 권한을 부여하세요.

GRANT REPLICATION SLAVE ON *.* TO '<username>'@'%'
GRANT REPLICATION CLIENT ON *.* TO '<username>'@'%'

복제된 모든 테이블에 SELECT 권한을 부여하세요.

GRANT SELECT ON <schema>.* TO '<username>'@'%'
GRANT SELECT ON <schema>.<table> TO '<username>'@'%'

복제 보안에 대한 자세한 내용은 Binary log를 참조하세요.

Snowflake 계정 설정

Openflow 관리자는 이 커넥터에 대해 다음 작업을 수행하세요. 기본 SNOWFLAKE_MANAGED 인증 전략에서는 런타임의 execute-as 역할이 커넥터가 Snowflake에 접근할 때 사용하는 신원이므로, 해당 역할에 권한을 부여하세요.

참고: Openflow - BYOC Deployments에 커넥터를 배포하면서 권장되는 SNOWFLAKE_MANAGED 대신 KEY_PAIR 인증 전략을 사용한다면, 런타임 관리 토큰에 의존하는 대신 동일한 execute-as 역할을 서비스 사용자에게도 부여해야 합니다. 서비스 사용자 생성은 'Set up key-pair authentication for Openflow - BYOC Deployments'를 참조하세요.

복제된 데이터를 저장할 데이터베이스를 만들고, execute-as 역할에 USAGE와 CREATE SCHEMA를 부여하세요. 커넥터는 목적지 스키마를 자동으로 만듭니다. Snowflake는 다른 커넥터를 포함한 다른 데이터 소스와의 충돌을 피하기 위해 커넥터당 전용 목적지 데이터베이스를 권장합니다. 이 목적지 데이터베이스를 런타임, 커넥터, 시크릿 같은 Openflow 인프라 객체가 있는 데이터베이스와 분리해 두세요. 커넥터는 소스 스키마와 테이블 이름을 기반으로 목적지 객체를 만들기 때문에, 그 이름은 제어할 수 없고 소스가 바뀌면 변할 수 있습니다.

CREATE DATABASE IF NOT EXISTS <destination_database>;

GRANT USAGE ON DATABASE <destination_database> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT CREATE SCHEMA ON DATABASE <destination_database> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

커넥터가 사용할 웨어하우스를 지정하고, execute-as 역할에 USAGE와 OPERATE를 부여하세요. XSMALL 웨어하우스 크기에서 시작해 복제되는 테이블 수와 전송되는 데이터 양에 따라 크기를 실험해 보세요. 큰 테이블 수는 웨어하우스 크기보다 다중 클러스터 웨어하우스에서 더 잘 확장되는 경향이 있습니다.

CREATE WAREHOUSE <ingest_warehouse>
 WITH
 WAREHOUSE_SIZE = 'XSMALL'
 AUTO_SUSPEND = 300
 AUTO_RESUME = TRUE;

GRANT USAGE, OPERATE ON WAREHOUSE <ingest_warehouse> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

Snowflake 배포 전용: 런타임의 외부 접근 통합(EAI)이 허용하는 네트워크 규칙이 이 커넥터의 소스 호스트와 포트를 허용하는지 확인하세요. EAI 자체는 이 커넥터가 아니라 런타임에 속합니다. EAI는 한 번 만들고 런타임에 연결하며 execute-as 역할에 USAGE를 부여합니다. 이 단계는 'Creating network rules and external access integrations'를 참조하세요. 이 커넥터에 특화된 점은 소스 호스트를 EAI가 참조하는 규칙에 넣는 것입니다. 규칙은 소스의 호스트와 포트를 단일 값(예: db.example.com:)으로 취합니다. 이는 커넥터 연결 URL에서 jdbc: 스킴, 드라이버 이름, 데이터베이스 경로를 뺀 호스트와 포트입니다. BYOC 배포는 클라우드 환경에서 아웃바운드 연결을 처리하므로 EAI나 네트워크 규칙을 사용하지 않습니다.

설치 전에 모아 두어야 할 것

이 항목들은 나중에 중단하고 수집해도 되지만, 미리 준비해 두면 커넥터를 한 번에 설치·구성할 수 있습니다.

MariaDB JDBC 드라이버 .jar 파일. 드라이버 파일 자체를 직접 공급해야 하므로 미리 다운로드하세요.
JDBC 연결 URL. 커넥터가 MariaDB 드라이버를 통해 연결하므로 jdbc:mariadb 스킴을 사용해야 합니다. SSL은 별도 속성이 아니라 URL 자체에서 구성되며, sslMode 파라미터를 추가해 지정합니다.
'소스 데이터베이스 설정'에 설명된 권한을 가진 소스 데이터베이스 사용자.
소스 데이터베이스 사용자의 비밀번호.
나중에 변경할 수 없는 설정에 대한 결정. 목적지 스키마 명명, 객체 식별자 해석(MySQL 이름을 대소문자 구분 혹은 대문자로 저장할지), 테이블 스토리지 형식은 커넥터가 구성을 적용하고 수집을 시작하면 고정됩니다. 나중에 변경하려면 새 커넥터 인스턴스와 새 스냅샷이 필요합니다.

커넥터 설치

세대(gen) 선택

이 커넥터는 gen 1과 gen 2 모두로 제공됩니다.

	Gen 2(권장)	Gen 1
관리	SQL 명령 + 설정 위저드	런타임 캔버스 UI
구성	버전 관리되는 구성 파일, CI/CD 친화적	캔버스 파라미터
릴리스 상태	Public Preview	Generally Available

확실하지 않다면 전체 비교를 위해 'Openflow gen 1 and gen 2'를 참조하세요.

참고: 카탈로그에는 MySQL과 MariaDB라는 같은 이름의 두 항목이 나열됩니다. gen 2 항목은 Gen 2 태그가 붙은 것이며 public preview 동안 Preview 태그도 함께 붙습니다. gen 1 항목에는 태그가 없습니다.

Openflow 커넥터 카탈로그에서 커넥터를 설치하세요.

데이터 엔지니어로서 커넥터를 설치하려면 다음을 수행하세요.

Openflow의 Connector library 탭으로 이동하세요.
Openflow connectors 페이지에서 선택한 세대의 항목을 찾아 Install을 선택하세요.
커넥터를 설치할 런타임을 선택하세요. 인증을 요청하면 Snowflake 계정 자격 증명으로 로그인하세요.

다음 단계는 선택한 세대에 따라 다릅니다.

Gen 2: 설정 위저드가 열리고 커넥터 구성이 하나의 안내 플로우로 수집됩니다. 아래 '커넥터 구성'으로 계속하세요. 이 커넥터가 필요한 값들을 설명합니다. 위저드 대신 프로그래밍 방식으로 커넥터를 구성하고 싶다면 'Configure a gen 2 connector with SQL'을 참조하세요.
Gen 1: 커넥터 프로세스 그룹이 추가된 Openflow 캔버스가 나타납니다.

커넥터 구성

gen 1을 사용하나요? 'Configure on the canvas'로 건너뛰세요.

설정 위저드나 SQL로 구성(gen 2)

팁: CoCo가 사전 준비 사항이 갖춰졌는지 확인하도록 도울 수 있습니다. 이 프롬프트를 CoCo에 붙여넣어 보세요. "Please help me with the prerequisites for a gen 2 Openflow connector for MySQL and MariaDB. Use skill @(serverSkill:openflow)."

Gen 2는 소스 데이터베이스 비밀번호를 인라인으로 받지 않고 GENERIC_STRING 유형의 Snowflake 시크릿으로 참조합니다. 런타임과 커넥터 같은 Openflow 인프라 객체를 담는 같은 데이터베이스와 스키마에 시크릿을 만들고, 복제된 데이터가 저장되는 목적지 데이터베이스와 인프라를 분리해 두세요.

CREATE SECRET <openflow_db>.<openflow_schema>.<secret_name>
 TYPE = GENERIC_STRING
 SECRET_STRING = '<source_db_password>';

GRANT READ ON SECRET <openflow_db>.<openflow_schema>.<secret_name> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

시크릿 값을 AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager 같은 외부 시크릿 공급자에서 가져올 수도 있습니다. 자세한 내용은 'Use external secret providers with Openflow'를 참조하세요.

execute-as 역할에 인프라 데이터베이스와 스키마에 대한 USAGE가 아직 없다면(예: 권장 설정 경로에서 벗어난 경우) 부여하세요.

GRANT USAGE ON DATABASE <openflow_db> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT USAGE ON SCHEMA <openflow_db>.<openflow_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

시크릿을 마련한 뒤 설정 위저드로 커넥터를 구성하거나, 자동화를 위해 SQL과 스테이지 파일 작업으로 커넥터의 config.json을 편집해 구성하세요. 'Configure a gen 2 connector with SQL' 참조.

Gen 2 파라미터

다음 표는 구성하는 위저드 단계별로 그룹화된 gen 2 커넥터 파라미터를 나열합니다. 위저드의 Step Documentation 패널이 각 속성을 완전히 설명합니다. 이 표는 위저드에 들어가기 전에 준비할 수 있도록 파라미터 이름과 목적을 제공합니다.

파라미터	위저드 단계	설명
Source Database Connection URL	Source	MySQL 또는 MariaDB 소스로의 JDBC URL. jdbc:mariadb://로 시작해야 하며 SSL 모드를 포함할 수 있음. 예: jdbc:mariadb://db.example.com:3306/?sslMode=verify-full
Source Database Driver	Source	위저드에서 업로드하는 MariaDB JDBC 드라이버 .jar
Source Database User	Source	REPLICATION SLAVE, REPLICATION CLIENT, SELECT, RELOAD 권한이 있는 소스 데이터베이스 사용자
Source Database Password	Source	소스 사용자의 비밀번호를 담고 execute-as 역할에 READ가 부여된 GENERIC_STRING 유형의 Snowflake 시크릿
Configure Logical Keys	Source	기본 기본 키 감지를 사용할지, 또는 사용 가능한 기본 키가 없는 테이블에 사용자 지정 논리 키를 선언할지
Included Source Table Pattern	Replication table schema	복제할 스키마와 테이블. 수동 선택 또는 정규식 일치
Replication Columns	Replication columns	테이블별 포함할 열, 그리고 새로 추가된 열을 자동 포함할지 여부
Snowflake Destination Database	Destination details	복제된 데이터가 저장되는 데이터베이스. execute-as 역할에 USAGE와 CREATE SCHEMA 필요
Snowflake Warehouse	Destination details	병합 작업에 사용되는 웨어하우스. XSMALL로 시작. 테이블이 많으면 더 큰 크기보다 다중 클러스터 웨어하우스가 더 잘 확장됨
Destination Schema Strategy	Destination details	여러 소스 데이터베이스를 단일 Snowflake 데이터베이스로 통합할 때 충돌을 피하기 위한 목적지 스키마 명명 방식. 첫 적용 후 고정
Object Identifier Resolution	Destination details	소스 객체 이름을 대소문자 구분(기본) 또는 대문자(권장)로 저장할지. 첫 적용 후 고정
Oversized Value Strategy	Destination details	16 MB 한도를 초과하는 값 처리 방식. 기본: Set Null
Error Handling Strategy	Destination details	잘못된 행 처리 방식. 기본: Log Errors and Continue
Table Storage Format	Destination details	표준 Snowflake 테이블 또는 Iceberg 테이블. 첫 적용 후 고정
Iceberg Version	Destination details	Iceberg 사용 시 테이블 버전(2 또는 3, 기본 3)
Merge Task Schedule CRON	Tuning	저널 데이터가 목적지 테이블에 병합되는 시점(웨어하우스 비용이 발생하는 시점)을 제어하는 CRON 표현식
Concurrent Snapshot Queries	Tuning	동시에 스냅샷할 테이블 수(기본 2). 각각 소스 데이터베이스 연결을 유지함
Ingestion Type	Migration	새 테이블이 CDC로 전환하기 전에 전체 스냅샷을 얻을지(기본) 아니면 바로 증분으로 갈지
Starting Binlog Position	Migration	binlog에서 읽기를 시작할 위치: Latest(기본) 또는 Earliest

gen 2를 사용하나요? 'Run the flow'로 건너뛰세요.

캔버스에서 구성(gen 1)

데이터 엔지니어로서 캔버스에서 커넥터를 구성하려면 다음을 수행하세요.

가져온 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Parameters를 선택하세요.
필수 파라미터 값을 채우세요. 필수 파라미터 값에 대한 자세한 내용은 다음 섹션을 참조하세요.
- MySQL Source Parameters: MySQL과 연결을 수립하는 데 사용.
- MySQL Destination Parameters: Snowflake와 연결을 수립하는 데 사용.
- MySQL Ingestion Parameters: 복제할 테이블을 지정하는 데 사용.
MySQL Source Parameters 컨텍스트의 파라미터 설정부터 시작해, 다음으로 MySQL Destination Parameters 컨텍스트를 설정하세요. 그 후 커넥터를 활성화할 수 있습니다. 커넥터는 MySQL과 Snowflake 양쪽에 연결되어 실행을 시작해야 합니다. 그러나 복제할 테이블이 구성에 명시적으로 추가될 때까지 커넥터는 어떤 데이터도 복제하지 않습니다.
특정 테이블을 복제하도록 구성하려면 MySQL Ingestion Parameters 컨텍스트를 편집하세요. MySQL Ingestion Parameters 컨텍스트에 변경을 적용하면 구성이 커넥터에 반영되고, 모든 테이블에 대해 복제 수명 주기가 시작됩니다.

한 런타임에서 여러 CDC 커넥터 인스턴스를 실행하려면 Runtime sizing을 참조하세요.

MySQL Source Parameters

파라미터	설명
MySQL Connection URL	소스 데이터베이스로의 전체 JDBC URL. 커넥터는 MySQL과 호환되는 MariaDB 드라이버를 사용하며 URL에 jdbc:mariadb 접두사가 필요함. SSL이 비활성화되면 연결 URL에 allowPublicKeyRetrieval 파라미터를 true로 설정해야 함. 예: SSL 활성화: jdbc:mariadb://example.com:3306. SSL 비활성화: jdbc:mariadb://example.com:3306?allowPublicKeyRetrieval=true
MySQL JDBC Driver	MariaDB JDBC 드라이버 jar의 절대 경로. 커넥터는 MySQL과 호환되는 MariaDB 드라이버를 사용함. MariaDB JDBC 드라이버를 업로드하려면 Reference asset 체크박스 선택. 예: /opt/resources/drivers/mariadb-java-client-3.5.2.jar
MySQL Username	커넥터용 사용자 이름
MySQL Password	커넥터용 비밀번호

MySQL Destination Parameters

파라미터	설명	필수
Destination Database	데이터가 저장되는 데이터베이스. Snowflake에 이미 존재해야 함. 이름은 대소문자를 구분함. 따옴표 없는 식별자는 대문자로 입력	예
Destination Schema Pattern	데이터가 저장되는 목적지 스키마 이름의 패턴. 커넥터는 스키마가 없으면 만듦. 다음 선택 변수로 테이블별 패턴을 사용자 지정할 수 있음: ${source.schema.name}(소스 데이터베이스, MySQL의 데이터베이스는 Snowflake의 스키마에 매핑), ${source.table.name}(소스 테이블 이름). 예: my_database.users 테이블의 경우 패턴 prefix_${source.schema.name}은 prefix_my_database로 해석됨. 모든 테이블을 단일 스키마로 수집하려면 destination_schema처럼 변수 없는 스키마 이름을 제공하세요. 중요: 커넥터가 데이터 수집을 시작한 뒤에는 이 설정을 변경하지 마세요. 수집 시작 후 변경하면 기존 수집이 깨집니다. 반드시 바꿔야 한다면 새 커넥터 인스턴스를 만드세요	예
Snowflake Authentication Strategy	사용하는 경우: Snowflake Openflow Deployment 또는 BYOC → SNOWFLAKE_MANAGED 사용. 이 토큰은 Snowflake가 자동 관리. BYOC 배포는 SNOWFLAKE_MANAGED를 사용하려면 사전에 execute-as 역할을 구성해야 함. BYOC → 대안으로 인증 전략 값에 KEY_PAIR 사용 가능	예
Snowflake Account Identifier	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 비워야 함. KEY_PAIR → [organization-name]-[account-name] 형식의 Snowflake 계정 이름	예
Snowflake Connection Strategy	KEY_PAIR 사용 시 Snowflake에 연결하는 전략 지정: STANDARD(기본) - 표준 공개 라우팅으로 Snowflake 서비스에 연결. PRIVATE_CONNECTIVITY - AWS PrivateLink 같은 지원 클라우드 플랫폼과 연결된 프라이빗 주소로 연결	KEY_PAIR가 있는 BYOC에만 필수, 그 외에는 무시됨
Snowflake Private Key	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 비워야 함. KEY_PAIR → PKCS8 표준에 따라 형식화되고 표준 PEM 헤더와 푸터를 포함하는 인증용 RSA 개인 키. Snowflake Private Key File 또는 Snowflake Private Key 중 하나는 정의되어야 함	아니요
Snowflake Private Key File	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 개인 키 파일은 비워야 함. KEY_PAIR → PKCS8 표준에 따라 형식화되고 표준 PEM 헤더와 푸터를 포함하는 인증용 RSA 개인 키가 담긴 파일을 Snowflake에 업로드. 헤더 줄은 -----BEGIN PRIVATE로 시작. Reference asset 체크박스 선택	아니요
Snowflake Private Key Password	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 비워야 함. KEY_PAIR → Snowflake Private Key File과 연결된 비밀번호 제공	아니요
Snowflake Role	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 런타임의 execute-as 역할(또는 여기에 부여된 하위 역할) 사용. Openflow UI에서 런타임의 View Details로 이동해 찾을 수 있음. KEY_PAIR → 서비스 사용자에 대해 구성된 유효한 역할 사용	예
Snowflake Username	사용하는 경우: SNOWFLAKE_MANAGED 인증 전략 → 비워야 함. KEY_PAIR → Snowflake 인스턴스에 연결하는 데 사용할 사용자 이름 제공	예
Oversized Value Strategy	복제 중 내부 크기 제한(16 MB)을 초과하는 값을 커넥터가 처리하는 방식 결정. 가능한 값: Fail Table(기본) - 테이블이 영구 실패로 표시되고 해당 테이블의 복제가 중지. Set Null - 값이 목적지 테이블에서 NULL로 대체됨. 초과 크기 값 너머의 테이블 데이터 손실이 허용 가능할 때 테이블 실패를 방지하려면 이를 사용	아니요
Error Handling Strategy	수집 중 Snowflake가 거부하는 잘못된 행 처리 방식 결정. 가능한 값: Fail Table(기본) - 첫 번째 잘못된 행에서 테이블이 실패로 표시되고 해당 테이블의 복제가 중지. Log Errors and Continue - 커넥터가 유효한 행을 계속 복제하고 거부된 각 행을 테이블의 오류 테이블에 기록	아니요
Table Storage Format	표준 Snowflake 테이블 또는 Iceberg 테이블. 기본: STANDARD. 커넥터 시작 후 변경하지 마세요	예
Iceberg Version	Iceberg 테이블 버전, 2 또는 3(기본 3). Table Storage Format이 ICEBERG일 때만 적용. 수집 시작 후 이 값을 변경하지 마세요	아니요
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스	예

MySQL Ingestion Parameters

파라미터	설명
Included Table Names	스키마를 포함한 테이블 경로의 쉼표로 구분된 목록. 예: public.my_table, other_schema.other_table
Included Table Regex	테이블 경로와 일치시키는 정규식. 표현식과 일치하는 모든 경로가 복제되며, 나중에 만들어지는 패턴 일치 새 테이블도 자동으로 포함됨. 예: public\.auto_.*
Column Filter JSON	선택 사항. 테이블별 포함·제외할 열을 지정하는 필터 객체의 JSON 배열. 구문 세부 사항과 예시는 'Replicate a subset of columns in a table' 참조
Table Key Configuration Service	선택 사항. 하나 이상의 테이블에 사용자가 선언한 논리 키를 공급하는 JsonTableKeyConfigService 컨트롤러 서비스. 서비스는 키 매핑을 정의하는 Table Key Configuration JSON 속성을 노출함. 구성되면 논리 키가 최우선 순위를 가지며 커넥터가 자동 감지하는 기본 키를 덮어씀. 자세한 내용은 'Specify a logical key for a table' 참조
Merge Task Schedule CRON	커넥터가 저널 데이터를 목적지 테이블에 병합하는 시점(웨어하우스 비용이 발생하는 시점)을 정의하는 CRON 표현식. Merge Journal to Destination 프로세서가 이 일정으로 병합을 수행. 대기 중인 새 변경이 없으면 병합이 실행되지 않아 웨어하우스가 자동 일시 중단될 수 있음. 연속 병합(최저 지연, 최고 비용)에는 * * * * * ?으로 설정하거나, 웨어하우스 실행 시간을 제한하도록 병합을 예약. 커넥터는 UTC 시간대에서 일정을 평가함. 예: * 0 * * * ? 문자열은 정각에 1분 동안 병합을 예약. * 20 14 ? * MON-FRI 문자열은 월요일부터 금요일까지 매일 오후 2:20에 병합을 예약. 추가 정보와 예시는 Quartz 문서의 cron triggers 튜토리얼 참조
Object Identifier Resolution	소스 객체 식별자(스키마, 테이블, 열 이름 등)가 Snowflake에서 어떻게 저장되고 쿼리되는지 지정. 이 설정은 SQL 쿼리에서 큰따옴표를 사용해야 함을 지정함. 옵션 1(기본, 대소문자 구분, 하위 호환용): 변환 - 대소문자가 보존됨. 예: My_Table은 My_Table로 유지. 쿼리 - SQL 쿼리는 데이터베이스 객체의 정확한 대소문자를 일치시키기 위해 큰따옴표를 사용해야 함. 예: SELECT * FROM "My_Table";. 참고: 레거시 또는 호환성 이유로 소스 대소문자를 보존해야 한다면 Snowflake는 이 옵션을 권장. 예를 들어 소스 데이터베이스에 대소문자만 다른 테이블 이름(MY_TABLE과 my_table)이 있다면, 대소문자 구분 없는 비교를 사용할 때 이름 충돌이 발생함. 옵션 2(권장, 대소문자 구분 없음): 변환 - 모든 식별자가 대문자로 변환. 예: My_Table은 MY_TABLE이 됨. 쿼리 - SQL 쿼리는 대소문자 구분 없이 동작해 SQL 큰따옴표가 필요 없음. 예: SELECT * FROM my_table;은 SELECT * FROM MY_TABLE;와 같은 결과를 반환. 참고: 데이터베이스 객체에 혼합 대소문자 이름이 예상되지 않으면 Snowflake는 이 옵션을 권장. 중요: 커넥터가 데이터 수집을 시작한 뒤에는 이 설정을 변경하지 마세요. 수집 시작 후 변경하면 기존 수집이 깨집니다. 반드시 바꿔야 한다면 새 커넥터 인스턴스를 만드세요
Concurrent Snapshot Queries	Snapshot 플로우에서 소스 데이터베이스로 실행할 최대 동시 쿼리 수. 늘리면 많은 테이블 스냅샷을 빠르게 할 수 있지만 소스 데이터베이스의 부하도 증가

테이블의 열 하위 집합 복제

다음은 gen 1 Column Filter JSON 파라미터를 설명합니다. gen 2에서는 설정 위저드의 Replication columns 단계에서 테이블별 열을 선택합니다. 그 단계는 'Configure with the setup wizard or SQL (gen 2)'를 참조하세요.

커넥터는 테이블별로 복제된 데이터를 구성된 열의 하위 집합으로 필터링할 수 있습니다. 기본 키 열은 제외와 무관하게 항상 포함됩니다.

열 필터를 적용하려면 Ingestion Parameters 컨텍스트의 Column Filter JSON 파라미터를 필터링하려는 테이블당 하나씩 필터 객체의 JSON 배열로 설정하세요.

열은 이름이나 정규식 패턴으로 포함하거나 제외할 수 있습니다. 테이블당 단일 조건을 적용하거나 여러 조건을 결합할 수 있으며, 제외가 항상 포함보다 우선합니다.

구문

배열의 각 객체는 테이블을 식별하고 포함·제외할 열을 지정합니다.

[
 {
 "schema": "<schema>" | "schemaPattern": "<regex>",
 "table": "<table>" | "tablePattern": "<regex>",
 "included": ["<column>", "<column>"],
 "excluded": ["<column>", "<column>"],
 "includedPattern": "<regex>",
 "excludedPattern": "<regex>"
 }
]

다음 규칙이 적용됩니다.

정확한 이름 일치에는 schema와 table을, 정규식 일치에는 schemaPattern과 tablePattern을 사용하세요. 같은 객체에서 필드와 그 패턴 변형을 둘 다 사용할 수는 없습니다(예: schema와 schemaPattern이 동시에 나타날 수 없음).
included, excluded, includedPattern, excludedPattern 중 최소 하나는 제공되어야 합니다.
included와 excluded 필터가 모두 지정되면 제외가 우선합니다.
여러 필터가 같은 테이블과 일치하면 마지막 일치 필터가 사용되며, 정확한 일치가 패턴 기반 필터보다 우선합니다.
값은 서로 다른 테이블에 서로 다른 필터를 적용하기 위한 객체 배열일 수 있습니다.

예시

이름으로 특정 열 포함:

[
 {
 "schema": "public",
 "table": "orders",
 "included": ["account_id", "status", "created_at"]
 }
]

이름으로 특정 열 제외:

[
 {
 "schema": "public",
 "table": "orders",
 "excluded": ["internal_note", "debug_flag"]
 }
]

포함 패턴과 특정 제외 결합(예: 모든 email 열 포함하되 admin_email 제외):

[
 {
 "schema": "public",
 "table": "contacts",
 "includedPattern": ".*_email",
 "excluded": ["admin_email"]
 }
]

스키마 패턴과 정확한 테이블 이름을 섞어 스키마 간 필터 적용:

[
 {
 "schemaPattern": "data_.*",
 "table": "customers",
 "excluded": ["internal_note"]
 }
]

여러 필터 객체를 전달해 서로 다른 테이블에 서로 다른 규칙 적용:

[
 {"schema": "public", "table": "orders", "included": ["account_id", "status"]},
 {"schema": "public", "table": "customers", "excludedPattern": ".*_internal"}
]

같은 열 포함·제외

테이블의 복제 집합에서 열을 제거하면(제외하거나 포함 목록에서 빼면) 목적지에 소스에서 열을 삭제하는 것과 같은 효과가 있습니다. 커넥터가 접미사(기본 __SNOWFLAKE_DELETED)를 붙여 이름을 바꿔 목적지에서 열을 소프트 삭제합니다. 그런 다음 열을 복제 집합에 다시 추가했다가 두 번째로 제거하면, 소프트 삭제된 열 이름이 이미 사용 중이므로 해당 테이블의 복제가 실패합니다. 복구하려면 해당 테이블의 복제를 다시 시작하세요.

테이블에 논리 키 지정

커넥터는 복제하는 모든 테이블에 복제 키를 요구합니다. 기본적으로 커넥터는 테이블의 기본 키를 사용합니다. 논리 키는 자동 감지된 키를 사용자가 선언한 대체물입니다. 다음 경우 논리 키를 구성하세요.

테이블에 기본 키는 없지만 하나 이상의 열이 데이터에서 고유한 경우.
커넥터가 자동 감지할 것과 무관하게 특정 열 또는 열 집합을 복제 키로 사용해야 하는 경우(예: 합성 기본 키를 덮어쓰려는 경우).

논리 키는 최우선 순위를 가집니다. 커넥터가 테이블에 대한 논리 키를 찾으면 그 키를 사용하고 테이블의 기본 키는 무시합니다.

JSON 구문

Table Key Configuration JSON 값은 JSON 배열입니다. 각 항목은 하나의 테이블을 그 논리 키 열에 매핑합니다.

[
 {
 "schema": "<schema>",
 "table": "<table>",
 "logicalKey": ["<column>", "<column>"]
 }
]

필드는 다음과 같습니다.

필드	설명
schema	필수. 정확한 소스 스키마 이름
table	필수. 정확한 소스 테이블 이름
logicalKey	필수. 테이블에서 행을 고유하게 식별하는 소스 열 이름의 비어 있지 않은 배열

다음 규칙이 적용됩니다.

schema, table, logicalKey 열 일치는 대소문자를 구분합니다. MySQL이 보고하는 정확한 이름을 사용하세요.
schema와 table이 어떤 복제된 테이블과도 일치하지 않는 항목은 조용히 무시됩니다.

논리 키 구성 예시

기본 키가 없는 테이블의 단일 열 논리 키:

[
 {
 "schema": "sales",
 "table": "audit_log",
 "logicalKey": ["event_id"]
 }
]

복합 논리 키:

[
 {
 "schema": "sales",
 "table": "order_lines",
 "logicalKey": ["order_id", "line_item_id"]
 }
]

하나의 JSON 값에 여러 테이블의 논리 키:

[
 {
 "schema": "sales",
 "table": "audit_log",
 "logicalKey": ["event_id"]
 },
 {
 "schema": "sales",
 "table": "order_lines",
 "logicalKey": ["order_id", "line_item_id"]
 }
]

제한 사항

다음 중 하나라도 해당되면 커넥터는 구성을 거부합니다.

logicalKey가 누락, 비어 있거나 배열이 아님.
logicalKey가 중복 열 이름을 포함.
logicalKey에 nullable 열 포함. 논리 키 열은 행을 안정적으로 식별하기 위해 NOT NULL로 정의되어야 함.
logicalKey가 소스 테이블에 존재하지 않는 열 이름을 포함.

구성이 거부되면 커넥터는 컨트롤러 서비스를 활성화하지 못하거나(활성화 시점에 감지된 구조적 문제), 테이블을 NEW 상태로 보류합니다(테이블 초기화 시 감지된 문제). 구성을 고친 뒤 테이블의 복제는 상태를 재설정하지 않고 재개됩니다.

위험한 구성에 대한 경고 로그

커넥터는 다음 구성을 받아들이지만 테이블 초기화 시 경고를 기록합니다.

논리 키 열을 선택할 때 높은 카디널리티와 가능하면 단조 증가하는 값의 열을 선호하세요. 낮은 카디널리티나 비단조 키는 스냅샷 성능을 저하시킬 수 있습니다.

논리 키 열이 대형 객체 유형(blob, tinyblob, mediumblob, longblob, text, tinytext, mediumtext, longtext)인 경우. 대형 객체를 키로 사용하면 MERGE 성능이 심각하게 저하됩니다.
논리 키 열이 부동 소수점 유형(float, double)인 경우. 부동 소수점 비교는 정밀도 차이로 일관되지 않은 결과를 낼 수 있습니다.
논리 키 열이 반구조화 유형(json)인 경우. 반구조화 값은 비결정적 동등 비교를 만들 수 있습니다.
복합 논리 키가 5개 이상의 열을 포함하는 경우. 긴 복합 키는 종종 설계 문제를 나타내며 MERGE 성능을 저하시킬 수 있습니다.
논리 키가 테이블의 기존 기본 키를 덮어쓰는 경우. 대체 키가 의도된 것인지 확인하세요. 커넥터는 더 이상 MERGE 작업에 기본 키를 사용하지 않습니다.

이러한 경고 중 하나라도 발생한 뒤 데이터 불일치가 관찰되면 목적지를 소스와 조정하기 위해 주기적으로 전체 재로드를 실행하세요.

논리 키에 영향을 주는 스키마 변경

논리 키는 열 이름을 참조합니다. 커넥터는 해당 열의 이름 변경이나 삭제를 따르지 않습니다.

논리 키 열이 소스에서 삭제되면 해당 테이블의 복제가 실패합니다. 테이블이 FAILED로 표시됩니다. 자세한 내용은 'Restart table replication'을 참조하세요.
논리 키 열이 소스에서 이름이 바뀌면 구성이 여전히 이전 이름을 참조해 복제가 실패합니다. JSON을 새 이름으로 업데이트하고 테이블 복제를 다시 시작하세요.

플로우 실행

Gen 2

위저드에서 구성을 적용하면 커넥터 상태가 Upgrading으로 이동하고, 업그레이드가 끝나면 Stopped로 이동합니다. Installed Connectors 탭에서 시작하세요. 커넥터 메뉴를 열고 Start를 선택하세요.

이 단계에 이르렀을 때 커넥터가 여전히 Draft 상태라면 구성이 적용되지 않은 것입니다. 설정 위저드를 열고 Apply를 선택해 시작 전에 변경이 적용되게 하세요.

시작한 뒤 커넥터의 관측 대시보드(observability dashboard)를 열어 데이터가 이동 중이고 오류가 없는지 확인하세요.

gen 2 커넥터를 프로그래밍 방식으로 시작, 중지 또는 관리하려면 'Manage the gen 2 Openflow connector lifecycle'을 참조하세요.

Gen 1

캔버스를 마우스 오른쪽 버튼으로 클릭하고 Enable all Controller Services를 선택하세요.
가져온 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Start를 선택하세요. 커넥터가 데이터 수집을 시작합니다.

알림 설정

Snowflake는 커넥터를 수동으로 확인하지 않고도 수집 오류나 중단된 복제를 통지받도록 알림을 설정할 것을 권장합니다. 이는 gen 1과 gen 2 커넥터 모두에 적용됩니다.

Openflow는 로그와 메트릭을 포함한 텔레메트리를 이벤트 테이블에 기록합니다. 예약 쿼리로 해당 텔레메트리에 알림을 구축하세요. 사용 가능한 텔레메트리와 예시 쿼리는 'Monitor Openflow using telemetry data'를, 쿼리에서 알림을 만드는 방법은 'Setting up alerts based on data in Snowflake'를 참조하세요.

MySQL용 Openflow 커넥터 설정