gen 2 커넥터 구성 및 버전 관리

gen 2 OpenFlow 커넥터는 파일 기반 엔티티(FBE, File Based Entity)예요. 즉 구성이 Snowflake가 커넥터 객체에 만들고 관리하는 내부 버전 스테이지의 파일로 저장되는 객체랍니다. 이 주제는 버전 상태, UI 라벨, 커넥터 구성을 편집하는 SQL 워크플로, 커넥터 스테이지에서 파일을 나열·다운로드·업로드하는 방법을 설명해요.

출처: Snowflake 문서 — gen 2 커넥터 구성 및 버전 관리

본문

팁: 설정 마법사나 Installed Connectors만 사용하나요? 일상 작업에는 이 주제가 필요하지 않아요. OpenFlow UI는 커넥터 설정을 설치·편집·저장할 때 구성 버전을 자동으로 만들고 관리해요. Draft나 Edits not applied 같은 라벨은 아래 설명하는 것과 같은 버전 상태를 반영해요. 스테이지나 COMMIT에 대해 읽지 않아도 마법사와 UI 프롬프트를 그대로 따라가면 돼요.

SQL, 스테이지에서의 GET/PUT, Git, 또는 다른 자동화로 커넥터를 구성한다면 — 또는 UI가 내부적으로 무엇을 하는지 이해하고 싶다면 — 이 주제를 읽어 주세요.

gen 2 OpenFlow 커넥터는 파일 기반 엔티티(FBE)예요. 즉 구성이 Snowflake가 커넥터 객체에 만들고 관리하는 내부 버전 스테이지의 파일로 저장되는 Snowflake 객체예요. 이 스테이지를 CREATE STAGE로 만들 필요는 없어요. 커넥터가 만들어질 때 자동으로 연결돼요. 구성 파일(예: config.json)과 자산(예: JDBC 드라이버 JAR)은 그 스테이지의 버전 경로 아래에 있어요.

다른 Snowflake 객체 유형(예: dbt 프로젝트와 Cortex 에이전트)도 각자의 snow:// URI 스킴으로 유사한 버전 스테이지 모델을 사용해요. 여기서는 OpenFlow 커넥터만 다뤄요.

커넥터의 버전 스테이지 접근 (Access the connector's versioned stage)

각 커넥터 버전은 커넥터 버전 기록의 불변 스냅샷이에요. 버전은 Git 커밋과 비슷하게 동작해요. 새 버전이 파일을 변경하지 않으면 두 버전 모두 같은 기본 파일을 참조할 수 있어요. 파일을 참조하려면 snow://openflow_connector/ URI 스킴을 사용하세요.

snow://openflow_connector/<database>.<schema>.<connector_name>/versions/<version>/[<file_name>]

version은 다음 중 하나예요:

live — 쓰기 가능한 작업 복사본(버전 상태 참조)
LAST — 가장 최근에 커밋된(기본) 버전의 별칭
VERSION$N — 특정 커밋된 버전 (예: VERSION$1)
사용자가 할당한 이름 — 커밋할 때 설정하며, 나중에 참조하기 위해 보존됨 (예: production-config)

커밋된 버전을 참조할 때는 snow:// 경로와 SQL에서 사용자 할당 이름이나 VERSION$N을 사용할 수 있어요.

표준 스테이지 명령(파일 스테이징 명령의 LIST, GET, PUT)으로 파일을 나열·다운로드·업로드해요. URI를 따옴표 문자열로 전달해요(예: GET 'snow://openflow_connector/...').

참고: Snowsight는 커넥터 스테이지에서 GET 또는 PUT을 지원하지 않아요. Snowflake CLI나 스테이지 파일 연산을 지원하는 다른 클라이언트를 사용하세요.

SHOW VERSIONS IN OPENFLOW CONNECTOR로 버전 메타데이터를, DESCRIBE OPENFLOW CONNECTOR로 커넥터 속성(활성 버전 포함)을 검사할 수도 있어요. SHOW VERSIONS IN OPENFLOW CONNECTOR와 DESCRIBE OPENFLOW CONNECTOR를 참고하세요.

버전 상태 (Version states)

용어	설명	SQL 경로
`live`	진행 중인 편집(쓰기 가능한 스테이지). UI 또는 SQL `FROM DEFINITION`으로 커넥터가 생성될 때 자동으로 만들어져요.	`versions/live`
`default`	커넥터가 시작될 때 런타임이 실행하는 커밋된 버전이에요.	`versions/LAST` (별칭)
`LAST`	가장 최근에 커밋된(기본) 버전의 별칭이에요.	`versions/LAST`

live 버전은 작업 복사본이에요. default 버전은 커넥터가 대상 런타임에서 시작될 때 실행되는 버전이에요. 스테이지 경로에서 versions/LAST는 default(커밋된) 버전을 가리켜요. live 버전을 커밋하면 새 불변 default가 만들어지고 live 버전은 제거돼요.

커넥터가 RUNNING인 동안에도 live 버전을 편집할 수 있어요. 변경 사항은 커밋할 때까지(UI의 Apply 또는 SQL COMMIT) 실행 중인 커넥터에 적용되지 않아요.

UI 라벨 (UI labels)

UI 라벨	의미
Draft	live 버전은 존재하지만 default 버전이 아직 없어요. 커넥터가 생성됐지만 커밋되지 않았어요. 시작 전에 커밋하세요.
Edits not applied	live 버전과 default 버전이 모두 존재해요. 변경이 진행 중이지만 커밋되지 않았어요.
(라벨 없음)	default 버전만 존재해요. 안정 상태예요.

구성 워크플로 (Configuration workflow)

CREATE OPENFLOW CONNECTOR ... FROM DEFINITION 또는 설정 마법사로 만든 새 커넥터는 live 버전이 있고 default가 없는(Draft) 상태로 시작해요.

live 버전에서 파일을 업로드하거나 편집해요. 새 커넥터에는 ADD LIVE VERSION을 건너뛰어요 — 이미 live 버전이 있으니까요.
live를 default로 승격하려면 커밋해요:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector COMMIT;

커밋되지 않은 변경을 버리려면:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector ABORT;

커밋된 커넥터를 편집하려면 현재 default에서 시드된 새 live 버전을 만들어요:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector ADD LIVE VERSION FROM LAST;

스테이지 파일 연산 (Stage file operations)

다음 예시들은 snow://openflow_connector/ URI를 사용해요. my_db.my_schema.my_connector를 커넥터의 정규화된 이름으로 바꿔 주세요.

live 버전의 파일 나열:

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

마지막으로 커밋된 config.json 다운로드(snow sql 또는 스테이지에서 GET을 지원하는 다른 클라이언트 사용 — Snowsight는 스테이지에서 GET/PUT을 지원하지 않아요):

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

live 버전에 업로드:

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

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

업로드 후 커밋해요:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector COMMIT;

SELECT SYSTEM$WAIT_FOR_STABLE_OPENFLOW_CONNECTORS(600, 'my_db.my_schema.my_connector');

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

이미 검증된 커넥터 구성이 있고 같은 설정으로 다른 커넥터를 만들고 싶을 때(예: 두 번째 런타임에 동일한 커넥터 구성, CI/CD로 반복 배포 자동화) 이 워크플로를 사용해요.

첫 커넥터에 쓸 경로는 아니에요. 설정 마법사나 CREATE OPENFLOW CONNECTOR ... FROM DEFINITION으로 커넥터를 한 번 만들고 구성한 뒤 구성을 내보내세요.

정의 vs 구성 (Definition vs configuration)

카탈로그 정의(예: OPENFLOW_POSTGRES_CDC)와 인스턴스 구성(config.json)은 별개예요.

CREATE OPENFLOW CONNECTOR의 FROM DEFINITION은 카탈로그 커넥터 유형을 선택해요. 그런 다음 커넥터의 버전 스테이지에서 config.json을 편집하고 COMMIT해요.
스테이지 경로의 FROM은 어떤 스테이지 참조에서든 완전한 구성 번들을 제공해요 — Git 저장소 스테이지(@my_git_repo/...), 같은 계정의 다른 커넥터 스테이지(snow://openflow_connector/...), 또는 다른 내부 스테이지예요. 카탈로그 정의는 config.json 안의 connectorDefinitionId로 이름이 지어지며, CREATE 명령에는 FROM DEFINITION 절이 없어요.

스테이지 경로와 함께 FROM을 사용하면 OpenFlow는 config.json에서 connectorDefinitionId를 읽어 커넥터 유형을 결정해요 — CREATE에서 FROM DEFINITION을 쓰지 않아요. 스테이지는 인스턴스 구성만 담아요: config.json, 자산 파일(예: JDBC 드라이버), 메타데이터. Snowflake는 생성 시 카탈로그 커넥터 패키지를 제공하며, 그걸 스테이지에 복사할 필요는 없어요.

CREATE를 실행하기 전에 대상 런타임에 맞게 연결 URL, 시크릿 참조, 대상 설정을 업데이트해 주세요.

초기 상태 차이 (Initial state difference)

경유	초기 상태
UI 또는 SQL `FROM DEFINITION`	live 버전 존재, default 없음(Draft). 시작 전에 커밋.
스테이지 `FROM '@<stage>[/path/]'` 또는 `snow://...`	default 버전 존재, live 버전 없음. 바로 시작 가능(COMMIT 단계 없음).

워크플로 (Workflow)

마법사나 FROM DEFINITION으로 커넥터를 만들고 구성해요. 소스 환경에서 작동할 때 구성을 커밋해요.
아직 Git 저장소가 없다면 Snowflake에 Git 저장소를 등록해요. Snowflake의 Git 저장소 사용을 참고하세요.
커넥터 구성을 내보내요:

ALTER OPENFLOW CONNECTOR my_db.my_schema.my_connector PUSH TO
  '@my_git_repo/branches/main/connectors/my_connector'
  USERNAME = 'my-git-username'
  PASSWORD = 'my-git-token'
  NAME = 'My Name'
  EMAIL = '[email protected]'
  COMMENT = 'Export connector config';

저장소의 config.json을 대상 환경에 맞게 검토하고 업데이트해요(시크릿, URL, 대상 설정).
스테이지 경로에서 새 커넥터를 만들어요:

CREATE OPENFLOW CONNECTOR my_db.my_schema.my_connector_prod
  IN RUNTIME my_db.my_schema.my_prod_runtime
  FROM '@my_git_repo/branches/main/connectors/my_connector/'
  COMMENT = 'Created from validated stage config';

Git 없이 같은 계정의 커넥터를 복제하려면 snow://openflow_connector/.../versions/LAST/ URI를 사용할 수도 있어요. 예:

'snow://openflow_connector/my_db.my_schema.my_connector/versions/LAST/'

CREATE, ADD VERSION FROM, PUSH, PULL 구문은 CREATE OPENFLOW CONNECTOR와 ALTER OPENFLOW CONNECTOR를 참고하세요.

구성의 시크릿 (Secrets in configuration)

민감한 값(예: 데이터베이스 비밀번호)은 config.json의 평문 대신 Snowflake 시크릿을 참조해야 해요. 자세한 내용은 설정 마법사로 gen 2 커넥터 구성의 구성의 시크릿을 참고하세요.

더 알아보기 (Learn more)

gen 2 커넥터를 SQL로 구성하기 — SQL 워크플로 자세히 보기
OpenFlow 개요 — OpenFlow 구성 요소와 기능 살펴보기