Database Inspector: какво е, как да работим с SQLite и да дебъгваме Room

Какво е Database Inspector?

Database Inspector — е инструмент на Android Studio за инспекция и дебъгване на локални бази данни в мобилното приложение. Той позволява преглед на всички SQLite бази данни, създадени от приложението, включително бази на Room, SQLiteOpenHelper и библиотеки на трети страни. Инструментът е достъпен от Android Studio 4.1 и се стартира чрез Android Profiler или директно от менюто View.

Предназначение и възможности

Основната задача на Database Inspector е визуализация на данни в процеса на разработка. Вместо да извежда съдържанието на базата в лог или да пише отделен екран за преглед на данни, разработчикът може да отвори Database Inspector и веднага да види всички таблици, тяхната схема и съдържание. Инструментът поддържа както релационни SQLite бази, така и Room с Auto-миграции.

Кога да използваме Database Inspector

Инструментът е незаменим в сценарии, когато трябва да проверите коректността на запазване на данни след изпълнение на операция: регистрация на потребител, синхронизация със сървър, кеширане на списъци. Вместо да пишете тестов UI, dump на базата се преглежда чрез Database Inspector. Инструментът се използва активно и за дебъгване на миграции на Room — актуалната схема на таблиците може да се види след всяко обновяване на схемата.

Как работи Database Inspector

Database Inspector се свързва с процеса на Android приложението чрез Android Profiler Service. Той открива всички отворени SQLite връзки в приложението и ги показва в страничния панел. За работа е необходима Debug версия на приложението с API Level 26 (Android 8.0) и по-висок.

Архитектура и механизъм на работа

При стартиране Database Inspector създава ADB тунел между приложението на устройството и IDE на компютъра. WAL (Write-Ahead Logging) файловете на SQLite базата данни се предават през този тунел за показване на съдържанието. SQL командите се изпращат директно до SQLite двигателя на приложението чрез поддръжката на Database Inspector в Room и SQLiteDatabase. Инструментът автоматично открива момента, когато приложението отваря база данни, и я добавя в списъка за инспекция.

Изисквания към средата

За коректна работа на Database Inspector е необходимо: Android Studio 4.1+, устройство или емулатор с API Level 26+, Debug версия на приложението. За Room допълнително е необходима библиотека room-runtime версия 2.2+. Ако базата данни е създадена в WAL режим, което е стандартно за Room 2.2+, инструментът може да чете данни без да блокира основното приложение.

// Пример за Room база данни, поддържана от 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
}

Основни възможности на Database Inspector

Database Inspector предоставя пълен набор от функции за работа с локални данни: от преглед на схемата на таблиците до изпълнение на сложни SQL заявки и редактиране на записи.

Преглед на таблици и схема

В левия панел се показват всички бази данни и таблици. При избор на таблица, нейното съдържание се отваря под формата на таблица с колони: всички полета на записа се показват като колони, всеки ред е отделен запис. Схемата на таблицата (име, тип, ограничения) се показва отгоре. За външни ключове се показват връзките между таблиците.

Изпълнение на SQL заявки

Разделът Query позволява изпълнение на произволни SQL команди директно към избраната база данни. Поддържат се SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN и всякакви други SQLite оператори. Резултатите се показват в табличен вид под редактора на заявки. Историята на заявките се запазва по време на сесията.

Редактиране на записи

Клетките на таблицата могат да се редактират директно — достатъчно е да кликнете върху стойността и да въведете нова. Промените се прилагат незабавно към работещото приложение. Това е особено полезно за тестване на гранични случаи: задаване на null в задължително поле, замяна на ID с несъществуващо, проверка на обработка на дълги низове. Всички промени се записват в реално време.

Дебъгване на Room с Database Inspector

Database Inspector има дълбока интеграция с Room, което го прави незаменим при разработката на приложения с тази библиотека. Освен стандартната функционалност, инспекторът предоставя специфични за Room възможности.

Преглед на DAO заявки

За Room бази, Database Inspector показва генерираните SQL заявки за всеки DAO метод. Това позволява да се уверите, че Room генерира правилен SQL, особено за сложни заявки с JOIN, @Relation и @Transaction. Ако Room изпълнява неефективна заявка (например N+1 заявки вместо един JOIN), това веднага се вижда в лога на заявките на Database Inspector.

Дебъгване на миграции

При обновяване на схемата на Room с AutoMigration или ръчни миграции, Database Inspector показва актуалната структура на таблиците след миграцията. Достатъчно е да отворите инспектора след стартиране на приложението и да проверите дали всички колони, индекси и външни ключове са създадени правилно. Ако миграцията е неуспешна с грешка, базата данни няма да се отвори — инструментът ще покаже последната налична версия.

Проверка на Relations и Embedded

Room позволява комбиниране на данни от множество таблици чрез @Relation и @Embedded. Database Inspector помага за визуална проверка на коректността на връзките, като показва данни на свързаните таблици една до друга. За всеки външен ключ можете да навигирате до свързаната таблица с едно кликване.

// Entity с Relation за проверка чрез 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>
)

Практически сценарии за използване на Database Inspector

Database Inspector решава конкретни програмни задачи, които възникват при работа с локално съхранение на данни. Нека разгледаме най-честите сценарии за използване на инструмента в ежедневната работа.

Проверка на кеширане на данни

Често приложението кешира API отговори в локална база данни. Database Inspector позволява да се уверите в коректността на кеширането: след изпълнение на синхронизация, актуалните записи могат да се видят в кеш таблицата. Ако данните не се появиха — проблемът е в кода за запазване. Ако се появиха дубликати — проблемът е в upsert логиката.

Дебъгване на грешки при вмъкване на данни

Когато DAO метод не запазва данни, но не хвърля изключение, Database Inspector показва актуалното състояние на таблицата. Типични причини: конфликт на Primary Key (настройка на OnConflictStrategy), неправилен тип данни в колона, нарушение на NOT NULL ограничения или Foreign Key violation. Инспекторът позволява да видите changeset на базата преди и след операцията. Сравняването на моментни снимки на данни преди и след извикване на DAO — един от най-ефективните начини за дебъгване на транзакционни грешки и проверка на коректността на бизнес логиката на приложението при сложни операции за запис.

Рефакториране на схема на база данни

При промяна на схемата на таблиците — добавяне на колони, преименуване на полета, разделяне на таблици — Database Inspector помага да проверите резултата от миграцията. Достатъчно е да стартирате приложението с новата версия на базата и да се уверите, че всички данни са правилно прехвърлени в новата структура. Ако след миграцията данните изчезнаха, те могат да бъдат възстановени от dump, запазен преди рефакторирането. Този сценарий е особено актуален при преминаване от SQLiteOpenHelper към Room или при промяна на структурата на съществуващи таблици в нова версия на приложението.

Мониторинг на производителността на заявки

Database Inspector може също да се използва за оценка на производителността на SQL заявки. Чрез изпълнение на SELECT през раздела Query и измерване на времето за отговор, могат да бъдат идентифицирани заявки, на които липсват индекси. Room автоматично логва бавни заявки в Logcat с маркировка SLOW SQL, а Database Inspector позволява незабавно изпълнение на EXPLAIN QUERY PLAN за анализ на плана за изпълнение.