Database Inspector: 개요, SQLite 작업 방법 및 Room 디버깅 방법

Database Inspector란?

Database Inspector는 모바일 애플리케이션의 로컬 데이터베이스를 검사하고 디버깅하기 위한 Android Studio 도구입니다. Room 데이터베이스, SQLiteOpenHelper 및 타사 라이브러리를 포함하여 애플리케이션에서 생성한 모든 SQLite 데이터베이스를 볼 수 있습니다. 이 도구는 Android Studio 4.1부터 사용 가능하며 Android Profiler를 통해 또는 View 메뉴에서 직접 실행할 수 있습니다.

목적 및 기능

Database Inspector의 주요 목적은 개발 중 데이터 시각화입니다. 데이터베이스 내용을 로그로 출력하거나 데이터를 보기 위한 별도 화면을 작성하는 대신, 개발자는 Database Inspector를 열고 모든 테이블, 스키마 및 내용을 즉시 확인할 수 있습니다. 이 도구는 관계형 SQLite 데이터베이스와 Auto-마이그레이션이 있는 Room을 모두 지원합니다.

Database Inspector 사용 시기

이 도구는 작업 수행 후 데이터 저장소의 정확성을 확인해야 하는 시나리오에서 필수적입니다: 사용자 등록, 서버 동기화, 목록 캐싱. 테스트 UI를 작성하는 대신 데이터베이스 덤프를 Database Inspector를 통해 확인합니다. 이 도구는 Room 마이그레이션 디버깅에도 적극적으로 사용되며, 스키마 업데이트 후 실제 테이블 스키마를 확인할 수 있습니다.

Database Inspector 작동 방식

Database Inspector는 Android Profiler Service를 통해 Android 애플리케이션의 프로세스에 연결됩니다. 애플리케이션의 모든 열린 SQLite 연결을 감지하여 측면 패널에 표시합니다. API Level 26(Android 8.0) 이상의 Debug 빌드 애플리케이션이 필요합니다.

아키텍처 및 메커니즘

실행 시 Database Inspector는 장치의 애플리케이션과 컴퓨터의 IDE 사이에 ADB 터널을 생성합니다. SQLite WAL(Write-Ahead Logging) 데이터베이스 파일이 이 터널을 통해 스트리밍되어 내용을 표시합니다. SQL 명령은 Room 및 SQLiteDatabase의 Database Inspector 지원을 통해 애플리케이션의 SQLite 엔진으로 직접 전송됩니다. 도구는 애플리케이션이 데이터베이스를 열 때 자동으로 감지하여 검사 목록에 추가합니다.

환경 요구 사항

Database Inspector가 올바르게 작동하려면 다음이 필요합니다: Android Studio 4.1+, API Level 26+의 장치 또는 에뮬레이터, 애플리케이션의 Debug 빌드. Room의 경우 room-runtime 라이브러리 버전 2.2+가 추가로 필요합니다. Room 2.2+의 표준인 WAL 모드로 데이터베이스가 생성된 경우 도구는 기본 애플리케이션을 차단하지 않고 데이터를 읽을 수 있습니다.

// Database Inspector가 지원하는 Room 데이터베이스 예제
@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로 교체, 긴 문자열 처리 확인. 모든 변경 사항은 실시간으로 커밋됩니다.

Database Inspector로 Room 디버깅

Database Inspector는 Room과 깊게 통합되어 있어 이 라이브러리로 애플리케이션을 개발할 때 필수적입니다. 표준 기능 외에도 검사기는 Room 특화 기능을 제공합니다.

DAO 쿼리 보기

Room 데이터베이스의 경우 Database Inspector는 각 DAO 메서드에 대한 생성된 SQL 쿼리를 표시합니다. 특히 JOIN, @Relation 및 @Transaction이 포함된 복잡한 쿼리에 대해 Room이 올바른 SQL을 생성하는지 확인할 수 있습니다. Room이 비효율적인 쿼리(예: 단일 JOIN 대신 N+1 쿼리)를 실행하는 경우 Database Inspector 쿼리 로그에서 즉시 확인할 수 있습니다.

마이그레이션 디버깅

AutoMigration 또는 수동 마이그레이션으로 Room 스키마를 업데이트할 때 Database Inspector는 마이그레이션 후 실제 테이블 구조를 표시합니다. 애플리케이션 실행 후 검사기를 열고 모든 열, 인덱스 및 외래 키가 올바르게 생성되었는지 확인하기만 하면 됩니다. 마이그레이션이 오류로 실패한 경우 데이터베이스가 열리지 않으며 도구는 마지막으로 사용 가능한 버전을 표시합니다.

Relations 및 Embedded 확인

Room은 @Relation 및 @Embedded를 통해 여러 테이블의 데이터를 결합할 수 있습니다. Database Inspector는 관련 테이블 데이터를 나란히 표시하여 관계의 정확성을 시각적으로 확인하는 데 도움을 줍니다. 각 외래 키에 대해 한 번의 클릭으로 관련 테이블로 이동할 수 있습니다.

// Database Inspector를 통해 확인하기 위한 Relation이 있는 Entity
@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 메서드가 데이터를 저장하지 않지만 예외를 throw하지 않는 경우 Database Inspector는 테이블의 실제 상태를 표시합니다. 일반적인 원인: Primary Key 충돌(OnConflictStrategy 설정), 열의 잘못된 데이터 유형, NOT NULL 제약 조건 위반 또는 Foreign Key 위반. 검사기를 통해 작업 전후의 데이터베이스 변경 세트를 확인할 수 있습니다. DAO 호출 전후의 데이터 스냅샷을 비교하는 것은 트랜잭션 오류를 디버깅하고 복잡한 쓰기 작업 중 애플리케이션 비즈니스 로직의 정확성을 확인하는 가장 효과적인 방법 중 하나입니다.

데이터베이스 스키마 리팩토링

테이블 스키마 변경 시(열 추가, 필드 이름 변경, 테이블 분할) Database Inspector는 마이그레이션 결과 확인에 도움을 줍니다. 새 데이터베이스 버전으로 애플리케이션을 실행하고 모든 데이터가 새 구조로 올바르게 전송되었는지 확인하기만 하면 됩니다. 마이그레이션 후 데이터가 누락된 경우 리팩토링 전에 저장된 덤프에서 복원할 수 있습니다. 이 시나리오는 SQLiteOpenHelper에서 Room으로 마이그레이션하거나 애플리케이션의 새 버전에서 기존 테이블 구조를 변경할 때 특히 중요합니다.

쿼리 성능 모니터링

Database Inspector는 SQL 쿼리 성능 평가에도 사용할 수 있습니다. Query 탭을 통해 SELECT를 실행하고 응답 시간을 측정하여 인덱스가 부족한 쿼리를 식별할 수 있습니다. Room은 자동으로 느린 쿼리를 SLOW SQL 태그와 함께 Logcat에 기록하며, Database Inspector를 통해 즉시 EXPLAIN QUERY PLAN을 실행하여 실행 계획을 분석할 수 있습니다.