ADR · ADR-0009 · v1.0.0

Daily Locking and Stale Lock Recovery

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

locking concurrency reliability recovery cron

db_bkup_daily.sh chrání proti paralelním běhům pomocí lock directory. Při násilném přerušení může zůstat stale lock — pro recovery existuje wrapper skript s bezpečnou detekcí aktivního procesu a volitelným --force override.

Related docs:

Kontext

db_bkup_daily.sh je spouštěn cronem. Pokud předchozí běh stále probíhá (pomalá záloha velké DB, síťové problémy s resticem) a cron spustí nový, mohlo by dojít ke kolizi:

souběžné pg_dump stejné databáze
souběžné zápisy do stejných metadata souborů
nekonzistentní restic snapshot

Po násilném přerušení (SIGKILL, restart kontejneru, OOM) lock directory zůstane — další cron běhy hlásí SKIP: daily backup already running donekonečna bez automatického recovery.

Zvažované alternativy:

A) Bez lockování — riziko souběžných běhů

B) flock / lockfile utility — závislost na externím nástroji, různé chování na různých OS

C) Lock directory + PID soubor + recovery skript (zvoleno) — bash-native, auditovatelné, s recovery

Rozhodnutí

✓ Chosen: C — lock directory s recovery skriptem (backup-container-daily-recover.sh)

Lock mechanismus:

mkdir daily.lock — atomická operace v bash, selže pokud adresář existuje
Lock je vytvořen na začátku běhu a odstraněn na konci (včetně trap EXIT cleanup)

Recovery skript (scripts/backup-container-daily-recover.sh):

Recovery provede tyto kroky v pořadí:

1. Ověří, že backup kontejner běží

2. Zkontroluje existenci daily.lock adresáře

3. Ověří aktivní backup procesy přes docker top (hledá db_bkup procesy)

4. Pokud žádný aktivní backup proces neběží → lock je stale → bezpečně smaže

5. Pokud aktivní procesy běží → odmítne smazat lock, vypíše varování

6. --force flag jako nouzový override pro případ kdy docker top nedetekuje správně

Výsledek: admin má bezpečný, standardní postup pro recovery bez rizika smazání locku běžícího backupu.

Follow-up: zvážit zápis PID + timestamp do lock metadata pro přesnější validaci stale-lock stavu.

Důsledky

Pozitivní:

Bezpečný standardní recovery postup — admin nemusí ručně mazat soubory naslepo
Menší riziko souběžného běhu backup pipeline — lock je atomický
Lepší operativní diagnostika — recovery skript zobrazí recent scheduler logy jako kontext
Recovery skript je konzervativní — raději odmítne smazat lock než riskovat souběh

Negativní:

Stale lock stále vyžaduje lidské rozhodnutí při --force — nelze plně automatizovat bez znalosti kontextu
docker top nemusí zachytit všechny subprocess formy backup skriptu — edge case při komplexním subshell spawning

TODO:

Zapsat PID + timestamp do lock adresáře (daily.lock/pid, daily.lock/started_at) pro přesnější automatickou validaci stale stavu bez nutnosti docker top

Changelog

Version	Date	Author	Note
1.0.0	2026-04-09	david.sorf + claude-sonnet-4-6	Migrace z doc/ADR/ADR-0009-daily-locking-and-stale-lock-recovery.md do DAK JSON formátu. Rozšířeno o alternativy A/B/C, krok-za-krokem popis recovery procesu, PID TODO a edge case s docker top.