Berg

Berg is a developer and operational management layer for Apache Iceberg.

The v1 foundation provides discovery, health, desired-state planning, guarded execution, customer-local Agent execution, and capability-aware Iceberg maintenance for approved metadata operations. Snapshot expiration is supported only where the configured backend exposes a complete Iceberg snapshot history.

Quick start

Install uv, then:

uv sync --group dev
export BERG_MINIO_USER='choose-a-local-user'
export BERG_MINIO_PASSWORD='choose-a-local-password'
export AWS_ACCESS_KEY_ID="$BERG_MINIO_USER"
export AWS_SECRET_ACCESS_KEY="$BERG_MINIO_PASSWORD"
docker compose up -d
uv run berg connect
uv run berg scan
uv run berg inspect analytics.events
uv run berg health analytics.events

Use --output json for automation. See docs/local-development.md for the local catalog and fixture workflow.

For a complete local acceptance check, run make local-clean-start. This explicitly resets only the project Docker volume, recreates fixtures, and verifies the full local workflow.

Desired state is expressed as a versioned berg.dev/v1 Table document. Use berg validate-spec table.yaml, berg diff table.yaml, or berg plan --spec table.yaml to inspect and plan declared changes.

Python users can author the same canonical document with berg.sdk.TableDefinition; see docs/python-api.md.

For customer-local automation, use the one-shot Agent container. Mount a Berg configuration, approved plan, state directory, and audit directory, then run berg agent apply; see docker-compose.agent.yml for the deployment shape.

Scope boundaries are documented in V0_SCOPE.md and the proposed next product contract is in V1_SCOPE.md.

The guarded execution slice supports explicitly approved properties, nullable schema additions, additive partition fields, snapshot expiration where certified, and age/reference-guarded orphan cleanup. Compaction and destructive changes remain intentionally unsupported.