Doplňkový SQL-based logical fingerprint (fingerprint.sql_v1) detekuje skutečné logické změny obsahu databáze nezávisle na binárním SHA256. Řeší false positives způsobené pg_dump version bumpy nebo formátovacími změnami bez změny dat.
SHA256 binárního dump souboru (ADR-0005) není dostatečný pro spolehlivou detekci logických změn:
Upgrade PostgreSQL nebo pg_dump verze může změnit binární výstup i pro identická data → false positive "změna"
Změna pg_dump parametrů, pořadí komentářů nebo verzovacích metadat v hlavičce → false positive
Obráceně: teoreticky by dvě různé DB mohly mít shodné SHA (byť extrémně nepravděpodobné)
Potřebujeme detekci změn na úrovni logického obsahu databáze — nezávislou na binární reprezentaci dumpu.
Zvažované alternativy:
A) Pouze SHA256 — rychlé, ale false positives při pg_dump změnách
B) Přímé SQL dotazy na row counts a checksums (zvoleno) — logická úroveň, odolná vůči formátovacím změnám
C) Plný diff obsahu tabulek — příliš pomalé a náročné na storage pro velké DB
Rozhodnutí
✓ Chosen: B — SQL-based logical fingerprint přes row counts a checksums klíčových tabulek
fingerprint.sql_v1 je hash odvozený ze série SQL dotazů spuštěných přímo na databázi před/po dumpu:
SELECT COUNT(*) FROM <table> pro každou tabulku
SELECT MD5(CAST(SUM(HASHTEXT(t::text)) AS text)) FROM <table> t nebo ekvivalent pro checksum obsahu
Výsledky jsou serializovány a hashovaný do jediného fingerprint stringu
Použití v pipeline:
run.changed a run.changed_reason kombinují SHA i fingerprint logiku
Pokud SHA je stejné → skip (ADR-0005)
Pokud SHA je jiné ale fingerprint stejný → pg_dump formátovací změna, není datová změna
Pokud fingerprint je jiný → skutečná logická změna
Report: zobrazuje zkrácený fingerprint (logical_fp) pro rychlou vizuální kontrolu.
Důsledky
Pozitivní:
Přesnější indikace logických změn obsahu DB — redukuje false positives z pg_dump formátovacích změn
Odolnost vůči pg_dump version bumps a změnám výstupního formátu
Zkrácený fingerprint v reportu umožňuje rychlou vizuální kontrolu bez čtení dump souborů
Kombinace SHA + fingerprint pokrývá oba failure modes (binární vs. logická shoda)
Negativní:
Výpočet fingerprintu je další SQL workload během zálohovacího běhu — přímé dotazy na produkční databázi
U velkých tabulek může být výpočet row-level checksum pomalý
Fingerprint algoritmus sql_v1 je vázán na schéma databáze — přidání/odebrání tabulky změní fingerprint i bez datové změny (žádoucí chování)
TODO: Definovat přesný SQL algoritmus pro sql_v1 v samostatné DS nebo technické specifikaci — aktuálně je implementace v kódu bez formální specifikace.
Changelog
Version
Date
Author
Note
1.0.0
2026-04-09
david.sorf + claude-sonnet-4-6
Migrace z doc/ADR/ADR-0006-sql-logical-fingerprint.md do DAK JSON formátu. Rozšířeno o alternativy, kombinační logiku SHA+fingerprint, konkrétní SQL přístup a TODO pro formální specifikaci algoritmu.