Depurar seu banco de dados com o Database Inspector

No Android Studio 4.1 e versões mais recentes, o Database Inspector permite inspecionar, consultar e modificar os bancos de dados do seu app enquanto ele está em execução. Isso é especialmente útil para a depuração do banco de dados. O Database Inspector funciona com o SQLite plain e com bibliotecas criadas com base no SQLite, como a Room.

Abrir o Database Inspector

Para abrir um banco de dados no Database Inspector, faça o seguinte:

  1. Execute o app em um emulador ou dispositivo conectado executando a API de nível 26 ou versões mais recentes.

  2. Selecione View > Tool Windows > App Inspection na barra de menus.

  3. Selecione a guia Database Inspector.

  4. Selecione o processo do app em execução no menu suspenso.

  5. Os bancos de dados no app atualmente em execução aparecem no painel Databases. Expanda o nó do banco de dados que você quer inspecionar.

Ver e modificar dados

O painel Databases exibe uma lista dos bancos de dados no app e as- tabelas que cada um deles contém. Clique duas vezes no nome de uma tabela para exibir os dados na janela do inspetor à direita. É possível clicar em um cabeçalho de coluna para classificar os dados na janela do inspetor por essa coluna.

Captura de tela da janela do Database Inspector.
Figura 1. Janela do Database Inspector.

Para modificar os dados em uma tabela, clique duas vezes em uma célula, digite um novo valor e pressione Enter. Se o app usa a Room e a IU observa o banco de dados, por exemplo, com LiveData ou Flow, todas as mudanças feitas nos dados ficam visíveis de imediato no app em execução. Caso contrário, só será possível visualizar essas informações na próxima vez que o app ler os dados modificados do banco de dados.

Ver mudanças no banco de dados em tempo real

Se você quiser que o Database Inspector atualize automaticamente os dados que apresenta durante a interação com seu app em execução, marque a caixa de seleção Live Updates na parte superior da janela do inspetor. Enquanto as atualizações em tempo real estão ativadas, a tabela na janela do inspetor torna-se apenas para leitura e não será possível modificar os valores.

Como alternativa, atualize manualmente os dados clicando no botão Refresh table, na parte superior da janela do inspetor.

Consultar o banco de dados

O Database Inspector pode executar consultas no banco de dados do seu app enquanto ele está em execução. A ferramenta pode usar consultas DAO caso seu app use a Room, mas também aceita consultas SQL personalizadas.

Executar consultas DAO

Se o app usa a Room, o Android Studio oferece ações de gutter para você executar rapidamente métodos de consulta já definidos nas classes de DAO. Essas ações estão disponíveis enquanto o app está em execução e o Database Inspector está aberto no ambiente de desenvolvimento integrado. É possível executar qualquer método de consulta em um DAO clicando no botão Run SQLite statement in Database Inspector ao lado da anotação @Query.

Captura de tela das ações de gutter DAO.
Figura 2. Ações de gutter em consulta DAO.

Caso seu app inclua mais de um banco de dados, o Android Studio solicita que você selecione o banco de dados para consultar uma lista suspensa. Caso seu método de consulta inclua parâmetros de vinculação, o Android Studio solicita valores para cada parâmetro antes de executar a consulta. Os resultados da consulta são exibidos na janela do inspetor.

Executar consultas SQL personalizadas

Também é possível usar o Database Inspector para executar consultas SQL personalizadas nos bancos de dados do seu app enquanto ele está em execução. Para consultar um banco de dados, siga estas etapas:

  1. Clique em Open New Query tab na parte superior do painel Databases para abrir uma nova guia na janela do inspetor.

    Captura de tela que indica o botão da guia new query.
    Figura 3. Abra uma guia New Query.
  2. Se o app incluir mais de um banco de dados, selecione o que você quer consultar na lista suspensa da guia New Query.

  3. Digite a consulta SQL personalizada no campo de texto na parte superior da guia New Query e clique em Run.

Se preferir, use o recurso de histórico de consultas para executar uma consulta feita anteriormente:

  1. Clique no botão Show query history Exibir botão do histórico de consultas para ver uma lista de consultas executadas anteriormente no banco de dados selecionado.

    Captura de tela mostrando a lista suspensa do histórico de consultas.
    Figura 4. O menu do histórico de consultas.
  2. Clique em uma consulta na lista para uma visualização de toda a consulta no editor e pressione Enter para copiá-la no editor.

  3. Clique em Run para executar a instrução.

Os resultados da consulta exibidos na guia New Query são somente leitura e não podem ser modificados. No entanto, é possível usar o campo de consulta SQL personalizado para executar instruções de modificadoras, como UPDATE, INSERT ou DELETE. Se o app usa a Room e a IU observa o banco de dados, por exemplo, com LiveData ou Flow, todas as mudanças feitas nos dados ficam visíveis de imediato no app em execução. Caso contrário, só será possível visualizar essas informações na próxima vez que o app ler os dados modificados do banco de dados.

Modo off-line

No Android Studio 4.2 e versões mais recentes, é possível continuar a inspecionar os bancos de dados do app após a desconexão de um processo. Isso facilita a depuração do app após uma falha.

Quando ocorre uma desconexão, o Database Inspector faz o download dos seus bancos de dados e os disponibiliza no modo off-line. Quando estiver off-line, ainda será possível abrir tabelas e executar consultas.

Quando você se reconecta a um processo de app ativo, o Database Inspector sai do modo off-line e mostra apenas os dados que estão no dispositivo. Em outras palavras, os dados exibidos no modo off-line não são mantidos quando você se reconecta a um processo de app. Devido a essa limitação, o Database Inspector não permite a edição de dados ou a execução de instruções SQL de modificação no modo off-line.

Manter as conexões do banco de dados abertas

O Database Inspector só pode modificar um banco de dados enquanto seu app mantém uma conexão ativa com ele. Isso significa que, se o app se conecta e desconecta com frequência dos bancos de dados, pode ser difícil depurá-los. O painel Databases usa ícones para identificar bancos de dados abertos () e fechados ().

Além disso, é possível impedir que as conexões de banco de dados sejam fechadas ao alternar Keep database connections open de desativado () para ativado () na parte superior do painel Databases.

Outros recursos

Para saber mais sobre o Database Inspector, consulte os seguintes recursos:

Postagens do blog

Vídeos