ADR · ADR-0005 · v1.0.0

Skip Storing Duplicate Dump by SHA (SKIP_IF_SAME_SHA)

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

deduplication sha256 storage efficiency

Pokud SHA256 nově vytvořeného dumpu odpovídá SHA256 předchozího latest artifaktu, nový dump se neuloží. Metadata záznamu odkážou na existující artefakt. Řídí se přepínačem SKIP_IF_SAME_SHA=1.

Related docs:

Kontext

Denní záloha databáze, ve které se reálně nic nezměnilo, produkuje identický dump. Bez deduplikace roste lokální storage lineárně s počtem beze-změnových dní — zejména problematické u větších databází nebo při krátkém retention intervalu.

Zvažované alternativy:

A) Vždy ukládat nový dump bez ohledu na obsah — jednoduchý kód, ale plýtvání storage

B) SHA porovnání s předchozím latest artefaktem, skip při shodě (zvoleno) — efektivní, minimální overhead

C) Plnohodnotný semantic diff databáze — příliš pomalé, komplexní, nevhodné pro tento use case

Rozhodnutí

✓ Chosen: B — SHA256 porovnání s předchozím latest, skip při shodě (SKIP_IF_SAME_SHA=1)

Při každém běhu se spočítá SHA256 nově vytvořeného dumpu. Pokud SKIP_IF_SAME_SHA=1 a SHA256 odpovídá SHA256 z meta.latest.json předchozího běhu:

nový dump soubor se neuloží (nebo se odstraní po výpočtu SHA)
metadata záznamu pro tento run odkážou na existující artefakt (path + SHA z předchozího běhu)
run.changed = false, run.changed_reason = sha_match

Pokud SHA neodpovídá:

dump se uloží standardně (ADR-0003 naming schema)
symlinky latest.dump a meta.latest.json se aktualizují
run.changed = true

SHA256 je binární hash dump souboru — doplněn SQL logical fingerprint (ADR-0006) pro přesnější sémantickou detekci změn.

Důsledky

Pozitivní:

Redukce lokálního růstu dat u databází s nízkou frekvencí změn
Restic deduplikace je efektivnější — méně nových bloků při snapshotu
run.changed flag poskytuje přehled aktivity databáze bez čtení samotných dumpů

Negativní:

SHA shoda je byte-level — není to plnohodnotný semantic diff. Různý pg_dump binary output (např. při upgrade PostgreSQL verze) může vygenerovat jiné SHA i pro identický obsah → false positive "změna". Proto doplněn SQL fingerprint (ADR-0006)
Při SKIP_IF_SAME_SHA=0 (vypnuto) se vždy ukládá nový dump — konfigurovatelné per deployment

TODO: Stejný mechanismus by měl být zvážen i pro JSON metadata soubory (run history) — viz ADR-0003 § důsledky.

Changelog

Version	Date	Author	Note
1.0.0	2026-04-09	david.sorf + claude-sonnet-4-6	Migrace z doc/ADR/ADR-0005-skip-if-same-sha.md do DAK JSON formátu. Rozšířeno o alternativy A/B/C, detail chování při shodě/neshodě SHA, changed flag semantiku a vazbu na ADR-0006.