skade_katalog/lib.rs
1// Apache-2.0 licensed. See LICENSE-APACHE.
2
3//! Pure-Rust, embedded Apache Iceberg catalog backed by [redb].
4//!
5//! `nornir-catalog` implements the `iceberg::Catalog` trait against a
6//! single-file [redb] database. All catalog metadata (namespaces, namespace
7//! properties, table-pointer rows) lives inside one `.redb` file. Iceberg
8//! table metadata JSON / Avro manifests / Parquet data files live in whatever
9//! storage backend the supplied `FileIO` points at (local fs, S3, GCS, …).
10//!
11//! ## Why redb?
12//!
13//! * **Pure Rust** — no `libsqlite3`, no JVM, no Postgres process.
14//! * **ACID** — every catalog mutation is a single redb `WriteTransaction`,
15//! so concurrent writers in the same process are serialized correctly and
16//! crashes leave the database consistent.
17//! * **No async runtime** in the storage layer — redb is sync; the
18//! `Catalog` trait wrapper is async only because the trait demands it.
19//! * **Multi-table atomic commits** — because every redb write transaction
20//! spans every table in the database, this crate exposes
21//! [`RedbCatalog::atomic_release`] which commits N
22//! `iceberg::TableCommit` values atomically. Useful when one logical
23//! release ("publish bench_runs + dep_graph + components together") must
24//! either succeed entirely or roll back entirely.
25//!
26//! ## Quickstart
27//!
28//! ```no_run
29//! use std::sync::Arc;
30//! use iceberg::CatalogBuilder;
31//! use iceberg::io::LocalFsStorageFactory;
32//! use skade_katalog::RedbCatalogBuilder;
33//!
34//! # async fn run() -> anyhow::Result<()> {
35//! let catalog = RedbCatalogBuilder::default()
36//! .db_path("/var/lib/myapp/catalog.redb")
37//! .warehouse_location("file:///var/lib/myapp/warehouse")
38//! .with_storage_factory(Arc::new(LocalFsStorageFactory))
39//! .load("myapp", std::collections::HashMap::new())
40//! .await?;
41//! # Ok(()) }
42//! ```
43//!
44//! ## What this crate is NOT
45//!
46//! * Not a distributed catalog. Single-process. Multiple processes opening
47//! the same file will be rejected by redb's file lock.
48//! * Not a REST endpoint. If you need that, run something like Lakekeeper.
49//! * Not schema-evolution-complete: iceberg-rust 0.9.1 does not yet expose
50//! public `TransactionAction`s for schema mutations. That's an upstream
51//! gap; once 0.10 lands it will work here unchanged.
52
53mod atomic;
54mod builder;
55mod catalog;
56mod error;
57mod keys;
58mod meta_cache;
59mod pointer_cache;
60mod static_index;
61mod store;
62mod table_cache;
63
64pub use builder::{
65 REDB_CATALOG_PROP_DB_PATH, REDB_CATALOG_PROP_DURABILITY,
66 REDB_CATALOG_PROP_METADATA_CACHE_BYTES, REDB_CATALOG_PROP_TABLE_HANDLE_CACHE_CAPACITY,
67 REDB_CATALOG_PROP_WAREHOUSE, RedbCatalogBuilder, WriteDurability,
68};
69pub use catalog::RedbCatalog;
70pub use error::RedbCatalogError;
71pub use meta_cache::DEFAULT_METADATA_CACHE_BYTES;
72pub use table_cache::DEFAULT_TABLE_HANDLE_CACHE_CAPACITY;