Database Inspector: co to jest, jak pracować z SQLite i debugować Room

Czym jest Database Inspector?

Database Inspector — to narzędzie Android Studio do inspekcji i debugowania lokalnych baz danych w aplikacji mobilnej. Pozwala przeglądać wszystkie bazy SQLite utworzone przez aplikację, w tym bazy Room, SQLiteOpenHelper i bibliotek zewnętrznych. Narzędzie jest dostępne od Android Studio 4.1 i uruchamiane przez Android Profiler lub bezpośrednio z menu View.

Przeznaczenie i możliwości

Głównym zadaniem Database Inspector jest wizualizacja danych w procesie programowania. Zamiast wypisywać zawartość bazy w logu lub pisać osobny ekran do przeglądania danych, programista może otworzyć Database Inspector i od razu zobaczyć wszystkie tabele, ich schemat i zawartość. Narzędzie obsługuje zarówno relacyjne bazy SQLite, jak i Room z Auto-migracjami.

Kiedy używać Database Inspector

Narzędzie jest niezastąpione w scenariuszach, gdy trzeba sprawdzić poprawność zapisu danych po wykonaniu operacji: rejestracja użytkownika, synchronizacja z serwerem, buforowanie list. Zamiast pisać testowy UI, dump bazy jest przeglądany przez Database Inspector. Narzędzie jest również aktywnie używane do debugowania migracji Room — można zobaczyć aktualny schemat tabel po każdej aktualizacji schematu.

Jak działa Database Inspector

Database Inspector łączy się z procesem aplikacji Android przez Android Profiler Service. Wykrywa wszystkie otwarte połączenia SQLite w aplikacji i wyświetla je w panelu bocznym. Do działania wymaga Debug-kompilacji aplikacji z API Level 26 (Android 8.0) i wyższym.

Architektura i mechanizm działania

Po uruchomieniu Database Inspector tworzy tunel ADB między aplikacją na urządzeniu a IDE na komputerze. Pliki WAL (Write-Ahead Logging) bazy danych SQLite są przesyłane przez ten tunel w celu wyświetlenia zawartości. Polecenia SQL są wysyłane bezpośrednio do silnika SQLite aplikacji poprzez obsługę Database Inspector w Room i SQLiteDatabase. Narzędzie automatycznie wykrywa moment otwarcia bazy danych przez aplikację i dodaje ją do listy inspekcji.

Wymagania środowiskowe

Do poprawnego działania Database Inspector wymaga: Android Studio 4.1+, urządzenia lub emulatora z API Level 26+, Debug-kompilacji aplikacji. Dla Room dodatkowo wymagana jest biblioteka room-runtime w wersji 2.2+. Jeśli baza danych jest tworzona w trybie WAL, co jest standardem dla Room 2.2+, narzędzie może czytać dane bez blokowania głównej aplikacji.

// Przykład bazy danych Room obsługiwanej przez 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
}

Główne funkcje Database Inspector

Database Inspector zapewnia pełen zestaw funkcji do pracy z danymi lokalnymi: od przeglądania schematu tabel po wykonywanie złożonych zapytań SQL i edycję rekordów.

Przeglądanie tabel i schematu

W lewym panelu wyświetlane są wszystkie bazy danych i tabele. Po wybraniu tabeli otwiera się jej zawartość w formie tabeli z kolumnami: wszystkie pola rekordu są wyświetlane jako kolumny, każdy wiersz to osobny rekord. Schemat tabeli (nazwa, typ, ograniczenia) jest wyświetlany u góry. Dla kluczy obcych pokazywane są powiązania między tabelami.

Wykonywanie zapytań SQL

Zakładka Query umożliwia wykonywanie dowolnych poleceń SQL bezpośrednio na wybranej bazie danych. Obsługiwane są SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN i wszelkie inne operatory SQL SQLite. Wyniki są wyświetlane w formie tabeli pod edytorem zapytań. Historia zapytań jest zapisywana w trakcie sesji.

Edycja rekordów

Komórki tabeli można edytować bezpośrednio — wystarczy kliknąć wartość i wprowadzić nową. Zmiany są stosowane natychmiastowo do działającej aplikacji. Jest to szczególnie przydatne do testowania przypadków brzegowych: ustawienie null w polu obowiązkowym, zamiana ID na nieistniejący, sprawdzanie obsługi długich ciągów. Wszystkie zmiany są rejestrowane w czasie rzeczywistym.

Debugowanie Room z Database Inspector

Database Inspector ma głęboką integrację z Room, co czyni go niezastąpionym przy tworzeniu aplikacji z tą biblioteką. Oprócz standardowej funkcjonalności, inspektor zapewnia specyficzne dla Room możliwości.

Przeglądanie zapytań DAO

Dla baz Room Database Inspector pokazuje wygenerowane zapytania SQL dla każdej metody DAO. Pozwala to upewnić się, że Room generuje poprawny SQL, szczególnie dla złożonych zapytań z JOIN, @Relation i @Transaction. Jeśli Room wykonuje nieefektywne zapytanie (np. N+1 zapytań zamiast jednego JOIN), jest to od razu widoczne w logu zapytań Database Inspector.

Debugowanie migracji

Podczas aktualizacji schematu Room z AutoMigration lub ręcznymi migracjami Database Inspector pokazuje aktualną strukturę tabel po migracji. Wystarczy otworzyć inspektora po uruchomieniu aplikacji i sprawdzić, czy wszystkie kolumny, indeksy i klucze obce zostały utworzone poprawnie. Jeśli migracja zakończyła się błędem, baza danych się nie otworzy — narzędzie pokaże ostatnią dostępną wersję.

Sprawdzanie Relations i Embedded

Room umożliwia łączenie danych z wielu tabel przez @Relation i @Embedded. Database Inspector pomaga wizualnie sprawdzić poprawność powiązań, wyświetlając dane powiązanych tabel obok siebie. Dla każdego klucza obcego można przejść do powiązanej tabeli jednym kliknięciem.

// Entity z Relation do sprawdzenia przez 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>
)

Praktyczne scenariusze użycia Database Inspector

Database Inspector rozwiązuje konkretne zadania programistyczne, które pojawiają się przy pracy z lokalnym przechowywaniem danych. Rozważmy najczęstsze scenariusze użycia narzędzia w codziennej pracy.

Sprawdzanie buforowania danych

Często aplikacja buforuje odpowiedzi API w lokalnej bazie danych. Database Inspector pozwala upewnić się o poprawności buforowania: po wykonaniu synchronizacji można zobaczyć aktualne rekordy w tabeli bufora. Jeśli dane się nie pojawiły — problem leży w kodzie zapisu. Jeśli pojawiły się duplikaty — problem w logice upsert.

Debugowanie błędów wstawiania danych

Gdy metoda DAO nie zapisuje danych, ale nie zgłasza wyjątku, Database Inspector pokazuje aktualny stan tabeli. Typowe przyczyny: konflikt Primary Key (ustawienie OnConflictStrategy), nieprawidłowy typ danych w kolumnie, naruszenie ograniczeń NOT NULL lub Foreign Key violation. Inspektor pozwala zobaczyć changeset bazy przed i po operacji. Porównanie migawek danych przed i po wywołaniu DAO — to jeden z najskuteczniejszych sposobów debugowania błędów transakcyjnych i sprawdzania poprawności logiki biznesowej aplikacji przy złożonych operacjach zapisu.

Refaktoryzacja schematu bazy danych

Podczas zmiany schematu tabel — dodawania kolumn, zmiany nazw pól, dzielenia tabel — Database Inspector pomaga sprawdzić wynik migracji. Wystarczy uruchomić aplikację z nową wersją bazy i upewnić się, że wszystkie dane zostały poprawnie przeniesione do nowej struktury. Jeśli po migracji dane zniknęły, można je przywrócić z dumpu zapisanego przed refaktoryzacją. Ten scenariusz jest szczególnie aktualny przy przejściu z SQLiteOpenHelper na Room lub przy zmianie struktury istniejących tabel w nowej wersji aplikacji.

Monitorowanie wydajności zapytań

Database Inspector może być również używany do oceny wydajności zapytań SQL. Wykonując SELECT przez zakładkę Query i mierząc czas odpowiedzi, można zidentyfikować zapytania, którym brakuje indeksów. Room automatycznie loguje wolne zapytania w Logcat z oznaczeniem SLOW SQL, a Database Inspector pozwala natychmiast wykonać EXPLAIN QUERY PLAN do analizy planu wykonania.