Openflow Connector for PostgreSQL: Iceberg table destinations¶

The Openflow Connector for PostgreSQL supports writing to Snowflake-managed Apache Apache Iceberg™ tables as an opt-in destination format. Iceberg v2 and v3 are both supported. Setting Table Storage Format = ICEBERG and choosing an Iceberg Version are the only connector-level changes required. The external volume, catalog, and serialization policy are inherited from the Snowflake destination database defaults. The Iceberg specification version is set via the Iceberg Version connector parameter, which defaults to 3 for both Gen2 (Openflow UI wizard) and Gen1 (parameter context) connectors.

Storage can be either Snowflake storage for Apache Apache Iceberg™ tables (EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED') or an external volume in your cloud storage. When you use Snowflake storage, no external cloud storage or IAM grants are required.

Existing connectors using standard tables aren’t affected.

Prerequisites¶

• Openflow runtime: An existing runtime to host the connector.
• PostgreSQL source configured for CDC: Logical replication enabled (wal_level = logical), a publication created, and a user with replication privileges. For details, see Set up the Openflow Connector for PostgreSQL.
• External volume in your cloud storage: An external volume configured for Iceberg storage, with USAGE granted to the connector’s Snowflake role. See CREATE EXTERNAL VOLUME. Not required when using Snowflake storage (EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED').
• Snowflake destination database: An existing database configured with Iceberg parameters (next section).

Step 1: Configure the Snowflake destination database¶

Set the Iceberg defaults on the destination database. The connector reads these defaults at runtime for external volume and serialization policy. The Iceberg specification version is configured per-connector via the Iceberg Version parameter (see Step 3), not solely via the database-level ICEBERG_VERSION_DEFAULT.

Option A: Snowflake storage¶

When you use Snowflake storage, Snowflake stores and manages the Iceberg table files for you. No external cloud storage or IAM grants are required.

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

To configure an existing database:

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

Option B: External volume in your cloud storage¶

If you need to keep table files in your own cloud storage, configure the database with your external volume:

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

To configure an existing database:

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

If using an external volume in your cloud storage (Option B), grant the connector’s Snowflake role USAGE on the external volume:

GRANT USAGE ON EXTERNAL VOLUME <volume> TO ROLE <openflow_role>;

This step is not required for Snowflake storage.

Step 2: Set Table Storage Format in the connector’s parameter context¶

Set the Table Storage Format parameter to ICEBERG in the connector’s destination parameter context. The default is STANDARD.

For the full connector creation and configuration workflow, see Set up the Openflow Connector for PostgreSQL.

Step 3: Set the Iceberg version¶

Set the Iceberg Version connector parameter to 2 or 3. This controls the Iceberg specification version used for type mapping (for example, JSON/JSONB maps to variant on v3 vs string on v2) and the ICEBERG_VERSION=<n> clause in CREATE ICEBERG TABLE DDL.

• Gen2 (Openflow UI wizard): Iceberg Version is a required field when Table Storage Format = ICEBERG, defaulting to 3. This setting is immutable after the connector configuration is first applied.
• Gen1 (parameter context): The Iceberg Version parameter defaults to 3. Review and change to 2 if needed before starting the connector. Do not change this value after ingestion begins.

Step 4: Start and verify¶

Start the connector as usual. After the initial snapshot completes, verify the destination tables are 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>;

Known limitations¶

• Tri-Secret Secure accounts and Snowflake storage: Accounts with Tri-Secret Secure (TSS) enabled may be unable to create new Snowflake-managed Iceberg tables that use Snowflake storage for Apache Apache Iceberg™ tables. For details, see Encryption.
• Incompatible type changes on the source cause table failure: Only same-family type widening is allowed on Iceberg tables (for example, int to long, float to double, or decimal(P,S) to decimal(P',S) with wider precision). Cross-family changes such as int to decimal, long to string, or int to boolean are not allowed. If a source column’s type changes to an incompatible Iceberg type, the table is marked as failed and requires a rebootstrap.
• TIMETZ offset not preserved: Iceberg timestamptz stores only the UTC instant. PostgreSQL TIMETZ values lose the original timezone offset when written to Iceberg tables.
• Do not change Table Storage Format or Iceberg Version after the connector starts: The connector’s Table Storage Format and Iceberg Version parameter should not be modified after ingestion begins. Gen2 connectors enforce this by making Iceberg Version immutable after first apply. Mixing settings across destination tables is not supported. To switch, follow the steps in Switching table storage format or Iceberg version.

Type mapping reference¶

The following table shows how PostgreSQL types map to Snowflake standard and Iceberg destination types:

Source types not listed in the table are mapped to TEXT on standard tables and string on Iceberg tables.

Switching table storage format or Iceberg version¶

Switching between Standard and Iceberg, or between Iceberg v2 and v3, requires recreating the connector. Follow these steps:

1. Stop the connector.
2. Delete the process group in Openflow.
3. Manually clean up the destination database (drop the replicated schemas/tables, or use a new database).
4. Reimport the connector with the new Table Storage Format and select the target Iceberg Version when configuring the connector.

This ensures all connector state is correctly cleaned up within Openflow. The new connector performs a fresh snapshot into the destination.

Upgrading an existing connector to use Iceberg Version pinning¶

Gen2 connector version 2026.7.21 and Gen1 connector version 0.60.0 introduce the Iceberg Version parameter. If you are upgrading from an earlier connector version (for example, Gen1 0.56.0 to 0.60.0 or later), a new Iceberg Version field appears that you must configure to match your existing destination tables.

1. Stop the connector.
2. Upgrade the runtime to version 2026.7.21 or later.
3. Upgrade the connector in place (Gen2: to version 2026.7.21 or later; Gen1: to version 0.60.0 or later).
4. Set the Iceberg Version parameter to match your existing destination tables:
   • Gen2 (Openflow UI wizard): After upgrading, open the connector configuration wizard. The Destination details step now includes a required Iceberg Version field, defaulting to 3. If your existing destination tables are Iceberg v2, change it to 2 before applying. This choice is locked after first apply and cannot be changed later.
   • Gen1 (parameter context): The Iceberg Version parameter defaults to 3 after the flow upgrade. If your existing destination tables are Iceberg v2, change it to 2 before starting the connector.
5. Start the connector.

References¶

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