AndroidのRoom Databaseマイグレーション 2026:自動マイグレーション、テスト、リレーション、Coroutines

Room 2.8とRoom 3によるAndroidのRoom Databaseマイグレーション:自動マイグレーション、手動Migration、MigrationTestHelperによるテスト、よくあるエラー、リレーション、Flowを解説します。

Room Database Android Kotlin SQLiteデータ永続化

RoomはAndroidでSQLiteの上に位置するJetpackの永続化ライブラリです。エンティティはテーブルに、DAOは生成されたクエリになり、2つのアプリバージョン間のスキーマ変更はすべてマイグレーションを経由する必要があります。安定版の2.x系(2026年9月時点で2.8.5)では、suspend DAOとFlowクエリがroom-runtimeに組み込まれており、Room 3.0はAPI全体をCoroutinesとSQLiteDriverインターフェースへ移行させています。

Room 2.8とRoom 3.0のどちらを選ぶか

Room 2.8.5(androidx.room)は現行の2.xリリースで、多くのAndroidコードベースが使用しているバージョンです。Room 3.0(androidx.room3、2026年7月に安定版、9月に3.0.3)はKotlin Multiplatformを主眼とした別パッケージで、KSPのみに対応し、マイグレーションはSQLiteConnectionに対して記述します。以下のコードはRoom 2.8を対象とし、Room 3での変更点は専用のセクションで示します。

AndroidにおけるRoom Databaseマイグレーションの仕組み

Room Databaseのマイグレーションは、ユーザーデータを削除せずにバージョンNのスキーマをバージョンN+1のスキーマへ変換するコードです。Roomは端末に保存されたバージョンと@Databaseのversionを比較し、経路上のすべてのマイグレーションを順に実行したうえで、エンティティから生成されたスキーマと結果を照合します。不一致があれば、データベースを開いた時点でクラッシュします。

戦略は3つあり、どれを選ぶかはスキーマ変更の種類で決まります。

戦略API使用する場面データの保持
自動マイグレーション@AutoMigration(from, to)テーブル、カラム、インデックスの追加。名前変更と削除はAutoMigrationSpecを併用あり
手動マイグレーションMigration(start, end) + addMigrations()テーブル分割、データ変換、型変更など、Roomが推論できない変更あり
破壊的フォールバックfallbackToDestructiveMigration(dropAllTables = true)キャッシュや再ダウンロード可能なデータなし

公式のマイグレーションガイドによると、同じバージョン区間を自動マイグレーションと手動マイグレーションの両方がカバーしている場合、Roomは手動マイグレーションを使用します。

KSPとRoom Gradle PluginによるRoom 2.8のセットアップ

Roomには3つのコアコンポーネントが必要です:エンティティ(テーブル)、DAO(データアクセスオブジェクト)、およびデータベースクラスです。KSPプロセッサがコンパイル時に実装コードを生成し、Room 2.7以降はKSP使用時にJavaではなくKotlinのコードを生成します。

古いチュートリアルからアップグレードするプロジェクトでは、依存関係の変更が2つ問題になります。Room 2.7以降、room-ktxはroom-runtimeに統合されて空のアーティファクトとして配布されているため、削除できます。また、スキーマのエクスポートにはRoom Gradle Pluginの使用が推奨されるようになりました。自動マイグレーションとマイグレーションテストはどちらもこのエクスポートに依存します。

build.gradle.kts (Module :app)kotlin
plugins {
    id("com.google.devtools.ksp") // KSP 2.x, version declared in the root build file
    id("androidx.room") version "2.8.5"
}

room {
    // Schema JSON files used by auto-migrations and MigrationTestHelper
    schemaDirectory("$projectDir/schemas")
}

dependencies {
    val roomVersion = "2.8.5"
    implementation("androidx.room:room-runtime:$roomVersion") // includes coroutine support since 2.7
    ksp("androidx.room:room-compiler:$roomVersion")
    androidTestImplementation("androidx.room:room-testing:$roomVersion")
}

Room 2.7以降はKotlin 2.0以上が必要で、Room 2.8ではライブラリのminSdkが21から23に引き上げられました。schemas/フォルダはコミットしてください。今後のすべてのマイグレーションの検証基準となるスキーマ履歴です。

プライマリキーとインデックスを含むエンティティの定義

エンティティはSQLiteテーブルに直接マッピングされます。各エンティティクラスには少なくとも1つのプライマリキーが必要です。頻繁にクエリされるカラムにインデックスを追加すると、書き込みが若干遅くなる代わりに読み取りパフォーマンスが向上します。

User.ktkotlin
import androidx.room.ColumnInfo
import androidx.room.Entity
import androidx.room.Index
import androidx.room.PrimaryKey

@Entity(
    tableName = "users",
    indices = [
        Index(value = ["email"], unique = true), // Unique constraint + index
        Index(value = ["created_at"]) // Index for sorting queries
    ]
)
data class User(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val email: String,
    @ColumnInfo(name = "display_name")
    val displayName: String,
    @ColumnInfo(name = "phone_number")
    val phoneNumber: String? = null, // Added in schema version 2
    @ColumnInfo(name = "created_at")
    val createdAt: Long = System.currentTimeMillis(),
    @ColumnInfo(name = "is_active")
    val isActive: Boolean = true
)

@ColumnInfoアノテーションは、Kotlinプロパティ名とカラム名が異なる場合にカラム名を指定します。指定しない場合、カラムはプロパティ名(isActive)で作成され、is_activeで絞り込むクエリはコンパイル時にエラーになります。

CoroutinesとFlowを使用したDAOの構築

DAOはデータベース操作を定義します。Room 2.xは、ワンショット操作用のsuspend関数、リアクティブストリーム用のFlow、Java相互運用用のListenableFutureまたはRxJavaをサポートしています。

UserDao.ktkotlin
import androidx.room.*
import kotlinx.coroutines.flow.Flow

@Dao
interface UserDao {
    // Default strategy ABORT: a duplicate email throws SQLiteConstraintException
    @Insert
    suspend fun insertUser(user: User): Long

    // Batch insert - efficient for multiple records
    @Insert(onConflict = OnConflictStrategy.IGNORE)
    suspend fun insertUsers(users: List<User>)

    // Flow emits new data whenever the table changes
    @Query("SELECT * FROM users WHERE is_active = 1 ORDER BY created_at DESC")
    fun observeActiveUsers(): Flow<List<User>>

    // Suspend function for one-shot read
    @Query("SELECT * FROM users WHERE id = :userId")
    suspend fun getUserById(userId: Long): User?

    // Update returns the number of affected rows
    @Update
    suspend fun updateUser(user: User): Int

    // Delete by primary key
    @Delete
    suspend fun deleteUser(user: User)

    // Custom delete query
    @Query("DELETE FROM users WHERE is_active = 0")
    suspend fun deleteInactiveUsers(): Int
}

Flowを返すクエリは、基礎となるデータが変更されると自動的に更新された結果を発行します。これによりViewModelでの手動更新ロジックが不要になります。

OnConflictStrategy.REPLACEは面接でよく出る落とし穴です。SQLiteはこれを削除と挿入の組み合わせとして実装するため、行は新しいライフサイクルを持ち、ForeignKey.CASCADEで宣言された子行も一緒に削除されます。子行を残したままupsertするには、@Upsert(Room 2.5以降)を使うと既存の行が更新されます。

Roomデータベースクラスの作成

データベースクラスはエンティティとDAOを結び付けます。シングルトンパターンにより複数のデータベースインスタンスを防止し、リソースリークを回避します。

AppDatabase.ktkotlin
import android.content.Context
import androidx.room.Database
import androidx.room.Room
import androidx.room.RoomDatabase

@Database(
    entities = [User::class, Post::class],
    version = 1,
    exportSchema = true // Writes schemas/<version>.json for migration validation
)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun postDao(): PostDao

    companion object {
        @Volatile
        private var INSTANCE: AppDatabase? = null

        fun getInstance(context: Context): AppDatabase {
            return INSTANCE ?: synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    AppDatabase::class.java,
                    "app_database"
                )
                    .fallbackToDestructiveMigration(dropAllTables = true) // Only for development
                    .build()
                INSTANCE = instance
                instance
            }
        }
    }
}

exportSchema = trueを設定すると、roomブロックで指定したディレクトリにバージョンごとのJSONファイルが1つずつ書き出され、自動マイグレーションとマイグレーションテストで使用されます。Room 2.7以降、引数なしのfallbackToDestructiveMigration()は非推奨となり、dropAllTablesを受け取るオーバーロードに置き換えられました。この引数は、スキーマに存在しなくなったテーブルも削除するかどうかを決めます。

本番環境でのマイグレーション戦略

ユーザーデータに対して本番環境でfallbackToDestructiveMigration()を使用してはいけません。マイグレーション経路が見つからない場合、すべてのテーブルが削除されます。被害を限定するには、fallbackToDestructiveMigrationFrom()で特定の旧バージョンに、fallbackToDestructiveMigrationOnDowngrade()でダウングレード時に適用範囲を絞り込みます。

安全なデータベースマイグレーションの作成

マイグレーションは、アプリバージョン間でスキーマが変更された際にユーザーデータを保持します。Roomは期待されるスキーマとマイグレーション後のデータベースを比較することで、実行時にマイグレーションを検証します。

マイグレーションは、データベースをバージョンNからバージョンN+1に変換するために必要なSQL文を定義します。

Migrations.ktkotlin
import androidx.room.migration.Migration
import androidx.sqlite.db.SupportSQLiteDatabase

// Migration from version 1 to 2: add phone_number column
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE users ADD COLUMN phone_number TEXT")
    }
}

// Migration from version 2 to 3: add posts table with foreign key
val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("""
            CREATE TABLE IF NOT EXISTS posts (
                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
                user_id INTEGER NOT NULL,
                title TEXT NOT NULL,
                content TEXT NOT NULL,
                created_at INTEGER NOT NULL,
                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
            )
        """.trimIndent())
        db.execSQL("CREATE INDEX index_posts_user_id ON posts(user_id)")
    }
}

// Register migrations in database builder
fun getInstance(context: Context): AppDatabase {
    return INSTANCE ?: synchronized(this) {
        Room.databaseBuilder(
            context.applicationContext,
            AppDatabase::class.java,
            "app_database"
        )
            .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
            .build()
            .also { INSTANCE = it }
    }
}

Roomはマイグレーションチェーンをサポートしています。ユーザーがバージョン1からバージョン3にアップグレードする場合、RoomはMIGRATION_1_2、次にMIGRATION_2_3を順番に実行します。これらと併せてMigration(1, 3)が登録されていれば、Roomは最短経路を選ぶため、そちらが優先されます。

手書きのマイグレーションが最も壊れやすいのは、非nullカラムの追加です。SQLiteはADD COLUMN ... NOT NULLをDEFAULT値付きでしか受け付けず、Roomはエンティティ側にも@ColumnInfo(defaultValue = "0")で同じデフォルト値を求めます。カラムの型変更や制約の削除はSQLiteのALTER TABLEではできないため、マイグレーション内でテーブルを再作成し、データをコピーし、旧テーブルを削除してから名前を変更する必要があります。

AutoMigrationSpecによる自動マイグレーション

単純なスキーマ変更(カラム、テーブル、インデックスの追加)の場合、Roomは自動的にマイグレーションを生成できます。これにより単純な更新のボイラープレートが削減されます。

AppDatabase.ktkotlin
@Database(
    entities = [User::class, Post::class],
    version = 3,
    autoMigrations = [
        AutoMigration(from = 1, to = 2), // Adding nullable column
        AutoMigration(
            from = 2,
            to = 3,
            spec = AutoMigration2To3::class // Complex changes need spec
        )
    ],
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase() {
    // DAOs...
}

// Migration spec for changes that need hints
@RenameColumn(tableName = "users", fromColumnName = "name", toColumnName = "display_name")
class AutoMigration2To3 : AutoMigrationSpec

自動マイグレーションは、比較のために両バージョンのエクスポート済みスキーマを必要とします。カラム名の変更、テーブル名の変更、削除の場合、@RenameColumn、@RenameTable、@DeleteColumn、@DeleteTableのいずれかを付けたAutoMigrationSpecを用意するまで、Roomはコンパイル時にエラーを出します。データ変換には、引き続きspec内のonPostMigrate()か手動マイグレーションが必要です。

MigrationTestHelperによるRoomマイグレーションのテスト

コンパイルが通るマイグレーションでも、データベースを開いた時点でクラッシュすることがあり、それはバージョンを飛ばした端末でしか起きません。room-testingのMigrationTestHelperは、エクスポートされたJSONスキーマから旧バージョンのデータベースを作成し、マイグレーションを実行して、期待されるスキーマと結果を照合します。Play Storeに出る前にエラーを検出できます。

MigrationTest.kt (androidTest)kotlin
import androidx.room.testing.MigrationTestHelper
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertTrue
import org.junit.Rule
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class MigrationTest {
    private val testDb = "migration-test"

    @get:Rule
    val helper = MigrationTestHelper(
        InstrumentationRegistry.getInstrumentation(),
        AppDatabase::class.java
    )

    @Test
    fun migrate1To2_keepsUsers() {
        // Version 1 schema: insert with raw SQL, DAOs expect the latest schema
        helper.createDatabase(testDb, 1).apply {
            execSQL("INSERT INTO users (id, email, display_name, created_at, is_active) VALUES (1, 'ada@example.com', 'Ada', 0, 1)")
            close()
        }

        // Runs MIGRATION_1_2 and checks the schema against schemas/2.json
        val db = helper.runMigrationsAndValidate(testDb, 2, true, MIGRATION_1_2)

        db.query("SELECT email, phone_number FROM users WHERE id = 1").use { cursor ->
            assertTrue(cursor.moveToFirst())
            assertTrue(cursor.isNull(1)) // New column exists and is empty
        }
    }
}

このヘルパーが検証するのはスキーマであってデータではないため、ユーザーデータが残ったことを証明するのはマイグレーション後の行に対するアサーションです。自動マイグレーションも同じ方法でテストでき、runMigrationsAndValidateは@Databaseで宣言されたものを明示的に渡さなくても適用します。バージョン1からすべてのマイグレーションを使って実際のデータベースを構築する2つ目のテストを用意すると、古いインストールが実際にたどる経路をカバーできます。

Roomマイグレーションでよくあるエラーと対処法

以下はリリース後にクラッシュレポートに現れるメッセージで、面接官が候補者のスキーマ変更リリース経験を確かめるために使う質問でもあります。

エラーメッセージ(冒頭)原因対処法
A migration from 1 to 2 was required but not foundバージョンを上げたが、そのステップのマイグレーションが登録されていないすべてのステップにMigrationまたは@AutoMigrationを追加するか、直接のMigration(1, 3)を追加する
Migration didn't properly handle: usersマイグレーション後のテーブルがエンティティと異なる(型、null許容、デフォルト値、インデックス)ログのExpectedとFoundのTableInfoを比較し、SQLをエンティティに合わせる
Room cannot verify the data integrityエンティティを変更したがversionを上げていないversionを上げてマイグレーションを追加する
Schema '1.json' required for migration was not found旧バージョンのスキーマがエクスポートされていない状態で自動マイグレーションを使用schemaDirectoryを設定し、最初のリリースからschemas/をコミットする
Cannot add a NOT NULL column with default value NULLDEFAULTなしのADD COLUMN ... NOT NULLSQLにDEFAULTを、@ColumnInfoにdefaultValueを追加する

最も多いのはMigration didn't properly handleです。Found側を見ると、エンティティがTEXT NOT NULLを期待しているカラムがTEXTで宣言されていたり、インデックスがRoomの生成するindex_<table>_<column>の命名規則と異なる名前で作成されていたりするのが典型です。

Androidの面接対策はできていますか?

インタラクティブなシミュレーター、flashcards、技術テストで練習しましょう。

Room 3.0のマイグレーション:Room 2.xからの変更点

Room 3.0は@Entity、@Dao、@Query、@Databaseおよび自動マイグレーションのアノテーションを維持していますが、パッケージとMavenグループはandroidx.room3になります。Room 3.0のリリースノートに記載された破壊的変更は、すべてマイグレーションコードに影響します。

  • SupportSQLiteDatabaseは廃止されました。データベースの構築にはSQLiteDriverが必須となり、マイグレーションはSQLiteConnectionを受け取ります。
  • Migration.migrate()とAutoMigrationSpec.onPostMigrate()はsuspend関数になりました。
  • サポートされるのはKSPのみで、KAPTとJavaコード生成は削除されました。
  • DAO関数はsuspendであるか、Flowなどのリアクティブ型を返す必要があります。
  • @TypeConverterは@ColumnTypeConverterに名称変更されました。
Room 3.0: the same migration, written against SQLiteConnectionkotlin
import androidx.room3.Room
import androidx.room3.migration.Migration
import androidx.sqlite.SQLiteConnection
import androidx.sqlite.driver.AndroidSQLiteDriver
import androidx.sqlite.executeSQL

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        connection.executeSQL("ALTER TABLE users ADD COLUMN phone_number TEXT")
    }
}

val db = Room.databaseBuilder<AppDatabase>(context, "app_database")
    .setDriver(AndroidSQLiteDriver()) // Required in Room 3
    .addMigrations(MIGRATION_1_2)
    .build()

各マイグレーション内のSQLは変わらず、変わるのはシグネチャ、パッケージ、ビルダーだけです。共有コードを持たないAndroid専用アプリでは、2.x系も引き続きリリースされている(2026年9月に2.8.5)ため、移行を急ぐ必要はありません。データレイヤーをiOSやデスクトップと共有するプロジェクトでは、Room 3が移行先になります。その構成はKotlin Multiplatformガイドで解説しています。SupportSQLiteDatabaseに依存するコードが残っている場合、移行期間中はroom3-sqlite-wrapperアーティファクトのgetSupportWrapper()を呼び出せます。

埋め込みオブジェクトによるエンティティリレーションのモデリング

Roomは3つのリレーションパターンをサポートしています:埋め込みオブジェクト、一対多、多対多です。ORMとは異なり、Roomはフラットなデータを返すため、リレーションには明示的なクエリが必要です。

一対多:ユーザーと投稿

ユーザーは複数の投稿を持つことができます。両方のエンティティを組み合わせたデータクラスで@Relationアノテーションを使用してリレーションを定義します。

Post.ktkotlin
@Entity(
    tableName = "posts",
    foreignKeys = [
        ForeignKey(
            entity = User::class,
            parentColumns = ["id"],
            childColumns = ["user_id"],
            onDelete = ForeignKey.CASCADE // Delete posts when user deleted
        )
    ],
    indices = [Index("user_id")] // Required for foreign key performance
)
data class Post(
    @PrimaryKey(autoGenerate = true) val id: Long = 0,
    @ColumnInfo(name = "user_id") val userId: Long,
    val title: String,
    val content: String,
    @ColumnInfo(name = "created_at") val createdAt: Long = System.currentTimeMillis()
)

// UserWithPosts.kt - Relation container
data class UserWithPosts(
    @Embedded val user: User,
    @Relation(
        parentColumn = "id",
        entityColumn = "user_id"
    )
    val posts: List<Post>
)

// In UserDao.kt
@Transaction // Ensures atomic read of user + posts
@Query("SELECT * FROM users WHERE id = :userId")
suspend fun getUserWithPosts(userId: Long): UserWithPosts?

@Transaction
@Query("SELECT * FROM users WHERE is_active = 1")
fun observeActiveUsersWithPosts(): Flow<List<UserWithPosts>>

@Transactionアノテーションは、内部的にリレーションが複数のクエリにまたがる場合の不整合な読み取りを防止します。

多対多:ユーザーとタグ

多対多リレーションには、外部キーのペアを格納するジャンクション(クロスリファレンス)テーブルが必要です。

Tag.ktkotlin
@Entity(tableName = "tags")
data class Tag(
    @PrimaryKey(autoGenerate = true) val tagId: Long = 0,
    val name: String
)

// UserTagCrossRef.kt - Junction table
@Entity(
    tableName = "user_tag_cross_ref",
    primaryKeys = ["userId", "tagId"],
    foreignKeys = [
        ForeignKey(entity = User::class, parentColumns = ["id"], childColumns = ["userId"], onDelete = ForeignKey.CASCADE),
        ForeignKey(entity = Tag::class, parentColumns = ["tagId"], childColumns = ["tagId"], onDelete = ForeignKey.CASCADE)
    ]
)
data class UserTagCrossRef(
    val userId: Long,
    val tagId: Long
)

// UserWithTags.kt
data class UserWithTags(
    @Embedded val user: User,
    @Relation(
        parentColumn = "id",
        entityColumn = "tagId",
        associateBy = Junction(UserTagCrossRef::class)
    )
    val tags: List<Tag>
)

associateByパラメータは、ユーザーとタグをリンクするジャンクションテーブルを指定します。

RoomとViewModelおよびRepositoryの統合

クリーンアーキテクチャはデータベースレイヤーをUIから分離します。Repositoryパターンはデータソースを抽象化し、ViewModelはCompose UIにステートを公開します。

UserRepository.ktkotlin
class UserRepository(private val userDao: UserDao) {

    val activeUsers: Flow<List<User>> = userDao.observeActiveUsers()

    suspend fun createUser(email: String, displayName: String): Long {
        val user = User(email = email, displayName = displayName)
        return userDao.insertUser(user)
    }

    suspend fun deactivateUser(userId: Long) {
        userDao.getUserById(userId)?.let { user ->
            userDao.updateUser(user.copy(isActive = false))
        }
    }
}

// UserViewModel.kt
class UserViewModel(
    private val repository: UserRepository
) : ViewModel() {

    val users: StateFlow<List<User>> = repository.activeUsers
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = emptyList()
        )

    fun createUser(email: String, name: String) {
        viewModelScope.launch {
            repository.createUser(email, name)
            // No manual refresh needed - Flow emits automatically
        }
    }
}

stateInオペレーターは、RoomからのコールドFlowをCompose収集に適したホットStateFlowに変換します。Coroutinesパターンの詳細については、Kotlin Coroutinesのガイドを参照してください。

Room Databaseのテスト

Roomはテスト用にインメモリデータベースビルダーRoom.inMemoryDatabaseBuilder()を提供しています。テストはより高速に実行され、実行間でデータは保持されません。DAOのテストにはインメモリビルダーを使い、マイグレーションのテストには実ファイル上でMigrationTestHelperを使います。インメモリデータベースには移行元となる旧バージョンが存在しないためです。

複合型のための型コンバーター

Roomはプリミティブ型のみをネイティブに格納します。型コンバーターは複合型(日付、列挙型、リスト)を格納可能な形式に変換します。

Converters.ktkotlin
import androidx.room.TypeConverter
import java.time.Instant
import java.time.LocalDate
import java.time.ZoneOffset

class Converters {
    // Instant <-> Long (milliseconds)
    @TypeConverter
    fun fromInstant(instant: Instant?): Long? = instant?.toEpochMilli()

    @TypeConverter
    fun toInstant(millis: Long?): Instant? = millis?.let { Instant.ofEpochMilli(it) }

    // LocalDate <-> String (ISO format)
    @TypeConverter
    fun fromLocalDate(date: LocalDate?): String? = date?.toString()

    @TypeConverter
    fun toLocalDate(dateStr: String?): LocalDate? = dateStr?.let { LocalDate.parse(it) }

    // List<String> <-> JSON string
    @TypeConverter
    fun fromStringList(list: List<String>?): String? =
        list?.joinToString(separator = ",")

    @TypeConverter
    fun toStringList(data: String?): List<String>? =
        data?.split(",")?.filter { it.isNotBlank() }
}

// Register in database class
@Database(...)
@TypeConverters(Converters::class)
abstract class AppDatabase : RoomDatabase()

複合オブジェクトのJSONシリアライゼーションには、手動の文字列操作の代わりにkotlinx.serializationの使用を検討してください。Room 3.0では、同じアノテーションの名前が@ColumnTypeConverterと@ColumnTypeConvertersになります。

Coroutinesでのデータベースエラーの処理

suspendのDAO関数はすでにRoom独自のクエリディスパッチャー上で実行されるため、withContext(Dispatchers.IO)で囲んでもコンテキストの切り替えが1回増えるだけで、スレッド安全性は変わりません。Repositoryの役割は、SQLiteの例外をドメインのエラーに変換することです。

UserRepository.kt with error handlingkotlin
import android.database.sqlite.SQLiteConstraintException

class UserRepository(private val userDao: UserDao) {

    suspend fun createUser(email: String, displayName: String): Result<Long> {
        return try {
            val id = userDao.insertUser(
                User(email = email, displayName = displayName)
            )
            Result.success(id)
        } catch (e: SQLiteConstraintException) {
            // Unique index on email, raised by the default ABORT strategy
            Result.failure(DuplicateEmailException(email))
        }
    }

    suspend fun deleteAllInactive(): Int = userDao.deleteInactiveUsers()
}

class DuplicateEmailException(email: String) : Exception("Email already exists: $email")

結果をResult<T>でラップすることで、ViewModelがtry-catchボイラープレートなしでエラーを処理できます。insertUserにOnConflictStrategy.REPLACEを指定していた場合、この例外は発生せず、既存のユーザーが警告なしに上書きされます。

参考資料

  • Roomリリースノート:Room 2.7(KMP、SQLiteConnection版マイグレーションのオーバーロード、room-ktxのroom-runtimeへの統合、Kotlin 2.0)、Room 2.8(minSdk 23)、現行安定版2.8.5
  • Room 3.0リリースノート:新しいandroidx.room3パッケージ、SQLiteDriver必須、KSPのみ、suspendマイグレーション、@ColumnTypeConverter
  • Roomデータベースの移行:自動マイグレーション、AutoMigrationSpec、マイグレーションテスト、破壊的フォールバック
  • SQLite ALTER TABLE:ADD COLUMNの制約とテーブル再作成の手順
  • KSPリリース:KSP 2.3以降、バージョン番号にKotlinのバージョンが前置されなくなった

本番環境と面接のためのRoomマイグレーションチェックリスト

本番環境に耐えるRoomデータベースレイヤーの構築は、面接官も確認するいくつかのプラクティスに集約されます。

  • Room 2.8ではKSPを使い、2.7以降は空になっているroom-ktxを削除する
  • schemaDirectoryを設定し、最初のリリースからschemas/をコミットする。これがないと自動マイグレーションもマイグレーションテストもできない
  • スキーマを変更するたびにversionを上げ、自動または手動ですべてのステップに経路を用意する
  • 非nullカラムは、@ColumnInfo(defaultValue)と一致するSQLのDEFAULT付きで追加する
  • 各マイグレーションをMigrationTestHelperでテストし、スキーマだけでなくマイグレーション後のデータもアサートする
  • fallbackToDestructiveMigration(dropAllTables = true)はキャッシュ専用とし、ユーザーデータには使わない
  • 子行がCASCADEで親に依存している場合は、REPLACEより@Upsertを選ぶ
  • 一貫した読み取りを確保するためにリレーションクエリには@Transactionを使用する
  • データレイヤーを他のプラットフォームと共有する場合はRoom 3.0への移行を計画する:SQLは同じ、migrate(SQLiteConnection)はsuspend、パッケージは新しくなる

面接の定番の質問は「ユーザーがバージョン1から一気にバージョン4へ更新したら何が起きるか」です。期待される回答は、Roomは登録されたマイグレーションを最短経路でつなげて実行し、最終的なスキーマを検証し、途中のステップが欠けていれば破壊的フォールバックが設定されていない限りIllegalStateExceptionをスローする、というものです。これらのパターンはRoom Databaseの面接質問で練習できます。

今すぐ練習を始めましょう!

面接シミュレーターと技術テストで知識をテストしましょう。

今日のチャレンジ

Android のバグを見つけられますか

実際のコード、隠れたバグ、1日1回。アカウントなしで試せます。

Anthony Fillion-Maillet

執筆

Anthony Fillion-Maillet

SharpSkill 創業者

10 年以上フルスタック開発に携わっています。SharpSkill を運営し、ここで公開される内容に責任を負っています。

2026年11月10日 更新

タグ

#android
#room
#kotlin
#sqlite
#coroutines
#database

共有

関連記事