DataCatalog

Source: src/Cloudflare/R2/DataCatalog.ts

Apache Iceberg data catalog attached to a Cloudflare R2 bucket.

R2 Data Catalog exposes an Iceberg REST catalog endpoint backed by an R2 bucket, so engines like Spark, PyIceberg, and DuckDB can create and query Iceberg tables stored in R2. The catalog is a singleton per bucket: this resource enables it, keeps its maintenance configuration in sync, and disables it on destroy (table data in the bucket is never deleted).

Enabling a catalog

const bucket = yield* Cloudflare.R2.Bucket("LakehouseBucket");

const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
  bucketName: bucket.bucketName,
});

// Point any Iceberg REST client at the warehouse:
const uri = catalog.catalogUri;
const warehouse = catalog.name;

Maintenance

Configure compaction and snapshot expiration

const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
  bucketName: bucket.bucketName,
  compaction: { state: "enabled", targetSizeMb: "256" },
  snapshotExpiration: {
    state: "enabled",
    maxSnapshotAge: "3d",
    minSnapshotsToKeep: 5,
  },
});

Register a maintenance credential

// Maintenance jobs need an API token with R2 read/write on the bucket.
const catalog = yield* Cloudflare.R2.R2DataCatalog("Lakehouse", {
  bucketName: bucket.bucketName,
  compaction: { state: "enabled" },
  token: maintenanceToken, // Redacted<string>
});