gen 2 커넥터를 SQL로 구성하기

SQL과 스테이지(stage) 명령을 사용해 gen 2 커넥터를 만들고 구성하는 방법을 설명하는 주제예요. 설정 마법사로 커넥터 구성하기의 프로그래밍 방식 대안이에요. 커넥터 설정을 자동화하거나, 구성을 코드로 관리하거나, CI/CD와 통합하고 싶을 때 이 워크플로를 사용해요.

출처: Snowflake 문서 — gen 2 커넥터를 SQL로 구성하기

본문

같은 커넥터 객체를 OpenFlow UI에서도 관리할 수 있어요. 한 인터페이스에서 만든 변경 사항은 다른 인터페이스에도 보여요.

사전 요구 사항 (Prerequisites)

시작하기 전에:

gen 2 배포와 런타임이 필요해요. 만들어야 한다면 Quickstart: gen 2 Openflow를 참고하세요.
스키마에 대한 CREATE OPENFLOW CONNECTOR 권한과 런타임에 대한 USAGE 권한이 필요해요.
커넥터별 소스 데이터베이스 사전 요구 사항을 먼저 완료하세요: PostgreSQL CDC, MySQL 및 MariaDB CDC. Snowflake 계정 설정(대상 데이터베이스, 웨어하우스, 시크릿)은 그 페이지들의 Snowflake account setup을 따르세요.
스테이지에서 GET과 PUT을 지원하는 클라이언트가 필요해요. Snowsight는 커넥터 스테이지에서 GET/PUT을 지원하지 않으므로 Snowflake CLI나 다른 지원 클라이언트를 사용하세요.

팁: 첫 커넥터 구성은 설정 마법사로 커넥터 구성을 사용하세요. SQL이나 자동화를 위한 템플릿이 필요하면 마법사로 초안(draft)을 만들고 라이브 버전에서 config.json을 다운로드하세요(구성 업로드 및 커밋 참조).

커넥터 만들기 (Create the connector)

이 주제의 SQL 예시는 데이터베이스와 스키마를 만들고(Quickstart: gen 2 Openflow 참조) 세션 컨텍스트를 설정했다고 가정해요.

USE DATABASE my_db;
USE SCHEMA my_schema;

커넥터와 런타임은 스키마 수준 객체예요. 아래 예시들은 단순 이름을 사용해요. snow:// URI 경로는 커넥터의 정규화된 이름을 사용해요.

카탈로그 정의 ID에서 gen 2 런타임으로 커넥터를 만들어요. 각 gen 2 카탈로그 항목은 정의 ID에 매핑되는데, 이 값이 FROM DEFINITION에 전달하는 값이에요.

계정에서 사용 가능한 정의 ID를 찾으려면:

SHOW OPENFLOW CONNECTOR DEFINITIONS를 실행하세요(선택적으로 LIKE로 필터링). name 컬럼이 정의 ID예요. SHOW OPENFLOW CONNECTOR DEFINITIONS를 참고하세요.
OpenFlow 커넥터 카탈로그에서 gen 2 항목을 살펴보세요(설정 마법사로 커넥터 구성 참조).

PostgreSQL CDC 예시:

CREATE OPENFLOW CONNECTOR my_connector
  IN RUNTIME my_runtime
  FROM DEFINITION OPENFLOW_POSTGRES_CDC
  DISPLAY_NAME = 'My Postgres CDC Connector';

커넥터는 Draft 상태로 STOPPED 상태로 만들어져요. 즉 라이브 구성 버전은 존재하지만 커밋된 기본 버전이 아직 없어요. 시작하기 전에 구성하고 커밋해야 해요. gen 2 커넥터 구성 및 버전 관리를 참고하세요.

구성 업로드 및 커밋 (Upload and commit configuration)

gen 2 커넥터는 커넥터의 내부 버전 스테이지에 있는 config.json에 구성을 저장해요. 표준 워크플로는 다운로드 → 편집 → 업로드 → 커밋이에요.

라이브 버전의 파일을 나열해요:

LS 'snow://openflow_connector/my_db.my_schema.my_connector/versions/live';

config.json을 로컬 머신으로 다운로드해요:

GET 'snow://openflow_connector/my_db.my_schema.my_connector/versions/live/config.json'
  file:///path/to/local/;

또는 Snowflake CLI로:

snow stage copy 'snow://openflow_connector/my_db.my_schema.my_connector/versions/live/config.json' .

config.json을 로컬에서 편집해요. 비밀번호와 기타 시크릿은 valueType = SECRET_REFERENCE로 참조하세요(구성의 시크릿 참조).
업데이트된 파일을 라이브 버전에 업로드해요:

PUT 'file:///path/to/config.json'
  'snow://openflow_connector/my_db.my_schema.my_connector/versions/live/'
  AUTO_COMPRESS = FALSE
  OVERWRITE = TRUE;

경고: 대상은 라이브 버전 디렉터리이지 파일 경로가 아니에요. PUT은 소스 파일 이름을 자동으로 덧붙여요. 대상에 config.json을 포함하면 실제 파일을 가리는 중첩된 config.json/config.json 객체가 만들어져요.

라이브 버전을 커밋해 기본 버전을 만들어요:

ALTER OPENFLOW CONNECTOR my_connector COMMIT;

SELECT SYSTEM$WAIT_FOR_STABLE_OPENFLOW_CONNECTORS(600, 'my_connector');

live, default, LAST 버전에 대한 자세한 내용은 gen 2 커넥터 구성 및 버전 관리를 참고하세요.

커넥터 시작 (Start the connector)

구성이 커밋된 뒤:

ALTER OPENFLOW CONNECTOR my_connector START;

SELECT SYSTEM$WAIT_FOR_STABLE_OPENFLOW_CONNECTORS(600, 'my_connector');

커넥터를 중지하거나 제거하려면 gen 2 OpenFlow 커넥터 생명주기 관리를 참고하세요. 커넥터 상태와 수집 상태를 모니터링하려면 OpenFlow Connectors Dashboard로 커넥터 모니터링을 참고하세요.

기존 커넥터 편집 (Edit an existing connector)

커밋 후 구성을 변경하려면:

현재 기본 버전에서 새 라이브 버전을 만들어요:

ALTER OPENFLOW CONNECTOR my_connector ADD LIVE VERSION FROM LAST;

구성 업로드 및 커밋에서처럼 config.json을 다운로드·편집·업로드해요.
커밋하거나 중단해요:

ALTER OPENFLOW CONNECTOR my_connector COMMIT;
-- Or discard changes:
ALTER OPENFLOW CONNECTOR my_connector ABORT;

구성의 시크릿 (Secrets in configuration)

비밀번호를 config.json에 평문으로 저장하지 마세요. Snowflake 시크릿을 만들고 valueType = SECRET_REFERENCE로 참조하세요. 대부분의 커넥터는 TYPE = GENERIC_STRING 시크릿을 요구해요. 커넥터의 설정 주제에서 필요한 유형을 확인하세요.

설정 마법사는 올바른 SECRET_REFERENCE 구조를 자동으로 생성해 줘요. SQL 워크플로에서는 마법사로 커넥터 초안을 만들고, 라이브 버전에서 config.json을 다운로드한 뒤, 추가 커넥터의 시크릿과 연결 설정을 편집할 때 그 구조를 재사용하세요.

SECRET_REFERENCE 예시 (PostgreSQL CDC):

"Source Database Password": {
  "valueType": "SECRET_REFERENCE",
  "fullyQualifiedSecretName": "openflow_db.openflow_schema.MY_SECRET"
}

참조한 각 시크릿에 대한 READ 권한을 런타임의 EXECUTE_AS_ROLE에 부여하세요. 그 역할은 시크릿의 데이터베이스와 스키마에 대한 USAGE 권한도 필요해요. 커넥터를 시작하기 전에 이 권한들을 부여하세요.

알려진 구성에서 생성 (Create from a known configuration, optional)

첫 커넥터에는 FROM DEFINITION(위)이나 설정 마법사를 사용하세요. 이미 검증된 config.json이 있고 같은 설정으로 다른 커넥터를 만들려면(예: 다른 런타임이나 환경) gen 2 커넥터 구성 및 버전 관리의 알려진 구성에서 생성하기를 참고하세요.

마법사 vs SQL (Wizard vs SQL)

접근 방식	언제 사용할까
설정 마법사로 커넥터 구성	단계별 검증이 있는 인터랙티브 설정. 설정 마법사를 지원하는 커넥터 유형의 첫 구성에 가장 좋아요.
SQL (이 주제)	자동화, 반복 배포, CI/CD, 대량 커넥터 생성. OpenFlow를 프로그래밍 방식으로 관리하는 클라이언트에 필요해요.

두 접근 방식 모두 동일한 gen 2 커넥터 객체와 config.json 형식을 만들어요.

다음 단계 (Next steps)

CREATE OPENFLOW CONNECTOR, ALTER OPENFLOW CONNECTOR — 커넥터의 전체 CREATE 및 ALTER 구문.
gen 2 커넥터 구성 및 버전 관리 — 버전 상태, UI 라벨, 알려진 구성에서 생성.
gen 2 OpenFlow 커넥터 생명주기 관리 — gen 2 커넥터 시작·중지·제거.

더 알아보기 (Learn more)

gen 2 커넥터 구성 및 버전 관리 — 버전 상태와 워크플로 자세히 보기
gen 2 커넥터 생명주기 관리 — 커넥터 시작·중지·제거하기
OpenFlow 개요 — OpenFlow 구성 요소와 기능 살펴보기