Apache Iceberg maintenance · Rust · Apache-2.0 OR MIT

Iceberg maintenance
without the JVM

Bergman keeps Iceberg tables healthy — compacting small files with their delete files applied, re-packing manifests, expiring snapshots and removing orphans — driven by declarative policies and built on iceberg-rust. No Spark, no Trino, no cluster. One crate, one binary, and a library any Rust service can embed.

$ bergman inspect

 TABLE                        FILES   SIZE       FILE SIZE p50/p95    DELETES
 prod.analytics.events        480     2.14 GiB   3.10 MiB / 9.80 MiB  —
 prod.streaming.events_raw    92      8.11 GiB   88.4 MiB / 96.1 MiB  1204 (23%)
 prod.finance.ledger          12      6.02 GiB   402 MiB / 2.90 GiB   —

Reads only, changes nothing.

0JVMs required
0clusters to run
1static binary
8checks before a delete

Maintenance is a background tenant.

It never wins against a foreground writer and never corrupts one: triggers instead of schedules, replan instead of retry, and eight independent checks in front of every delete.

Policies declare intent

Every setting resolves through five layers: the matching rule, your defaults, the catalog's policy (Apache Polaris, opt-in), the table's own Iceberg properties, then the specification default.

How layering works →

Triggered, not scheduled

A schedule decides when a table is evaluated; measurements decide whether anything runs. A healthy table costs a few metadata reads and no data I/O.

What triggers a rewrite →

Every decision is legible

Each planned operation carries the measurement that crossed a threshold and the threshold it crossed. policy explain prints every effective value with the layer it came from.

See provenance →

Deletion is the hard part

Dry run by default, a hard 24-hour grace floor, unknown age treated as young, segment-wise containment, no scanning around a nested table, re-verification before deleting, a blast-radius ceiling, and a refusal when listing and metadata share no file.

The safety model →

Replan, never re-commit

Losing a compare-and-swap to a foreground writer is reported as conflicted, not failed. Each retry reloads the table rather than re-submitting a commit computed against one that has moved.

The commit model →

A library first

The binary is a thin consumer of the same public API. No global state, no logger installed, no runtime created. Planning is pure: dry-run is stopping before run().

Embed it →

What plan shows is what run does

Both build the plan through the same code. Every operation carries the measurement that triggered it and the threshold it crossed.

$ bergman plan

prod.analytics.events
  rule: prod.analytics.*
  -> compact
     why: partition d=2026-08-20: 412 of 480 files below 384 MiB (86% ≥ 30%)
     reads 412 files (1.83 GiB), writes ~5 files
  -> expire-snapshots
     why: oldest snapshot is 34d old (> 7d), 61 snapshots retained (keeping at least 3)
     removes up to 58 snapshots

1 tables, 2 operations, 1.83 GiB to read

It reads 412 files, not 480: only the files a rewrite would improve are read. Which files those are →

Policies, in one file

[[catalogs]]
name      = "prod"
uri       = "http://localhost:8181/catalog"
warehouse = "s3://lake/warehouse"
token_env = "BERGMAN_CATALOG_TOKEN"   # a name, never a value

[defaults.snapshots]
max_age     = "7d"        # omitted -> history.expire.max-snapshot-age-ms
min_to_keep = 3

# A streaming target: files are the right size, but equality deletes
# amplify every read. Trigger on the delete ratio, not on file sizes.
[[rules]]
match    = "prod.streaming.events_*"
schedule = "0 */2 * * *"
[rules.compaction.trigger]
delete_ratio = 0.05

[[rules]]
match = "prod.tmp.**"
skip  = true              # explicit exclusion beats implicit

Validate it offline — no catalog, no credentials, suitable for CI: bergman policy lint. Configuration reference →

Pick your shape

Cron job

One cycle, then exit. A Kubernetes CronJob, an ECS scheduled task, or a line in a crontab. Exits 2 when an operation failed or was refused.

bergman run \
  --config /etc/bergman.toml \
  --audit-log /var/log/bergman.jsonl

Daemon

Follows each rule's schedule and reacts to commit events. Ask it what it is doing, and what needs you, from anywhere.

bergman daemon --listen 0.0.0.0:9090
bergman status --daemon http://bergman:9090

Read-only first

Report health and plan work without writing anything — through the same code path run uses.

bergman inspect
bergman plan --format json \
  | jq '.tables[].operations[]'

Embedded

A Rust service holding the engine in-process — a catalog, a streaming writer, a control plane — with an observer for metrics or an approval gate.

let bergman = Bergman::builder(config)
    .with_observer(observer)
    .build()
    .await?;

let plan = bergman.plan().await?;
let report = bergman.run(&plan).await?;

Start by looking, not writing

bergman inspect reads your catalog and changes nothing.