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

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

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

Kotlinを基礎からしっかり学びたい人や、 Java経験を活かしてモダンな言語にステップアップしたい人には、定番の入門書がこちらです。

基礎からわかるKotlinをAmazonで見る

※ Amazon広告リンク

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

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

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

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

【未経験OK】Kotlinで始めるプログラミング入門｜ゼロから「動く喜び」を体験する60分

「プログラミングを始めたい」を形にする。最新言語Kotlinで楽しむ、ものづくりの第一歩。

本講座は、プログラミング経験が全くない方のためのエントリー講座です。「コードを書くってどういうこと？」という基本から、世界中で使われている最新言語Kotlin（コトリン）を使って、実際にプログラムを動かすまでを体験します。難しい理屈よりも、まずは「自分の手で動かす楽しさ」を最短距離で実感していただきます。