Recupera il database SQLite corrotto di un'app Android

Su qualsiasi dispositivo Android il database risiede nella sandbox privata dell'app, in /data/data/<pacchetto>/databases/, di solito come tre file: il principale <nome>.db, un registro di scrittura anticipata (write-ahead log) <nome>.db-wal e un indice in memoria condivisa <nome>.db-shm. Il file principale si apre con la stringa magica di 16 byte "SQLite format 3\000"; la dimensione di pagina di due byte si trova all'offset 16 in byte, e i byte di versione di lettura/scrittura del formato, agli offset 18 e 19, valgono 2 quando il database è in modalità WAL — che Room attiva per impostazione predefinita.

Room aggiunge delle impronte che puoi usare per confermare di avere il file giusto. Crea una tabella android_metadata che contiene un'unica riga con le impostazioni internazionali (per esempio en_US) — quella tabella viene scritta dalla classe SQLiteDatabase di Android per ogni database di app, che si usi Room o meno — e una room_master_table con le colonne id e identity_hash, dove Room memorizza l'hash dello schema nella riga fissa id = 42. Le tue tabelle di entità (annotate con @Entity) e i relativi indici si trovano accanto a esse, tutte elencate nella tabella di schema sqlite_master (con alias sqlite_schema nelle versioni più recenti di SQLite). Un'app con SQLiteOpenHelper puro salta la room_master_table, ma per il resto è lo stesso file SQLite standard.

Un database SQLite è un array piatto di pagine di dimensione fissa (4096 byte per impostazione predefinita). La pagina 1 contiene l'intestazione e lo schema; ogni tabella e indice è un albero-B le cui pagine interne contengono puntatori di cella che scendono fino alle pagine foglia, e le foglie custodiscono i tuoi record veri e propri. Il motore legge l'intestazione, trova lo schema in sqlite_master e poi segue quei puntatori fino alle righe.

I puntatori sono il punto debole. Quando il processo dell'app viene ucciso dal low-memory killer di Android a metà di una scrittura, il telefono resta senza batteria, lo spazio di archiviazione si riempie, oppure due processi aprono lo stesso file senza un blocco corretto, una singola pagina interna o un campo dell'intestazione può rimanere incoerente. SQLite si ferma allora al primo problema e rifiuta l'intero file con database disk image is malformed — codice di risultato 11 (SQLITE_CORRUPT) — anche se le pagine foglia oltre la rottura contengono ancora record intatti e autodescrittivi. Un guasto affine, file is not a database — codice di risultato 26 (SQLITE_NOTADB) — significa che la stringa magica di 16 byte dell'intestazione è errata: o quei byte si sono danneggiati (le pagine che stanno dietro sono spesso integre e recuperabili) oppure il file è davvero qualcos'altro, come un database cifrato con SQLCipher che si legge come rumore ad alta entropia.

Una trappola specifica di Android rende tutto ciò urgente: il DefaultDatabaseErrorHandler.onCorruption() del framework elimina il file del database quando rileva una corruzione all'apertura. Perciò un'app che ha incontrato l'errore "malformed" potrebbe aver già cancellato il file al suo avvio successivo. Copia il database fuori dal dispositivo — e lavora su quella copia — prima di riaprire l'app.

Room attiva per impostazione predefinita il registro di scrittura anticipata (enableWriteAheadLogging()), il che significa che le modifiche confermate di recente vengono conservate provvisoriamente nel file gemello <nome>.db-wal finché un checkpoint non le riversa di nuovo nel .db principale. Dopo un crash, le tue righe più recenti possono vivere solo in quel WAL. Estrai il file principale senza di esso e al database recuperato mancherà tutto ciò che è stato scritto dall'ultimo checkpoint — un motivo frequente per cui la gente pensa "metà dei miei dati sono spariti".

Il WAL non è il database principale: inizia con un'intestazione di 32 byte il cui numero magico è 0x377f0682 o 0x377f0683 (il bit meno significativo sceglie somme di controllo dei frame big-endian o little-endian), seguita da frame composti ciascuno da un'intestazione di frame di 24 byte più un'immagine di pagina. Il file -shm è soltanto un indice in memoria condivisa verso il WAL; viene rigenerato automaticamente ed è sicuro lasciarlo indietro. Quindi estrai insieme il .db principale e il -wal: trascina qui sopra il database, poi aggiungi il -wal nella casella laterale opzionale e i suoi frame confermati vengono sovrapposti prima della scansione, in modo che il recupero rifletta l'ultima transazione confermata anziché l'ultimo checkpoint.

In una build debuggabile puoi raggiungere la cartella privata con run-as: per esempio adb exec-out run-as <pacchetto> tar c ./databases | tar xv, oppure copiare i file nell'archiviazione condivisa con run-as <pacchetto> cp databases/<nome>.db /sdcard/ e poi adb pull. Le app di release (non debuggabili) rifiutano run-as, quindi ti serve un dispositivo con root oppure la funzione di esportazione dell'app stessa. La vecchia via adb backup -f backup.ab <pacchetto> è stata deprecata in Android 12 e rispetta android:allowBackup, perciò non è affidabile per questo scopo. Qualunque strada tu scelga, prendi <nome>.db, <nome>.db-wal e <nome>.db-shm in un colpo solo, così il WAL corrisponde al file principale.

Con la copia sul tuo computer, il controllo classico è sqlite3 name.db "PRAGMA integrity_check;" (o il più rapido quick_check), e la riparazione classica è il comando .recover di SQLite stesso, che legge ogni riga decodificabile e la scrive in un file nuovo di zecca. Questa pagina fa esattamente questo nel browser: percorre le pagine, ricostruisce gli alberi-B, ricorre a una scansione grezza delle pagine per le righe che la catena di puntatori non raggiunge più, e mette tutto ciò che non riesce ad attribuire a una tabella nota in una tabella lost_and_found invece di scartarlo — così non si butta via niente e non si carica niente.