Database Inspector: qué es, cómo trabajar con SQLite y depurar Room

¿Qué es Database Inspector?

Database Inspector es una herramienta de Android Studio para inspeccionar y depurar bases de datos locales en una aplicación móvil. Permite ver todas las bases de datos SQLite creadas por la aplicación, incluyendo bases de Room, SQLiteOpenHelper y bibliotecas de terceros. La herramienta está disponible a partir de Android Studio 4.1 y se puede iniciar a través de Android Profiler o directamente desde el menú View.

Propósito y capacidades

El propósito principal de Database Inspector es la visualización de datos durante el desarrollo. En lugar de sacar el contenido de la base de datos a un registro o escribir una pantalla separada para ver los datos, el desarrollador puede abrir Database Inspector y ver inmediatamente todas las tablas, su esquema y contenido. La herramienta es compatible tanto con bases de datos SQLite relacionales como con Room con Auto-migraciones.

Cuándo usar Database Inspector

La herramienta es indispensable en escenarios donde se necesita verificar la corrección del almacenamiento de datos después de realizar una operación: registro de usuario, sincronización con el servidor, almacenamiento en caché de listas. En lugar de escribir una interfaz de prueba, el volcado de la base de datos se visualiza a través de Database Inspector. La herramienta también se utiliza activamente para depurar migraciones de Room — se puede ver el esquema real de las tablas después de cada actualización del esquema.

Cómo funciona Database Inspector

Database Inspector se conecta al proceso de la aplicación Android a través de Android Profiler Service. Detecta todas las conexiones SQLite abiertas en la aplicación y las muestra en el panel lateral. Se requiere una compilación Debug de la aplicación con API Level 26 (Android 8.0) o superior.

Arquitectura y mecanismo

Al iniciarse, Database Inspector crea un túnel ADB entre la aplicación en el dispositivo y el IDE en el ordenador. Los archivos de base de datos SQLite WAL (Write-Ahead Logging) se transmiten a través de este túnel para mostrar el contenido. Los comandos SQL se envían directamente al motor SQLite de la aplicación a través del soporte de Database Inspector en Room y SQLiteDatabase. La herramienta detecta automáticamente cuando la aplicación abre una base de datos y la añade a la lista inspeccionada.

Requisitos del entorno

Para que Database Inspector funcione correctamente, se necesita: Android Studio 4.1+, un dispositivo o emulador con API Level 26+, y una compilación Debug de la aplicación. Para Room, se requiere adicionalmente la biblioteca room-runtime versión 2.2+. Si la base de datos se crea con modo WAL, que es estándar para Room 2.2+, la herramienta puede leer datos sin bloquear la aplicación principal.

// Ejemplo de base de datos Room compatible con 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
}

Características principales de Database Inspector

Database Inspector proporciona un conjunto completo de funciones para trabajar con datos locales: desde la visualización del esquema de tablas hasta la ejecución de consultas SQL complejas y la edición de registros.

Visualización de tablas y esquema

El panel izquierdo muestra todas las bases de datos y tablas. Al seleccionar una tabla, su contenido se muestra en una cuadrícula con columnas: todos los campos del registro se muestran como columnas, cada fila es un registro independiente. El esquema de la tabla (nombre, tipo, restricciones) se muestra en la parte superior. Para las claves externas, se muestran las relaciones entre tablas.

Ejecución de consultas SQL

La pestaña Query permite ejecutar comandos SQL arbitrarios directamente en la base de datos seleccionada. Se admiten SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN y cualquier otro operador SQLite. Los resultados se muestran en formato tabular debajo del editor de consultas. El historial de consultas se conserva durante la sesión.

Edición de registros

Las celdas de la tabla se pueden editar directamente — basta con hacer clic en un valor e introducir uno nuevo. Los cambios se aplican inmediatamente a la aplicación en ejecución. Esto es especialmente útil para probar casos límite: establecer null en un campo obligatorio, reemplazar un ID por uno inexistente, comprobar el manejo de cadenas largas. Todos los cambios se confirman en tiempo real.

Depuración de Room con Database Inspector

Database Inspector tiene una integración profunda con Room, lo que lo hace indispensable al desarrollar aplicaciones con esta biblioteca. Además de la funcionalidad estándar, el inspector proporciona capacidades específicas de Room.

Visualización de consultas DAO

Para las bases de datos Room, Database Inspector muestra las consultas SQL generadas para cada método DAO. Esto permite verificar que Room genera SQL correcto, especialmente para consultas complejas con JOIN, @Relation y @Transaction. Si Room ejecuta una consulta ineficiente (por ejemplo, N+1 consultas en lugar de un solo JOIN), es inmediatamente visible en el registro de consultas de Database Inspector.

Depuración de migraciones

Al actualizar el esquema de Room con AutoMigration o migraciones manuales, Database Inspector muestra la estructura real de las tablas después de la migración. Basta con abrir el inspector después de iniciar la aplicación y comprobar que todas las columnas, índices y claves externas se han creado correctamente. Si una migración falló con un error, la base de datos no se abrirá — la herramienta mostrará la última versión disponible.

Verificación de Relations y Embedded

Room permite combinar datos de múltiples tablas a través de @Relation y @Embedded. Database Inspector ayuda a verificar visualmente la corrección de las relaciones mostrando los datos de las tablas relacionadas una al lado de la otra. Para cada clave externa, se puede navegar a la tabla relacionada con un solo clic.

// Entidad con Relation para verificar mediante 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ácticos de uso de Database Inspector

Database Inspector resuelve tareas de desarrollo específicas que surgen al trabajar con almacenamiento local de datos. Veamos los casos de uso más comunes de la herramienta en el trabajo diario.

Verificación del almacenamiento en caché

A menudo, una aplicación almacena en caché las respuestas de la API en una base de datos local. Database Inspector permite verificar la corrección del almacenamiento en caché: después de la sincronización, se pueden ver los registros reales en la tabla de caché. Si los datos no aparecen — el problema está en el código de guardado. Si aparecen duplicados — el problema está en la lógica de upsert.

Depuración de errores de inserción de datos

Cuando un método DAO no guarda datos pero no lanza una excepción, Database Inspector muestra el estado real de la tabla. Causas típicas: conflicto de Primary Key (configuración de OnConflictStrategy), tipo de dato incorrecto en una columna, violación de restricción NOT NULL o violación de Foreign Key. El inspector permite ver el changeset de la base de datos antes y después de la operación. Comparar instantáneas de datos antes y después de una llamada DAO es una de las formas más efectivas de depurar errores transaccionales y verificar la corrección de la lógica de negocio de la aplicación durante operaciones de escritura complejas.

Refactorización del esquema de base de datos

Al cambiar el esquema de las tablas — añadir columnas, renombrar campos, dividir tablas — Database Inspector ayuda a verificar el resultado de la migración. Basta con iniciar la aplicación con la nueva versión de la base de datos y comprobar que todos los datos se han transferido correctamente a la nueva estructura. Si faltan datos después de la migración, se pueden restaurar desde un volcado guardado antes de la refactorización. Este escenario es especialmente relevante al migrar de SQLiteOpenHelper a Room o al cambiar la estructura de tablas existentes en una nueva versión de la aplicación.

Monitorización del rendimiento de consultas

Database Inspector también se puede utilizar para evaluar el rendimiento de consultas SQL. Ejecutando SELECT a través de la pestaña Query y midiendo el tiempo de respuesta, se pueden identificar consultas que carecen de índices. Room registra automáticamente las consultas lentas en Logcat con la etiqueta SLOW SQL, y Database Inspector permite ejecutar inmediatamente EXPLAIN QUERY PLAN para analizar el plan de ejecución.