Getting started
Install Bergman, point it at a catalog, and read what is wrong with your tables — before it writes anything.
The first two commands read only.
Install
brew install hupe1980/tap/bergman # macOS (Apple Silicon) and Linux
cargo install bergman # anywhere Rust builds
Or as a container — distroless, non-root, statically linked, no shell:
docker run --rm \
-v ./bergman.toml:/etc/bergman/bergman.toml:ro \
ghcr.io/hupe1980/bergman:latest inspect
Or a binary from the releases page:
static musl Linux for x86_64 and aarch64, and macOS on Apple Silicon, each with
a .sha256 beside it.
Or from source — Rust 1.95 or later:
git clone https://github.com/hupe1980/bergman && cd bergman
cargo build --releasePoint it at a catalog
The smallest useful bergman.toml:
[[catalogs]]
name = "prod"
uri = "http://localhost:8181/catalog"
warehouse = "s3://lake/warehouse"
[catalogs.properties]
"s3.region" = "eu-central-1"
[[rules]]
match = "prod.**"
Check it offline — no catalog, no credentials, so it runs in CI:
bergman policy lintok: 1 catalog, 1 ruleLook before you write
bergman inspect TABLE FILES SIZE FILE SIZE p50/p95 DELETES SNAPSHOTS MANIFESTS
prod.analytics.events 480 2.14 GiB 3.10 MiB / 9.80 MiB — 61 / 34d 48 (41 small)
prod.streaming.events_raw 92 8.11 GiB 88.4 MiB / 96.1 MiB 1204 (23%) 8 / 2h 6
prod.finance.ledger 12 6.02 GiB 402 MiB / 2.90 GiB — 4 / 6d 2
Every number comes from manifest metadata; no data file is opened.
p50far below target — small files. Half ofevents' files are under 3.10 MiB against the 512 MiB default target.p95far above target — oversized files a mean would hide.ledger's largest are 2.90 GiB, so one query task does all their work.DELETESwith a percentage — read amplification: 23% ofevents_raw's rows are named by delete files, and every query pays to apply them.SNAPSHOTSwith an age — metadata growth: 61 manifest lists reaching back 34 days.
Ask what maintenance would do
bergman planprod.analytics.events
rule: prod.**
-> 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
Each operation names the measurement that triggered it and the threshold it
crossed; policy explain shows where each
threshold came from. Only the files a rewrite would
improve are read — 412, not 480.
Run it
bergman run --audit-log /var/log/bergman.jsonlprod.analytics.events
[ok] compact: 412 files (1.83 GiB) rewritten into 5 (1.79 GiB) across 1 groups
in 1 partitions
[ok] expire-snapshots: 58 snapshots expired
1 tables, 2 operations succeeded in 47s
run builds the plan through the same code as plan, then executes it. Both
take --table <glob> to scope which tables are examined and --only to scope
which operations run:
# Reclaim storage tonight; rewrite nothing.
bergman run --only remove-orphans,expire-snapshots
Any subset is safe: per-table order is preserved.
bergman runexits2when any operation failed or was refused.
What is on by default
| Operation | Default | Opt in |
|---|---|---|
| Snapshot expiration (metadata) | on | — writes no data files |
| Expiration file cleanup | off | snapshots.delete_files |
| Orphan removal | off | orphans.enabled, then mode = "delete" |
| Compaction | off | compaction.enabled |
| Manifest rewrite | off | manifests.rewrite |
Next
- Policies — how a setting is resolved, and why
- Orphan files — read before enabling deletion
- Status — what executes, and what is refused