Oracle용 Openflow 커넥터: Iceberg 테이블 목적지

Oracle용 Openflow 커넥터: Iceberg 테이블 목적지

Oracle(다중 데이터베이스)용 Openflow 커넥터는 선택형(opt-in) 목적지 형식으로 Snowflake 관리형 Apache Iceberg™ 테이블에 쓰기를 지원합니다. Iceberg v2와 v3가 모두 지원됩니다. Table Storage Format = ICEBERG로 설정하고 Iceberg Version을 선택하는 것이 필요한 유일한 커넥터 수준 변경입니다. 외부 볼륨, 카탈로그, 직렬화 정책은 Snowflake 목적지 데이터베이스 기본값에서 상속됩니다.

출처: Snowflake 문서

본문

Iceberg 스펙 버전은 Iceberg Version 커넥터 파라미터로 설정되며 기본값은 3입니다.

스토리지는 Apache Iceberg™ 테이블용 Snowflake 스토리지(EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED')이거나 클라우드 스토리지의 외부 볼륨일 수 있습니다. Snowflake 스토리지를 사용하면 외부 클라우드 스토리지나 IAM 부여가 필요 없습니다.

표준 테이블을 사용하는 기존 커넥터는 영향을 받지 않습니다.

사전 준비 사항

• Openflow 런타임: 커넥터를 호스팅할 기존 런타임.
• CDC용으로 구성된 Oracle 소스: 아카이브 로깅 활성화(ARCHIVELOG 모드), 보충 로깅(supplemental logging) 구성, 필수 권한이 있는 LogMiner 또는 XStream 사용자. 자세한 내용은 'Set up the Openflow Connector for Oracle'을 참조하세요.
• Snowpipe Streaming v2: Oracle 커넥터는 Snowpipe Streaming v2 기반 쓰기가 활성화되어 있어야 합니다. Iceberg 테이블 목적지에 필수입니다.
• 클라우드 스토리지의 외부 볼륨: Iceberg 스토리지용으로 구성된 외부 볼륨으로, 커넥터의 Snowflake 역할에 USAGE가 부여되어 있어야 함. 'CREATE EXTERNAL VOLUME' 참조. Snowflake 스토리지(EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED')를 사용할 때는 필요 없음.
• Snowflake 목적지 데이터베이스: Iceberg 파라미터로 구성된 기존 데이터베이스(다음 섹션).

1단계: Snowflake 목적지 데이터베이스 구성

목적지 데이터베이스에 Iceberg 기본값을 설정합니다. 커넥터는 런타임 시 외부 볼륨과 직렬화 정책에 대해 이 기본값을 읽습니다. Iceberg 스펙 버전은 데이터베이스 수준 ICEBERG_VERSION_DEFAULT만이 아니라 Iceberg Version 파라미터(3단계 참조)로 커넥터마다 구성됩니다.

옵션 A: Snowflake 스토리지

Snowflake 스토리지를 사용하면 Snowflake가 Iceberg 테이블 파일을 저장하고 관리해 줍니다. 외부 클라우드 스토리지나 IAM 부여가 필요 없습니다.

CREATE DATABASE <db>
 EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED'
 STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

기존 데이터베이스를 구성하려면:

ALTER DATABASE <db> SET
 EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED'
 STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

옵션 B: 클라우드 스토리지의 외부 볼륨

테이블 파일을 직접 소유한 클라우드 스토리지에 유지해야 한다면 외부 볼륨으로 데이터베이스를 구성하세요.

CREATE DATABASE <db>
 EXTERNAL_VOLUME = '<volume>'
 STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

기존 데이터베이스를 구성하려면:

ALTER DATABASE <db> SET
 EXTERNAL_VOLUME = '<volume>'
 STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

참고: CATALOG = 'SNOWFLAKE'는 각 CREATE ICEBERG TABLE 문에서 커넥터가 자동으로 설정합니다. 데이터베이스 수준에서 설정하지 마세요. 각 테이블의 기본 위치는 평면 레이아웃을 사용해 자동 파생됩니다: STORAGE_BASE_URL/database/schema/table_name.randomId/[data | metadata]/. 사용자 구성이 필요 없습니다.

클라우드 스토리지에서 외부 볼륨(옵션 B)을 사용한다면 커넥터의 Snowflake 역할에 외부 볼륨에 대한 USAGE를 부여하세요.

GRANT USAGE ON EXTERNAL VOLUME <volume> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

이 단계는 Snowflake 스토리지에는 필요하지 않습니다.

2단계: 커넥터의 파라미터 컨텍스트에서 Table Storage Format 설정

커넥터의 목적지 파라미터 컨텍스트에서 Table Storage Format 파라미터를 ICEBERG로 설정하세요. 기본값은 STANDARD입니다.

전체 커넥터 생성·구성 워크플로는 'Set up the Openflow Connector for Oracle'을 참조하세요.

3단계: Iceberg 버전 설정

Iceberg Version 커넥터 파라미터를 2 또는 3으로 설정하세요. 이는 유형 매핑에 사용되는 Iceberg 스펙 버전(예: JSON이 v3에서는 variant로, v2에서는 string으로 매핑)과 CREATE ICEBERG TABLE DDL의 ICEBERG_VERSION=<n> 절을 제어합니다.

Iceberg Version 파라미터 기본값은 3입니다. 커넥터 시작 전에 필요하면 2로 검토·변경하세요. 수집 시작 후에는 이 값을 변경하지 마세요.

4단계: 시작 및 확인

평소대로 커넥터를 시작하세요. 초기 스냅샷이 완료된 뒤 목적지 테이블이 Iceberg인지 확인하세요.

-- Confirm the table is Iceberg
SELECT GET_DDL('TABLE', '<db>.<schema>.<table>');

-- Confirm the Iceberg version on the database
SHOW PARAMETERS LIKE 'ICEBERG_VERSION_DEFAULT' IN DATABASE <db>;

알려진 제한 사항

• Tri-Secret Secure 계정과 Snowflake 스토리지: Tri-Secret Secure(TSS)가 활성화된 계정은 Apache Iceberg™ 테이블용 Snowflake 스토리지를 사용하는 새 Snowflake 관리형 Iceberg 테이블을 만들지 못할 수 있습니다. 자세한 내용은 Encryption을 참조하세요.
• 호환되지 않는 유형 변경: 소스 열 유형이 다른 Iceberg 유형으로 매핑되는 유형으로 바뀌면 테이블이 실패로 표시되고 재스냅샷이 필요합니다. 완전한 소스→Iceberg 유형 매핑은 Type mapping reference를 참조하세요.
• 같은 Iceberg 유형 내 파라미터 변경: 커넥터는 같은 Iceberg 유형 내의 파라미터 변경(예: decimal(10,2)에서 decimal(20,2)로)을 인식하지 못합니다. 열은 현재 Iceberg 유형을 유지합니다.
• v3의 나노초 타임스탬프 범위 제한: TIMESTAMP(7..9) 열이 v3에서 timestamp_ns 또는 timestamptz_ns로 매핑되면 표현 가능한 날짜 범위가 1677-09-21부터 2262-04-11로 좁아집니다. 이 범위 밖의 값은 삽입 시점에 거부됩니다.
• TIMESTAMP WITH TIME ZONE 오프셋이 UTC로 축소: Iceberg에는 오프셋을 보존하는 타임스탬프 유형이 없습니다. 원래 시간대 오프셋이나 리전 이름은 손실되며 UTC 인스턴트만 저장됩니다.
• v3에서 소스 TIMESTAMP 정밀도 확장 미지원: 소스 열의 정밀도가 증가하면(예: TIMESTAMP(6)을 TIMESTAMP(7)로 변경) Iceberg 열 유형을 timestamp에서 timestamp_ns로 승격할 수 없습니다. 커넥터는 원래 정밀도로 만들어졌기 때문입니다.
• 커넥터 시작 후 Table Storage Format 또는 Iceberg Version을 변경하지 마세요: 수집 시작 후 커넥터의 Table Storage Format과 Iceberg Version 파라미터를 수정해서는 안 됩니다. 목적지 테이블 간 설정 혼합은 지원되지 않습니다. 전환하려면 'Switching table storage format or Iceberg version'의 단계를 따르세요.

유형 매핑 참조

다음 표는 Oracle 유형이 Snowflake 표준 및 Iceberg 목적지 유형으로 매핑되는 방식을 보여줍니다.

표에 나열되지 않은 소스 유형은 표준 테이블에서는 TEXT로, Iceberg 테이블에서는 string으로 매핑됩니다.

테이블 스토리지 형식 또는 Iceberg 버전 전환

Standard와 Iceberg 사이, 또는 Iceberg v2와 v3 사이를 전환하려면 커넥터를 다시 만들어야 합니다. 다음 단계를 따르세요.

• 커넥터를 중지합니다.
• Openflow에서 프로세스 그룹을 삭제합니다.
• 목적지 데이터베이스를 수동으로 정리합니다(복제된 스키마/테이블 삭제 또는 새 데이터베이스 사용).
• 새 Table Storage Format으로 커넥터를 다시 가져오고, 커넥터 구성 시 대상 Iceberg Version을 선택합니다.

이렇게 하면 Openflow 내에서 모든 커넥터 상태가 올바르게 정리됩니다. 새 커넥터는 목적지에 새 스냅샷을 수행합니다.

기존 커넥터를 Iceberg Version 고정 사용으로 업그레이드

커넥터 버전 0.42.0(임베디드 라이선스) / 0.41.0(독립 라이선스)이 Iceberg Version 파라미터를 도입합니다. 더 이른 커넥터 버전에서 업그레이드한다면 기존 목적지 테이블과 일치하도록 구성해야 하는 새 Iceberg Version 필드가 나타납니다.

• 커넥터를 중지합니다.
• 런타임을 버전 2026.7.21 이상으로 업그레이드합니다.
• 커넥터를 위에 나열된 버전 이상으로 제자리에서 업그레이드합니다.
• 플로우 업그레이드 후 Iceberg Version 파라미터 기본값은 3입니다. 기존 목적지 테이블이 Iceberg v2이면 커넥터 시작 전에 2로 검토·변경하세요.
• 커넥터를 시작합니다.

주의: 기존 목적지 테이블과 일치하지 않는 Iceberg Version을 선택하면 유형 매핑 오류나 DDL 실패가 발생할 수 있습니다. 값을 선택하기 전에 항상 기존 테이블의 버전을 확인하세요.

참조

• CREATE EXTERNAL VOLUME
• Data types for Apache Iceberg tables
• ALTER DATABASE
• STORAGE_SERIALIZATION_POLICY
• Set up the Openflow Connector for Oracle

더 알아보기 (Learn more)

• Oracle용 Openflow 커넥터 설정
• Oracle용 Openflow 커넥터 소개