Iceberg Wrapper
Overview
Iceberg Wrapper
Apache Iceberg is a high-performance open table format for large-scale analytic datasets. It adds ACID transactions, schema evolution, hidden partitioning, time travel, and version rollback to data stored in object storage, making it the industry-standard format for data lake and lakehouse architectures.
The Iceberg Wrapper brings your Iceberg tables into Postgres as queryable foreign tables. Read and write Iceberg data with plain SQL, join it against your application data, and query across AWS S3 Tables or any Iceberg REST Catalog backed by S3-compatible storage. Works with Supabase Vault for secure credential management.
Supported Data Types
| Postgres Type | Iceberg Type |
|---|---|
| boolean | boolean |
| real | float |
| integer | int |
| double precision | double |
| bigint | long |
| numeric | decimal |
| text | string |
| date | date |
| time | time |
| timestamp | timestamp, timestamp_ns |
| timestamptz | timestamptz, timestamptz_ns |
| jsonb | struct, list, map |
| bytea | binary |
| uuid | uuid |
Preparation
Before you get started, make sure the wrappers extension is installed on your database:
_10create extension if not exists wrappers with schema extensions;
and then create the foreign data wrapper:
_10create foreign data wrapper iceberg_wrapper_10 handler iceberg_fdw_handler_10 validator iceberg_fdw_validator;
Secure your credentials (optional)
By default, Postgres stores FDW credentials inside pg_catalog.pg_foreign_server in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with Vault, which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
For Iceberg, store your AWS credentials as two separate secrets and use the returned key IDs in the create server command with a vault_ prefix:
_11select vault.create_secret(_11 '<access key id>',_11 'aws_access_key_id',_11 'AWS access key for Wrappers'_11);_11_11select vault.create_secret(_11 '<secret access key>',_11 'aws_secret_access_key',_11 'AWS secret access key for Wrappers'_11);
Connecting to Iceberg
We need to provide Postgres with the credentials to connect to Iceberg. We can do this using the create server command. For any credentials stored in Vault, prefix the option name with vault_ and use the secret ID as the value.
AWS S3 Tables
With Vault:
_10create server iceberg_server_10 foreign data wrapper iceberg_wrapper_10 options (_10 vault_aws_access_key_id '<key_ID>',_10 vault_aws_secret_access_key '<secret_key>',_10 region_name 'us-east-1',_10 aws_s3table_bucket_arn 'arn:aws:s3tables:us-east-1:204203087419:bucket/my-table-bucket'_10 );
Without Vault:
_10create server iceberg_server_10 foreign data wrapper iceberg_wrapper_10 options (_10 aws_access_key_id '<key_ID>',_10 aws_secret_access_key '<secret_key>',_10 region_name 'us-east-1',_10 aws_s3table_bucket_arn 'arn:aws:s3tables:us-east-1:204203087419:bucket/my-table-bucket'_10 );
Iceberg REST Catalog with AWS S3 (or compatible) storage
With Vault:
_10create server iceberg_server_10 foreign data wrapper iceberg_wrapper_10 options (_10 vault_aws_access_key_id '<key_ID>',_10 vault_aws_secret_access_key '<secret_key>',_10 region_name 'us-east-1',_10 catalog_uri 'https://rest-catalog/ws',_10 warehouse 'warehouse',_10 "s3.endpoint" 'https://alternative-s3-storage:8000' -- optional_10 );
Without Vault:
_10create server iceberg_server_10 foreign data wrapper iceberg_wrapper_10 options (_10 aws_access_key_id '<key_ID>',_10 aws_secret_access_key '<secret_key>',_10 region_name 'us-east-1',_10 catalog_uri 'https://rest-catalog/ws',_10 warehouse 'warehouse',_10 "s3.endpoint" 'https://alternative-s3-storage:8000' -- optional_10 );
Resources
Details
Third-party integrations and docs are managed by Supabase partners.