ADR · ADR-0001 · v1.1.0

Metadata-First Backup Inventory

accepted v1.0.0 accepted 2026-02-24 Authors: david.sorf Created: 2026-02-24 Updated: 2026-04-09

metadata inventory observability

Backup systém vede explicitní JSON metadata (sources, plan, run) jako primární zdroj pravdy o každém běhu — místo spoléhání na logy nebo live dotazy na databáze.

Related docs:

Kontext

Je potřeba mít spolehlivý přehled o:

co bylo detekováno jako dostupný source/databáze
co bylo skutečně plánováno k backupu
co proběhlo a s jakým výsledkem

Pouhé logy nestačí pro strojové zpracování ani report. Live dotazy na DB při reportování by znamenaly závislost na dostupnosti zdrojů.

Rozhodnutí

✓ Chosen: Metadata-first přístup — každý run zapíše strukturované JSON soubory před, během i po záloze

Zálohovací běh produkuje tři typy inventory souborů:

meta/inventory/sources.<run_ts>.json — detekované zdroje
meta/inventory/plan.<run_ts>.json — zálohovací plán
meta/inventory/run.<run_ts>.json — výsledek běhu

Každý typ má symlink *.latest.json pro rychlý přístup na poslední stav.

Report skript (db_bkup_report.sh) čte pouze tato metadata — neprochází živé DB ani kontejnery. Metadata jsou psána i při částečném selhání (ADR-0004).

Důsledky

Pozitivní:

Rychlý report bez přístupu na DB — stačí číst soubory
Auditní stopa: kompletní historie detekce, plánování a výsledků každého runu
Jednodušší automatizace — strojově čitelný JSON
Report funkční i když jsou zdroje dočasně nedostupné

Negativní:

Metadata musí být pravidelně refreshována runem (db_bkup.sh) — neaktualizují se samy
Přibývají soubory s každým runem; lifecycle metadat je závislý na retenci dump souborů

Řešení negativních důsledků:

Problém zastaralosti metadat je řešen cron orchestrací — db_bkup_daily.sh zajišťuje pravidelný refresh. Detaily viz TODO: ADR-XXXX (Cron orchestrace a scheduling) a DS-0001 § roadmap (scheduled integrity checks). Tato ADR záměrně neřeší timing refreshe — to je odpovědnost orchestrační vrstvy.
Lifecycle souborů je řešen retention modelem — viz ADR-0009 (prune) a retention.db_bkup.json.

Nápady a budoucí rozšíření

[Nápad] Git-based metadata backup: JSON metadata soubory (meta/inventory/) jsou díky své struktuře přirozeně vhodné pro git. Po každém úspěšném zálohovacím běhu by bylo možné automaticky commitnout a pushnout metadata do dedikovaného git repozitáře. Výsledkem by byl verzovaný, auditovatelný archiv zálohovací historie — záloha zálohy — snadno prohledatelný přes standardní git nástroje (git log, git diff). Implementace by vyžadovala post-hook skript a přístupové oprávnění na remote git repo. TBD: zvážit jako volitelný feature flag v backup.env.
[TODO] Doplnit ADR pro cron orchestraci a scheduling (ADR-XXXX) — bude obsahovat detaily o frekvenci refreshe metadat, failure handling a alerting při vynechání běhu.

Changelog

Version	Date	Author	Note
1.1.0	2026-04-09	david.sorf + claude-sonnet-4-6	Rozšířeny důsledky: přidáno řešení zastaralosti metadat přes cron orchestraci s odkazem na TODO ADR-XXXX (Cron scheduling) a DS-0001 roadmap. Přidána sekce 'Nápady': git-based metadata backup (JSON soubory jako záloha zálohy v dedikovaném git repo) a TODO placeholder pro ADR cron orchestrace.
1.0.0	2026-04-09	david.sorf + claude-sonnet-4-6	Migrace z doc/ADR/ADR-0001-metadata-first-inventory.md do DAK JSON formátu. Obsah rozšířen o kontext live-query závislosti a detail symlink strategie.