DuckDB

Last updated Oct 1, 2026 Below is an example of using DuckDB ↗︎ to connect to Basin Catalog. For more information on connecting to Basin Catalog with DuckDB, refer to DuckDB documentation ↗︎.

Prerequisites

• Sign up for a Cloudflare account ↗︎.
• Create an R2 bucket and enable the data catalog.
• Create an R2 API token with both R2 and data catalog permissions.
• Install DuckDB ↗︎.
• Note: DuckDB 1.4.0 ↗︎ or greater is required to attach and write to Iceberg REST Catalogs ↗︎.
• Note: DuckDB does not currently support ↗︎ DELETE on partitioned tables.

Example usage

In the DuckDB CLI ↗︎ (Command Line Interface), run the following commands:

-- Install the Iceberg DuckDB extension if needed, then load the extension.
INSTALL iceberg;
LOAD iceberg;

-- Install and load httpfs extension for reading/writing files over HTTP(S).
INSTALL httpfs;
LOAD httpfs;

-- Create a DuckDB secret to store Basin Catalog credentials.
CREATE SECRET r2_secret (
    TYPE ICEBERG,
    TOKEN '<token>'
);

-- Attach Basin Catalog with the following ATTACH statement.
ATTACH '<warehouse_name>' AS my_r2_catalog (
    TYPE ICEBERG,
    ENDPOINT '<catalog_uri>'
);

-- Create the default schema in the catalog and set it as the active schema.
CREATE SCHEMA my_r2_catalog.default;
USE my_r2_catalog.default;

-- Create and populate a sample Iceberg table with data.
CREATE TABLE my_iceberg_table AS SELECT a FROM range(4) t(a);

-- Show all available tables.
SHOW ALL TABLES;

-- Query the Iceberg table you just created.
SELECT * FROM my_r2_catalog.default.my_iceberg_table;

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/basin-catalog/config-examples/duckdb/#page","headline":"DuckDB","description":"Connect DuckDB to Basin Catalog to query and manage Iceberg tables.","url":"https://developers.cloudflare.com/basin-catalog/config-examples/duckdb/","inLanguage":"en","image":"https://developers.cloudflare.com/basin-catalog/config-examples/duckdb/og.png?v=9c709b4d966a5902","dateModified":"2026-10-01","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Connect PyIceberg to Basin Catalog to create and query Iceberg tables in Python. title: PyIceberg image: https://developers.cloudflare.com/basin-catalog/config-examples/pyiceberg/og.png?v=b3f18a06e2e6f5ca

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/basin-catalog/llms.txt
Use this file to discover all available pages before exploring further.