See what is really present in your PostgreSQL backup repository.
Read-only, format-aware, and honest when the evidence is incomplete.
ObjectStoreViewer is a small web application for inspecting PostgreSQL backup repositories in S3, Azure Blob Storage, and GCS. It turns object-store metadata into a bounded inventory, a Barman backup catalog, WAL continuity diagnostics, and conservative observed recovery coverage.
Important
ObjectStoreViewer reports structural evidence. It does not prove that a restore will succeed.
- Read-only by construction — the application can list, inspect, and read bounded metadata; it has no upload, delete, restore, or mutation surface.
- Useful at a glance — see completed, running, failed, malformed, missing, or unsupported backups without digging through object keys by hand.
- WAL-aware — inspect compact WAL ranges, timeline history, duplicates, partial files, and candidate or confirmed gaps.
- Honest uncertainty — incomplete, stale, truncated, or unsupported
evidence stays
unknown; it never quietly becomes healthy. - Cloud-neutral — the same evidence model is used over S3, Azure, and GCS.
| Capability | Status |
|---|---|
| Barman Cloud inventory, backup catalog, WAL and timelines | ✅ Available |
| S3, Azure Blob Storage, and GCS adapters | ✅ Available |
| Standalone web dashboard | ✅ Available |
| pgConsole sidecar evidence producer | 🧪 Integration preview |
| pgBackRest catalog and dependency semantics | 🚧 Planned |
| Raw backup download or restore operations | ⛔ Not provided |
You need Go 1.26+, make, a repository root, and credentials restricted to
list/get operations.
git clone https://github.com/fyannk/pgObjectStoreViewer.git
cd pgObjectStoreViewer
make build
REPOSITORY_FORMAT=barman-cloud \
PROVIDER=s3 \
DESTINATION_PATH=s3://example-backups/repository \
AWS_REGION=eu-west-1 \
./bin/objectstoreviewerThen open http://localhost:3000.
| URL | Purpose |
|---|---|
/ |
Backup inventory and evidence summary |
/wals |
Searchable Barman WAL evidence |
/healthz |
Process liveness |
/readyz |
Configuration and recent store reachability |
The example uses the AWS workload-identity chain. Static credentials are accepted only through mounted files; see the configuration guide.
Only the provider coordinates change:
# Azure
PROVIDER=azure
DESTINATION_PATH=azure://backup-container/repository
# GCS
PROVIDER=gcs
DESTINATION_PATH=gs://backup-bucket/repositoryProvider-specific identity options are documented in Configuration.
Versioned, multi-architecture images are published to GitHub Container Registry with SBOM and provenance attestations:
docker pull ghcr.io/fyannk/pgobjectstoreviewer:v0.1.1The latest release also provides Linux amd64/arm64 binaries, checksums, an SPDX SBOM, license inventory, vulnerability report, and the immutable image digest.
For Kubernetes, adapt the hardened
deploy/kubernetes-example.yaml manifest and
its read-only policies under deploy/policies/.
Warning
The standalone application provides no authentication or TLS. Put it behind an authentication proxy and an operator-managed network boundary. Never expose its port directly.
The details live in the documentation site:
- Getting started
- Installation
- Evidence model
- Security and trust boundary
- Configuration reference
- pgConsole sidecar
- Roadmap
Bug reports, format edge cases, fixtures, documentation fixes, and pull requests are welcome. Start with:
make test # fast, hermetic unit suite
make check # complete non-Docker verification
make docs # type-check and build the documentation siteDocker-backed provider, scale, and restricted-runtime checks are described in
the verification guide. Read
CONTRIBUTING.md before changing behavior, and note that
participation is governed by the
Code of Conduct.
Found a vulnerability? Do not open a public issue. Report it privately
through
GitHub Security Advisories.
SECURITY.md covers supported versions, what is in and out of
scope, and how to verify the provenance of what you run.
ObjectStoreViewer is available under the Apache License 2.0.