Database Inspector: o que é, como trabalhar com SQLite e depurar Room

O que é Database Inspector?

Database Inspector é uma ferramenta do Android Studio para inspecionar e depurar bancos de dados locais em um aplicativo móvel. Permite visualizar todos os bancos de dados SQLite criados pelo aplicativo, incluindo bancos Room, SQLiteOpenHelper e bibliotecas de terceiros. A ferramenta está disponível a partir do Android Studio 4.1 e pode ser iniciada via Android Profiler ou diretamente do menu View.

Propósito e capacidades

O principal propósito do Database Inspector é a visualização de dados durante o desenvolvimento. Em vez de enviar o conteúdo do banco para um log ou escrever uma tela separada para visualizar dados, o desenvolvedor pode abrir o Database Inspector e ver imediatamente todas as tabelas, seus esquemas e conteúdos. A ferramenta suporta tanto bancos de dados SQLite relacionais quanto Room com Auto-migrações.

Quando usar o Database Inspector

A ferramenta é indispensável em cenários quando você precisa verificar a exatidão do armazenamento de dados após realizar uma operação: registro de usuário, sincronização com servidor, cache de listas. Em vez de escrever uma interface de teste, o dump do banco de dados é visualizado através do Database Inspector. A ferramenta também é ativamente usada para depurar migrações Room — você pode ver o esquema real das tabelas após cada atualização de esquema.

Como o Database Inspector funciona

O Database Inspector conecta-se ao processo do aplicativo Android através do Android Profiler Service. Ele detecta todas as conexões SQLite abertas no aplicativo e as exibe no painel lateral. É necessária uma compilação Debug do aplicativo com API Level 26 (Android 8.0) ou superior.

Arquitetura e mecanismo

Ao ser iniciado, o Database Inspector cria um túnel ADB entre o aplicativo no dispositivo e o IDE no computador. Os arquivos de banco de dados SQLite WAL (Write-Ahead Logging) são transmitidos através deste túnel para exibir o conteúdo. Comandos SQL são enviados diretamente ao mecanismo SQLite do aplicativo através do suporte do Database Inspector no Room e SQLiteDatabase. A ferramenta detecta automaticamente quando o aplicativo abre um banco de dados e o adiciona à lista inspecionada.

Requisitos de ambiente

Para o Database Inspector funcionar corretamente, você precisa de: Android Studio 4.1+, um dispositivo ou emulador com API Level 26+, e uma compilação Debug do aplicativo. Para Room, a biblioteca room-runtime versão 2.2+ é adicionalmente necessária. Se o banco de dados for criado com modo WAL, que é padrão para Room 2.2+, a ferramenta pode ler dados sem bloquear o aplicativo principal.

// Exemplo de banco de dados Room suportado pelo 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
}

Principais recursos do Database Inspector

O Database Inspector fornece um conjunto completo de funções para trabalhar com dados locais: desde a visualização do esquema de tabelas até a execução de consultas SQL complexas e edição de registros.

Visualização de tabelas e esquema

O painel esquerdo exibe todos os bancos de dados e tabelas. Quando uma tabela é selecionada, seu conteúdo é exibido em uma grade com colunas: todos os campos do registro são mostrados como colunas, cada linha é um registro separado. O esquema da tabela (nome, tipo, restrições) é exibido na parte superior. Para chaves estrangeiras, as relações entre tabelas são mostradas.

Execução de consultas SQL

A aba Query permite executar comandos SQL arbitrários diretamente no banco de dados selecionado. SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN e qualquer outro operador SQLite são suportados. Os resultados são exibidos em formato tabular abaixo do editor de consultas. O histórico de consultas é preservado durante a sessão.

Edição de registros

As células da tabela podem ser editadas diretamente — basta clicar em um valor e inserir um novo. As alterações são aplicadas imediatamente ao aplicativo em execução. Isso é especialmente útil para testar casos extremos: definir null em um campo obrigatório, substituir um ID por um inexistente, verificar o tratamento de strings longas. Todas as alterações são confirmadas em tempo real.

Depuração Room com Database Inspector

O Database Inspector tem uma integração profunda com Room, tornando-o indispensável ao desenvolver aplicativos com esta biblioteca. Além da funcionalidade padrão, o inspetor fornece capacidades específicas do Room.

Visualização de consultas DAO

Para bancos de dados Room, o Database Inspector mostra as consultas SQL geradas para cada método DAO. Isso permite verificar se o Room gera SQL correto, especialmente para consultas complexas com JOIN, @Relation e @Transaction. Se o Room executar uma consulta ineficiente (por exemplo, consultas N+1 em vez de um único JOIN), isso é imediatamente visível no log de consultas do Database Inspector.

Depuração de migrações

Ao atualizar o esquema Room com AutoMigration ou migrações manuais, o Database Inspector mostra a estrutura real das tabelas após a migração. Basta abrir o inspetor após iniciar o aplicativo e verificar se todas as colunas, índices e chaves estrangeiras foram criados corretamente. Se uma migração falhou com erro, o banco de dados não abrirá — a ferramenta mostrará a última versão disponível.

Verificação de Relations e Embedded

Room permite combinar dados de várias tabelas através de @Relation e @Embedded. O Database Inspector ajuda a verificar visualmente a exatidão das relações exibindo dados de tabelas relacionadas lado a lado. Para cada chave estrangeira, você pode navegar para a tabela relacionada com um clique.

// Entidade com Relation para verificação via 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>
)

Casos práticos de uso do Database Inspector

O Database Inspector resolve tarefas de desenvolvimento específicas que surgem ao trabalhar com armazenamento local de dados. Vejamos os casos de uso mais comuns da ferramenta no trabalho diário.

Verificação de cache de dados

Muitas vezes, um aplicativo armazena em cache as respostas da API em um banco de dados local. O Database Inspector permite verificar a exatidão do cache: após a sincronização, você pode ver os registros reais na tabela de cache. Se os dados não aparecerem — o problema está no código de salvamento. Se aparecerem duplicatas — o problema está na lógica de upsert.

Depuração de erros de inserção de dados

Quando um método DAO não salva dados, mas não lança uma exceção, o Database Inspector mostra o estado real da tabela. Causas típicas: conflito de Primary Key (configuração OnConflictStrategy), tipo de dado incorreto em uma coluna, violação de restrição NOT NULL ou violação de Foreign Key. O inspetor permite ver o changeset do banco de dados antes e depois da operação. Comparar instantâneos de dados antes e depois de uma chamada DAO é uma das formas mais eficazes de depurar erros transacionais e verificar a exatidão da lógica de negócios do aplicativo durante operações de escrita complexas.

Refatoração de esquema de banco de dados

Ao alterar o esquema das tabelas — adicionar colunas, renomear campos, dividir tabelas — o Database Inspector ajuda a verificar o resultado da migração. Basta iniciar o aplicativo com a nova versão do banco de dados e verificar se todos os dados foram transferidos corretamente para a nova estrutura. Se os dados estiverem faltando após a migração, você pode restaurá-los a partir de um dump salvo antes da refatoração. Este cenário é especialmente relevante ao migrar de SQLiteOpenHelper para Room ou ao alterar a estrutura de tabelas existentes em uma nova versão do aplicativo.

Monitoramento de desempenho de consultas

O Database Inspector também pode ser usado para avaliar o desempenho de consultas SQL. Executando SELECT através da aba Query e medindo o tempo de resposta, você pode identificar consultas que carecem de índices. Room registra automaticamente consultas lentas no Logcat com a tag SLOW SQL, e o Database Inspector permite executar imediatamente EXPLAIN QUERY PLAN para análise do plano de execução.