🌿 db-guard v1.0.0 · MIT

Detect and quarantine zero-byte SQLite "decoy" databases before they cause silent corruption.

The problem

A buggy or legacy script runs sqlite3.connect(path) on a stale path. The sqlite3 module silently creates an empty file there. Later, anything referencing that path finds a 0-byte file and either crashes — or worse, treats it as a valid database and "succeeds" against a hollow DB. The corruption is completely silent until it hurts.

What it does

Classifies every 0-byte *.db / *.sqlite / *.sqlite3 in a tree: decoys (non-canonical, safe to archive) vs canonical corruption (real data DB gone hollow → exit 2 alert, never touched).
Never deletes: --archive moves decoys (timestamped) into a quarantine dir.
Declarative canonicals: --canonical (repeatable) marks your real, data-bearing DBs.
Built-in excludes (.git, node_modules, __pycache__, tmp, backup patterns…) plus --exclude-dir / --exclude-pattern.
Cron-friendly: --json output, exit codes 0 clean · 1 decoys · 2 canonical corruption.
Zero dependencies, Python ≥ 3.8, single module.

Install (pip)

pip install db-guard @ git+https://mandrilly.com/git/db-guard.git

Usage

db-guard [ROOT]                          # scan + report
db-guard [ROOT] --json                   # machine-readable
db-guard [ROOT] --archive                # move decoys to the archive dir
db-guard [ROOT] --canonical data.db other/real.sqlite

Tests

bash run_tests.sh   # 8 checks → "8 passed, 0 failed"

Source

git clone https://mandrilly.com/git/db-guard.git