sqliteproof

Find out which tables survived, not which pages broke.

SQLite's own PRAGMA integrity_check is good at detecting corruption. What it gives you is this:

*** in database main ***
Tree 25 page 35 cell 18: Offset 57005 out of range 239..4092
database disk image is malformed

That's a page number. Nobody stores data by page number. What you actually need to know at 3am is which tables can I still trust, how many rows did I lose, and is this worth restoring from backup.

$ sqliteproof app.db

app.db  —  DAMAGED

  table                        verdict         rows     lost
  ------------------------------------------------------------
  orders                       damaged      392/400        8
      breaks after row 182: database disk image is malformed
  audit_log                    intact       400/400        0
  customers                    intact       400/400        0

  1192 rows read, 8 unreadable.
  Tables marked intact above are safe to export. Restore the damaged
  ones from backup rather than trusting a partial read.

Install

pip install sqliteproof

Python 3.9+. No dependencies — standard library only.

Usage

sqliteproof app.db            # full report
sqliteproof app.db --json     # machine-readable
sqliteproof app.db --quiet    # verdict line only

Exit codes: 0 intact · 1 damaged · 2 unreadable or undetermined. Drops straight into a backup script:

sqliteproof app.db --quiet || echo "corruption detected" | mail -s alert me@example.com

It opens the database read-only

A tool asked to inspect a damaged file must never be able to damage it further. The connection is opened with mode=ro and nothing is written to the database, ever.

Runs entirely on your machine. No network, nothing uploaded.

It will not bluff

UNKNOWN is never dressed up as clean. A tool that reports a corrupt database as healthy is worse than no tool.

Limitations — read these first

Structural, not semantic. It verifies rows can be read. It cannot detect corruption that produces valid-looking values — a flipped bit inside an integer that still parses is invisible to it.

Row counts come from the same damaged btree. When COUNT(*) itself fails, the expected count is unknown and the verdict degrades to UNKNOWN rather than guessing.

It does not repair anything. It tells you what survived so you can export the good tables and restore the rest. Recovery is a different tool.

v0.1.0. Tested against databases built by SQLite and damaged at known page offsets: 3/3 corrupted databases localised to the correct table, 0 false alarms, 0 false-clean. That corpus is deliberate byte corruption, which is one failure mode among several — real corruption also arrives via truncated files, interrupted writes, and failing disks.

Tests

python sqliteproof/tests/corrupt.py   # build the corpus
python sqliteproof/tests/score.py     # score localisation vs ground truth

Ground truth comes from SQLite's own page allocation: tables are built one at a time and the pages added between "before" and "after" belong to that table. The file format isn't my invention and the damage lands where SQLite chose to put the data.

If you got here from an error message

These are the messages SQLite prints when a database has gone bad. If you pasted one into a search engine and landed here, this is what each one means and what this tool does about it.

Two things worth knowing before you do anything else:

1. Copy the file first. Work on the copy. Several recovery approaches write to the database, and a failed repair on your only copy is unrecoverable. sqliteproof itself opens the file read-only and never writes, which is why it is safe to run first.
2. A clean report is not a guarantee of correct data. It means every row was structurally readable. Corruption that produces valid-looking values cannot be detected this way, and this tool says so rather than implying otherwise.

If you need to repair rather than assess, SQLite's own .recover command in the sqlite3 shell is the right next step. This tool tells you whether that is worth doing and what you stand to lose — it does not replace it.

Related

statementproof — the same idea for bank statement PDFs. Most converters hand you a CSV and leave you to trust it; statementproof checks the extracted rows against the statement's own opening and closing balances and names the row where the running total stops following.

License

MIT.