KotlinのRoomでデータベースマイグレーションを行う基本手順を初心者向けに解説！

先生と生徒の会話形式で理解しよう

生徒

「KotlinのRoomを使っていて、後からテーブルのカラムを追加したいときってどうすればいいんですか？」

先生

「そのときに使うのが『データベースマイグレーション』という方法です。Roomでは、バージョンアップに合わせて正しくデータを移行することができますよ。」

生徒

「それって難しそうですが、具体的にどんなことをするんですか？」

先生

「それでは、KotlinでRoomのマイグレーションをする基本的な流れを、分かりやすく説明していきましょう！」

1. Roomのデータベースマイグレーションとは？

マイグレーションとは、古いバージョンのデータベースを新しい形に変える処理のことです。

たとえば、アプリのバージョン1では「名前と年齢」しかなかったけれど、バージョン2では「メールアドレス」も保存したくなったとします。こういうときに、すでにインストール済みの人のデータを壊さずに新しい構造に変えるための手順が「マイグレーション」です。

2. マイグレーションが必要になる場面とは？

Roomを使ったアプリでは、データベースのversionを上げたときに、過去のデータと新しい構造の整合性が必要になります。

カラム（列）を追加した
テーブルを新しく作った
テーブル名を変更した

これらの変更を正しくアプリに反映するには、マイグレーション処理を設定する必要があります。

3. KotlinのRoomでマイグレーションする基本の書き方

ここでは、ユーザーテーブルに「email」というカラムを追加する例で、Roomのマイグレーション処理を見てみましょう。

① 新しいエンティティを作る


@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Int,
    val name: String,
    val age: Int,
    val email: String // 新しく追加されたカラム
)

② データベースバージョンを上げる

RoomDatabaseのversionを1から2に上げます。


@Database(entities = [User::class], version = 2)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}

③ Migrationオブジェクトを定義する


val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE users ADD COLUMN email TEXT NOT NULL DEFAULT ''")
    }
}

④ Roomのビルダーにマイグレーションを追加する


val db = Room.databaseBuilder(
    context,
    AppDatabase::class.java, "my_database"
).addMigrations(MIGRATION_1_2).build()

4. execSQLって何？

execSQLは、データベースに直接SQL文（命令文）を送る関数です。Roomの裏ではSQLite（エスキューライト）という仕組みが動いており、execSQLを使ってテーブルの形を変更します。

「カラムを追加する」には、ALTER TABLE テーブル名 ADD COLUMN カラム名型 DEFAULT 初期値 という命令を使います。

5. DEFAULTの設定を忘れずに！

新しくカラムを追加するとき、すでに入っている古いデータにはそのカラムがありません。だからこそ、初期値（DEFAULT）を必ずつける必要があります。

例えば、emailを追加したけど、今までのデータにはメールアドレスがない…というとき、''（空文字）を入れておくことでエラーを防げます。

6. バージョン番号は必ず1ずつ上げよう

Roomのマイグレーションでは、versionを飛び越えることはできません。たとえば、バージョン1から3にするには、

MIGRATION_1_2
MIGRATION_2_3

のように順番に設定する必要があります。ひとつひとつの段階を丁寧に用意していきましょう。

7. マイグレーションを使えばデータを壊さずアップデートできる

KotlinとRoomを使ってアプリを作ると、あとから「もっと情報を保存したい」と思うことがよくあります。

そんなときでも、マイグレーションを正しく設定しておけば、ユーザーの大切なデータを消すことなく、新しい形に安全に更新できます。

初心者のうちは怖く感じるかもしれませんが、流れさえ分かれば意外とシンプルです。何度も練習して慣れていきましょう。