Database Inspector: cos'è, come lavorare con SQLite e debug di Room

Cos'è Database Inspector?

Database Inspector è uno strumento di Android Studio per ispezionare e eseguire il debug di database locali in un'applicazione mobile. Consente di visualizzare tutti i database SQLite creati dall'applicazione, inclusi database Room, SQLiteOpenHelper e librerie di terze parti. Lo strumento è disponibile a partire da Android Studio 4.1 e può essere avviato tramite Android Profiler o direttamente dal menu View.

Scopo e capacità

Lo scopo principale di Database Inspector è la visualizzazione dei dati durante lo sviluppo. Invece di inviare il contenuto del database a un log o scrivere una schermata separata per visualizzare i dati, lo sviluppatore può aprire Database Inspector e vedere immediatamente tutte le tabelle, i loro schemi e contenuti. Lo strumento supporta sia database SQLite relazionali che Room con Auto-migrazioni.

Quando usare Database Inspector

Lo strumento è indispensabile negli scenari in cui è necessario verificare la correttezza dell'archiviazione dei dati dopo aver eseguito un'operazione: registrazione utente, sincronizzazione con il server, caching di elenchi. Invece di scrivere un'interfaccia di test, il dump del database viene visualizzato tramite Database Inspector. Lo strumento viene utilizzato anche attivamente per il debug delle migrazioni Room — è possibile vedere lo schema effettivo delle tabelle dopo ogni aggiornamento dello schema.

Come funziona Database Inspector

Database Inspector si connette al processo dell'applicazione Android tramite Android Profiler Service. Rileva tutte le connessioni SQLite aperte nell'applicazione e le mostra nel pannello laterale. È necessaria una build Debug dell'applicazione con API Level 26 (Android 8.0) e superiore.

Architettura e meccanismo

All'avvio, Database Inspector crea un tunnel ADB tra l'applicazione sul dispositivo e l'IDE sul computer. I file di database SQLite WAL (Write-Ahead Logging) vengono trasmessi attraverso questo tunnel per visualizzare il contenuto. I comandi SQL vengono inviati direttamente al motore SQLite dell'applicazione attraverso il supporto di Database Inspector in Room e SQLiteDatabase. Lo strumento rileva automaticamente quando l'applicazione apre un database e lo aggiunge all'elenco ispezionato.

Requisiti di ambiente

Per il corretto funzionamento di Database Inspector, è necessario: Android Studio 4.1+, un dispositivo o emulatore con API Level 26+, e una build Debug dell'applicazione. Per Room, è inoltre richiesta la libreria room-runtime versione 2.2+. Se il database viene creato con modalità WAL, che è standard per Room 2.2+, lo strumento può leggere i dati senza bloccare l'applicazione principale.

// Esempio di database Room supportato da Database Inspector
@Database(
    entities = [User::class, Order::class],
    version = 2,
    autoMigrations = [AutoMigration(from = 1, to = 2)]
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun orderDao(): OrderDao
}

Caratteristiche principali di Database Inspector

Database Inspector fornisce un set completo di funzioni per lavorare con i dati locali: dalla visualizzazione dello schema delle tabelle all'esecuzione di query SQL complesse e alla modifica dei record.

Visualizzazione di tabelle e schema

Il pannello di sinistra mostra tutti i database e le tabelle. Quando si seleziona una tabella, il suo contenuto viene visualizzato in una griglia con colonne: tutti i campi del record vengono mostrati come colonne, ogni riga è un record separato. Lo schema della tabella (nome, tipo, vincoli) viene visualizzato nella parte superiore. Per le chiavi esterne, vengono mostrate le relazioni tra le tabelle.

Esecuzione di query SQL

La scheda Query consente di eseguire comandi SQL arbitrari direttamente sul database selezionato. SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN e qualsiasi altro operatore SQLite sono supportati. I risultati vengono visualizzati in formato tabellare sotto l'editor di query. La cronologia delle query viene conservata durante la sessione.

Modifica dei record

Le celle della tabella possono essere modificate direttamente — basta fare clic su un valore e inserirne uno nuovo. Le modifiche vengono applicate immediatamente all'applicazione in esecuzione. Ciò è particolarmente utile per testare i casi limite: impostare null in un campo obbligatorio, sostituire un ID con uno inesistente, verificare la gestione di stringhe lunghe. Tutte le modifiche vengono impegnate in tempo reale.

Debug di Room con Database Inspector

Database Inspector ha un'integrazione profonda con Room, rendendolo indispensabile quando si sviluppano applicazioni con questa libreria. Oltre alla funzionalità standard, l'ispettore fornisce capacità specifiche di Room.

Visualizzazione delle query DAO

Per i database Room, Database Inspector mostra le query SQL generate per ogni metodo DAO. Ciò consente di verificare che Room generi SQL corretto, specialmente per query complesse con JOIN, @Relation e @Transaction. Se Room esegue una query inefficiente (ad esempio, N+1 query invece di un singolo JOIN), è immediatamente visibile nel log delle query di Database Inspector.

Debug delle migrazioni

Quando si aggiorna lo schema Room con AutoMigration o migrazioni manuali, Database Inspector mostra la struttura effettiva delle tabelle dopo la migrazione. Basta aprire l'ispettore dopo aver avviato l'applicazione e verificare che tutte le colonne, gli indici e le chiavi esterne siano stati creati correttamente. Se una migrazione è fallita con un errore, il database non si aprirà — lo strumento mostrerà l'ultima versione disponibile.

Verifica di Relations e Embedded

Room consente di combinare dati da più tabelle tramite @Relation e @Embedded. Database Inspector aiuta a verificare visivamente la correttezza delle relazioni mostrando i dati delle tabelle correlate affiancati. Per ogni chiave esterna, è possibile navigare alla tabella correlata con un clic.

// Entità con Relation per verifica tramite Database Inspector
@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String
)

data class UserWithOrders(
    @Embedded val user: User,
    @Relation(parentColumn = "id", entityColumn = "user_id")
    val orders: List<Order>
)

Scenari pratici di utilizzo di Database Inspector

Database Inspector risolve compiti di sviluppo specifici che sorgono quando si lavora con l'archiviazione locale dei dati. Esaminiamo i casi d'uso più comuni dello strumento nel lavoro quotidiano.

Verifica del caching dei dati

Spesso, un'applicazione memorizza nella cache le risposte API in un database locale. Database Inspector consente di verificare la correttezza del caching: dopo la sincronizzazione, è possibile vedere i record effettivi nella tabella della cache. Se i dati non compaiono — il problema è nel codice di salvataggio. Se compaiono duplicati — il problema è nella logica upsert.

Debug degli errori di inserimento dati

Quando un metodo DAO non salva i dati ma non lancia un'eccezione, Database Inspector mostra lo stato effettivo della tabella. Cause tipiche: conflitto di Primary Key (impostazione OnConflictStrategy), tipo di dato errato in una colonna, violazione del vincolo NOT NULL o violazione di Foreign Key. L'ispettore consente di vedere il changeset del database prima e dopo l'operazione. Confrontare gli snapshot dei dati prima e dopo una chiamata DAO è uno dei modi più efficaci per eseguire il debug degli errori transazionali e verificare la correttezza della logica di business dell'applicazione durante operazioni di scrittura complesse.

Refactoring dello schema del database

Quando si modifica lo schema delle tabelle — aggiunta di colonne, ridenominazione di campi, divisione di tabelle — Database Inspector aiuta a verificare il risultato della migrazione. Basta avviare l'applicazione con la nuova versione del database e verificare che tutti i dati siano stati trasferiti correttamente nella nuova struttura. Se i dati mancano dopo la migrazione, è possibile ripristinarli da un dump salvato prima del refactoring. Questo scenario è particolarmente rilevante durante la migrazione da SQLiteOpenHelper a Room o quando si modifica la struttura di tabelle esistenti in una nuova versione dell'applicazione.

Monitoraggio delle prestazioni delle query

Database Inspector può anche essere utilizzato per valutare le prestazioni delle query SQL. Eseguendo SELECT tramite la scheda Query e misurando il tempo di risposta, è possibile identificare le query a cui mancano gli indici. Room registra automaticamente le query lente in Logcat con il tag SLOW SQL e Database Inspector consente di eseguire immediatamente EXPLAIN QUERY PLAN per analizzare il piano di esecuzione.