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

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

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

출처: Snowflake 문서

본문

Iceberg 스펙 버전은 Iceberg Version 커넥터 파라미터로 설정되며, Gen2(Openflow UI 위저드)와 Gen1(파라미터 컨텍스트) 커넥터 모두 기본값이 3입니다.

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

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

사전 준비 사항

• Openflow 런타임: 커넥터를 호스팅할 기존 런타임.
• CDC용으로 구성된 PostgreSQL 소스: 논리적 복제 활성화(wal_level = logical), publication 생성, 복제 권한이 있는 사용자. 자세한 내용은 'Set up the Openflow Connector for PostgreSQL'을 참조하세요.
• 클라우드 스토리지의 외부 볼륨: 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 PostgreSQL'을 참조하세요.

3단계: Iceberg 버전 설정

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

• Gen2(Openflow UI 위저드): Iceberg Version은 Table Storage Format = ICEBERG일 때 필수 필드이며 기본값은 3입니다. 이 설정은 커넥터 구성을 처음 적용한 뒤에는 변경할 수 없습니다.
• Gen1(파라미터 컨텍스트): 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 유형을 유지합니다.
• TIMETZ 오프셋 미보존: Iceberg timestamptz는 UTC 인스턴트만 저장합니다. PostgreSQL TIMETZ 값은 Iceberg 테이블에 쓸 때 원래 시간대 오프셋을 잃습니다.
• 커넥터 시작 후 Table Storage Format 또는 Iceberg Version을 변경하지 마세요: 수집 시작 후 커넥터의 Table Storage Format과 Iceberg Version 파라미터를 수정해서는 안 됩니다. Gen2 커넥터는 Iceberg Version을 첫 적용 후 불변으로 만들어 이를 강제합니다. 목적지 테이블 간 설정 혼합은 지원되지 않습니다. 전환하려면 'Switching table storage format or Iceberg version'의 단계를 따르세요.

유형 매핑 참조

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

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

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

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

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

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

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

Gen2 커넥터 버전 2026.7.21과 Gen1 커넥터 버전 0.60.0이 Iceberg Version 파라미터를 도입합니다. 더 이른 커넥터 버전(예: Gen1 0.56.0에서 0.60.0 이상)에서 업그레이드한다면 기존 목적지 테이블과 일치하도록 구성해야 하는 새 Iceberg Version 필드가 나타납니다.

• 커넥터를 중지합니다.
• 런타임을 버전 2026.7.21 이상으로 업그레이드합니다.
• 커넥터를 제자리에서 업그레이드합니다(Gen2: 버전 2026.7.21 이상, Gen1: 버전 0.60.0 이상).
• 기존 목적지 테이블과 일치하도록 Iceberg Version 파라미터를 설정합니다.
  • Gen2(Openflow UI 위저드): 업그레이드 후 커넥터 구성 위저드를 엽니다. Destination details 단계에 이제 필수 Iceberg Version 필드가 포함되며 기본값은 3입니다. 기존 목적지 테이블이 Iceberg v2이면 적용 전에 2로 변경하세요. 이 선택은 첫 적용 후 잠기며 나중에 변경할 수 없습니다.
  • Gen1(파라미터 컨텍스트): 플로우 업그레이드 후 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 PostgreSQL

더 알아보기 (Learn more)

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