Database Inspector: What It Is, How to Work with SQLite and Debug Room

What is Database Inspector?

Database Inspector is an Android Studio tool for inspecting and debugging local databases in a mobile application. It allows you to view all SQLite databases created by the application, including Room databases, SQLiteOpenHelper, and third-party libraries. The tool is available starting with Android Studio 4.1 and can be launched via Android Profiler or directly from the View menu.

Purpose and Capabilities

The main purpose of Database Inspector is data visualization during development. Instead of outputting database contents to a log or writing a separate screen for viewing data, the developer can open Database Inspector and immediately see all tables, their schema, and contents. The tool supports both relational SQLite databases and Room with Auto-migrations.

When to Use Database Inspector

The tool is indispensable in scenarios when you need to verify the correctness of data storage after performing an operation: user registration, server synchronization, list caching. Instead of writing a test UI, the database dump is viewed through Database Inspector. The tool is also actively used for debugging Room migrations — you can see the actual table schema after each schema update.

How Database Inspector Works

Database Inspector connects to the process of the Android application through the Android Profiler Service. It detects all open SQLite connections in the application and displays them in the side panel. A Debug build of the application with API Level 26 (Android 8.0) and above is required.

Architecture and Mechanism

When launched, Database Inspector creates an ADB tunnel between the application on the device and the IDE on the computer. SQLite WAL (Write-Ahead Logging) database files are streamed through this tunnel to display the contents. SQL commands are sent directly to the application's SQLite Engine through Database Inspector's support in Room and SQLiteDatabase. The tool automatically detects when the application opens a database and adds it to the inspected list.

Environment Requirements

For Database Inspector to work correctly, you need: Android Studio 4.1+, a device or emulator with API Level 26+, and a Debug build of the application. For Room, the room-runtime library version 2.2+ is additionally required. If the database is created with WAL mode, which is standard for Room 2.2+, the tool can read data without blocking the main application.

// Example Room database supported by 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
}

Key Features of Database Inspector

Database Inspector provides a full set of functions for working with local data: from viewing table schemas to executing complex SQL queries and editing records.

Viewing Tables and Schema

The left panel displays all databases and tables. When a table is selected, its contents are displayed in a table with columns: all record fields are shown as columns, each row is a separate record. The table schema (name, type, constraints) is displayed at the top. For foreign keys, relationships between tables are shown.

Executing SQL Queries

The Query tab allows you to execute arbitrary SQL commands directly against the selected database. SELECT, INSERT, UPDATE, DELETE, CREATE INDEX, JOIN, and any other SQLite operators are supported. Results are displayed in a tabular format below the query editor. Query history is preserved during the session.

Editing Records

Table cells can be edited directly — just click on a value and enter a new one. Changes are applied immediately to the running application. This is especially useful for testing edge cases: setting null in a required field, replacing an ID with a non-existent one, checking handling of long strings. All changes are committed in real time.

Debugging Room with Database Inspector

Database Inspector has deep integration with Room, making it indispensable when developing applications with this library. In addition to standard functionality, the inspector provides Room-specific capabilities.

Viewing DAO Queries

For Room databases, Database Inspector shows generated SQL queries for each DAO method. This allows you to verify that Room generates correct SQL, especially for complex queries with JOIN, @Relation, and @Transaction. If Room executes an inefficient query (e.g., N+1 queries instead of a single JOIN), it is immediately visible in the Database Inspector query log.

Debugging Migrations

When updating the Room schema with AutoMigration or manual migrations, Database Inspector shows the actual table structure after migration. Just open the inspector after launching the application and check that all columns, indexes, and foreign keys are created correctly. If a migration failed with an error, the database will not open — the tool will show the last available version.

Checking Relations and Embedded

Room allows combining data from multiple tables through @Relation and @Embedded. Database Inspector helps visually verify the correctness of relationships by displaying related table data side by side. For each foreign key, you can navigate to the related table with one click.

// Entity with Relation for checking 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>
)

Practical Use Cases for Database Inspector

Database Inspector solves specific development tasks that arise when working with local data storage. Let's look at the most common use cases for the tool in daily work.

Checking Data Caching

Often, an application caches API responses in a local database. Database Inspector allows you to verify the correctness of caching: after synchronization, you can see the actual records in the cache table. If data does not appear — the problem is in the save code. If duplicates appear — the problem is in the upsert logic.

Debugging Data Insertion Errors

When a DAO method does not save data but does not throw an exception, Database Inspector shows the actual state of the table. Typical causes: Primary Key conflict (OnConflictStrategy setting), incorrect data type in a column, NOT NULL constraint violation, or Foreign Key violation. The inspector allows you to see the database changeset before and after the operation. Comparing data snapshots before and after a DAO call is one of the most effective ways to debug transactional errors and verify the correctness of application business logic during complex write operations.

Database Schema Refactoring

When changing the table schema — adding columns, renaming fields, splitting tables — Database Inspector helps verify the migration result. Just launch the application with the new database version and verify that all data has been correctly transferred to the new structure. If data is missing after migration, you can restore it from a dump saved before refactoring. This scenario is especially relevant when migrating from SQLiteOpenHelper to Room or when changing the structure of existing tables in a new version of the application.

Query Performance Monitoring

Database Inspector can also be used for evaluating SQL query performance. By executing SELECT through the Query tab and measuring response time, you can identify queries that lack indexes. Room automatically logs slow queries in Logcat with the SLOW SQL tag, and Database Inspector allows you to immediately execute EXPLAIN QUERY PLAN for execution plan analysis.